design-system

デザインシステム

デザインシステムを構築、進化、監査します。原則としてスタックに依存しません。実装はスタックごとに異なります（Figma、Storybook、コードライブラリなど）が、構造とガバナンスの原則は共通して適用できます。

このスキルは、システムを構築するためのものです。特定のページやコンポーネントにシステムを適用する場合は、design-standardsを使用してください。ブランドのビジュアルアイデンティティには、brand-identityを使用してください。

---

使用する場面

• デザインシステムをゼロから構築する
• 既存のシステムの不足や断片化を監査する
• システムレベルでデザイントークンを定義する
• コンポーネントライブラリを構成する
• コントリビューションとガバナンスのモデルを確立する
• 場当たり的なコンポーネントから、文書化されたシステムへ移行する

使用しない場面

• 単一のページやコンポーネントをデザインする場合（design-standardsを使用）
• ブランドアイデンティティに関する作業（brand-identityを使用）
• コンポーネントレベルのフロントエンド実装（frontend-component-buildを使用）
• マーケティング向けの純粋なデザインドキュメント（brand-style-guideを使用）

---

必要な入力

• ブランドアイデンティティ（トークン、トーン、画像の方向性）
• システムがサポートする必要があるプロダクトの対象領域（Web、モバイル、マーケティング、アプリ、社内ツール）
• チームと使用するツール（Figma、コードフレームワーク、ドキュメントプラットフォーム）
• 既存のコンポーネント（文書化されていないものも含む）
• 制約（アクセシビリティ要件、パフォーマンス目標、ブラウザーのサポート範囲）

ブランドアイデンティティが未定義の場合は、まずbrand-identityを実行してください。

---

フレームワーク：5つのレイヤー

完全なデザインシステムは、積み重なる5つのレイヤーで構成されます。各レイヤーは、その上のレイヤーに情報を提供します。

1. 基盤（トークン）

最小単位となる設計上の決定です。色、文字、間隔、角丸、影、動き、ブレークポイントが含まれます。

このレイヤーが重要な理由：

• トークンは、上位のすべての要素に対する信頼できる唯一の情報源です
• トークンを変更すると、あらゆる場所に自動で反映されます
• トークンがなければ、システムに基盤はありません

成果物：

• 文書化されたトークンセット（design-standards/references/design-tokens-template.mdを参照）
• コードでのトークン実装（CSS変数、JSオブジェクト、Style Dictionaryなど）
• Figmaでのトークン実装（変数とスタイル）
• トークンをいつ使用するかを説明する入門ドキュメント

一般的なパターン：

• 2層のトークン：ベーストークン（生の値）＋セマンティックトークン（用途を示す名前）。例：color-blue-600（ベース）＋color-text-link（セマンティック）。コンポーネントはセマンティックトークンを参照します。テーマを変更する際は、ベーストークンではなくセマンティックトークンを更新します。

2. 要素（アトム）

最小の機能的な構成要素です。ボタン、入力欄、ラベル、バッジ、アイコン、リンク、区切り線が含まれます。

要素ごとに文書化する内容：

• 視覚的なバリエーション（プライマリ、セカンダリ、ゴーストなど）
• サイズのバリエーション（小、中、大）
• 状態（デフォルト、ホバー、フォーカス、アクティブ、無効、エラー、読み込み中）
• 構造（要素を構成するパーツ）
• 間隔と比率
• アクセシビリティ（キーボード対応、スクリーンリーダーの動作、ARIA）
• コードでの使用方法（props、例）

成果物：

• Figmaの要素ライブラリ
• コードの要素コンポーネント
• 要素ごとのドキュメント

3. コンポーネント（モレキュール＋オーガニズム）

認識しやすいUIパターンを形成する、要素の組み合わせです。カード、アラート、モーダル、ナビゲーション、フォーム、データテーブル、ヘッダー、フッターが含まれます。

コンポーネントごとに記載する内容：

• 構成（使用する要素）
• バリエーションと設定
• ユースケース（代替手段ではなく、これを選ぶ場面）
• レイアウトの動作（レスポンシブ、コンテナ内、全幅）
• アンチパターン（使用してはならない場面）

成果物：

• コンポーネントライブラリ
• 使用ガイダンスを含む、コンポーネントごとのドキュメント

4. パターン（テンプレート）

コンポーネントを組み合わせた、より大きな構造です。サインインフロー、設定ページ、ダッシュボードレイアウト、マーケティングページのセクションが含まれます。

パターンごとに記載する内容：

• 構造と使用するコンポーネント
• 対応するユーザージャーニー
• レイアウトグリッドと間隔
• レスポンシブ時の動作
• バリエーション（例：「サイドバー付き」、「全画面」、「モーダル」）

成果物：

• パターンライブラリまたはページテンプレート
• 完全な使用例を示すドキュメント

5. ドキュメントとガバナンス

システムの利用、コントリビューション、保守の方法を定めます。

ドキュメントには、以下を含めます。

• 新しいチームメンバー向けのスタートガイド
• 利用方法と拡張方法
• コントリビューションモデル
• バージョニングポリシー
• 破壊的変更が発生した場合の移行パス
• 主要なシステム上の判断を記録した意思決定ログ

ガバナンスには、以下を含めます。

• システムのオーナー（チームまたはローテーション）
• 新しいコンポーネントの提案と承認の方法
• 意見の対立を解決する方法
• システムを進化させる方法と安定性を保つ方法
• レビューと更新の頻度

---

ワークフロー

新しいデザインシステムの場合

1. 既存のUIを棚卸しします。 製品内のすべてのコンポーネント、ボタン、フォーム、モーダルのスクリーンショットを撮ります。異なるUIパターンの一覧が、最初に取り組む範囲になります。
2. 重複を特定します。 同じコンポーネントが製品内で5通りの方法で構築されている場合、それらは統合効果の高い対象です。
3. 基盤を定義します。 ベースレイヤーとセマンティックレイヤーの両方を含むトークンセットを定義し、それぞれを文書化します。
4. 要素を監査します。 棚卸し結果をもとに、実際の要素（ボタン、入力欄など）を特定し、バリエーションを管理可能なセットに絞り込みます。
5. 要素ライブラリを構築します。 Figmaとコードで構築し、各要素を文書化します。
6. 優先度の高いコンポーネントを特定します。 最も頻繁に使われる10〜15個のコンポーネントから構築します。
7. パターンを文書化します。 システムの利用例を示すページレベルのテンプレートを作成します。
8. ガバナンスを確立します。 オーナー、コントリビューションモデル、レビュー頻度を定めます。
9. 展開します。 既存の画面を段階的にシステムへ移行します。

既存のデザインシステムを監査する場合

1. 現状を棚卸しします。 文書化されているもの、Figmaにあるもの、コードにあるもの、本番環境で実際に使われているものを確認します。
2. 不足箇所を洗い出します。 システムが不完全な箇所と、システムがニーズを満たせないためにチームがシステム外で構築している箇所を特定します。
3. 断片化の状況を把握します。 システムの実装が乖離している箇所（Figmaとコード、Webとモバイル、複数チーム間など）を確認します。
4. 劣化を特定します。 文書化された標準から乖離しているコンポーネントを見つけます。
5. 修正の優先順位を付けます。 まず基盤の不足箇所、次に使用頻度の高いコンポーネントの乖離、最後に使用頻度の低いコンポーネントの整理に取り組みます。
6. 展開を計画します。 大きな変更には移行パスが必要です。

---

失敗のパターン

• ブランドが確定する前にシステムを構築する。 トークンはブランドに依存します。先にブランドを確定してください。
• アトムから始めることにこだわりすぎる。 誰も使わないコンポーネントを作る前に、トークンと要素に6か月を費やしてしまいます。必要とされるコンポーネントをリリースし、トークンは反復的に改善してください。
• 一人だけで管理するシステム。 ガバナンスのないシステムは、最初のデザイナーがいなくなった時点で破綻します。早い段階でオーナーシップを確立してください。
• ドキュメントが古いままになっている。 コードとドキュメントの内容が乖離したシステムは、システムがないよりも悪い状態です。同期するか、ドキュメントを廃止してください。
• すべてにバージョンを付ける。 すべてのコンポーネントにメジャーバージョンが必要だと扱ってしまいます。ほとんどのコンポーネントはそのまま進化します。バージョニングは破壊的変更に限ってください。
• 「アトミックデザイン」を教条的に採用する。 アトム／モレキュール／オーガニズムは有用なメンタルモデルであり、厳密な分類体系ではありません。何かがモレキュールかオーガニズムかを議論しないでください。
• 現場の意見を取り入れずに構築する。 利用するチームの意見を反映せずに設計されたシステムは無視されます。利用者と共同で設計してください。
• 廃止の手順がない。 削除しても問題ないか誰もわからないため、古いコンポーネントがいつまでもコードに残ります。廃止について明示的に文書化してください。
• トークンを増やしすぎる。 10色のブランドに対して200個のカラートークンを定義してしまいます。節度を保ってください。多くの製品で必要なトークンは、実際に用意されている数より少なくて済みます。

---

出力形式

デザインシステムには、複数の成果物があります。一般的なものは次のとおりです。

• ドキュメントサイト（Notion、専用サイト、GitHub Pages、Storybook アドオンなど）
• Figma ライブラリ（または同等のデザインツール）
• コードライブラリ（npm パッケージ、モノレポのワークスペース、コピー＆ペーストできるコンポーネント）
• 意思決定ログ（システムレベルの決定事項とその根拠）
• ロードマップと変更履歴

デザインシステムを監査する場合は、design-system-audit.md に Markdown レポートを出力します。

1. 既存の要素の一覧（基盤、要素、コンポーネント、パターン）
2. ギャップ分析
3. 断片化の分析
4. ドリフト分析
5. 優先順位を付けた改善計画
6. ガバナンスに関する推奨事項

---

必要なデータを利用できない場合

このスキルの出力は、独自には生成できないデータ、測定値、またはツールの結果に依存します。必要な入力、ツール、またはデータソースを利用できない、あるいは検証できない場合、認められる出力は、不足している内容を明記した成果物です。具体的には、何が必要だったか、実際に何を取得または検証できたか、出力のどの部分に影響するかを記載します。成果物を完成させるために、必要な数値を捏造、推定、または補間することは認められません。不足している内容を明示すれば、それで完全な回答となります。

---

参照ファイル

• references/system-architecture.md - 4 層モデル（トークン、プリミティブ、パターン、テンプレート）と、新しい作業の位置付けを判断する方法。
• references/system-audit-template.md - 既存のデザインシステムを監査するためのテンプレート。
• references/governance-playbook.md - 運用中のシステムにおける貢献モデル、オーナーシップ、意思決定プロセス。