UI 视觉设计 / 系统课时

输出可切换主题的 CSS 变量

输出可切换主题的 CSS 变量

把已解析的浅色与深色语义 Token 编译成一份 CSS:用 :root 提供默认值,用主题属性选择器覆盖取值。浏览器切换主题时,订单卡片和按钮继续引用原有的 var(),无需修改组件样式。

学习目标

  • 把两套已解析语义值映射为同名 CSS 自定义属性。
  • 生成默认主题与深色主题的选择器及覆盖规则。
  • 在浏览器切换 data-theme,检查组件计算样式和失效原因。

准备主题编译输入

建立 resolved-themes.json,保存 Resolver 已解析出的最终色值。这里是编译中间数据,不是 DTCG 原始 Token 文件;如果源文件使用 $value 或别名,应先完成主题选择、别名解析和颜色序列化,再进入本步骤。两种模式的键必须完全相同,组件才可以共用变量名。

json
{
  "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。生成物统一放在主题选择器下,不在组件里硬编码品牌色或深色值。

js
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 和脚本,再在项目目录执行构建命令:

bash
node build-tokens.mjs

预期输出:

text
已生成 tokens.css:2 套主题,每套 5 个变量

生成的 tokens.css 内容如下,可直接检查选择器和声明是否符合预期:

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。

语义 Token 编译为 CSS 变量并由主题属性触发覆盖

让浏览器切换主题并验证

创建与 tokens.css 同目录的 index.html。组件只写 var(--color-...),切换事件只修改根元素的 data-theme;color-scheme 同步提示浏览器调整原生控件配色。本例是完整静态页面,可直接用浏览器打开。

html
<!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,避免加载后才切换导致的闪烁。

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

目录与阅读设置

阅读设置

17

记录一个想法

输出可切换主题的 CSS 变量

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

登录哪都通