design-system

/design-system

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

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

使用方法

/design-system audit                    # Full system audit
/design-system document [component]     # Document a component
/design-system extend [pattern]         # Design a new component or pattern

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

デザイントークン

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

• 色（ブランド、セマンティック、ニュートラル）
• タイポグラフィ（スケール、ウェイト、行の高さ）
• 余白（スケール、コンポーネントのパディング）
• ボーダー（角丸、幅）
• シャドウ（エレベーションレベル）
• モーション（持続時間、イージング）

コンポーネント

次の項目が定義された再利用可能な UI 要素です。

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

パターン

複数のコンポーネントを組み合わせた、一般的な UI ソリューションです。

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

原則

1. 創造性より一貫性 — チームが同じものを一から作り直さずに済むよう、システムが存在します
2. 制約の中で柔軟性を保つ — コンポーネントは硬直的ではなく、組み合わせて使える必要があります
3. すべてをドキュメント化する — ドキュメント化されていないものは、存在しないのと同じです
4. バージョン管理と移行 — 互換性を破る変更には移行手段が必要です

出力 — 監査

## Design System Audit

### Summary
**Components reviewed:** [X] | **Issues found:** [X] | **Score:** [X/100]

### Naming Consistency
| Issue | Components | Recommendation |
|-------|------------|----------------|
| [Inconsistent naming] | [List] | [Standard to adopt] |

### Token Coverage
| Category | Defined | Hardcoded Values Found |
|----------|---------|----------------------|
| Colors | [X] | [X] instances of hardcoded hex |
| Spacing | [X] | [X] instances of arbitrary values |
| Typography | [X] | [X] instances of custom fonts/sizes |

### Component Completeness
| Component | States | Variants | Docs | Score |
|-----------|--------|----------|------|-------|
| Button | ✅ | ✅ | ⚠️ | 8/10 |
| Input | ✅ | ⚠️ | ❌ | 5/10 |

### Priority Actions
1. [Most impactful improvement]
2. [Second priority]
3. [Third priority]

出力 — ドキュメント化

## Component: [Name]

### Description
[What this component is and when to use it]

### Variants
| Variant | Use When |
|---------|----------|
| [Primary] | [Main actions] |
| [Secondary] | [Supporting actions] |

### Props / Properties
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| [prop] | [type] | [default] | [description] |

### States
| State | Visual | Behavior |
|-------|--------|----------|
| Default | [description] | — |
| Hover | [description] | [interaction] |
| Active | [description] | [interaction] |
| Disabled | [description] | Non-interactive |
| Loading | [description] | [animation] |

### Accessibility
- **Role**: [ARIA role]
- **Keyboard**: [Tab, Enter, Escape behavior]
- **Screen reader**: [Announced as...]

### Do's and Don'ts
| ✅ Do | ❌ Don't |
|------|---------|
| [Best practice] | [Anti-pattern] |

### Code Example
[Framework-appropriate code snippet]

出力 — 拡張

## New Component: [Name]

### Problem
[What user need or gap this component addresses]

### Existing Patterns
| Related Component | Similarity | Why It's Not Enough |
|-------------------|-----------|---------------------|
| [Component] | [What's shared] | [What's missing] |

### Proposed Design

#### API / Props
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| [prop] | [type] | [default] | [description] |

#### Variants
| Variant | Use When | Visual |
|---------|----------|--------|
| [Variant] | [Scenario] | [Description] |

#### States
| State | Behavior | Notes |
|-------|----------|-------|
| Default | [Description] | — |
| Hover | [Description] | [Interaction] |
| Disabled | [Description] | Non-interactive |
| Loading | [Description] | [Animation] |

#### Tokens Used
- Colors: [Which tokens]
- Spacing: [Which tokens]
- Typography: [Which tokens]

### Accessibility
- **Role**: [ARIA role]
- **Keyboard**: [Expected interactions]
- **Screen reader**: [Announced as...]

### Open Questions
- [Decision that needs design review]
- [Edge case to resolve]

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

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

• Figmaでコンポーネントを直接監査し、命名、バリアント、トークンの使用状況を確認します
• ドキュメント作成のため、コンポーネントのプロパティとレイヤー構造を取得します

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

• 既存のコンポーネントドキュメントと使用ガイドラインを検索します
• 更新したドキュメントを社内Wikiに公開します

ヒント

1. まず監査から始める — どこへ向かうかを決める前に、現状を把握しましょう。
2. 構築しながらドキュメント化する — コンポーネントは、設計中にドキュメント化するほうが簡単です。
3. 完璧さより網羅性を優先する — コンポーネントの80%をドキュメント化するほうが、10個のコンポーネントを100%ドキュメント化するより価値があります。