twltr/design-system

デザインシステム

リーフスキル（Design内）— ドメインまたは名前からアクセス可能。

デザインシステムは、チームがそれを信頼している間だけ意思決定を節約します。漂流（ドリフト）は、その信頼を静かに侵食します。1つのコンポーネントに3つの名前、重複するトークンの横にある生の16進数値、誰も文書化しなかった状態。人々がシステムを信頼しなくなると、システムを回避して構築し始めます。このメソッドは3つのモードで動作します — 監査（現状のシステムを）、文書化（正しく使えるようにコンポーネントを）、拡張（適合するパターンでシステムを） — そして、それぞれを実際のソース（トークンファイル、コンポーネントコード、デザインファイル）に基づかせ、デザインシステムの一般的な概念に頼りません。

監査結果の実例

状況（架空）: トークンファイルを持つReactライブラリ。「ボタンとカードを監査して」というリクエスト。

命名    Button、IconBtn、.btn-link が1つの概念を3通りの名前で表している。
          → Button を採用し、`icon` と `link` のバリアントを追加。古い名前は1リリースの間エイリアスとして保持。
トークン  Card と Modal に23のハードコードされた色。18は既存トークンと一致（機械的に置換可能）。5はどのトークンとも一致しない。
          → 5つは判断が必要：欠落したトークンか、修正すべきデザインエラーか。
状態    Card はクリック可能だがフォーカス状態がない。

再利用可能な判断基準は、トークンを重複する値（機械的な修正）と、トークンに一致しない値（デザイン上の問題であり、推測ではなく人の判断を仰ぐべき）との分割です。

システムを収集する

判断する前に、存在するものを読み取ります。トークンソース、コンポーネントコードまたはライブラリ、ドキュメントです。rg -n '#[0-9a-fA-F]{3,8}\b|[0-9]+px' src/components のような検索で、コード内のハードコードされた値を見つけられます。パターンはスタックに合わせて調整してください。

~~ でマークされたセクションは、製品ではなくツールカテゴリを示します。~~design tool（例：Figma）や ~~knowledge base（例：Notion）。ホストが提供する該当カテゴリの接続ツールを使用し、提供されていない場合はそのステップをスキップします。

~~design tool がある場合は、デザインファイル内のコンポーネント名、バリアント、レイヤー構造、トークン使用状況を調査し、コードと比較します。~~knowledge base がある場合は、既存のコンポーネントページと利用ガイドラインを見つけ、依頼があった場合のみ、更新されたドキュメントをそこに公開します。

システムには3つのレイヤーがあり、監査とドキュメントはそれぞれをカバーします：

| レイヤー | 内容 | |---||---| | トークン | 色（ブランド、セマンティック、ニュートラル）、タイポグラフィ、スペーシング、半径とボーダー、エレベーション、モーションの持続時間とイージング | | コンポーネント | バリアント、状態（デフォルト、ホバー、フォーカス、アクティブ、無効、ローディング、エラー）、サイズ、動作、アクセシビリティ | | パターン | フォーム、ナビゲーション、データ表示、フィードバック — 繰り返し発生する問題を解決するために組み合わされたコンポーネント |

トークンがツール間で移動する場合、Design Tokens Community Group フォーマット（初回安定版2025.10、2025年10月）が共通の交換フォーマットです。プロジェクトが既に使用しているフォーマットに従ってください。

原則

1. 新規性よりも一貫性。 システムはチームが同じことを再決定するのをやめるために存在します。一回限りのバリアントには、システムに欠けている理由が必要です。
2. 制約内で構成可能。 新しいコンポーネントよりも、既存コンポーネントのバリアントまたは組み合わせを優先します。
3. 文書化されていないものは使えない。 誰も見つけられない状態やバリアントは再構築されます。
4. バージョン管理と移行。 破壊的な名前変更や削除には、移行パスが必要です（例：1リリースのエイリアス、コードモッド、または使用箇所を見つける検索）。

監査

スコアではなく、数と証拠を報告します。基準のない数字は、どの問題が重要かを隠します。

## デザインシステム監査: [範囲]

**レビュー対象:** [コンポーネント、トークンファイル] | **発見事項:** [カテゴリ別の件数]

### 命名
| 問題 | 場所 | 推奨事項 |
|---|---|---|

### トークンカバレッジ
| カテゴリ | 定義されたトークン数 | ハードコードされた値 | 既存トークンと一致する値 |
|---|---|---|---|

### コンポーネントの完全性
| コンポーネント | 状態 | バリアント | ドキュメント | アクセシビリティ |
|---|---|---|---|---|
| Button | 完了 | 部分的: アイコンのみサイズが不足 | 欠落 | フォーカスリングあり |

### 優先アクション
1. [ユーザーまたはチームへの影響が最大のものから、必要な労力を添えて]

文書化

コンポーネントを利用する全員のために、再利用可能なコンポーネントを文書化します。propsとコード例は、実際のコンポーネントから取得し、発明されたAPIは使用しません。

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

[そのコンポーネントが何であり、いつ使用するか — そして、いつ別のものを使うべきか]

### バリアント
| バリアント | 使用する状況 |
|---|---|

### Props
| Prop | 型 | デフォルト値 | 説明 |
|---|---|---|---|

### 状態
| 状態 | 見た目 | 動作 |
|---|---|---|

### アクセシビリティ
- **ロール:** [ロールまたはネイティブ要素]
- **キーボード:** [Tab、Enter、Space、Escape、矢印キー]
- **スクリーンリーダー:** [〜として告知される]

### 推奨事項と禁止事項
| 推奨 | 禁止 |
|---|---|

### 例
[プロジェクトのフレームワークでの短いスニペット]

拡張

新しいものを提案する前に、近い既存コンポーネントをリストアップし、それぞれがなぜ不十分かを説明します。ほとんどのリクエストは新しいバリアントとして解決されます。新しいコンポーネントは既存トークンを再利用し、新しいトークンはその理由と共にのみ提案します。

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

### 問題
[ユーザーニーズまたはギャップ]

### 既存の選択肢
| コンポーネント | 共有する点 | 不十分な理由 |
|---|---|---|

### デザイン
ドキュメントテンプレートと同様のprops、バリアント、状態。使用するトークン。

### アクセシビリティ
ロール、キーボード、スクリーンリーダーの動作。

### 未解決の質問
[デザインレビューが必要な判断事項]

システムのコンポーネントとトークンがこのメソッドの対象です。1つの機能や画面の仕様書、新製品のビジュアルディレクションは別のデザイン作業です。システム監査はWCAG監査の代わりにはなりません。