Vue / 系统课时

主题与设计令牌

主题与设计令牌

主题系统的目标不是简单把一组颜色切成深色,而是让组件只依赖稳定的设计语义。本节用 CSS 变量组织颜色、间距和圆角,再通过根节点主题属性覆盖语义令牌,让亮色、暗色与系统主题切换时无需修改业务组件样式。

学习目标

  • 用 CSS 变量建立可复用的颜色、间距和圆角设计令牌。
  • 区分语义令牌与组件样式,降低主题切换的耦合。
  • 实现亮色、暗色和跟随系统三种主题模式并持久化用户选择。

让组件依赖语义而不是具体颜色

企业项目中更稳妥的做法,是让组件使用 --color-bg、--color-text、--color-border 这类语义变量,而不是直接引用具体十六进制颜色或 gray-900 之类基础色名。主题切换只需要替换语义变量,组件不必知道当前是亮色还是暗色。

间距和圆角通常不随主题变化,也适合统一成令牌。这样设计系统调整页面密度或圆角时,只修改根变量就能覆盖整个应用,而不需要逐个组件搜索固定值。

设计令牌分层与主题覆盖关系

定义全局设计令牌

建议把全局令牌集中放在主题入口样式文件,并通过 data-theme 覆盖真正需要变化的颜色。下面的 CSS 可以直接作为基础配置;组件只消费令牌,不再重复编写暗色选择器。

css
:root {
  --color-bg: #f6f7f9;
  --color-surface: #ffffff;
  --color-text: #1f2329;
  --color-text-muted: #646a73;
  --color-border: #dfe3e8;
  --color-primary: #2563eb;

  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-6: 24px;

  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;
}

:root[data-theme='dark'] {
  --color-bg: #111318;
  --color-surface: #1a1d24;
  --color-text: #f3f4f6;
  --color-text-muted: #a8adb7;
  --color-border: #343944;
  --color-primary: #60a5fa;
}

.card {
  background: var(--color-surface);
  color: var(--color-text);
  padding: var(--space-4);
  border: 1px solid var(--color-border);
  border-radius: var(--radius-md);
}

预期结果

text
data-theme 未设置或使用亮色时,Card 使用亮色背景和深色文字。
data-theme 为 dark 时,Card 自动切换到暗色背景和浅色文字。
间距与圆角保持不变,.card 不需要再维护一套暗色样式。

在 TypeScript 中切换主题

主题状态建议只保存 light、dark、system 三种用户选择;真正写入 DOM 的仍然是解析后的亮色或暗色。这样用户选择“跟随系统”后,操作系统主题变化可以立即反映到页面。

下面代码是浏览器端完整模块示例,可放入 src/theme.ts。若项目使用 SSR,应在客户端挂载阶段再执行访问 window、document 和 localStorage 的逻辑。

ts
export type ThemeMode = 'light' | 'dark' | 'system'

const STORAGE_KEY = 'app-theme'
const media = window.matchMedia('(prefers-color-scheme: dark)')

let currentMode =
  (localStorage.getItem(STORAGE_KEY) as ThemeMode | null) ?? 'system'

function resolveTheme(mode: ThemeMode): 'light' | 'dark' {
  if (mode === 'system') {
    return media.matches ? 'dark' : 'light'
  }
  return mode
}

function applyTheme(mode: ThemeMode) {
  const resolved = resolveTheme(mode)
  document.documentElement.dataset.theme = resolved
  document.documentElement.style.colorScheme = resolved
}

export function setTheme(mode: ThemeMode) {
  currentMode = mode
  localStorage.setItem(STORAGE_KEY, mode)
  applyTheme(mode)
}

media.addEventListener('change', () => {
  // 只有跟随系统时,系统外观变化才覆盖当前页面主题。
  if (currentMode === 'system') applyTheme(currentMode)
})

applyTheme(currentMode)

预期结果

text
setTheme('dark'):根节点得到 data-theme="dark",并把 dark 写入 localStorage。
setTheme('light'):根节点得到 data-theme="light"。
setTheme('system'):根据 prefers-color-scheme 选择亮色或暗色,系统主题变化时自动跟随。

让令牌扩展而不失控

令牌数量增加后,应优先扩展“语义”,而不是继续把具体色值暴露给组件。例如危险操作使用 --color-danger,成功状态使用 --color-success;按钮、提示框和表格状态再基于这些变量构造自己的样式。未来更换品牌色或增加高对比度主题时,修改的是令牌映射,而不是几十个组件。

也不要把所有组件私有变量都塞进 :root。全局层只保留跨组件共享的语义令牌;只有某个组件需要的变量,可以在组件根选择器中定义,例如 --button-height。这样可以控制命名空间规模,并明确令牌的作用范围。

处理闪烁和可访问性

如果页面加载后才执行主题模块,浏览器可能先绘制亮色,再瞬间切换到暗色。实际项目可以在应用主脚本执行前读取已保存的主题,并尽早给根节点设置 data-theme;使用 SSR 时,则应尽量让服务端输出与客户端初始偏好一致的主题,减少水合前的闪烁。

同时设置 color-scheme 能让表单控件、滚动条等浏览器原生界面更好地匹配当前主题,但仍应检查文字与背景的对比度。主题系统真正解决的是视觉规则的集中管理:组件依赖稳定语义,主题只负责映射这些语义,设计调整和后续扩展因此能够保持在可控范围内。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

主题与设计令牌

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通