DESIGN.md broken-ref 规则全解：token 引用如何解析与报错

DESIGN.md broken-ref 规则全解token 引用如何解析与报错【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.mdDESIGN.md 是一款面向 AI 编码代理的设计系统描述规范它用 YAML front matter 存放机器可读的 design tokens再用 Markdown 文字解释为什么。在 11 条 lint 规则里broken-ref是最重要的一条——它专门捕获指向了不存在的 token的断链引用broken reference一旦组件里写的{colors.primary}之类的引用解析不到任何已定义的 tokenlint 就会以error级别报错让代理不会再猜出一个错误的颜色值。本文带你从引用格式、解析流程到报错输出完整看懂broken-ref是怎么工作的。broken-ref 规则在 DESIGN.md 中做什么DESIGN.md 把 token 分为「原始 token」colors/typography/rounded/spacing和「组件」components。组件并不直接写死颜色值而是用引用指向某个原始 token例如components: button-primary: backgroundColor: {colors.tertiary} textColor: {colors.on-tertiary} rounded: {rounded.sm}这样一旦改色所有引用它的组件自动跟随。但引用路径写错了怎么办broken-ref就是为此而生的守门员。它的规则描述是Broken/circular references and unknown component sub-tokens.即它同时检查两类问题引用断裂/循环报错以及未知组件子 token告警。规则定义见 broken-ref.tsexport const brokenRefRule: RuleDescriptor { name: broken-ref, severity: error, description: Broken/circular references and unknown component sub-tokens., run: brokenRef, };severity: error意味着只要出现断链lint命令就会以非零退出码结束方便接入 CI。token 引用的格式与解析流程引用长什么样引用统一写作{section.token-name}用一对花括号包裹以点号分隔的路径。判断函数isTokenReference用正则^\{[a-zA-Z0-9._-]\}$来识别合法引用见 spec.ts。也就是说{colors.primary}、{spacing.md}合法而{ colors.primary }带空格或裸字符串colors.primary都不算引用。分三阶段解析解析的核心在 model/handler.ts 的ModelHandler它分三个阶段阶段做什么对引用的意义一、构建 symbol table逐个解析colors/typography/rounded/spacing把值登记进一张扁平的符号表遇到引用字符串时先记下原文如symbolTable.set(colors.x, {colors.primary})留到后面再解析二、跟随引用对符号表里每个仍是引用字符串的项resolveReference沿着路径一层层追下去支持链式引用用visited集合检测循环、用MAX_REFERENCE_DEPTH限制深度三、构建 components遍历每个组件属性对引用值调用resolveReference解析成功 → 存解析结果失败 → 推进unresolvedRefs随后由 broken-ref 规则报错resolveReference的关键逻辑在 handler.ts它带visited集合与depth计数器——function resolveReference(symbolTable, path, visited, depth 0) { if (depth MAX_REFERENCE_DEPTH) return null; // 深度超限 → 视为解析失败 if (visited.has(path)) return null; // 检测到循环 → 返回 null visited.add(path); const value symbolTable.get(path); if (value undefined) return null; // 路径不存在 → 返回 null if (typeof value string isTokenReference(value)) { return resolveReference(symbolTable, value.slice(1, -1), visited, depth 1); // 继续追链 } return value; }null是统一的解析失败信号不管是路径打错、token 被删、还是循环/超深最终都归结为解析不到。组件属性里引用解析失败时发生了什么在第三阶段组件属性遇到引用时的处理见 handler.ts} else if (isTokenReference(rawValue)) { const refPath rawValue.slice(1, -1); const resolved resolveReference(symbolTable, refPath, new Set()); if (resolved ! null) { properties.set(propName, resolved); // 成功存解析结果 } else { unresolvedRefs.push(rawValue); // 失败记入未解析列表 properties.set(propName, rawValue); } }注意失败时不会抛异常而是把原始引用字符串推进unresolvedRefs定义见 model/spec.ts。这个列表随后被broken-ref规则逐条消费。broken-ref 的报错两种发现findingsbrokenRef函数遍历每个组件输出两类结果见 broken-ref.ts1. 断链 / 循环引用 → error核心对unresolvedRefs里的每一项findings.push({ path: components.${compName}, message: Reference ${ref} does not resolve to any defined token., });路径components.组件名消息Reference {colors.nonexistent} does not resolve to any defined token.级别继承规则默认的error这是唯一会让lint退出码变 1 的情况也是本文重点。2. 未知组件子 token → warning顺带检查组件的属性名是否属于合法的子 token 集合。合法子 token共 8 个定义在 spec-config.yamlbackgroundColor·textColor·typography·rounded·padding·size·height·width如果写了borderColor这种不认识的属性名findings.push({ severity: warning, path: components.${compName}.${propName}, message: ${propName} is not a recognized component sub-token. Valid sub-tokens: ..., });注意即便属性名不合法它的引用值仍会走解析流程——所以未知子 tokenwarning和断链引用error可以同时出现在同一个组件上。如何用 lint 触发 broken-ref 并看懂输出一条命令跑所有命令都接受文件路径或-stdin默认输出 JSONnpx google/design.md lint DESIGN.md如果存在断链引用summary.errors会大于 0进程以退出码1结束否则为0。报错 JSON 长这样对应引用{colors.nonexistent}解析失败{ findings: [ { severity: error, rule: broken-ref, path: components.button-primary, message: Reference {colors.nonexistent} does not resolve to any defined token. } ], summary: { errors: 1, warnings: 0, infos: 0 } }不想装 CLI用编程接口linter 也作为库提供见 README 的 Programmatic API 部分import { lint } from google/design.md/linter; const report lint(markdownString); // report.findings 里按 rule broken-ref 过滤即可拿到断链 console.log(report.findings); console.log(report.summary); // { errors, warnings, info }常见报错场景与修复清单场景报错信息根因修复路径拼错Reference {colors.primry} does not resolve...token 名打错把引用改成已定义的 token 名token 被删/改名Reference {colors.tertiary} does not resolve...源 token 不存在补回定义或改引用指向现存 token循环引用同上A → B → A成环断开链条让链尾落在一个具体值上引用链过深同上超过max_reference_depth当前 10 层缩短链式引用顶层段写错同上写成{colour.primary}段名须为colors/typography/rounded/spacing未知子 tokenborderColor is not a recognized component sub-token属性名不在合法集合改用 8 个合法子 token 之一自检口诀每个{...}引用的顶层段名是否正确colors不是colour引用的完整点路径是否与 YAML 里定义的 token 逐字一致区分大小写是否存在两个 token 互相指向形成的环。把这三点过一遍broken-ref的 error 基本就能清零——这也是让diff对比两版设计系统时无回归的基础。相关模块路径规则实现broken-ref.ts规则测试用例broken-ref.test.ts同目录解析引擎model/handler.ts引用识别与符号表类型model/spec.ts子 token 与深度限制配置spec-config.yaml完整规范文档docs/spec.md项目说明README.md小结broken-ref用一套符号表 链式解析 循环/深度保护的机制把 DESIGN.md 里每个{path.to.token}引用都追到底解析得到就存值追不到就推进unresolvedRefs并最终以error报出Reference {…} does not resolve to any defined token.。理解它你就能在第一时间发现断链与循环引用让 AI 代理拿到一份引用永远落得实的设计系统。【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考