extract

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

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

トークン、コンポーネント、パターンの違い、ドリフト、そして不整合をトークンの乱立に変えない方法については、デザインシステムの整合性を参照してください。

必須の準備

ユーザーは /extract を使ってこのワークフローを開始します。このスキルが有効になったら、$frontend-design を読み込みます。ここにはデザイン原則、アンチパターン、コンテキスト収集プロトコルが含まれています。先に進む前に、このプロトコルに従ってください。まだデザインコンテキストがない場合は、必ず最初に $setup を読み込んでください。

調査

対象領域を分析して、抽出できる機会を特定します。

1. デザインシステムを見つける：デザインシステム、コンポーネントライブラリ、または共有 UI ディレクトリを探します（「design system」「ui」「components」などを grep します）。その構造を把握します。

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

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

2. パターンを特定する：次の点を確認します。

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

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

3. 価値を評価する：すべてを抽出すべきとは限りません。次の点を考慮します。
   • 3 回以上使われているか、または再利用される可能性が高いか？
   • 体系化することで一貫性が向上するか？
   • 汎用的なパターンか、特定のコンテキストに限定されるか？
   • メンテナンスコストに対して、どのようなメリットがあるか？

抽出を計画する

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

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

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

既存のコンポーネントライブラリがある場合の抽出

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

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

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

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

抽出と拡充

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

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

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

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

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

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

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

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

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

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

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

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

絶対に行わないこと：

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

移行

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

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

ドキュメント化

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

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

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