| id | component-variants-states |
| name | Component Variants / States Documentation コンポーネント状態の文書化 |
| description | 新規追加された UI コンポーネントに、variants（種類）とインタラクティブ状態（hover / focus / disabled / loading / error）が定義・文書化されているかを確認し、状態設計の欠落を検出する |
| version | 0.1.0 |
| category | midstream |
| phase | midstream |
| applyTo | ["src/**/*.{tsx,jsx}","app/**/*.{tsx,jsx}","components/**/*.{tsx,jsx}"] |
| tags | ["design-system","component","variants","states","midstream"] |
| severity | minor |
| inputContext | ["diff"] |
| outputKind | ["findings","questions"] |
| modelHint | balanced |
| dependencies | ["code_search"] |
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 を返す。
ゲート不成立時の出力: NO_REVIEW: component-variants-states — 新規 UI コンポーネントの追加が検出されない
False-positive guards / 抑制条件
- 状態を持たない純粋な表示コンポーネント（静的なテキスト・アイコン表示など、インタラクションが無い）は指摘しない。
- variants / states が別ファイル（Storybook の
*.stories.*、型定義、ドキュメント）に定義されている場合は、code_search で確認してから指摘する。差分内に見えないだけで断定しない。
- 既存コンポーネントの軽微な変更（新規追加でないもの）は対象外とする。
- プロトタイプ・内部限定など、状態網羅が不要と差分内で明記されている場合は抑制する。
Rule / ルール
検出ロジック
- 新規コンポーネントの特定: 差分から、新規に追加された再利用可能な UI コンポーネント（export される表示要素）を特定する。
- 状態・variants の確認: そのコンポーネントが受け付けるべき状態を判定し、定義・文書化を確認する。
- インタラクティブ要素での disabled / loading / error 状態の扱い
- variants（サイズ・種類・トーンなど）の定義
code_search で *.stories.* や型定義など別ファイルの記載も確認する
- 報告: 欠落している状態・variants を
<file>:<line> で示し、定義の追加を提案する。
制約
- 検出は最大 5 件。実害の大きい状態欠落（disabled / error の欠落）を優先する。
- 各指摘に「対象コンポーネント」「欠落している状態 / variants」「あるべき定義」を必ず含める。
- 別ファイルでの定義有無を確認してから報告する（差分内に無いだけで断定しない）。
