UI 视觉设计 / 系统课时
输出可切换主题的 CSS 变量
输出可切换主题的 CSS 变量
把已解析的浅色与深色语义 Token 编译成一份 CSS:用 :root 提供默认值,用主题属性选择器覆盖取值。浏览器切换主题时,订单卡片和按钮继续引用原有的 var(),无需修改组件样式。
学习目标
- 把两套已解析语义值映射为同名 CSS 自定义属性。
- 生成默认主题与深色主题的选择器及覆盖规则。
- 在浏览器切换
data-theme,检查组件计算样式和失效原因。
准备主题编译输入
建立 resolved-themes.json,保存 Resolver 已解析出的最终色值。这里是编译中间数据,不是 DTCG 原始 Token 文件;如果源文件使用 $value 或别名,应先完成主题选择、别名解析和颜色序列化,再进入本步骤。两种模式的键必须完全相同,组件才可以共用变量名。
{
"light": {
"color.surface.default": "#ffffff",
"color.text.primary": "#182230",
"color.action.primary": "#0066cc",
"color.action.on-primary": "#ffffff",
"color.border.default": "#cbd5e1"
},
"dark": {
"color.surface.default": "#0f172a",
"color.text.primary": "#e2e8f0",
"color.action.primary": "#93c5fd",
"color.action.on-primary": "#0b1220",
"color.border.default": "#475569"
}
}命名规则固定为点号转连字符并加前缀 --:color.action.primary 编译成 --color-action-primary。本例每个主题有 5 个语义键;在真实工程中还要检测归一化后是否发生重名,并拒绝缺失值,而不是悄悄输出空声明。
编译默认值与深色覆盖
使用 Node.js 20 或更高版本,在同一目录创建 build-tokens.mjs。构建器以浅色主题定义输出顺序,检查两套主题的键集合,然后写入 tokens.css。生成物统一放在主题选择器下,不在组件里硬编码品牌色或深色值。
import { readFile, writeFile } from "node:fs/promises";
const url = new URL("./resolved-themes.json", import.meta.url);
const themes = JSON.parse(await readFile(url, "utf8"));
if (!themes.light || !themes.dark) {
throw new Error("缺少 light 或 dark 主题");
}
// 两个主题必须同名、同数量,否则覆盖后的组件可能读取到旧值。
const keys = Object.keys(themes.light);
if (!keys.length ||
keys.some((key) => typeof themes.light[key] !== "string") ||
Object.keys(themes.dark).length !== keys.length ||
keys.some((key) => typeof themes.dark[key] !== "string")) {
throw new Error("两套主题的语义键和字符串值必须一一对应");
}
// 语义路径稳定映射成 CSS 自定义属性名,主题只改变属性值。
const render = (selector, values) => {
const lines = keys.map(
(key) => ` --${key.replaceAll(".", "-")}: ${values[key]};`
);
return `${selector} {\n${lines.join("\n")}\n}`;
};
// 默认主题与覆盖主题一起发布,避免加载时切换样式表。
const css = [
render(":root", themes.light),
render('html[data-theme="dark"]', themes.dark)
].join("\n\n") + "\n";
await writeFile(new URL("./tokens.css", import.meta.url), css, "utf8");
console.log(`已生成 tokens.css:2 套主题,每套 ${keys.length} 个变量`);先保存上述 JSON 和脚本,再在项目目录执行构建命令:
node build-tokens.mjs预期输出:
已生成 tokens.css:2 套主题,每套 5 个变量生成的 tokens.css 内容如下,可直接检查选择器和声明是否符合预期:
:root {
--color-surface-default: #ffffff;
--color-text-primary: #182230;
--color-action-primary: #0066cc;
--color-action-on-primary: #ffffff;
--color-border-default: #cbd5e1;
}
html[data-theme="dark"] {
--color-surface-default: #0f172a;
--color-text-primary: #e2e8f0;
--color-action-primary: #93c5fd;
--color-action-on-primary: #0b1220;
--color-border-default: #475569;
}:root 定义页面默认值;当根元素具有 data-theme="dark" 时,更具体的 html[data-theme="dark"] 规则覆盖同名自定义属性。由于普通 --* 属性会继承,页面内按钮等后代能读取根元素当前的值,而不需要维护两份组件 CSS。

让浏览器切换主题并验证
创建与 tokens.css 同目录的 index.html。组件只写 var(--color-...),切换事件只修改根元素的 data-theme;color-scheme 同步提示浏览器调整原生控件配色。本例是完整静态页面,可直接用浏览器打开。
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>主题切换验证</title>
<!-- 先加载生成的变量,再声明组件使用方式。 -->
<link rel="stylesheet" href="./tokens.css">
<style>
html { color-scheme: light; }
html[data-theme="dark"] { color-scheme: dark; }
body {
margin: 32px;
font: 16px/1.5 system-ui, sans-serif;
background: var(--color-surface-default);
color: var(--color-text-primary);
}
.card {
max-width: 360px;
padding: 24px;
background: var(--color-surface-default);
border: 1px solid var(--color-border-default);
border-radius: 12px;
}
.primary {
border: 0;
border-radius: 8px;
padding: 10px 16px;
background: var(--color-action-primary);
color: var(--color-action-on-primary);
}
</style>
</head>
<body>
<main class="card">
<h1>订单确认</h1>
<p>组件不需要知道当前使用哪套主题。</p>
<button id="toggle" class="primary" type="button">切换为深色</button>
<p id="status" aria-live="polite">当前主题:浅色</p>
</main>
<script>
const root = document.documentElement;
const button = document.querySelector("#toggle");
const status = document.querySelector("#status");
// 主题切换只改根元素的属性,不修改每个组件的样式。
button.addEventListener("click", () => {
const next = root.dataset.theme === "dark" ? "light" : "dark";
root.dataset.theme = next;
button.textContent = next === "dark" ? "切换为浅色" : "切换为深色";
status.textContent = `当前主题:${next === "dark" ? "深色" : "浅色"}`;
});
</script>
</body>
</html>预期页面结果:首次打开显示浅色订单卡片;点击“切换为深色”后,卡片变为深蓝背景,按钮变为浅蓝背景,状态文字显示“当前主题:深色”;再次点击恢复浅色。CSS 组件规则及 var() 引用在整个过程中保持不变。
| 检查项 | 默认浅色 | 点击后的深色 |
|---|---|---|
| 根元素主题属性 | 无 data-theme |
data-theme="dark" |
| 卡片背景 | #ffffff |
#0f172a |
| 按钮背景 | #0066cc |
#93c5fd |
| 按钮文字 | #ffffff |
#0b1220 |
在浏览器开发者工具的 Elements(元素)面板选中按钮,在 Computed(计算样式)里查 background-color;浅色应为 rgb(0, 102, 204),深色应为 rgb(147, 197, 253)。这验证了实际应用到组件的值,而不只是 CSS 文件中出现了对应声明。
排除覆盖失效与维护隐患
如果按钮没有变色,按顺序核对:tokens.css 是否加载成功;根元素上的属性值是否精确为 dark;生成文件是否具有对应选择器;组件的 background 是否被后续更高优先级的硬编码声明或 !important 覆盖。不要依赖 var(--color-action-primary, #0066cc) 的回退值来完成主题切换:回退参数用于变量无有效取值时,并不会替代主题选择器。
发布时把 resolved-themes.json 视为中间输入、tokens.css 视为生成产物;Token 变更后重新执行构建,并至少校验浅色与深色两种状态。如果要记住用户主题偏好,可在页面首次绘制前恢复 data-theme,避免加载后才切换导致的闪烁。