UI 视觉设计 / 系统课时
输出 CSS 变量与主题选择器
输出 CSS 变量与主题选择器
把已导出的设计令牌编译成浏览器可加载的 tokens.css:默认主题写入 :root,暗色主题按属性选择器覆盖语义变量。同时检查别名和尺寸单位,并让页面切换主题或局部改色时无需重新构建。
学习目标
- 将 DTCG 颜色、尺寸及别名令牌转换为 CSS 自定义属性。
- 用相同的变量名提供明暗主题,并验证生成结果。
- 在浏览器中切换主题、覆盖单个组件的颜色并排查失效原因。
约定变量名称与作用域
组件只引用语义名称,如 --ds-color-action,不要直接绑定 --ds-color-blue-600。浅色与深色输出相同的语义属性名,只改变取值;不随主题变化的间距只在 :root 声明一次。
| 用途 | CSS 变量 | 浅色 | 深色 |
|---|---|---|---|
| 交互强调色 | --ds-color-action |
#2563EB |
#93C5FD |
| 卡片表面色 | --ds-color-surface |
#FFFFFF |
#111827 |
| 中等间距 | --ds-space-md |
12px |
继承 12px |
这里采用根元素主题选择器 :root[data-theme="dark"],页面只需修改根元素的 data-theme。该选择器不会响应嵌套容器上的同名属性;需要局部主题时应另行设计容器级作用域。

整理可编译的令牌源
将 Figma 导出的变量规范化为 DTCG 风格的 tokens.json。$type 标记类型,$value 存储值;{color.blue.600} 是引用路径,不是 CSS 语法。按 DTCG 2025.10,颜色的 $value 使用 colorSpace 与 components 对象;这里采用不透明 sRGB 颜色和 px 尺寸,方便直接核验编译结果。
{
"color": {
"blue": {
"600": {"$type": "color", "$value": {"colorSpace": "srgb", "components": [0.145098, 0.388235, 0.921569]}},
"300": {"$type": "color", "$value": {"colorSpace": "srgb", "components": [0.576471, 0.772549, 0.992157]}}
},
"neutral": {
"0": {"$type": "color", "$value": {"colorSpace": "srgb", "components": [1, 1, 1]}},
"900": {"$type": "color", "$value": {"colorSpace": "srgb", "components": [0.066667, 0.094118, 0.152941]}}
}
},
"spacing": {
"md": {"$type": "dimension", "$value": {"value": 12, "unit": "px"}}
},
"semantic": {
"light": {
"action": {"$type": "color", "$value": "{color.blue.600}"},
"surface": {"$type": "color", "$value": "{color.neutral.0}"}
},
"dark": {
"action": {"$type": "color", "$value": "{color.blue.300}"},
"surface": {"$type": "color", "$value": "{color.neutral.900}"}
}
}
}不要把 dimension 的 { "value": 12, "unit": "px" } 直接序列化成 CSS 对象,也不要对 opacity 这类无单位数值追加 px。单位必须根据令牌类型和目标平台转换。
生成并核对 tokens.css
使用 Node.js 20 或更新版本,在 tokens.json 同一目录保存以下 build.mjs。它在构建期展开别名,检查缺失路径、循环引用和类型不匹配,最后生成一个同时包含两个主题的文件。示例刻意只支持不透明 sRGB 颜色(转为六位十六进制)与 px、rem 尺寸;生产中支持其他色域、透明度或复合类型时应扩展转换或使用 Style Dictionary。
import { readFileSync, mkdirSync, writeFileSync } from 'node:fs';
const source = JSON.parse(
readFileSync(new URL('./tokens.json', import.meta.url), 'utf8')
);
function resolve(path, chain = []) {
if (chain.includes(path)) {
throw new Error(`循环别名:${[...chain, path].join(' -> ')}`);
}
const token = path.split('.').reduce((obj, key) => obj?.[key], source);
if (!token || !Object.hasOwn(token, '$value')) {
throw new Error(`未知令牌:${path}`);
}
const raw = token.$value;
const ref = typeof raw === 'string' ? /^\{([^{}]+)\}$/.exec(raw) : null;
if (ref) {
const target = resolve(ref[1], [...chain, path]);
if (target.type !== token.$type) throw new Error(`类型不匹配:${path}`);
return target;
}
// 不透明 sRGB 三分量转换成浏览器支持的六位 hex。
if (token.$type === 'color' && raw?.colorSpace === 'srgb' &&
Array.isArray(raw.components) && raw.components.length === 3 &&
raw.components.every(n => Number.isFinite(n) && n >= 0 && n <= 1) &&
(raw.alpha === undefined || raw.alpha === 1)) {
const hex = raw.components.map(n => Math.round(n * 255)
.toString(16).padStart(2, '0')).join('').toUpperCase();
return { type: 'color', value: `#${hex}` };
}
if (token.$type === 'dimension' && raw &&
Number.isFinite(raw.value) && ['px', 'rem'].includes(raw.unit)) {
return { type: 'dimension', value: `${raw.value}${raw.unit}` };
}
throw new Error(`不支持的值:${path}`);
}
const val = (path) => resolve(path).value;
const css = [
':root {',
` --ds-space-md: ${val('spacing.md')};`,
` --ds-color-action: ${val('semantic.light.action')};`,
` --ds-color-surface: ${val('semantic.light.surface')};`,
'}',
':root[data-theme="dark"] {',
` --ds-color-action: ${val('semantic.dark.action')};`,
` --ds-color-surface: ${val('semantic.dark.surface')};`,
'}',
''
].join('\n');
mkdirSync('dist', { recursive: true });
writeFileSync('dist/tokens.css', css, 'utf8');
console.log('已生成 dist/tokens.css');执行 node build.mjs。预期输出:
已生成 dist/tokens.css生成文件的内容应为:
:root {
--ds-space-md: 12px;
--ds-color-action: #2563EB;
--ds-color-surface: #FFFFFF;
}
:root[data-theme="dark"] {
--ds-color-action: #93C5FD;
--ds-color-surface: #111827;
}这里选择把引用在构建期展开为颜色值,便于直接发布。若希望保留 var(--ds-color-blue-600) 形式的运行时别名,则必须同时输出它引用的基础变量;Style Dictionary 的 css/variables 格式可通过 outputReferences 控制该行为。
切换主题与局部覆盖
把下面的页面保存为同目录下的 index.html,用浏览器打开。组件仅使用语义变量;根元素控制全页主题,而卡片自身的行内自定义属性可单独覆盖文字色,不影响其他卡片。
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>CSS Token 验证</title>
<link rel="stylesheet" href="./dist/tokens.css">
<style>
.card {
padding: var(--ds-space-md);
color: var(--ds-color-action);
background: var(--ds-color-surface);
border: 1px solid currentColor;
}
</style>
</head>
<body>
<section class="card" id="card">主题预览</section>
<button id="theme">切换主题</button>
<button id="accent">覆盖卡片文字色</button>
<script>
const root = document.documentElement;
const card = document.querySelector('#card');
// 只改主题属性,组件 CSS 不需要重写。
document.querySelector('#theme').addEventListener('click', () => {
root.dataset.theme = root.dataset.theme === 'dark' ? 'light' : 'dark';
});
// 再次点击移除局部覆盖,回到语义变量继承值。
document.querySelector('#accent').addEventListener('click', () => {
const old = card.style.getPropertyValue('--ds-color-action');
if (old) card.style.removeProperty('--ds-color-action');
else card.style.setProperty('--ds-color-action', '#DC2626');
});
</script>
</body>
</html>预期结果:初始卡片为白底、蓝字、12px 内边距;切换后为深灰底、浅蓝字;点击覆盖后文字变成 #DC2626,再次点击恢复当前主题色。可在浏览器开发者工具的 Computed(计算后样式)中检查 color、background-color 和 padding。
排查样式没有生效的情况
| 现象 | 先检查 | 修正方式 |
|---|---|---|
padding 未生效 |
--ds-space-md 是否为 12 而非 12px |
在构建时按 dimension 类型输出单位 |
| 深色没有切换 | data-theme 是否设置在 html 上 |
与 :root[data-theme="dark"] 选择器保持一致 |
| 改主题后文字仍为红色 | 卡片是否存在行内 --ds-color-action |
调用 removeProperty 清除局部覆盖 |
| 构建失败 | 是否引用了不存在的路径、形成循环或跨类型引用 | 修复源令牌,不发布不完整 CSS |
var(--ds-color-action, #2563EB) 可以在变量缺失时提供后备值,但无法修复变量已存在却包含无效颜色值的问题。交付前至少验证浅色、深色、局部覆盖恢复三个状态,并故意把一处引用改为不存在的路径,确认构建明确报错。