/design-system

不明なプレースホルダーを見かけた場合や、接続されているツールを確認する必要がある場合は、CONNECTORS.md を参照してください。

デザインシステムを管理します — 一貫性の監査、コンポーネントのドキュメント化、または新しいパターンの設計。

使用方法

/design-system audit                    # システム全体の監査
/design-system document [component]     # コンポーネントをドキュメント化
/design-system extend [pattern]         # 新しいコンポーネントまたはパターンを設計

デザインシステムの構成要素

デザイントークン

ビジュアル言語を定義するアトミック値:

• カラー（ブランド、セマンティック、ニュートラル）
• タイポグラフィ（スケール、ウェイト、行間）
• スペーシング（スケール、コンポーネントパディング）
• ボーダー（半径、幅）
• シャドウ（高さレベル）
• モーション（期間、イージング）

コンポーネント

定義された再利用可能な UI 要素:

• バリエーション（プライマリ、セカンダリ、ゴースト）
• ステート（デフォルト、ホバー、アクティブ、ディセーブル、ロード中、エラー）
• サイズ（sm、md、lg）
• 動作（インタラクション、アニメーション）
• アクセシビリティ（ARIA、キーボード）

パターン

コンポーネントを組み合わせた一般的な UI ソリューション:

• フォーム（入力グループ、バリデーション、送信）
• ナビゲーション（サイドバー、タブ、ブレッドクラム）
• データ表示（テーブル、カード、リスト）
• フィードバック（トースト、モーダル、インラインメッセージ）

原則

1. 創意工夫より一貫性 — システムが存在するのは、チームが車輪を再発明しないため
2. 制約内での柔軟性 — コンポーネントは堅牢ではなく、構成可能であるべき
3. すべてをドキュメント化 — ドキュメント化されていなければ、それは存在しない
4. バージョン管理と移行 — 破壊的変更には移行パスが必要

出力 — 監査

## デザインシステム監査

### サマリー
**レビュー済みコンポーネント:** [X] | **検出された問題:** [X] | **スコア:** [X/100]

### 命名の一貫性
| 問題 | コンポーネント | 推奨事項 |
|-------|------------|----------------|
| [命名の矛盾] | [リスト] | [採用する標準] |

### トークンカバレッジ
| カテゴリ | 定義済み | ハードコード値の発見 |
|----------|---------|----------------------|
| カラー | [X] | [X] 件のハードコード hex |
| スペーシング | [X] | [X] 件の任意の値 |
| タイポグラフィ | [X] | [X] 件のカスタムフォント/サイズ |

### コンポーネント完成度
| コンポーネント | ステート | バリエーション | ドキュメント | スコア |
|-----------|--------|----------|------|-------|
| Button | ✅ | ✅ | ⚠️ | 8/10 |
| Input | ✅ | ⚠️ | ❌ | 5/10 |

### 優先アクション
1. [最も効果的な改善]
2. [第二優先事項]
3. [第三優先事項]

出力 — ドキュメント化

## コンポーネント: [名前]

### 説明
[このコンポーネントが何で、いつ使用するか]

### バリエーション
| バリエーション | 使用時期 |
|---------|----------|
| [プライマリ] | [メインアクション] |
| [セカンダリ] | [補助アクション] |

### プロップ / プロパティ
| プロパティ | 型 | デフォルト | 説明 |
|----------|------|---------|-------------|
| [prop] | [type] | [default] | [description] |

### ステート
| ステート | ビジュアル | 動作 |
|-------|--------|----------|
| デフォルト | [説明] | — |
| ホバー | [説明] | [インタラクション] |
| アクティブ | [説明] | [インタラクション] |
| ディセーブル | [説明] | インタラクティブでない |
| ロード中 | [説明] | [アニメーション] |

### アクセシビリティ
- **ロール**: [ARIA ロール]
- **キーボード**: [Tab、Enter、Escape の動作]
- **スクリーンリーダー**: [アナウンス...]

### Do's と Don'ts
| ✅ Do | ❌ Don't |
|------|---------|
| [ベストプラクティス] | [アンチパターン] |

### コード例
[フレームワーク適切なコードスニペット]

出力 — 拡張

## 新しいコンポーネント: [名前]

### 問題
[このコンポーネントが対処するユーザーニーズまたはギャップ]

### 既存パターン
| 関連コンポーネント | 類似点 | 十分ではない理由 |
|-------------------|-----------|---------------------|
| [コンポーネント] | [共有内容] | [不足している内容] |

### 提案設計

#### API / プロップ
| プロパティ | 型 | デフォルト | 説明 |
|----------|------|---------|-------------|
| [prop] | [type] | [default] | [description] |

#### バリエーション
| バリエーション | 使用時期 | ビジュアル |
|---------|----------|--------|
| [バリエーション] | [シナリオ] | [説明] |

#### ステート
| ステート | 動作 | メモ |
|-------|----------|-------|
| デフォルト | [説明] | — |
| ホバー | [説明] | [インタラクション] |
| ディセーブル | [説明] | インタラクティブでない |
| ロード中 | [説明] | [アニメーション] |

#### 使用トークン
- カラー: [使用するトークン]
- スペーシング: [使用するトークン]
- タイポグラフィ: [使用するトークン]

### アクセシビリティ
- **ロール**: [ARIA ロール]
- **キーボード**: [期待されるインタラクション]
- **スクリーンリーダー**: [アナウンス...]

### 未解決の質問
- [デザインレビューが必要な決定]
- [解決する必要があるエッジケース]

コネクタが利用可能な場合

~~デザインツール が接続されている場合:

• Figma で直接コンポーネントを監査 — 命名、バリエーション、トークン使用をチェック
• ドキュメント化用にコンポーネントプロパティとレイヤー構造を取得

~~ナレッジベース が接続されている場合:

• 既存のコンポーネントドキュメントと使用ガイドラインを検索
• 更新されたドキュメントを wiki に公開

ヒント

1. 監査から始める — どこにいるかを知ってから、どこに行くかを決めましょう。
2. 構築しながらドキュメント化する — コンポーネントの設計中にドキュメント化する方が簡単です。
3. 完璧性よりもカバレッジを優先 — 10 個のコンポーネントの 100% より 80% のコンポーネントをドキュメント化する方が優れています。