--- 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 / 扱わないこと - 既存コンポーネントの再利用可否（`rr-midstream-design-system-component-reuse-001` の領域）。 - 実行時の loading / error 状態の配線そのもの（mutation 中の loading は `rr-midstream-loading-state-001` の領域。本スキルはコンポーネント定義側の状態網羅を見る）。 - focus-visible のアクセシビリティ実装（`rr-midstream-modern-web-a11y-interactive-001` の領域）。 - デザイントークン準拠（design-source / token-enforcement の領域）。 ## Pre-execution Gate / 実行前ゲート このスキルは以下の条件がすべて満たされない限り `NO_REVIEW` を返す。 - [ ] 差分に**新規 UI コンポーネント**（再利用可能な表示要素を export する `.tsx` / `.jsx` の追加）が含まれている - [ ] inputContext に diff が含まれ、`code_search`（grep）が利用可能である ゲート不成立時の出力: `NO_REVIEW: rr-midstream-component-variants-states-001 — 新規 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 を `:` で示し、定義の追加を提案する。 ### 制約 - 検出は最大 5 件。実害の大きい状態欠落（disabled / error の欠落）を優先する。 - 各指摘に「対象コンポーネント」「欠落している状態 / variants」「あるべき定義」を必ず含める。 - 別ファイルでの定義有無を確認してから報告する（差分内に無いだけで断定しない）。 ## Evidence / 根拠の取り方 - 対象コンポーネントと欠落箇所は `:` に紐づけ、推測で状態欠落を述べない。 - 別ファイル（stories / 型定義）を `code_search` で確認した結果を根拠として示す。 ## Output / 出力フォーマット すべて日本語。 ```text (component-variants-states):1: [要約] 最も重大な状態設計の欠落は〈1文〉 :: [状態欠落1] <タイトル> 対象: <新規コンポーネント名>(:) 欠落: 影響: <後付け対応での破綻 / UX の不整合> Fix: <欠落状態 / variants の定義・文書化（stories や型での明示）> ``` ## 評価指標（Evaluation） - 合格基準: 新規 UI コンポーネントを `:` で示し、欠落状態を別ファイル確認の上で具体的に説明している。 - 不合格基準: 既存コンポーネントへの指摘、状態を持たない表示要素への難癖、別ファイル定義の未確認による誤検出、loading 配線・a11y・トークンへの越境。 ## 人間に返す条件（Human Handoff） - どの状態・variants を必須とするかが、プロダクトのデザインシステム方針に依存する場合。 - 状態網羅の要否が、コンポーネントの用途（内部限定かどうか）の判断を要する場合。