UI 视觉设计 / 系统课时
对引用与命名执行自动校验
对引用与命名执行自动校验
源 Token 文件通过 JSON 语法检查,并不代表能够安全发布:路径可能在 CSS 命名转换后重叠,别名可能指向不存在的 Token,也可能形成引用环。这里用 Node.js 编写一个无依赖校验器,让构建在发现错误时退出并报告对应路径。
学习目标
- 区分 DTCG 名称限制与 CSS 导出命名冲突。
- 检查类型、缺失引用和循环依赖,并定位出错路径。
- 将同一校验命令放入本地检查与拉取请求流程。
确定构建前必须拦截的错误
按 DTCG 2025.10 规范,普通组名与 Token 名不能以 $ 开头,也不能包含 {、}、.;Token 路径区分大小写。然而,导出 CSS 时常把 brandPrimary 和 brand-primary 都转换为 brand-primary,所以还需检查输出名是否唯一。
| 校验项 | 触发条件 | 报错应携带的信息 |
|---|---|---|
| 命名 | 两条源路径变成同一个 CSS 变量名 | 两个源路径及输出名 |
| 类型 | 无法推导有效类型,或类型不在 DTCG 类型集合内 | Token 路径和类型值 |
| 引用 | {group.token} 指向不存在的 Token |
当前路径和目标路径 |
| 环路 | A 引用 B,B 又间接或直接引用 A | 完整循环路径 |
示例校验器面向单个 JSON 文件中的完整 Token 别名 {path.to.token},支持组级 $type 继承与别名推断类型;它是发布前的结构预检查,不代替完整的 DTCG Schema 与值格式校验。$ref、$extends、复合值内部引用,需要在采用这些特性时补充相应解析器。
准备能重现问题的源文件
在项目根目录新建 tokens.json。文件包含六个 Token,故意设置一个输出名冲突、一处非法类型、一处缺失引用和一个双节点环。length 不是合法 DTCG 类型;8 像素应使用 $type: dimension,单位写在 $value.unit。
{
"color": {
"brandPrimary": {
"$type": "color",
"$value": { "colorSpace": "srgb", "components": [0, 0.4, 0.8], "hex": "#0066cc" }
},
"brand-primary": {
"$type": "color",
"$value": { "colorSpace": "srgb", "components": [0, 0.6, 0.4], "hex": "#009966" }
}
},
"space": {
"bad": { "$type": "length", "$value": { "value": 8, "unit": "px" } }
},
"semantic": {
"missing": { "$type": "color", "$value": "{color.unknown}" }
},
"alias": {
"a": { "$type": "color", "$value": "{alias.b}" },
"b": { "$type": "color", "$value": "{alias.a}" }
}
}将 Token 路径整理成引用图
校验分两趟执行:先递归收集所有带 $value 的 Token,记录源路径、导出名和可继承类型;再沿别名边进行深度优先搜索。搜索状态为“未访问、访问中、已完成”,若再次遇到访问中节点,就能报告实际环路,而不是仅提示解析失败。

将下面代码保存为 validate-tokens.mjs,在 Node.js 20 或 22 中可直接运行。这里的 cssName 必须与项目实际发布脚本采用的命名转换一致,否则可能漏检或误报。
import { readFileSync } from 'node:fs';
const source = JSON.parse(readFileSync(process.argv[2] ?? 'tokens.json', 'utf8'));
const knownTypes = new Set([
'color', 'dimension', 'fontFamily', 'fontWeight', 'duration',
'cubicBezier', 'number', 'strokeStyle', 'border', 'transition',
'shadow', 'gradient', 'typography'
]);
const tokens = new Map();
const exportedNames = new Map();
const errors = [];
const metadata = new Set(['$schema', '$type', '$description', '$extensions', '$deprecated', '$extends']);
function cssName(parts) {
const names = parts.at(-1) === '$root' ? parts.slice(0, -1) : parts;
return '--' + names.map((name) => name
.replace(/([a-z0-9])([A-Z])/g, '$1-$2')
.replace(/_/g, '-').toLowerCase()).join('-');
}
function walk(group, path = [], inheritedType) {
for (const [name, value] of Object.entries(group)) {
if (name.startsWith('$') && name !== '$root') {
if (!metadata.has(name)) errors.push(`非法字段: ${[...path, name].join('.')}`);
continue; // 只跳过已知元数据,不吞掉拼错的 $ 字段
}
const parts = [...path, name];
const id = parts.join('.');
if (/[{}.]/.test(name)) errors.push(`非法命名: ${id}`);
if (!value || typeof value !== 'object' || Array.isArray(value)) {
errors.push(`非法结构: ${id}`);
continue;
}
if (Object.hasOwn(value, '$value')) {
const css = cssName(parts);
if (exportedNames.has(css)) {
errors.push(`命名冲突: ${exportedNames.get(css)} / ${id} -> ${css}`);
} else exportedNames.set(css, id);
tokens.set(id, { value: value.$value, explicit: value.$type, inherited: inheritedType });
} else walk(value, parts, value.$type ?? inheritedType);
}
}
walk(source, [], source.$type);
const status = new Map();
const types = new Map();
const chain = [];
function check(id) {
if (status.get(id) === 1) {
errors.push(`循环依赖: ${[...chain.slice(chain.indexOf(id)), id].join(' -> ')}`);
return;
}
if (status.get(id) === 2) return types.get(id);
status.set(id, 1);
chain.push(id);
const node = tokens.get(id);
const match = typeof node.value === 'string' ? /^\{([^{}]+)\}$/.exec(node.value) : null;
let referencedType;
if (match) {
const target = match[1];
if (!tokens.has(target)) errors.push(`缺失引用: ${id} -> ${target}`);
else referencedType = check(target); // 深度优先搜索引用图
}
const type = node.explicit ?? referencedType ?? node.inherited;
if (!knownTypes.has(type)) errors.push(`非法类型: ${id} -> ${String(type)}`);
if (node.explicit && referencedType && node.explicit !== referencedType) {
errors.push(`类型不匹配: ${id} -> ${match[1]}`);
}
chain.pop();
status.set(id, 2);
types.set(id, type);
return type;
}
for (const id of tokens.keys()) check(id);
for (const error of errors.sort()) console.error(error);
if (errors.length) {
console.error(`校验失败: ${errors.length} 项`);
process.exitCode = 1; // CI 在非零退出码时失败
} else console.log(`校验通过: ${tokens.size} 个 Token`);预期结果:对上面的故障源文件执行此脚本时,会报告四类错误并返回退出码 1;只有错误列表为空时才打印通过信息,具体终端输出见下节。
运行校验并逐项修正
在两个文件所在目录执行以下命令;预期先出现四个明确诊断,随后返回非零退出码。错误路径应能直接定位到需要修改的 JSON 节点。
node validate-tokens.mjs tokens.json预期输出(错误信息写入标准错误流,命令退出码为 1):
命名冲突: color.brandPrimary / color.brand-primary -> --color-brand-primary
循环依赖: alias.a -> alias.b -> alias.a
缺失引用: semantic.missing -> color.unknown
非法类型: space.bad -> length
校验失败: 4 项修复时按实际路径修改:将 color.brand-primary 改名为 color.brandSecondary;将 space.bad.$type 改为 dimension;将 semantic.missing.$value 改为 {color.brandPrimary};将 alias.a.$value 改为 {color.brandPrimary},保留 alias.b 引用 alias.a。再次运行相同命令,预期得到 校验通过: 6 个 Token,进程退出码为 0。
让拉取请求在校验失败时停止
在 GitHub 仓库中新建 .github/workflows/token-lint.yml,把 Token 校验放在构建或发布之前。以下配置在推送 main 和打开或更新拉取请求时执行;只要校验进程返回 1,作业就会失败。
name: Token Lint
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
jobs:
tokens:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '22'
- run: node validate-tokens.mjs tokens.json预期结果:包含上述四种错误的提交在 GitHub Actions 中显示 Token Lint 失败;修正后检查通过。若仓库启用了分支保护,将该作业设为必需状态检查,才能真正阻止带错 Token 的拉取请求合并。新增类型或修改 CSS 命名转换时,应同步维护 knownTypes 与 cssName,并保留四类反例作为回归测试。