UI 视觉设计 / 系统课时
按用途组织 Group 与文件目录
按用途组织 Group 与文件目录
同一套颜色 Token 如果只按页面堆在一个文件里,修改品牌色时很难判断会影响哪些组件。本篇以按钮为例,把基础色、语义色、组件色分别放进 DTCG 文件,并确保拆分后仍能沿完整路径解析引用。
学习目标
- 区分 Group 的层级路径与物理文件目录。
- 制定可长期使用的 Token 命名与三层拆分规则。
- 编写三份 DTCG JSON,并验证跨文件别名链。
按职责确定命名和边界
DTCG 2025.10 中,没有 $value 的对象是 Group;含 $value 的对象是 Token。Group 可以嵌套,也能通过 $type 为后代设置默认类型,但规范不会根据 color、button 这类名字自动判断含义。
采用小写英文、短横线和固定层级,避免跨平台导出时重命名。此项目规定 primitive、semantic、component 三个顶层 Group:
| 层级 | 负责什么 | 完整 Token 路径 |
|---|---|---|
primitive |
不带用途的原始色阶 | primitive.color.brand.600 |
semantic |
跨组件共享的用途与状态 | semantic.color.action.primary |
component |
具体组件的插槽与变体 | component.button.primary.background |
DTCG 禁止 Group 与 Token 的名称以 $ 开头,也禁止名称中包含 .、{、}。例如不要创建单个键 brand.600,应拆为 brand Group 和 600 Token。命名虽区分大小写,团队仍应禁止仅大小写不同的重名项。
让文件与 Group 各司其职
建立以下三个文件。目录负责代码仓库中的归属和评审;文件内容的 Group 才决定 DTCG 引用路径。
| 文件路径 | 文件中的顶层 Group | 变更归属 |
|---|---|---|
tokens/primitives/color.tokens.json |
primitive |
品牌色与中性色 |
tokens/semantic/color.tokens.json |
semantic |
交互、文字等语义 |
tokens/components/button.tokens.json |
component |
按钮专属映射 |

.tokens.json 是规范推荐的文件扩展名。拆成多个文件不代表引用会自动跨文件生效:发布管线应先加载三份文件,合成统一 Token 树,再解析别名;不同工具如何组合文件需要单独配置。
编写三份可合并的 JSON
先在 tokens/primitives/color.tokens.json 定义原始颜色。color Group 的 $type 会传给子 Token;DTCG 2025.10 的颜色值使用 colorSpace 与 components,这里的 sRGB 分量取值为 0~1。
{
"primitive": {
"color": {
"$type": "color",
"brand": {
"600": {
"$value": {
"colorSpace": "srgb",
"components": [0, 0.4, 0.8],
"hex": "#0066cc"
}
}
},
"neutral": {
"0": {
"$value": {
"colorSpace": "srgb",
"components": [1, 1, 1],
"hex": "#ffffff"
}
}
}
}
}
}在 tokens/semantic/color.tokens.json 只表达用途,不再复制十六进制色值。{primitive.color.brand.600} 指向合并后根节点下的完整 Token 路径。
{
"semantic": {
"color": {
"$type": "color",
"action": {
"primary": {
"$value": "{primitive.color.brand.600}"
}
},
"text": {
"on-primary": {
"$value": "{primitive.color.neutral.0}"
}
}
}
}
}最后在 tokens/components/button.tokens.json 把语义色映射到按钮的背景与文字。组件不直接依赖 primitive,以后调整主题只需要修改语义映射。
{
"component": {
"button": {
"primary": {
"background": {
"$value": "{semantic.color.action.primary}"
},
"text": {
"$value": "{semantic.color.text.on-primary}"
}
}
}
}
}这些是三份完整 JSON 文件,不是把三个顶层对象原样拼接成一个文本文件。别名 Token 的类型可以从目标 Token 解析得到;但解析器必须能访问引用的目标文件。
合并并检查引用链
在项目根目录创建 scripts/check-tokens.mjs。下面的 Node.js 20+ 示例只使用内置模块:合并不同顶层 Group,并检查此案例中的引用缺失和循环;它不是完整的 DTCG 规范校验器。
import { readFileSync } from "node:fs";
const files = [
"tokens/primitives/color.tokens.json",
"tokens/semantic/color.tokens.json",
"tokens/components/button.tokens.json"
];
const root = {};
// 文件名不参与 Token 路径;同名顶层 Group 不能被静默覆盖
for (const file of files) {
const data = JSON.parse(readFileSync(file, "utf8"));
for (const [name, group] of Object.entries(data)) {
if (Object.hasOwn(root, name)) throw new Error(`重复根 Group:${name}`);
root[name] = group;
}
}
function resolve(path, seen = new Set()) {
if (seen.has(path)) throw new Error(`循环引用:${path}`);
const token = path.split(".").reduce((node, key) => node?.[key], root);
if (!token || !Object.hasOwn(token, "$value")) {
throw new Error(`引用缺失:${path}`);
}
const value = token.$value;
// 本例只解析引用整个 Token 的大括号别名
if (typeof value === "string" && value.startsWith("{") && value.endsWith("}")) {
return resolve(value.slice(1, -1), new Set([...seen, path]));
}
return value;
}
for (const path of [
"component.button.primary.background",
"component.button.primary.text"
]) {
console.log(`${path} = ${resolve(path).hex}`);
}保存三个文件与脚本后,在项目根目录执行:
node scripts/check-tokens.mjs预期输出:
component.button.primary.background = #0066cc
component.button.primary.text = #ffffff若把语义文件的 brand.600 错写成 brand.500,脚本应抛出 引用缺失:primitive.color.brand.500,而不是悄悄用空值发布。正式构建还应增加 DTCG 类型、颜色分量和命名合法性校验。
用失败案例审核拆分质量
- 目录名冒充 Group:文件放在
semantic/中,却只写顶层color,引用就不是semantic.color...。修复方法是在 JSON 内显式保留semantic。 - 组件绕过语义层:按钮背景直接引用
{primitive.color.brand.600}虽然可能合法,却会让品牌调整波及组件文件。改为引用{semantic.color.action.primary}。 - Token 与 Group 混为一体:一个对象已经含
$value,就不能再往其中加入hover、pressed子 Token。把它们改为同一 Group 下的兄弟 Token。 - 随意改路径:把
action.primary改成interactive.default属于破坏性重命名;先全仓查找旧引用,完成迁移后再删除旧路径。
验收时应同时满足三件事:每个 Token 的完整路径唯一,组件引用只穿过约定的语义层,合并后全部别名可解析。规范原文可对照 DTCG Format 2025.10;文件拆分策略属于本项目约定,不是 DTCG 强制规定的目录结构。