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 供人工核对。同一个基础值可以被多个用途引用,但每个用途保留自己的语义名。
{
"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 自定义属性。
.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 校验器。
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,预期输出:
#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。再次执行相同命令,预期输出:
#0f766e
#111827这证明主操作色值随基础色更新,正文色未受影响,两个 semantic 路径始终不变。实际工程还应检查主题模式下的前景/背景对比度、hover 与 focus 状态,以及构建产物的变量名是否稳定;本例没有覆盖这些视觉与工具链检查。
避免把色值名伪装成语义名
常见错误是把 semantic.blue.600、semantic.buttonBlue 或 semantic.redText 作为公共变量。前两者泄漏外观,后一者没有说明错误、强调还是警告;当品牌改色或暗色主题上线时,名称就可能与真实用途冲突。
审核新 Token 时,问两个可验证的问题:去掉颜色值还能准确说出职责吗? 更换浅色、深色或品牌主题时,这个名字还成立吗? 若答案为否,优先改为 text.primary、border.subtle、feedback.error.text 等角色名。同一色值服务不同职责时允许两个别名;只有确实存在组件独有规则时,才新增更窄的组件级 Token,不要为每张卡片复制一套全新的语义色。