UI 视觉设计 / 系统课时

制定颜色 Token 的命名规则

制定颜色 Token 的命名规则

颜色 Token 进入设计文件和前端工程后,随意改名会导致组件引用失效、主题切换异常和交付信息不一致。本课以订单工作台的主按钮为例,制定基础色、语义色与组件色的命名层级,并明确哪些颜色可以覆盖、哪些名称必须保持稳定。

学习目标

  • 区分基础色、语义色和组件色三层 Token 的命名职责。
  • 制定可扩展的命名格式,避免把颜色外观与业务含义混在一起。
  • 使用实际 CSS 变量验证主题覆盖,并检查设计令牌是否正确映射到组件。

建立三层颜色命名结构

一套颜色系统通常需要回答三个不同的问题:实际使用什么颜色、这个颜色承担什么职责、哪个组件使用它。将三个问题拆成独立层级,可以避免按钮直接绑定某个品牌蓝色。

推荐使用以下结构,设计工具中的 Token 名称采用点号分层,导出 CSS 时统一转换为短横线分隔。

层级 命名格式 示例 负责内容
基础色 color.palette.{色系}.{色阶} color.palette.blue.600 具体颜色值,如 #2563EB
语义色 color.semantic.{意图}.{角色}.{属性} color.semantic.action.primary.background 交互或信息传达职责
组件色 color.component.{组件}.{变体}.{属性} color.component.button.primary.background 具体组件对语义色的引用

例如,一个浅色订单工作台的主按钮可以建立以下引用:

  1. color.palette.blue.600 保存基础蓝色 #2563EB。
  2. color.semantic.action.primary.background 引用该基础蓝色,表示主要操作的背景。
  3. color.component.button.primary.background 引用主要操作背景,提供给按钮组件使用。

这样,组件不必知道颜色属于哪个色阶,设计师也不必在每个按钮实例上修改十六进制色值。

基础色语义色与组件色的三层引用及主题覆盖关系

固定命名顺序与语义边界

命名时应先确定层级,再写职责,最后写属性。名称描述长期稳定的用途,实际色值则通过主题映射决定。

语义 Token 不应该包含具体色相或明度,因为同一个主要操作在浅色与深色主题中可能采用完全不同的色阶。

不推荐 推荐 原因
color.primaryBlue color.semantic.action.primary.background 避免将品牌蓝固定为语义职责
color.successGreen color.semantic.feedback.success.background 成功表示信息含义,不限定颜色
color.buttonBlue2 color.component.button.primary.background 用组件变体代替临时编号
color.errorTextRed color.semantic.feedback.error.foreground 文本前景角色与具体颜色解耦

对于组件状态,可以在变体与属性之间增加状态段,保持顺序一致。例如:

  • 默认:color.component.button.primary.background
  • 悬停:color.component.button.primary.hover.background
  • 按下:color.component.button.primary.pressed.background
  • 禁用:color.component.button.primary.disabled.background

默认状态可以省略状态段,但团队必须统一这一规则,不要同时存在 default.background 与 background 两套同义 Token。

属性词也需要收敛。建议优先使用 background、foreground、border 和 focus-ring。不要在同一个项目中混用 bg、backgroundColor、fillColor 表示同一种背景职责。

使用 CSS 验证命名与主题覆盖

前端落地时,可以把点号层级转换为 CSS 自定义属性。例如 color.component.button.primary.background 转换为 --color-component-button-primary-background。转换规则应由导出工具统一执行,避免人工产生多个名称版本。

下面是一个可独立运行的 HTML 示例。把内容保存为 tokens-demo.html,使用浏览器打开,即可看到同一个按钮组件在两套主题下引用不同的基础色。

html
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <title>颜色 Token 命名验证</title>
  <style>
    :root {
      /* 基础色:只表达色系和色阶 */
      --color-palette-blue-600: #2563eb;
      --color-palette-blue-200: #bfdbfe;
      --color-palette-neutral-0: #ffffff;
      --color-palette-slate-900: #0f172a;

      /* 语义色:由主题决定具体引用 */
      --color-semantic-action-primary-background: var(--color-palette-blue-600);
      --color-semantic-action-primary-foreground: var(--color-palette-neutral-0);

      /* 组件色:只引用语义职责 */
      --color-component-button-primary-background: var(--color-semantic-action-primary-background);
      --color-component-button-primary-foreground: var(--color-semantic-action-primary-foreground);
    }

    [data-theme="dark"] {
      --color-semantic-action-primary-background: var(--color-palette-blue-200);
      --color-semantic-action-primary-foreground: var(--color-palette-slate-900);
      background: #0f172a;
      color: #ffffff;
    }

    .demo { padding: 16px; margin: 8px 0; }
    .demo button {
      background: var(--color-component-button-primary-background);
      color: var(--color-component-button-primary-foreground);
      padding: 10px 16px;
      border: 0;
      border-radius: 6px;
    }
  </style>
</head>
<body>
  <div class="demo" data-theme="light">浅色主题 <button>提交订单</button></div>
  <div class="demo" data-theme="dark">深色主题 <button>提交订单</button></div>
</body>
</html>

预期结果:页面依次显示浅色与深色两个区域,两个按钮的文案都是“提交订单”。浅色按钮使用 #2563EB 背景与白色文字;深色按钮使用 #BFDBFE 背景与深色文字。

打开浏览器开发者工具,选中两个按钮,在 Computed 样式中检查 background-color:浅色应为 rgb(37, 99, 235),深色应为 rgb(191, 219, 254)。

这里的主题通过 data-theme 属性选择。正式项目可以由应用根节点统一设置该属性,示例中分别设置在两个容器上,仅用于同时演示两种映射。

明确覆盖边界与新增规则

三层 Token 应分别设置修改边界,否则很容易出现组件绕开语义层、直接引用基础色的问题。

层级 允许修改 不推荐的做法
基础色 调整色阶的具体颜色值,增加品牌色系 用业务状态命名基础色
语义色 根据浅色、深色或品牌主题更改基础色引用 为每个主题创建不同语义名称
组件色 在确有组件专属需求时调整语义引用 直接写十六进制色值或覆盖整套基础色

例如,品牌 A 使用蓝色,品牌 B 使用紫色,两者的主按钮仍然引用 color.semantic.action.primary.background。切换品牌只改变该语义 Token 对基础色的引用,不应该增加 button.brandA.blue 和 button.brandB.purple 两组组件名称。

如果需要一个危险操作按钮,应先判断是否已有 color.semantic.action.danger.background。有就复用,没有才新增这个语义角色,而不是建立 color.palette.deleteRed。

新增 Token 时采用以下顺序:

  1. 检查现有 Token 是否已经覆盖相同的视觉职责,优先复用。
  2. 如果职责确实不同,先在语义层增加名称和定义,再建立组件引用。
  3. 为全部受支持主题补齐映射,并验证前景与背景的可读性。
  4. 只有某个组件存在独特视觉契约时,才新增专属组件 Token。

对于多个组件都要使用的成功、警告、错误状态,优先放在语义层;仅属于某种按钮的特殊悬停效果,才考虑在组件层增加对应状态。

检查命名是否可以交付

可以选择订单工作台的主按钮、错误提示和输入框三个组件,逐项检查以下规则:

  • 名称稳定性:浅色、深色和不同品牌主题下,语义 Token 名称保持完全一致。
  • 引用完整性:组件色指向语义色,语义色指向基础色,不存在未定义引用或循环引用。
  • 命名唯一性:每个 Token 名称只对应一个明确职责,不存在 bg 和 background 两套重复名称。
  • 覆盖正确性:切换主题后,按钮、提示和输入框显示新的映射值,而无需修改组件代码。
  • 可访问性:分别检查各主题实际渲染的前景与背景。普通文本通常应达到 WCAG AA 的 4.5:1 对比度要求,大字至少 3:1;不能因为引用结构正确就跳过视觉验证。

交付时,设计文件和前端工程应使用同一份规范名称清单,至少包含 Token 名称、层级、用途、默认引用和各主题覆盖值。重命名已经被组件使用的 Token 时,应同步更新全部引用并检查导出结果,避免出现样式回退或未解析变量。

通过验收的颜色命名体系,应保证修改基础色或主题映射后,组件可以自动更新,同时不会改变成功、错误、主要操作等语义职责。

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

目录与阅读设置

阅读设置

17

记录一个想法

制定颜色 Token 的命名规则

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

登录哪都通