figma-extract-design-system

figma-extract-design-system — 本番アプリ → デザインシステム

組織では、小規模なチームがAIを活用して製品を開発できます。製品は動作しますが、その基盤となるデザインシステムがないため、一貫性、再利用性、バージョン管理ができません。このスキルでは、抽出作業を実施します：アプリ → コンポーネント一覧 → DTCGトークン → Storybookパッケージ →（任意で）Figma。

有効な終了地点は2つあります。

• コード主導の組織：Storybookパッケージの作成で終了します。これがバージョン管理された信頼できる唯一の情報源となり、パッケージ化して製品に再インポートします。
• デザイン主導の組織：Figmaまで続けます。トークンは変数（figma_import_tokens）になり、主要なコンポーネントはFigmaのコンポーネントセットになります。

ツール構成

• 推奨 — figma-console-mcp 接続時（ローカルモード）： 5つの figma_ds_* ツールを使用します。処理は決定論的で範囲が限定されており、マニフェストは <outDir>/.extraction/ に保存されるため、セッションをまたいで作業を継続できます。
• 代替 — console MCP がない場合： Read/Grep/Bash を使って、同じフェーズを自分で実施します（低速で、決定性も低くなります）。同じ成果物を維持してください。自分で作成する analysis.json、DTCG の tokens/tokens.json、および同じパッケージ構成です。Figmaとの往復には figma-import-tokens スキル（公式 Figma MCP の use_figma）を使用します。

フェーズ 0 — 発見（最初に対話）

スキャンの前に、ユーザーと次の項目を確認します。

1. 対象アプリのパス — 絶対パスを指定します。複数のアプリを対象にすることもできます。実際のデザインシステムは、それらの製品の共通部分です。
2. コード主導か、デザイン主導か？ フェーズ 6（Figma）を実施するかどうかを決めます。
3. ブランド／命名のコンテキスト — 製品名、既存のブランドカラー名があればその名称。セマンティックな命名の工程で必要です。
4. デザインシステムの配置場所 — デフォルトは <first app>/design-system、またはモノレポ内の別ディレクトリです。

フェーズ 1 — 分析

figma_ds_analyze { targets: ["/abs/path/app"], outDir: "/abs/path/app/design-system" }

先に進む前に、サマリーをユーザーと一緒に確認します。特に、デザインシステムと UI キットを分ける**architecture ブロック**を確認してください。

• **specializations**は、用途に基づいて名付けられたコンポーネントです（FollowButton、ModerationMenu、NodeCard）。それぞれ実際には、汎用コンポーネント（Button、Menu、Card）に用途を組み合わせたものです。「フォローボタン」にしているのは用途であり、コンポーネント自体はボタンです。
• **missingPrimitives**は、構築対象のリストです。アプリで使われているものの、まだ作られていない汎用コンポーネントを示します。
• **levels**は、アトミックデザインの分類（アトム／モレキュール／オーガニズム／テンプレート）です。これはヒューリスティックなので、ユーザーに組織内で使われている用語を確認してください。

汎用化の工程（確認後、移植作業の前または作業中に実施）：****design-systems-assistant MCPが接続されている場合は、その情報を判断の根拠にしてください（命名規則、コンポーネント API の設計、アトミックな階層構造についてはsearch_design_knowledgeを使います。さまざまな業界のベストプラクティスが反映されています）。続いて、次の作業を行います。

1. 合意した各missingPrimitiveを、確認できた特殊化を幅広くカバーできるバリアント／プロパティ API を備えた汎用コンポーネントとして構築します。
2. 各特殊化をレシピとして再表現します。汎用コンポーネントのストーリー（「Button → Recipes/Follow」など）にするか、recipes/階層に薄いラッパーを作成します。プリミティブの兄弟として作成することは避けてください。プロダクトにはフォローボタンが残りますが、システムが提供するのは Button です。
3. Storybook は、単一のフラットなComponents/リストではなく、選択した階層（Primitives/、Components/、Patterns/など）に沿って整理します。
4. すべての特殊化を統合できるわけではありません。位置を示す修飾語を持つもの（LeftNav）や、真に固有のオーガニズム（ThreadCanvas）はそのまま残す場合があります。レポートが提案し、採否はユーザーが決めます。

従来の項目も確認します。

• 分類は重要です。vendored（shadcn 形式でコピーされたソース）とbespokeはそのまま移植し、wrappedはベンダーパッケージをピア依存関係として維持して移植します。pure-vendor（MUI／Chakra を直接使用）は移植しません。テーマ／トークンと使用方法のドキュメントで表現します。
• duplicateGroupsは、バイブコーディングの兆候です（Button.tsx が 3 つあるなど）。グループごとの正規版をユーザーと決め、採用しないものはメモを添えてfigma_ds_statusでskippedとして記録します。
• 移植の順序は、ツールの使用状況ランキング（topByUsage）に従います。使用されていないニッチなコンポーネントは、確認なしに移植しないでください。

フェーズ 2 — トークンの抽出

figma_ds_extract_tokens { outDir, formats: [...match the app's styling method...] }

• declaredトークン（CSS 変数、@theme、SCSS 変数、Tailwind テーマ、shadcn の HSL トリプレット）は名前を維持し、sourcesで由来を記録します。.dark／[data-theme=dark]の値は、実際の Light／Dark マルチモード構造にします。
• inferredトークンは、頻度に基づいて昇格された生の値です。ユーザーと一緒に確認してください。belowThresholdリストをざっと確認すると、あと一歩で昇格する値を見つけられます。

**セマンティック命名の工程（ツールではなく、あなたが担当）：**構造的な名前（color/blue/500、color/extracted/hex-22c55e）は正確ですが、そのままでは出荷できません。ユーザーのブランドに関する情報を踏まえ、tokens/tokens.jsonを編集してセマンティックエイリアストークン（color/primary → {color.blue.500}）を追加します。Semanticグループに追加し、プリミティブを{dot.path}エイリアスで参照してください。プリミティブは削除しないでください。コードベースが変更された場合のみfigma_ds_extract_tokensを再実行します（再生成が行われるため、生成済みの投影への手動編集は失われます。tokens.jsonへの編集はスキャフォールドの入力になります）。

フェーズ 3 — スキャフォールドと Storybook

figma_ds_scaffold { outDir, packageName: "@org/design-system" }
cd <outDir> && npm install && npm create storybook@latest -- --yes --no-dev
figma_ds_setup_storybook { outDir }    # AFTER init — wires the workshop to the extraction

figma_ds_setup_storybookは.storybook/preview.cssを生成します（抽出したトークンに加え、ソースアプリの@themeマッピング、@utility定義、@layer base、@font-faceルールを含むため、本番環境のクラス名とフォントが忠実に表示されます）。また、セルフホストのフォントをコピーし、main.js（Tailwind Vite プラグインと自動 JSX ランタイム）とpreview.jsx（抽出されたモード名に基づくテーマツールバー／デコレーター）にパッチを適用します。返されたmanualStepsを適用してから、開発サーバーを再起動してください。.storybook/mainのストーリーの glob にsrc/**/*.mdxが含まれていることを確認します。生成されたsrc/docs/*.mdxページは、トークン／タイポグラフィ／アイコノグラフィのショーケースです。

フェーズ 4 — コンポーネントを移植する（ループ）

コンポーネントごとに、使用頻度の順位に従って進めます。

1. figma_ds_extract_component { outDir, component: "Button" } — ソース、ローカルインポートの 依存関係、プロパティの契約、確認された呼び出し元でのバリエーション、スタイルの関連箇所、CSF3 ストーリーの スキャフォールドが得られます。
2. <outDir>/src/components/<Name>/ に移植します — 各コンポーネントには、独自のディレクトリ、コンポーネント ファイル、ストーリーファイル、インデックスを用意します（ファイルを単一にまとめないでください）。アプリ固有のインポート （ルーティング、データ取得、グローバル状態）を切り離し、ハードコードされた値はトークンに置き換えます（ styleTouchpoints.customProperties と tokens.json を照合してください）。
3. ストーリーのスキャフォールドを調整します — 実際の バリエーション（observedProps）ごとにストーリーを 1 つ作成し、 tags: ['autodocs'] を指定します。
4. 完了とする前に、Storybook（ブラウザー）で視覚的に確認します。
5. figma_ds_status { outDir, update: { component, status: "ported", storyFile } }。

長期にわたる作業では、セッション開始時に figma_ds_status { outDir } を実行すると、どこまで進んだかが正確に わかります。

フェーズ 5 — コード主導の区切り

ビルド可能でバージョン管理されたパッケージを作成します。コンポーネント、トークン、Storybook を含めます。組織で使用している 公開・バージョン管理の仕組み（changesets、プライベートレジストリなど）を設定します。その後、各プロダクトはローカルコピーの代わりに @org/design-system を利用します — この移行は別の作業となります。

フェーズ 6 — デザイン主導：Figma へ

1. トークン → 変数： tokens/tokens.json を指定して figma_import_tokens を実行します（最上位のグループは コレクションになり、Light／Dark モードも引き継がれます）。まず strategy: "dry-run" でプレビューします。
2. コンポーネント → Figma： 既存のツール（figma_create_component_set、figma_execute）または figma-generate-library ／ prototype-to-figma ワークフローを使って、主要なコンポーネントをコンポーネントセットとして再構築します。塗り、線、角丸を インポートした変数にバインドし、Figma とコードで同じトークンソースを共有します。
3. 以降の同期ループでは、差分を認識したマージを行う figma_export_tokens ／ figma_import_tokens を使用します。

境界と注意点

• figma_ds_* ツールはローカルモード専用です（ローカルファイルシステムを読み書きします）。
• 抽出によって対象アプリが変更されることはありません — すべて outDir 以下に配置されます。
• パスは必ず絶対パスを指定してください。MCP サーバーの作業ディレクトリはプロジェクトとは異なります。
• 生成された投影ファイル（tokens.css、theme.css など）を手動で編集しないでください。tokens.json（または ソースアプリ）を編集して再生成します。
• 各トークンの $extensions["figma-console-mcp.extraction"] に出所情報があります。これを使って、ユーザーに判断の根拠を 説明してください（「これは 214 回使われているため、主要なものです」）。