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。该选择器不会响应嵌套容器上的同名属性;需要局部主题时应另行设计容器级作用域。

令牌别名解析、CSS 编译与主题覆盖数据流

整理可编译的令牌源

将 Figma 导出的变量规范化为 DTCG 风格的 tokens.json。$type 标记类型,$value 存储值;{color.blue.600} 是引用路径,不是 CSS 语法。按 DTCG 2025.10,颜色的 $value 使用 colorSpace 与 components 对象;这里采用不透明 sRGB 颜色和 px 尺寸,方便直接核验编译结果。

json
{
  "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。

js
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。预期输出:

text
已生成 dist/tokens.css

生成文件的内容应为:

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,用浏览器打开。组件仅使用语义变量;根元素控制全页主题,而卡片自身的行内自定义属性可单独覆盖文字色,不影响其他卡片。

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) 可以在变量缺失时提供后备值,但无法修复变量已存在却包含无效颜色值的问题。交付前至少验证浅色、深色、局部覆盖恢复三个状态,并故意把一处引用改为不存在的路径,确认构建明确报错。

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

目录与阅读设置

阅读设置

17

记录一个想法

输出 CSS 变量与主题选择器

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

登录哪都通