Vue / 系统课时
主题与设计令牌
主题与设计令牌
主题系统的目标不是简单把一组颜色切成深色,而是让组件只依赖稳定的设计语义。本节用 CSS 变量组织颜色、间距和圆角,再通过根节点主题属性覆盖语义令牌,让亮色、暗色与系统主题切换时无需修改业务组件样式。
学习目标
- 用 CSS 变量建立可复用的颜色、间距和圆角设计令牌。
- 区分语义令牌与组件样式,降低主题切换的耦合。
- 实现亮色、暗色和跟随系统三种主题模式并持久化用户选择。
让组件依赖语义而不是具体颜色
企业项目中更稳妥的做法,是让组件使用 --color-bg、--color-text、--color-border 这类语义变量,而不是直接引用具体十六进制颜色或 gray-900 之类基础色名。主题切换只需要替换语义变量,组件不必知道当前是亮色还是暗色。
间距和圆角通常不随主题变化,也适合统一成令牌。这样设计系统调整页面密度或圆角时,只修改根变量就能覆盖整个应用,而不需要逐个组件搜索固定值。

定义全局设计令牌
建议把全局令牌集中放在主题入口样式文件,并通过 data-theme 覆盖真正需要变化的颜色。下面的 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);
}预期结果
data-theme 未设置或使用亮色时,Card 使用亮色背景和深色文字。
data-theme 为 dark 时,Card 自动切换到暗色背景和浅色文字。
间距与圆角保持不变,.card 不需要再维护一套暗色样式。在 TypeScript 中切换主题
主题状态建议只保存 light、dark、system 三种用户选择;真正写入 DOM 的仍然是解析后的亮色或暗色。这样用户选择“跟随系统”后,操作系统主题变化可以立即反映到页面。
下面代码是浏览器端完整模块示例,可放入 src/theme.ts。若项目使用 SSR,应在客户端挂载阶段再执行访问 window、document 和 localStorage 的逻辑。
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)预期结果
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 能让表单控件、滚动条等浏览器原生界面更好地匹配当前主题,但仍应检查文字与背景的对比度。主题系统真正解决的是视觉规则的集中管理:组件依赖稳定语义,主题只负责映射这些语义,设计调整和后续扩展因此能够保持在可控范围内。