extract

再利用可能なパターン、コンポーネント、デザイントークンを特定し、デザインシステムに抽出・集約して、体系的に再利用できるようにします。

コードベース内のすべての値を取り込むことが目的ではありません。今後のデザイン上の判断を減らし、インターフェースの一貫性を保つ、制約のあるシステムを作ることが目的です。

トークン、コンポーネント、パターンの違い、ドリフト、そして不整合をトークンの乱立に変えない方法については、design-system alignmentを参照してください。

必須の事前準備

frontend-designを読み、Context Gathering Protocolに従ってください。利用可能なコンテキストを再利用し、重大な不足点についてのみ質問してください。

発見

対象領域を分析し、抽出できるものを特定します。

1. デザインシステムを探す：「design system」「ui」「components」などで検索し、デザインシステム、コンポーネントライブラリ、共有UIディレクトリを特定します。その構成を把握してください。

   • コンポーネントの構成と命名規則
   • デザイントークンの構成（存在する場合）
   • ドキュメントのパターン
   • インポート／エクスポートの規則

   重要：デザインシステムが存在しない場合は、作成する前に確認してください。まず、希望する配置場所と構成を把握してください。

2. パターンを特定する：以下を探します。

   • 繰り返し使われているコンポーネント：複数回使われている類似のUIパターン（ボタン、カード、入力欄など）
   • ハードコードされた値：トークンにすべき色、余白、タイポグラフィ、シャドウ
   • 一貫性のないバリエーション：同じ概念に対する複数の実装（異なるボタンスタイルが3種類あるなど）
   • 再利用可能なパターン：体系化する価値のあるレイアウト、構成、インタラクションのパターン

• 不足しているシステム：チームが余白、文字、色、角丸、エレベーションを何度も再検討していることが明らかな箇所

3. 価値を評価する：すべてを抽出する必要はありません。以下を検討してください。
   • 3回以上使われているか、または再利用される見込みがあるか
   • 体系化することで一貫性が向上するか
   • 汎用的なパターンか、特定のコンテキストに限られるか
   • メンテナンスコストに対してメリットがあるか

抽出を計画する

体系的な抽出計画を作成します。

• 抽出するコンポーネント：どのUI要素を再利用可能なコンポーネントにするか
• 作成するトークン：どのハードコードされた値をデザイントークンにするか
• システムの境界：混沌を記録するのではなく、判断の指針となるよう、どのトークンセットを意図的に小さく保つか
• サポートするバリエーション：各コンポーネントにどのようなバリエーションが必要か
• 命名規則：既存のパターンに沿ったコンポーネント名、トークン名、プロパティ名
• 移行経路：既存の使用箇所をどのようにリファクタリングし、新しい共有バージョンを使うようにするか

重要：デザインシステムは段階的に成長します。いつか再利用するかもしれないものをすべてではなく、現時点で明らかに再利用可能なものを抽出してください。

すでにコンポーネントライブラリがある場合の抽出

プロジェクトですでにshadcn/uiなどのライブラリを使用している場合は、以下の抽出を優先してください。

• ローカルのラッパー
• 再利用可能な構成
• ドキュメント化されたパターン

プロジェクトに安定したカスタマイズ済みの抽象化が本当に必要な場合を除き、アップストリームのプリミティブを冗長なローカルコピーに置き換えないでください。

優れた抽出は、ライブラリのプリミティブの一つ上のレイヤーに位置することがよくあります。汎用的な「Button」をもう一つ作るのではなく、既存のプリミティブを一貫して使う、製品固有のアクションバー、フィルターパネル、設定セクション、空状態のパターンを作成します。

抽出と拡充

改善し、再利用できるバージョンを作成します。

• コンポーネント：適切に設計されたコンポーネントを作成します。次の点を備えている必要があります。

  • 妥当なデフォルト値を設定した、明確な props API
  • さまざまなユースケースに対応する適切なバリエーション
  • 組み込みのアクセシビリティ機能（ARIA、キーボード操作、フォーカス管理）
  • ドキュメントと使用例

• デザイントークン：次の点を備えたトークンを作成します。

  • 明確な命名（プリミティブとセマンティックの区別）
  • 適切な階層と構成
  • 各トークンを使用する場面の説明
  • 該当する場合、スペーシング、タイポグラフィ、カラー、角丸、エレベーションに制約のあるスケールを設定

次のようなシステムを優先してください。

• スペーシング：4 から 64 までの数値をすべて用意するのではなく、意味のある間隔で構成した小さなスケール

• タイポグラフィ：UI の役割に合わせて手作業で整えたサイズとウェイトのセット

• カラー：場当たり的な明度調整ではなく、定義済みのカラースケール

• エレベーション：際限なくカスタムの box-shadow を作るのではなく、意味を持たせた少数のシャドウ

• パターン：次の内容を含めてパターンをドキュメント化します。

  • このパターンを使用する場面
  • コード例
  • バリエーションと組み合わせ

絶対に行わないこと：

• 汎用化せずに、特定のコンテキストにしか使えない実装を抽出する
• 使い道がないほど汎用的なコンポーネントを作成する
• 既存のデザインシステムの規約を考慮せずに抽出する
• 適切な TypeScript 型や props のドキュメント化を省略する
• あらゆる値にトークンを作成する（トークンにはセマンティックな意味が必要です）
• 不整合を単純なシステムにまとめず、トークンのカタログに変える

移行

既存の使用箇所を、新しい共有バージョンに置き換えます。

• すべての使用箇所を見つける：抽出したパターンを検索します
• 体系的に置き換える：各使用箇所を更新し、共有バージョンを使用するようにします
• 十分にテストする：見た目と機能が同等であることを確認します
• 不要なコードを削除する：古い実装を削除します

ドキュメント化

デザインシステムのドキュメントを更新します。

• 新しいコンポーネントをコンポーネントライブラリに追加する
• トークンの使い方と値を説明する
• 例とガイドラインを追加する
• Storybook やコンポーネントカタログを更新する

覚えておいてください。優れたデザインシステムは、常に進化するシステムです。パターンが生まれたら抽出し、慎重に拡充し、一貫性を保って維持してください。