UI 视觉设计 / 系统课时

在组件样式中消费语义变量

在组件样式中消费语义变量

把 Design Token 编译成 CSS 自定义属性后,组件应通过表示用途的语义变量取色,而不是直接依赖基础色阶。本篇用一个可在浏览器打开的双主题按钮示例,说明全局变量、组件局部变量、var() 回退值如何协作,并验证最终样式来自哪里。

学习目标

  • 在组件 CSS 中消费语义 Token,避免直接绑定基础色阶。
  • 区分根级默认值、主题容器覆盖与组件局部覆盖。
  • 使用 var() 的回退参数,并在浏览器中验证计算后的颜色。

为什么组件不应引用基础色阶

基础变量如 --palette-blue-600 描述具体色阶,语义变量如 --color-action-primary 描述“主要操作背景”的用途。如果按钮直接使用 var(--palette-blue-600),品牌改成绿色时,业务组件就要改引用;使用 var(--color-action-primary),只需在主题层重新映射语义值。

建议把消费边界定为:Token 源文件或编译器负责基础值到语义值的映射;业务组件只认识语义变量;少数组件特有的差异再由 --button-bg 等局部变量承接。示例中的 CSS 变量名是一套约定,实际接入时必须与编译产物保持一致。

全局变量、主题覆盖与局部变量

默认语义值定义在 :root;暗色主题容器 .theme-dark 覆盖同名语义变量。普通、未通过 @property 特殊注册的 CSS 自定义属性会继承,因此容器内的按钮可以自动读取所在主题的值。

组件再提供自己的变量入口:主按钮未声明 --button-bg,便回退到全局语义变量;次按钮声明 --button-bg,优先使用自己的组件值。变体不必重复整套 background-color、color 等属性。

根级语义变量、主题覆盖与按钮局部变量的消费路径

运行双主题按钮示例

把下面的完整内容保存为 index.html,双击用现代浏览器打开即可。为保证示例独立运行,语义变量直接写在 style 内;实际项目通常由构建产物 tokens.css 提供这些根级与主题变量,组件文件只保留消费规则。

html
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <title>语义 Token 按钮示例</title>
  <style>
    :root {
      --color-action-primary: #155eef;
      --color-text-on-action: #ffffff;
      --color-surface-default: #ffffff;
      --color-text-primary: #1e293b;
      --color-border-default: #cbd5e1;
    }

    /* 主题只覆盖语义变量,组件规则保持不变 */
    .theme-dark {
      --color-action-primary: #9bbcff;
      --color-text-on-action: #0b1b36;
      --color-surface-default: #1e293b;
      --color-text-primary: #f8fafc;
      --color-border-default: #94a3b8;
    }

    .demo {
      display: flex;
      gap: 12px;
      padding: 16px;
      background-color: var(--color-surface-default, #fff);
    }

    /* 先取组件局部变量;没有时读取语义变量 */
    .button {
      padding: 10px 16px;
      border: 1px solid transparent;
      border-radius: 8px;
      background-color: var(--button-bg, var(--color-action-primary, #155eef));
      color: var(--button-fg, var(--color-text-on-action, #fff));
      cursor: pointer;
    }

    /* 变体只重映射局部变量,不复制主按钮样式 */
    .button--secondary {
      --button-bg: var(--color-surface-default, #fff);
      --button-fg: var(--color-text-primary, #1e293b);
      border-color: var(--color-border-default, #cbd5e1);
    }
  </style>
</head>
<body>
  <div class="demo">
    <button class="button" type="button">主操作</button>
    <button class="button button--secondary" type="button">次操作</button>
  </div>
  <div class="demo theme-dark">
    <button class="button" type="button">主操作</button>
    <button class="button button--secondary" type="button">次操作</button>
  </div>
</body>
</html>

预期结果:页面出现上下两组按钮。上组为浅色主题,主按钮背景是 #155eef,次按钮为白底深字;下组为深色主题,主按钮背景是 #9bbcff,次按钮为深色底浅字。两组使用相同的 .button 规则,没有按品牌或模式复制组件样式。

回退值能处理什么,不能处理什么

var(--button-bg, var(--color-action-primary, #155eef)) 按顺序取值:先看按钮元素是否有可用的 --button-bg,缺失时查找所在作用域的 --color-action-primary,两者都不可用才使用 #155eef。回退参数适用于可选的组件覆盖值,以及防止样式因变量缺失而失效。

回退值不能修复类型错误。例如将 --color-action-primary 定义为 12px,变量虽然存在,但 12px 不是合法的 background-color;浏览器不会因此采用 #155eef,背景声明会在计算值阶段无效。也不要让回退值长期掩盖漏发的 Token 文件:发布构建应校验所需语义变量是否存在、类型是否正确。细节参见 MDN:CSS var()。

在浏览器中验收覆盖顺序

  1. 在 Chrome 或 Edge 按 F12,进入 Elements → Computed,选中上组主按钮;background-color 应为 rgb(21, 94, 239),即 #155eef。
  2. 选中下组主按钮,背景应为 rgb(155, 188, 255),即 #9bbcff。在 Styles 面板向上检查 .theme-dark 的 --color-action-primary,确认它覆盖了根级定义。
  3. 选中下组次按钮,在 Styles 中查找 .button--secondary 的 --button-bg;它应引用 --color-surface-default,最终背景为 #1e293b,而不是主操作蓝色。
  4. 把 :root 中 --color-action-primary 改为 #0f766e 并刷新。只有上组主按钮改变;下组主按钮仍使用暗色主题覆盖值,两组次按钮不受影响。

如果颜色未变化,先查组件是否写死了 background-color,再核对 CSS 变量名拼写和主题类是否挂在组件祖先节点上。组件长期只依赖语义名称,后续更换品牌或模式就可以留在 Token 层完成。

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

目录与阅读设置

阅读设置

17

记录一个想法

在组件样式中消费语义变量

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

登录哪都通