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

當定義了色彩但沒有任何 typography token 時提出警告。沒有 typography 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 中至少新增一個 typography 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	已定義色彩但沒有 typography token
`section-order`	warning	章節未依標準順序排列
`missing-sections`	info	缺少可選章節（spacing、rounded）
`token-summary`	info	各章節定義的 token 數量