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。

json
{
  "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 必须与项目实际发布脚本采用的命名转换一致,否则可能漏检或误报。

js
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 节点。

bash
node validate-tokens.mjs tokens.json

预期输出(错误信息写入标准错误流,命令退出码为 1):

text
命名冲突: 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,作业就会失败。

yaml
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,并保留四类反例作为回归测试。

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

目录与阅读设置

阅读设置

17

记录一个想法

对引用与命名执行自动校验

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

登录哪都通