v0.1.0 to v0.1.0

---

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-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 / 出力フォーマット

すべて日本語。

```text

(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 を必須とするかが、プロダクトのデザインシステム方針に依存する場合。

- 状態網羅の要否が、コンポーネントの用途（内部限定かどうか）の判断を要する場合。