UI 视觉设计 / 系统课时

把设计变量映射成CSS Token

把设计变量映射成CSS Token

把设计稿中的颜色、文字、间距和圆角转换为 CSS 自定义属性,并让组件通过语义变量取值。本篇用一个可切换明暗主题的工单卡片完成映射、实现和验收,避免组件散落硬编码颜色。

学习目标

  • 区分基础 Token 与语义 Token,并建立可追溯的命名映射。
  • 使用 CSS 自定义属性统一控制颜色、文字、间距和圆角。
  • 验证主题切换时语义引用和组件计算样式是否同步变化。

建立设计变量到 CSS 的对照

先从 Figma 的 Variables 面板整理变量名称、模式和值。以下是一套示例约定;实际项目可采用不同路径,但导出名称必须固定,不能一处写 blue-600、另一处写 primaryBlue。

Figma 设计变量(示例) CSS 基础 Token 值
Color/Blue/600 --palette-blue-600 #2563eb
Color/Blue/300 --palette-blue-300 #93c5fd
Color/Neutral/0 --palette-white #ffffff
Color/Neutral/900 --palette-ink-900 #0f172a
Typography/Body/Size --font-size-body 16px
Typography/Body/Weight --font-weight-body 400
Spacing/2、Spacing/3 --space-2、--space-3 8px、12px
Radius/Medium --radius-md 8px

基础变量保存色板或尺寸标尺;语义变量描述用途,例如 --color-primary(主操作)和 --color-surface(页面底色)。设计稿里的语义变量应逐项对应到 CSS 语义变量,而不是让按钮直接引用 --palette-blue-600。

理清明暗主题的引用链

浅色模式下,--color-primary 指向 --palette-blue-600;深色模式改为 --palette-blue-300。按钮始终只写 background: var(--color-primary),因此切换模式时不必改按钮类名。文字和页面底色同理;间距 12px 与圆角 8px 在本例中跨主题保持一致。

Figma 语义变量(示例) CSS 语义 Token Light 引用 Dark 引用
Semantic/Action/Primary --color-primary --palette-blue-600 --palette-blue-300
Semantic/Surface/Default --color-surface --palette-white --palette-ink-900
Semantic/Text/Primary --color-text --palette-ink-900 --palette-muted-100

基础变量、语义变量与组件在明暗主题中的引用关系

实现可切换主题的最小页面

将下面内容保存为 tokens.html,用浏览器直接打开。:root 中声明基础值和默认语义映射,:root[data-theme='dark'] 只覆盖需要变动的语义值。页面与按钮使用相同的语义入口,JS 仅切换根元素的 data-theme。

html
<!doctype html>
<html lang='zh-CN' data-theme='light'>
<head>
  <meta charset='utf-8'>
  <meta name='viewport' content='width=device-width, initial-scale=1'>
  <title>CSS Token 演示</title>
  <style>
    :root {
      /* 基础层:与设计变量的实际取值对应 */
      --palette-blue-600: #2563eb;
      --palette-blue-300: #93c5fd;
      --palette-white: #ffffff;
      --palette-ink-900: #0f172a;
      --palette-ink-800: #1e293b;
      --palette-muted-100: #f1f5f9;
      --palette-border-200: #cbd5e1;
      --font-size-body: 16px;
      --font-weight-body: 400;
      --space-2: 8px;
      --space-3: 12px;
      --radius-md: 8px;

      /* 语义层:组件不直接依赖色板编号 */
      --color-surface: var(--palette-white);
      --color-text: var(--palette-ink-900);
      --color-border: var(--palette-border-200);
      --color-primary: var(--palette-blue-600);
      --color-on-primary: var(--palette-white);
    }
    :root[data-theme='dark'] {
      --color-surface: var(--palette-ink-900);
      --color-text: var(--palette-muted-100);
      --color-border: var(--palette-ink-800);
      --color-primary: var(--palette-blue-300);
      --color-on-primary: var(--palette-ink-900);
    }
    body {
      margin: 0;
      padding: var(--space-3);
      background: var(--color-surface);
      color: var(--color-text);
      font: var(--font-weight-body) var(--font-size-body) system-ui, sans-serif;
    }
    .panel {
      padding: var(--space-3);
      border: 1px solid var(--color-border);
      border-radius: var(--radius-md);
    }
    button {
      padding: var(--space-2) var(--space-3);
      border: 0;
      border-radius: var(--radius-md);
      background: var(--color-primary);
      color: var(--color-on-primary);
      cursor: pointer;
    }
  </style>
</head>
<body>
  <section class='panel'>
    <p>工单概览</p>
    <button id='theme-toggle' type='button'>切换主题</button>
  </section>
  <script>
    const root = document.documentElement;
    const toggle = document.querySelector('#theme-toggle');
    function reportTheme() {
      const style = getComputedStyle(document.body);
      console.log(`${root.dataset.theme}: ${style.backgroundColor} / ${style.color}`);
    }
    // 只切换主题标记,保留各组件的 Token 引用。
    toggle.addEventListener('click', () => {
      root.dataset.theme = root.dataset.theme === 'light' ? 'dark' : 'light';
      reportTheme();
    });
    reportTheme();
  </script>
</body>
</html>

预期输出(以 Chrome 的 Console 为例,首次加载后点击一次按钮):

text
light: rgb(255, 255, 255) / rgb(15, 23, 42)
dark: rgb(15, 23, 42) / rgb(241, 245, 249)

可见效果是页面从白底深字变为深底浅字,按钮从深蓝底白字变为浅蓝底深字;卡片内边距仍是 12px,圆角仍是 8px。控制台打印的是实际计算后的颜色,不是尚未展开的 var(...) 引用。

检查覆盖层级和交付一致性

  1. 在 Chrome 按 F12 打开开发者工具,进入 Elements → Styles,选中按钮,确认 background 来自 var(--color-primary),而不是写死的十六进制色值。
  2. 进入 Computed,检查按钮的最终 background-color:浅色为 rgb(37, 99, 235),深色为 rgb(147, 197, 253);页面 background-color 同步切换。
  3. 检查根元素 html 的 data-theme:点击前是 light,点击后是 dark。若深色不生效,先看属性是否错误地加在 body 上,因为本例选择器匹配的是 :root。
  4. 回到设计变量表逐项核对单位和取值:16px 正文字号、8px/12px 间距、8px 圆角在两个主题下均不应改变。

若某项样式突然消失,先检查 var() 中的名称是否拼错;无回退值的无效变量引用会让该属性声明失效,不要靠随意添加回退色掩盖错误。

交付给开发时,至少同时提供设计变量名、基础 Token、语义 Token、明暗模式对应值这四列映射;验收以浏览器实际计算样式为准,不能只核对 CSS 中是否出现了变量名。

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

目录与阅读设置

阅读设置

17

记录一个想法

把设计变量映射成CSS Token

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

登录哪都通