Lint 规则

@google/design.md linter 会针对解析后的 DESIGN.md 文件运行规则。每条规则产生的检查结果都有一个固定的严重级别：error（退出码 1）、warning 或 info。

broken-ref

严重级别： error

检测无法解析到 YAML front matter 中任何已定义 token 的 token 引用（{path.to.token}）。同时会标记未知的组件子 token 属性名。

触发条件：

组件引用了不存在的 token 路径（例如未定义 accent 色彩时使用 {colors.accent}）
组件使用了不在可识别集合内的属性名（backgroundColor、textColor、typography、rounded、padding、size、height、width）

检查结果示例：

error  components.button-primary  Reference {colors.accent} does not resolve to any defined token.

解决方式： 在 YAML front matter 中定义缺失的 token，或修正引用路径。对于未知属性，请改用可识别的组件子 token 名称之一。

missing-primary

严重级别： warning

当 front matter 中定义了色彩，但不存在名为 primary 的 token 时发出警告。没有主色，智能体会自动生成一个，从而削弱你对调色板的控制。

触发条件： colors 章节有一个或多个条目，但没有任何一个名为 primary。

检查结果示例：

warning  colors  No 'primary' color defined. The agent will auto-generate key colors, reducing your control over the palette.

解决方式： 在 colors 章节中添加一个 primary 条目。

contrast-ratio

严重级别： warning

检查组件 backgroundColor 与 textColor 配对的 WCAG 对比度。当对比度低于 AA 最低标准 4.5:1 时发出警告。

触发条件： 组件同时定义了 backgroundColor 和 textColor，且解析后的色彩值产生的对比度低于 4.5:1。

检查结果示例：

warning  components.card-dark  textColor (#999999) on backgroundColor (#333333) has contrast ratio 3.48:1, below WCAG AA minimum of 4.5:1.

解决方式： 调整背景色或文字色，使其满足 4.5:1 的最低对比度。

orphaned-tokens

严重级别： warning

找出已定义但从未被任何组件引用的色彩 token。孤立的 token 会增加噪音，也可能意味着设计系统并不完整。

触发条件： colors 章节中存在某个色彩 token，但没有任何组件的属性引用它。仅在至少定义了一个组件时才会触发。

检查结果示例：

warning  colors.tertiary  'tertiary' is defined but never referenced by any component.

解决方式： 在某个组件中引用该 token，或者如果不再需要就删除它。

missing-typography

严重级别： warning

当定义了色彩但不存在排版 token 时发出警告。没有排版 token，智能体会退回到自己选择的字体。

触发条件： colors 章节有条目，但 typography 章节为空。

检查结果示例：

warning  typography  No typography tokens defined. Agents will use default font choices, reducing your control over the design system's typographic identity.

解决方式： 在 front matter 中至少添加一个排版 token（如 body-md）。

section-order

严重级别： warning

当 markdown 章节没有按规范定义的规范顺序出现时发出警告。预期顺序为：Overview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components、Do’s and Don’ts。

触发条件： 某个可识别的章节标题出现在另一个本应排在其前面的可识别章节之前。检查之前会先解析章节别名（例如“Elevation”对应“Elevation & Depth”）。

检查结果示例：

warning  Section 'Components' appears before 'Typography', which is out of order. Expected order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts

解决方式： 调整 markdown 正文中章节的顺序，使其符合规范顺序。

missing-sections

严重级别： info

当已经定义了其他 token 的文件缺少可选 token 章节（spacing、rounded）时给出提示。这些章节不是必需的，但缺少它们意味着智能体会退回到默认值。

触发条件： colors 章节有条目，但 spacing 或 rounded 没有任何条目。

检查结果示例：

info  spacing  No 'spacing' section defined. Layout spacing will fall back to agent defaults.

解决方式： 如果希望显式控制这些值，请在 front matter 中添加 spacing 或 rounded 章节。

token-summary

严重级别： info

输出一条汇总诊断，报告每个章节中定义了多少 token。它纯粹用于提供信息。

检查结果示例：

info  Design system defines 4 colors, 3 typography scales, 2 rounding levels, 6 spacing tokens, 3 components.

总结

规则	严重级别	检查内容
`broken-ref`	error	无法解析的 token 引用；未知的组件子 token
`missing-primary`	warning	定义了色彩但不存在 `primary`
`contrast-ratio`	warning	组件的 backgroundColor/textColor 对比度低于 WCAG AA 4.5:1
`orphaned-tokens`	warning	定义了色彩 token 但从未被任何组件引用
`missing-typography`	warning	定义了色彩但不存在排版 token
`section-order`	warning	章节顺序不符合规范顺序
`missing-sections`	info	缺少可选章节（spacing、rounded）
`token-summary`	info	每个章节定义的 token 数量