UI 视觉设计 / 系统课时

按使用场景命名语义颜色

按使用场景命名语义颜色

本篇把散落在文字、页面背景、边框、按钮和错误提示中的颜色整理为可复用的语义 Token。完成后,组件只引用用途名;即使品牌主色从蓝色改为青绿色,也无需逐个修改按钮的样式引用。

学习目标

  • 根据界面职责区分基础色与语义色,制定可复用的命名规则。
  • 用 DTCG 别名把文字、背景、边框、交互和反馈颜色映射到基础色。
  • 验证替换基础色后,语义引用路径和无关组件保持稳定。

先按职责分组,再决定颜色

以订单工作台为例,正文、页面底色、分隔线、主按钮和表单错误都可能用到蓝灰或红色,但它们的职责不同。基础色可以叫 primitive.brand.600,组件却不应写“使用第 600 阶蓝色”,而应表达“使用主操作默认背景色”。

使用场景 推荐语义路径 用途
正文 semantic.text.primary 主要可读文字
次级文字 semantic.text.secondary 说明、辅助信息
按钮上的文字 semantic.text.on-action 与主操作底色搭配的文字
页面底色 semantic.background.canvas 页面画布
弱边界 semantic.border.subtle 卡片、列表分隔线
主操作 semantic.action.primary.default 主按钮默认背景
主操作悬停 semantic.action.primary.hover 主按钮悬停背景
错误反馈 semantic.feedback.error.text 校验错误文字

约定从职责类别 → 语义用途 → 可选交互状态逐级收窄。状态词统一用 default、hover、pressed、disabled、focus 等项目词表,未分状态的普通文字无需硬加 default。路径中的点表示 Group 层级,而非把带点字符串直接作为 DTCG Token 名称。

用别名连接语义色与基础色

下面的 tokens.json 采用 DTCG 2025.10 的 $type、$value 和 {路径} 别名;颜色用 sRGB 组件表达,hex 供人工核对。同一个基础值可以被多个用途引用,但每个用途保留自己的语义名。

json
{
  "primitive": {
    "neutral": {
      "$type": "color",
      "0": { "$value": { "colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff" } },
      "200": { "$value": { "colorSpace": "srgb", "components": [0.898039, 0.905882, 0.921569], "hex": "#e5e7eb" } },
      "600": { "$value": { "colorSpace": "srgb", "components": [0.294118, 0.333333, 0.388235], "hex": "#4b5563" } },
      "900": { "$value": { "colorSpace": "srgb", "components": [0.066667, 0.094118, 0.152941], "hex": "#111827" } }
    },
    "brand": {
      "$type": "color",
      "600": { "$value": { "colorSpace": "srgb", "components": [0.145098, 0.388235, 0.921569], "hex": "#2563eb" } },
      "700": { "$value": { "colorSpace": "srgb", "components": [0.113725, 0.305882, 0.847059], "hex": "#1d4ed8" } }
    },
    "red": {
      "$type": "color",
      "600": { "$value": { "colorSpace": "srgb", "components": [0.862745, 0.14902, 0.14902], "hex": "#dc2626" } }
    }
  },
  "semantic": {
    "$type": "color",
    "text": {
      "primary": { "$value": "{primitive.neutral.900}" },
      "secondary": { "$value": "{primitive.neutral.600}" },
      "on-action": { "$value": "{primitive.neutral.0}" }
    },
    "background": { "canvas": { "$value": "{primitive.neutral.0}" } },
    "border": { "subtle": { "$value": "{primitive.neutral.200}" } },
    "action": {
      "primary": {
        "default": { "$value": "{primitive.brand.600}" },
        "hover": { "$value": "{primitive.brand.700}" }
      }
    },
    "feedback": { "error": { "text": { "$value": "{primitive.red.600}" } } }
  }
}

$type 在 Group 上声明后由子 Token 继承;别名引用的是完整目标 Token 的值,不能写成只指向 hex 字段的 {primitive.brand.600.hex}。如果希望一个按钮与链接共用品牌色,也应分别声明 action.primary.default 和适当的链接语义名,避免把“按钮背景”误当“任何蓝色内容”。

基础色通过语义用途映射到界面组件,换色时引用路径不变

让组件消费语义路径

DTCG 定义 Token 数据与引用,不规定 CSS 变量必须叫什么。若团队的构建工具约定把 semantic.action.primary.default 转成 --semantic-action-primary-default,组件就能按下列方式使用。以下是片段示例,依赖构建产物已注入对应的 CSS 自定义属性。

css
.order-submit {
  color: var(--semantic-text-on-action);
  background-color: var(--semantic-action-primary-default);
}

.order-submit:hover {
  background-color: var(--semantic-action-primary-hover);
}

无论后续映射蓝色还是青绿色,.order-submit 的三个变量引用都无需改名。不要在组件中直接写 #2563eb,也不要把 primitive.brand.600 转成组件直接消费的变量。

用替换测试检查引用稳定性

把上面的 JSON 保存为 tokens.json,在同一目录新建 check.mjs。以下代码可在 Node.js 20 及以上运行:沿点分隔路径找到 Token,并逐层解析别名。它专门验证本例所用的整项别名,不是完整的 DTCG 校验器。

js
import { readFileSync } from "node:fs";

const tokens = JSON.parse(readFileSync("tokens.json", "utf8"));

function resolve(path, visited = new Set()) {
  // 禁止别名互相指向形成循环
  if (visited.has(path)) throw new Error(`循环引用: ${path}`);
  visited.add(path);

  const token = path.split(".").reduce((node, key) => node?.[key], tokens);
  if (!token || !("$value" in token)) throw new Error(`不存在的 Token: ${path}`);
  const value = token.$value;

  // 花括号别名必须指向完整 Token
  if (typeof value === "string" && /^\{[^{}]+\}$/.test(value)) {
    return resolve(value.slice(1, -1), visited);
  }
  return value;
}

console.log(resolve("semantic.action.primary.default").hex);
console.log(resolve("semantic.text.primary").hex);

执行 node check.mjs,预期输出:

text
#2563eb
#111827

现在替换整套品牌色阶:将 primitive.brand.600 的 components 改为 [0.058824, 0.462745, 0.431373]、hex 改为 #0f766e;将 primitive.brand.700 的 components 改为 [0.066667, 0.368627, 0.34902]、hex 改为 #115e59。再次执行相同命令,预期输出:

text
#0f766e
#111827

这证明主操作色值随基础色更新,正文色未受影响,两个 semantic 路径始终不变。实际工程还应检查主题模式下的前景/背景对比度、hover 与 focus 状态,以及构建产物的变量名是否稳定;本例没有覆盖这些视觉与工具链检查。

避免把色值名伪装成语义名

常见错误是把 semantic.blue.600、semantic.buttonBlue 或 semantic.redText 作为公共变量。前两者泄漏外观,后一者没有说明错误、强调还是警告;当品牌改色或暗色主题上线时,名称就可能与真实用途冲突。

审核新 Token 时,问两个可验证的问题:去掉颜色值还能准确说出职责吗? 更换浅色、深色或品牌主题时,这个名字还成立吗? 若答案为否,优先改为 text.primary、border.subtle、feedback.error.text 等角色名。同一色值服务不同职责时允许两个别名;只有确实存在组件独有规则时,才新增更窄的组件级 Token,不要为每张卡片复制一套全新的语义色。

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

目录与阅读设置

阅读设置

17

记录一个想法

按使用场景命名语义颜色

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

登录哪都通