sb-figma

sb-figma — Figma ↔ Storybook ブリッジ

sb-figma は、承認済みのデザインを本番 Storybook に反映し（ジョブ 1〜2）、コード上の正しい状態を Figma に戻します（ジョブ 3、およびオプトインでの書き込み）。Figma MCP を使用しますが、探索用のスキルではありません。

前提条件 — 最初の呼び出しの前に確認

ジョブ	必要なもの	ツール
トークンの読み取り（ジョブ 1、推奨）	ファイルへの編集アクセス権、リモートサーバー	use_figma（読み取り専用スクリプト）
トークンの読み取り（フォールバック）	いずれかのシート	get_variable_defs
コンポーネントの反映（ジョブ 2）	いずれかのシート	get_design_context、get_metadata、download_assets
Code Connect（ジョブ 3）	Organization または Enterprise プラン、公開済みのライブラリコンポーネント	get_code_connect_suggestions、get_context_for_code_connect、send_code_connect_mappings
Figma への書き込み（オプトイン）	既存のファイルには Full シート（下書きへの書き込みはどのシートでも可能）、リモートサーバー、ベータ版	use_figma、generate_figma_design

• リモートサーバー（https://mcp.figma.com/mcp）を優先してください。デスクトップサーバーでは、書き込み、コードからキャンバスへの反映、スキルのいずれも利用できません。
• レート制限はプランとシートごとに設定されています（Starter の View／Collab シートでは月に数回、Dev／Full シートでは 1 日あたり約 200 回の呼び出しが可能です）。whoami、add_code_connect_map、create_new_file は回数に含まれません。
• アクセス、権限、またはレート制限のエラーで呼び出しに失敗した場合は、whoami を呼び出し（プランとシートを確認）、再試行する代わりに不足しているものを報告してください。
• Figma 独自のスキル（figma-use、figma-design-to-code、figma-code-connect、figma-generate-design）は Figma プラグインに付属しています。プラグインがない場合は、MCP から skill://figma/<name>/SKILL.md として読み取ってください。スキルが必要なツールは説明にその旨が記載されています。先にスキルを読み込み、skillNames を渡してください。

ライフサイクルの流れ（最初に読み込んでください）。 未決定／選択肢を試している段階 → sb-explore（Lab サンドボックスで Figma ノードを対象に反復）→ sb-ship（Lab の実験を正式な成果物にする）。Figma ですでに承認済み → sb-figma（本番に直接反映）。どちらも Figma MCP を使用しますが、違いは探索と反映です。ユーザーがまだ検討中の場合は、sb-explore に引き継いでください。references/figma-token-sync.md を参照してください。

各実行から学ぶ — ギャップとプロジェクトルール

各実行はここから始まり、ここで終わります。

1. まず未解決のギャップを読み取ります。 node scripts/workbench-settings.mjs gaps を実行してください。それぞれのギャップには、前回の実行でできなかったことと、その修正方法が記載されています。新しい作業を始める前にユーザーに示してください。
2. スクリプトは進行中にギャップを .storybook/figma/gaps.json に記録します。 collision（複数の Figma 変数が 1 つのトークンに対応）、weak-match（最後の単語だけで名前が一致）、unmapped-name（対応するコードトークンがない Figma 変数）、unsupported-value（パリティチェックで読み取れない色の構文）、unmapped-variant-value（対応するコードの値がない Figma バリアント値）です。後の実行で見つからなくなったギャップは、解決済みとしてマークされます。
3. 自分だけが把握している情報を記録します。 確認する必要があった、対応トークンのない値（missing-token）や、Figma に拒否されたツール（tool-refused）を記録してください。 node scripts/workbench-settings.mjs add --kind missing-token --detail "icon #116932 has no token" --suggestion "…"。
4. ギャップはスキルを編集せず、プロジェクトルールで修正します。 ルールは .storybook/workbench.json にあります（ひな形：node scripts/workbench-settings.mjs --init、スキーマ：references/workbench.schema.json）。このファイルはプロジェクトが管理するため、スキルの更新で上書きされることはありません。また、コマンドラインフラグが引き続き優先されます。
   • css — トークンの CSS の場所 · darkSelectors — ダークテーマを示すセレクター
   • nameMap — "fg/error": "--color-error-text"：名前の推測より優先され、名前の衝突を解決します
   • ignore — 対象外にする Figma 変数（"Size/*"） · variantValues — "status - success": "success"
   • codeConnectLabel — Code Connect のデフォルトラベル
5. ルールで修正できないもの（未対応の色の構文、誤った結果など）がある場合は、report-issue.sh --gaps を実行してください。未解決のギャップを種類ごとの件数として含む、サニタイズ済みのイシューの下書きが作成されます。名前や値は含まれません。

ジョブ 0 — MCP の出力を取得する（必ず最初に行うこと）

NATIVE の構造化ツールを必ず使用してください — スクリーンショットを基に作業してはいけません。 スクリーンショットはピクセル情報であり、変数、スタイル、コンポーネントの props は取得できません。全体像を把握できるのはネイティブの MCP ツールだけです。ビルドや接続を始める前に、次の 3 種類すべてを取得する必要があります。

• 変数 → get_variable_defs（解決済みのトークン値：色／間隔／書体／エフェクト）。
• コンポーネント + スタイル → get_design_context（参照コード、適用済みスタイル、props／バリアント）。
• 構造 → get_metadata（ノードツリー。途中で切り詰められた場合は、子ノード ID をたどってください — 親ノードで諦めてはいけません）。 get_screenshot は視覚的な参照専用です — 構造化データから構築した後に目視で差分を確認するためのものです。スクリーンショットからトークン、props、レイアウトを読み取ってはいけません。ページ ID を指定してツールが「nothing selected」を返した場合は、具体的なコンポーネントノードをたどってください（ページはレイヤーではありません）。

スクリプトから Figma MCP を呼び出すことはできず、MCP の結果はエージェントのコンテキストにしか存在しません — 一時的なものであり、次のセッションでは消え、ヘッドレス環境にもありません。そのため、使用する前に、呼び出す Figma MCP の結果をすべてユニバーサルストアに保存してください。これにより、パイプラインを再現可能かつ反復可能にできます。

# pipe each tool's output straight in (JSON, code text and XML are all stored as returned):
<get_variable_defs output>  | node scripts/capture-figma.mjs --tool get_variable_defs   --file <FILE> --node <NODE> --from-mcp -
<get_design_context output> | node scripts/capture-figma.mjs --tool get_design_context  --file <FILE> --node <NODE> --from-mcp -
<get_metadata output>       | node scripts/capture-figma.mjs --tool get_metadata        --file <FILE> --node <NODE> --from-mcp -
<get_code_connect_map out>  | node scripts/capture-figma.mjs --tool get_code_connect_map --file <FILE> --node <NODE> --from-mcp -
# get_screenshot returns an image — save it, then register the file:
node scripts/capture-figma.mjs --tool get_screenshot --file <FILE> --node <NODE> --image /tmp/frame.png
# see the whole inventory (degrade / iterate):
node scripts/capture-figma.mjs --list

ストアの構成：.storybook/figma/manifest.json + .storybook/figma/<tool>/<node>.json（画像は拡張子を保持します）。同じ（tool,node）を再取得すると上書きされます — Figma 上で何が変わったかを確認するには、git と比較してください。後続の手順ではストアを読み込み、MCP を再度呼び出してはいけません。

MCP の実情（2026-06-22 に実地確認済み；ツールスキーマは 2026-10-01 に再確認済み）

稼働中の Figma MCP が実際に返す内容 — スクリプトはすでにこれらに対応しています。出力に振り回されないよう、内容を把握しておいてください。

• get_variable_defs はフラットな { "name": "value" } マップです（ネストされた DTCG 形式でも配列でもありません）。色はすでに 16 進数に解決済みで返されます（"semantic/background":"#fbfcfc"）。8 桁のアルファ値も含まれます（"#e4e5e580"）。数値は単なる文字列です（"spacing-2":"8"、"wght/semibold":"650"）。タイポグラフィは不透明な Font(family: …, size: …) 文字列です — pull-figma-variables が {family,size,weight,lineHeight,…} に解析します（フィールド自体が size/text-lg のような変数名参照の場合もあります）。シャドウは Effect(…) → effect ファミリーです。classify() は値に基づいて分類します。
• get_metadata は XML を返し、大きなフレームでは途中で切り詰められます（テーブルビューはトークン上限を超えました）。切り詰められた場合は、部分 XML から子ノード ID を確認し、親ではなくサブノードに対して get_design_context／get_metadata を呼び出してください。再取得が不要になるよう、各サブノードをストアに保存してください。
• ノード ID：URL では 1-6965、API の例では 1:6965 が使われます。どちらの形式もすべてのツールで使用できます。 capture-figma はダッシュ形式でキャプチャを保存するため、どちらの形式でも見つかります。また、すべてのツールには URL から取得した fileKey が必要です（figma.com/design/<fileKey>/…；ブランチ URL の場合はブランチキーを使用します）。
• get_design_context はコードテキストとデフォルトのスクリーンショットを返し、get_metadata は XML を返します。 JSON を返すのは get_variable_defs と use_figma 読み取りスクリプトだけです。
• 保存とスクリーンショット↔ノードの関連付けはジョブ 0 で解決済みです — ストアにはノード ID とともにすべての出力がマニフェストに保存されるため、スクリーンショットを手動で相互参照したり、MCP を再度呼び出したりする必要はありません（以前はどちらも実際に支障の原因となっていました）。

ジョブ（すべてジョブ 0 のストアを読み込みます）

ジョブ 1 — 基礎トークン → Foundations/Colors|Tokens|Type（sb-figma がこれらを直接書き込みます）

Figma の変数をコードのトークンにマッピングするスキルはほかにないため、基礎の整合性は sb-figma がエンドツーエンドで担います。

1. 変数を読み取る — すべてのモード。 推奨：Figma の figma-use スキル（または skill://figma/figma-use/SKILL.md リソース）を読み込み、references/read-figma-variables.js の内容を code として、skillNames: "figma-use" を指定して use_figma を呼び出します。読み取りのみを行い、ローカルの すべてのコレクションとすべてのモード（Light、Dark、…）を対象に、エイリアスを解決します。大規模なシステムでは 出力が約 20 kB に制限されるため、ONLY にコレクションを 1 つ指定し、コレクションごとに 1 回呼び出します。結果を 保存します（ジョブ 0）。 use_figma を実行できない場合（ファイルへの編集アクセスがない場合）の代替手段：トークンを使うノードに対して get_variable_defs を実行します。そのノードが使う変数のみが、1 つのモードで返されるため、Dark は比較されません。 ファイルが使用しているものの所有していないライブラリ変数については、get_libraries を実行してから、 {"entity":"variable", …} を指定して search_design_system を実行します。
2. 正規化 — node scripts/pull-figma-variables.mjs --from-mcp .storybook/figma/<tool>/<NODE>.json --out .storybook/figma-variables.json。 どちらの形式も受け付けます。デフォルトモードでは color／spacing／type が設定され、ほかのモードは modes に格納されます。--from-mcp を指定しない場合は、最後にキャッシュされたデータを再利用します（ヘッドレス時の フォールバック経路）。
3. 整合性を構築 — node scripts/build-token-parity.mjs --variables .storybook/figma-variables.json --css <token-css-glob> --out .storybook/figma-token-parity.json。 CSS はテーマごとに読み取られます。:root がデフォルト、.dark／[data-theme=dark]／dark の @media ブロックが ダークテーマです。Figma のデフォルトモードはデフォルトテーマと比較され、Figma の「Dark」モードは ダークテーマと比較されます（出力では modes.Dark）。OKLCH のチャンネルトリプレットは hex に変換され、 semantic/* は var() のエイリアスチェーンに沿って、プロジェクトの --token にマッピングされます。
4. 基礎のストーリーを接続します。TokenMatrix に figmaParity を渡すと（figma-token-parity.json を読み取ります）、 色の表の問題列に差分が表示されます（ホバー時に figma Δ、code #X vs figma #Y）。フィールドは任意です。Figma ファイルがないプロジェクトでは、従来どおりに表示されます。
5. sb-health の形式で差分を報告します。Figma の値 ≠ コードの値（色は OKLCH から hex への変換で許容誤差を適用し、 spacing／type は完全一致）、モードごとに報告します。アプリ固有のロール（--popover、--ring、…）は想定内であり、 エラーではありません。

ジョブ 2 — 承認済み Figma コンポーネントから本番環境へ（sb-figma が配信し、sb-stories が作成）

1. まず配信サイズを見積もります。大きなボードは分割してください。 複数のアートボードを含む機能（フロー全体、多くのセクションを含む画面）は、MCP のトークン予算を超えてしまいます。アートボードまたはセクションごとに分割し、1 つずつ配信、検証、記録してから、次に進みます。Figma Inventory（ステップ 8）では、各パーツのストーリーを統合します。
2. Figma のデザインからコードへのガイダンスを読み込みます。 get_design_context では必須になりました。/figma-design-to-code スキル（Figma プラグイン）を使用するか、skill://figma/figma-design-to-code/SKILL.md MCP リソースを読み込み、呼び出し時に skillNames: "figma-design-to-code"（リソースから読み込む場合は "resource:figma-design-to-code"）を渡します。clientFrameworks／clientLanguages（例：react、typescript）を設定します。
3. 抽出します（Job 0 のストアに保存）。 get_design_context を 1 回呼び出すと、参照コード、アセットのダウンロード URL、スクリーンショットが返されます。これらを保存してください。メタデータのみが返された場合（サイズが大きすぎる場合）は、親ノードではなく、そこに記載された子ノードを取得します。構造だけが必要な場合は、get_metadata でツリーを取得できます。
4. 作成する前に再利用します。 Code Connect でマッピングされたコンポーネントは、デザインコンテキスト内で実際のインポートとして返されます。これらを使用してください。それ以外の場合は、同じ概念を扱う既存のコンポーネントを grep で探し、拡張します（guardrails §8 step 3）。search_design_system を使うと、ライブラリのコンポーネントを名前で検索できます。
5. アセット。 まず、プロジェクト内に完全一致するものがあれば使用します（例：アプリで使用しているアイコンパッケージの同じアイコン）。それ以外の場合は、get_design_context のレスポンスに記載された方法で各アセットをダウンロードし、プロジェクトのアセットフォルダーに保存します。プレースホルダー、新しいアイコンパッケージ、コードに残る一時的な Figma アセット URL は使用しないでください。
6. 承認済みのトークンとプリミティブのみを使って構築します。 マジックナンバーではなく、トークンを使用してください。Figma の値に対応するトークンがない場合は、作業を止めて確認します（トークン不足のタスクとして Job 1 にするか、ユーザーに確認します）。参照コードは適応させるための出発点であり、そのまま貼り付けるものではありません。
7. sb-stories の規約に従ってストーリーを作成します（実質的に異なる状態のみを作成し、3 つ以上のストーリーで同じ形状を共有する場合はファクトリーを使用）。ノード ID をファイル先頭のコメントと parameters.design に記載し（共有の仕組みを利用）、保存したスクリーンショットと照らし合わせて、ライト／ダーク／モバイル表示を検証します。
8. 配信内容を Figma Inventory に記録します。これにより、この機能で作成したストーリーが分類体系の中で散らばるのを防げます。冪等性があるため、配信ごとに再実行できます。ストーリーは ID で統合されます。

   python3 scripts/record-figma-delivery.py . \
     --figma-url "<board url>" [--feature "<Name>"] --spec-url "<spec node url>" --node-ids 101-9717 \
     --description "<one line>" \
     --story "Hunts/Hunt Packs:hunts-hunt-packs--default:component"   # repeat per story you created
   

   次に、ルートのサーフェスが存在することを確認します。scaffold-wrapper.sh --figma を使って一度だけスキャフォールドし、figma-inventory.stories.tsx テンプレート（タイトルは Figma Inventory）を配置します。機能ごとにエクスポートを 1 つずつ追加し（export const Hunts = { args: { feature: 'Hunts' } }）、.storybook/preview の options.storySort.order: ['Figma Inventory', '*'] で先頭に固定します。FigmaInventory ラッパーは figma-inventory.json を読み込み、インデックスと各機能のボードリンク、およびその機能で追加されたストーリーを表示します。

ジョブ 3 — 接続：Storybook → Figma（コード → デザイン）

コードの実態を Figma に反映し、Figma Dev Mode で実際のコンポーネントを表示できるようにします。Code Connect を利用するには、Organization または Enterprise プランと、公開済みライブラリのコンポーネントが必要です（前提条件を参照）。Figma の手順に従ってください。すべての呼び出しは Job-0 のストアを経由します。

1. アクセスを確認する — whoami。Org／Enterprise プランでない場合は停止し、その旨を伝えます。Dev Mode にマッピングは表示されません。
2. コンポーネントを探す — ページまたはフレームに対して get_code_connect_suggestions を実行します（マッピングされていないコンポーネントを絞り込んで一覧表示するには excludeMappingPrompt: true を指定します）。
3. それぞれを読み取る — コンポーネントのノードごとに get_context_for_code_connect を実行し、プロパティ、バリアントの選択肢、子孫ノードを確認します。対応するコードコンポーネントと照合します（該当ノードの parameters.design を持つストーリーが最も確かな手がかりです。それがない場合はコンポーネント名を使います）。
4. ペイロードを作成する — comps.json（component、codeFile、figmaNode、省略可能な componentName、label、tokens、variantProperties、modes）を書き込み、次に以下を実行します。

   node scripts/build-code-connect.mjs --components comps.json --file <FILE_KEY> \
        --parity .storybook/figma-token-parity.json --usage .storybook/component-usage.json \
        --out .storybook/code-connect.json
   

   send は send_code_connect_mappings の入力そのものです（fileKey、nodeId、mappings[{nodeId, componentName, source, label}]）。context には、確認用のトークン、実際のプロパティ、バリアントからプロパティへのマッピングが格納されます。reverseParity には、Figma ノードまたはソースがないコンポーネント、未対応のラベル、ずれが生じたトークンが一覧表示されます。
5. 確認してから送信する — マッピングをユーザーに提示し、承認後、send をそのまま指定して send_code_connect_mappings を呼び出します。マッピングが 1 つだけの場合は、add_code_connect_map も使えます。どちらも Figma に書き込みます。
6. プロパティレベルのスニペット（省略可能） — 通常のマッピングで表示されるのはインポートとコンポーネントです。プロパティ（バリアント選択からコードのプロパティへの対応）をマッピングするには、Code Connect テンプレートを記述します。@figma/code-connect CLI 2.x では Component.figma.ts を使います（2.0 以降、保守されている形式はテンプレートファイルのみです。.figma.tsx と figma.connect() は移行専用です）。または、マッピングに template を渡します。テンプレートについては、Figma の /figma-code-connect スキルを参照してください。入力には context[].propMappings を使います。

Figma ノードのないコンポーネント（componentsWithoutNode）には接続先がありません。作成は書き込み操作です（以下を参照）。

このループが完了します。配信時（ジョブ 1〜2）に追加した parameters.design のノード ID を、ジョブ 3 が読み取って接続に使います。

Figma への書き込み（オプトイン、デフォルトではオフ）

ユーザーから明示的な依頼があった場合のみ実行し、書き込みのたびに確認してください。ユーザーのファイルに変更を加えます。既存ファイルには Full シートが必要です（前提条件を参照）。

• デフォルト：use_figma（最初に figma-use をロードし、skillNames: "figma-use" を指定します）。ファイル独自のコンポーネントと変数（search_design_system）を使って作成し、作成したノード ID をすべて返して記録します。
• トークン → Figma 変数（コレクションを作成するか、Light と Dark の両方を含む既存のコレクションを更新します）。

  node scripts/build-figma-variables.mjs --css "src/**/*.css" --prefix "--color-bg,--color-text-" \
       --collection "Code tokens" --out .storybook/figma-variables-push.json
  

  references/write-figma-variables.js にエントリを 1 つ PAYLOAD として貼り付け、use_figma で実行します。まずは DRY = true にしてください。作成・更新される内容が返されます。それをユーザーに提示してから、DRY = false で実行します。同名のコレクションまたは変数があれば再利用し、値を上書きします。削除はしません。ジョブ 1 で確認してください。コレクションを読み戻してパリティを実行し、差分がゼロであることを確認します。
• generate_figma_design は、レンダリング済みのページを初回に取り込む場合のみ使用します — たとえば、単独でレンダリングしたストーリーの場合：http://localhost:6006/iframe.html?id=<story-id>&viewMode=story。ピクセル単位のコピーが作成されるため、ライブラリのコンポーネントを使って use_figma で調整します。すでに取り込み済みのページを更新する場合は、use_figma を使います。
• 書き込み後、新しいノード ID をストーリーの parameters.design に戻して追加します。ジョブ 2〜3 でそのノードを確認できます。

共通の仕組み — Figma デザインの埋め込み（Docs）

sb-figma が扱うすべてのストーリーでは、カタログページにデザインソースが保持されます。

parameters: { design: { type: 'figma', url: 'https://figma.com/file/<FILE_ID>?node-id=<NODE_ID>' } }

これは @storybook/addon-designs（「Design」タブ）で、フレームに対して sb-explore が使うものと同じ仕組みです。さらに、parameters.docs.description にノード ID のスタンプとリンクを追加します。ノード ID がわかっている場合、sb-explore と sb-stories はこのスニペットを再利用できます。

境界 — 兄弟ツールの動詞を決して重複させない

• 探索／「v2 を試す」／未決定 → sb-explore（Lab）。sb-figma は 承認済み デザインのみを対象とします。
• Lab の実験を正式採用する → sb-ship（cp を保持し、呼び出し箇所を書き換えます）。sb-figma が成果物を提供するのは Figma からであり、/explore/ の実験からではありません。
• 既存のコードコンポーネントをドキュメント化する（Figma なし） → sb-stories。sb-figma は作成時に sb-stories のルールを 呼び出し、再実装はしません。
• コード内部のトークンの健全性／孤立した要素 → sb-health／sb-inventory（Figma 不要）。sb-figma は、これらでは把握できない デザイン↔コード の整合性を追加します。

エージェントが最初に解決すべき入力

• Figma ファイルの URL → すべてのツールで必要な fileKey。ジョブ 2～3 では ノード URL も必要です（get_variable_defs のフォールバックでは、トークンを使用するフレームが必要です）。貼り付けられていない場合は確認してください。
• トークン CSS のパス — --token: <value> 宣言がある場所（例：src/styles/**/*.css）。
• デザインは承認済みですか？ ユーザーがまだ反復中の場合 → 停止し、sb-explore に案内してください。
• ジョブ 3 と書き込みに必要なプランおよびシート — 前提条件（whoami）を参照してください。

次の手順

まずジョブ 1（トークン）を実行し、ジョブ 2 で構築するコンポーネントが、実際の整合性確認済みトークンを使用するようにします。クリーンな状態から再開できるよう、進捗を .storybook/audit/status.md に追記してください。呼び出し順序の全体と OKLCH→hex に関する注意事項： references/figma-token-sync.md。