Lint ルール

@google/design.md の linter は、解析済みの DESIGN.md ファイルに対してルールを実行します。各ルールは、error（終了コード 1）、warning、info のいずれかの固定された重大度で検出結果を生成します。

broken-ref

重大度： error

YAML front matter で定義されたどのトークンにも解決されないトークン参照（{path.to.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 で定義するか、参照パスを修正します。不明なプロパティについては、認識済みのコンポーネントサブトークン名のいずれかを使用してください。

missing-primary

重大度： warning

front matter でカラーが定義されているのに、primary という名前のトークンが存在しない場合に警告します。primary カラーがないと、エージェントが自動的に 1 つ生成するため、パレットに対する制御が弱まります。

発生条件： colors セクションに 1 つ以上のエントリがあるが、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

定義されているものの、どのコンポーネントからも参照されていないカラートークンを特定します。孤立したトークンはノイズを増やし、デザインシステムが不完全であることを示している可能性があります。

発生条件： colors セクションにカラートークンが存在するが、どのコンポーネントのプロパティからも参照されていない。少なくとも 1 つのコンポーネントが定義されている場合にのみ発火します。

検出結果の例：

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

解決方法： コンポーネントでそのトークンを参照するか、不要になった場合は削除します。

missing-typography

重大度： warning

カラーは定義されているのにタイポグラフィトークンが存在しない場合に警告します。タイポグラフィトークンがないと、エージェントは独自のフォント選択にフォールバックします。

発生条件： colors セクションにエントリがあるが、typography セクションが空である。

検出結果の例：

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

解決方法： 少なくとも 1 つのタイポグラフィトークン（例：body-md）を front matter に追加します。

section-order

重大度： warning

markdown のセクションが、仕様で定義された正規の順序から外れている場合に警告します。期待される順序は、Overview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components、Do's and Don'ts です。

発生条件： ある認識済みセクション見出しが、本来その前に来るべき別の認識済みセクションよりも先に現れている。セクションの別名（例：「Elevation & Depth」に対する「Elevation」）は、チェック前に解決されます。

検出結果の例：

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

他のトークンをすでに定義しているファイルに、任意のトークンセクション（spacing、rounded）がない場合に通知します。これらのセクションは必須ではありませんが、ない場合、エージェントはデフォルトにフォールバックします。

発生条件： colors セクションにエントリがあるが、spacing または rounded にエントリがない。

検出結果の例：

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

解決方法： これらの値を明示的に制御したい場合は、spacing または rounded セクションを front matter に追加します。

token-summary

重大度： info

各セクションで定義されているトークンの数を報告するサマリー診断を出力します。これは純粋に情報提供を目的としています。

検出結果の例：

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

まとめ

ルール	重大度	チェック内容
`broken-ref`	error	解決されないトークン参照、不明なコンポーネントサブトークン
`missing-primary`	warning	カラーは定義されているが `primary` が存在しない
`contrast-ratio`	warning	コンポーネントの backgroundColor/textColor が WCAG AA 4.5:1 を下回る
`orphaned-tokens`	warning	カラートークンが定義されているが、どのコンポーネントからも参照されていない
`missing-typography`	warning	カラーは定義されているがタイポグラフィトークンが存在しない
`section-order`	warning	セクションが正規の順序から外れている
`missing-sections`	info	任意のセクション（spacing、rounded）がない
`token-summary`	info	セクションごとに定義されたトークンの数