Component Variants / States Documentation コンポーネント状態の文書化

Pattern declaration

Primary pattern: Reviewer Secondary patterns: Inversion Why: 新規コンポーネントの状態網羅はチェックリスト的に確認できるが、対象が「新規 UI コンポーネントの追加」かどうかの判定が必要。新規コンポーネント追加を含まない変更では実行を止めるゲートが必要。

Goal / 目的

• 新規追加された UI コンポーネントに、variants（種類・バリエーション）とインタラクティブ状態（hover / focus / disabled / loading / error）が定義・文書化されているかを確認する。
• 「コンポーネントは追加したが、disabled / loading / error の状態設計が欠落し、後から後付けで破綻する」パターンを検出する。

Non-goals / 扱わないこと

• 既存コンポーネントの再利用可否（design-system-component-reuse の領域）。
• 実行時の loading / error 状態の配線そのもの（mutation 中の loading は loading-state の領域。本スキルはコンポーネント定義側の状態網羅を見る）。
• focus-visible のアクセシビリティ実装（modern-web-a11y-interactive の領域）。
• デザイントークン準拠（design-source / token-enforcement の領域）。

Pre-execution Gate / 実行前ゲート

このスキルは以下の条件がすべて満たされない限り NO_REVIEW を返す。

• 差分に新規 UI コンポーネント（再利用可能な表示要素を export する .tsx / .jsx の追加）が含まれている
• inputContext に diff が含まれ、code_search（grep）が利用可能である

ゲート不成立時の出力: NO_REVIEW: component-variants-states — 新規 UI コンポーネントの追加が検出されない

False-positive guards / 抑制条件

• 状態を持たない純粋な表示コンポーネント（静的なテキスト・アイコン表示など、インタラクションが無い）は指摘しない。
• variants / states が別ファイル（Storybook の *.stories.*、型定義、ドキュメント）に定義されている場合は、code_search で確認してから指摘する。差分内に見えないだけで断定しない。
• 既存コンポーネントの軽微な変更（新規追加でないもの）は対象外とする。
• プロトタイプ・内部限定など、状態網羅が不要と差分内で明記されている場合は抑制する。

Rule / ルール

検出ロジック

1. 新規コンポーネントの特定: 差分から、新規に追加された再利用可能な UI コンポーネント（export される表示要素）を特定する。
2. 状態・variants の確認: そのコンポーネントが受け付けるべき状態を判定し、定義・文書化を確認する。
   • インタラクティブ要素での disabled / loading / error 状態の扱い
   • variants（サイズ・種類・トーンなど）の定義
   • code_search で *.stories.* や型定義など別ファイルの記載も確認する
3. 報告: 欠落している状態・variants を <file>:<line> で示し、定義の追加を提案する。

制約

• 検出は最大 5 件。実害の大きい状態欠落（disabled / error の欠落）を優先する。
• 各指摘に「対象コンポーネント」「欠落している状態 / variants」「あるべき定義」を必ず含める。
• 別ファイルでの定義有無を確認してから報告する（差分内に無いだけで断定しない）。

Evidence / 根拠の取り方

• 対象コンポーネントと欠落箇所は <file>:<line> に紐づけ、推測で状態欠落を述べない。
• 別ファイル（stories / 型定義）を code_search で確認した結果を根拠として示す。

Output / 出力フォーマット

すべて日本語。

(component-variants-states):1: [要約] 最も重大な状態設計の欠落は〈1文〉

<file>:<line>: [状態欠落1] <タイトル>
  対象: <新規コンポーネント名>(<file>:<line>)
  欠落: <disabled / loading / error / variants のどれか>
  影響: <後付け対応での破綻 / UX の不整合>
  Fix: <欠落状態 / variants の定義・文書化（stories や型での明示）>

評価指標（Evaluation）

• 合格基準: 新規 UI コンポーネントを <file>:<line> で示し、欠落状態を別ファイル確認の上で具体的に説明している。
• 不合格基準: 既存コンポーネントへの指摘、状態を持たない表示要素への難癖、別ファイル定義の未確認による誤検出、loading 配線・a11y・トークンへの越境。

人間に返す条件（Human Handoff）

• どの状態・variants を必須とするかが、プロダクトのデザインシステム方針に依存する場合。
• 状態網羅の要否が、コンポーネントの用途（内部限定かどうか）の判断を要する場合。