figma-bridge-mcp

AIアシスタントがFigma Desktopのデザインを検査、作成、更新できるローカルMCPサーバーです。小さなFigma開発プラグインを介して接続し、スクリーンショット、デザイン仕様、JSXレンダリング、トークン、アセット、コンポーネント、FigJam、Figma Slidesに特化したツールを公開します。

すべては127.0.0.1上で動作します。Figma Personal Access Tokenは不要です。クラウドも不要です。Figmaアプリのバイナリパッチも不要です。

オプションのRESTアドオンは、バージョン履歴、コメント、公開ライブラリのメタデータを追加します。そのFigmaトークンはあなたのマシンに留まり、MCPクライアントの設定やチャットに配置されることはありません。

要件: Node.js 18以降、Figma Desktop、およびローカルのstdioサーバーを起動できるMCPクライアント。

Codex、Claude Code、Cursor: MCPとスキルをひとつのバンドルに

Figma Bridgeは、3つの焦点を絞った共有スキルと、3つのクライアントすべてに対応する薄いプラグインアダプターを提供します:

• figma-bridge-design-to-code — ターゲットスタックでの正確なFigma実装

• figma-bridge-code-to-figma — コードからのセマンティックでコンポーネント化された画面

• figma-bridge-component-library — トークン、スタイル、コンポーネント、バリアント、プロパティ

アダプターはすべて同じskills/ディレクトリを検出し、同じローカルMCPパッケージを起動します。ユーザーはスキルを個別にダウンロードしたり管理したりする必要はありません。

Codexの場合、このリポジトリをマーケットプレイスとして追加し、バンドルをインストールします:

codex plugin marketplace add KaiUweHella/figma-bridge-mcp
codex plugin add figma-bridge-mcp@figma-bridge

これはGitHubでホストされているリポジトリマーケットプレイスであり、ユニバーサルなOpenAIプラグインディレクトリへの提出ではありません。カタログはリポジトリに従いますが、リリースされた各プラグインエントリは正確なv<version> Gitタグを固定し、対応するnpmランタイムバージョンを起動します。したがって、mainや@latestがインストール済みのスキルバンドルを異なるサーバー契約に静かに移動させることはできません。

Claude Codeの場合、このリポジトリをマーケットプレイスとして追加し、バンドルをインストールします:

claude plugin marketplace add KaiUweHella/figma-bridge-mcp
claude plugin install figma-bridge-mcp@figma-bridge

Claudeマーケットプレイスは、同じ固定されたGitHubリリースと共有スキルツリーを使用します。プラグインはnpxを介してローカルのstdioサーバーを起動するため、ユーザーがそのリリースをインストールする前に、対応するnpmパッケージが公開されている必要があります。

Cursor TeamsまたはEnterpriseの場合、このGitHubリポジトリをチームマーケットプレイスにインポートし、CustomizeからFigma Bridgeをインストールします。個人ユーザーやコントリビューターは、中央のCursorリストなしで同じGitHubソースを使用できます: タグ付きリリースをクローンし、そのチェックアウトをCursorにリンクし、ウィンドウをリロードします:

mkdir -p ~/.cursor/plugins/local
ln -s /absolute/path/to/figma-bridge-mcp ~/.cursor/plugins/local/figma-bridge-mcp

CursorはルートのAgent Pluginマニフェストを検出し、スキルとMCPサーバーの両方をロードします。

プラグインやAgent Skillをサポートしていないクライアントは、以下の通常のサーバー設定を引き続き使用します。それらは、MCP命令、ユーザーが呼び出すdesign-to-code、code-to-figma、create-figma-component MCPプロンプト、およびfigma_reference {name:"workflow"}を通じて、コンパクトな必須ワークフローを受け取ります。

クイックスタート

1. MCPサーバーを追加する（MCPのみのフォールバック）

完全なプラグインインストールが利用できない場合や、バンドルされたスキルなしでMCPツールのみが必要な場合に使用します。npxセットアップはクローンやビルド手順を必要としません。Claude Codeの場合:

claude mcp add figma-bridge -- npx -y figma-bridge-mcp@latest

別のMCPクライアントの場合は、同等のサーバー設定を追加します:

{
  "mcpServers": {
    "figma-bridge": {
      "command": "npx",
      "args": ["-y", "figma-bridge-mcp@latest"]
    }
  }
}

MCPクライアントがすぐにサーバーを検出しない場合は、再起動してください。意図的にenvブロックはありません: ブリッジはペアリング中にローカル認証情報を作成します。

git clone https://github.com/KaiUweHella/figma-bridge-mcp.git
cd figma-bridge-mcp
npm install

{
  "mcpServers": {
    "figma-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/figma-bridge-mcp/src/server.js"]
    }
  }
}

2. Figma Desktopを一度ペアリングする

1. AIアシスタントにFigmaに接続するよう依頼するか、直接figma_connectを呼び出します。ローカルブリッジが起動し、アクセスキーとプラグインマニフェストのパスが返されます。

2. Figma Desktopで: Plugins → Development → Import plugin from manifest… を選択し、~/.figma-bridge-mcp/plugin/manifest.json（figma_connectが返したパス）を選びます。

3. Plugins → Development → Figma Bridge を開き、アクセスキーを貼り付けて、Save & connect をクリックします。

4. プラグインに Connected (authenticated) と表示されたら、アシスタントはそのFigmaファイルで作業できます。ペアリングは記憶されます。以降のセッションでは、使用したいファイルでプラグインを再度開くだけです。

Figma Dev Modeは別のアダプターが必要です。Figmaは既存のFigJamエディターターゲットとdevを1つのマニフェストで組み合わせることをサポートしていないためです:

• Figma Bridge Dev Mode用に~/.figma-bridge-mcp/plugin/manifest.dev.jsonをインポートします。これにより、認証されたMCPブリッジが選択、検査、仕様、エクスポートのために接続されたままになります。Dev Modeは読み取り専用であるため、レンダリングやキャンバス編集には、ファイルをDesignモードに切り替え、通常のFigma Bridgeプラグインをそこで開く必要があります。

3. Figmaで使用する

Figmaでフレームまたはレイヤーを選択し、希望する結果を説明します。例:

• "現在の選択を検査し、そのレイアウトを説明してください。"

• "選択したフレームの隣に設定カードを作成してください。"

• "選択した画面のトークンとアセットをこのプロジェクトにエクスポートしてください。"

• "選択したフレームを実装し、その結果をFigmaと比較してください。"

アシスタントは現在の選択を読み取り、スクリーンショットや仕様をキャプチャし、JSXをレンダリングし、アセットをエクスポートし、または対象を絞った編集を適用できます。アシスタントがアクセスするすべてのドキュメントでFigma Bridgeプラグインを開いたままにしてください。複数のドキュメントが接続されている場合は、Figma URLまたはファイルキーを渡してターゲットを明確にしてください。

Related MCP server: tellfigma

仕組み

MCP client ──stdio──▶ figma-bridge-mcp (src/)
                        │
                    MCP tool adapters ─▶ Capability Catalog ─▶ CommandPlan
                                                                  │
                                          ┌───────────────────────┴──────────┐
                                  Command Application Modules   generic CLI adapter
                                             │            │
                                      Design Capture      │
                                      Asset Policy        │
                                             └──────┬─────┘
                                      Daemon Client Module
                                             │  HTTP: signed requests
                                             ▼
                                  local daemon :3456–3460
                                             │  WS: challenge/response
                                             ▼
                                  Figma Bridge plugin in Figma Desktop

• エンジンはengine/の下にあります。figma-ds-cli v2.1.0のフォークとして始まり、そこから大きく分岐しています（帰属を参照）。Chrome DevToolsの「Yoloモード」（Figmaアプリのバイナリをパッチするもの）は完全に削除されました。それへのコードパスはありません。

• 特殊化されたMCP読み取り（figma_spec、figma_inspect、figma_screenshot）は、値を返すCommand Application Modulesを介して直接実行されます。MCPとCLIは同じ実装に対する薄いアダプターです。汎用のfigma_runは、意図的に広範な子プロセスCLIアダプターとして残されています。1つのDaemon Client Moduleが、両方のパスの署名、タイムアウト、トランスポートエラーを管理します。

• Design Capture Moduleは、明示的なノードを一度だけ走査し、構造、スタイル、およびそれらの同じ事実からのロスレス出力形式をローカルに投影します。キャプチャは、安価なリビジョンプローブが認証されたプラグイン接続とFigmaドキュメントリビジョンが変更されていないことを証明した後にのみ再利用されます。リビジョンメタデータがないか不安定な場合は再利用が無効になります。選択および名前付きセクションの呼び出しは、この最初のスライスではキャッシュされません。キャプチャは、作成されたFigma Auto Layout/Grid、FigmaのマークされたinferredAutoLayoutヒューリスティック、およびジオメトリフォールバックを区別します。また、後続のネイティブFigma注釈とは別に、Code-to-Figmaのセマンティック/フォールバックメタデータ、および完全なコンポーネントと変数モードの契約を保持します。

• Design Link Registryは、コンポーネント、画面、またはフレームに1つの永続的でリポジトリが所有するDesign Entity IDを付与します。figma-bridge.jsonはポータブルなコード/Storybook/Figmaリンクを保持します。Figmaプラグインデータは同じIDと種類のみを保持します。この二重アンカーにより、将来のエージェントはリポジトリパスをFigmaドキュメントに配置することなく、どちら側からでも正確な既存コンポーネントを解決できます。

• レポート専用のRound-trip Plannerは、現在のコードと現在の正規化されたFigmaサブツリーを、明示的にAccepted Design Baselineと比較します。Project Design Contextは、そのステータス、エンティティリンク、および正確な次の読み取りを、1つのインプロセスCommand Applicationを通じて投影します。セマンティックパスが存在する場合、変更されたサブツリーは現在のノードIDとともに報告されます。プラグインマーカー自体は視覚的な変更としてカウントされません。

• Design Contractは、リンクされた1つのDesign Entityの完全なDesign Captureを決定論的なリポジトリゲートに変換します。figma_run ["contract", "capture","ui.button"]を一度実行し、JSONを確認します。後でfigma_run ["contract","check","ui.button"]を実行すると、正規のドリフトを報告し、バリアントマトリックス、トークンバインディングフロア、ジオメトリ許容差、プロトタイプ遷移を個別に強制します。揮発性のFigmaハンドルは無視され、深さ制限のあるキャプチャは拒否されます。

• 1つのCapability Catalogは、MCPを介して入力されるすべてのFigma Commandを、いずれかの実行アダプターが実行する前に不変の計画に解決します。その計画は、公開、Figma/ワークスペース/共有状態への影響、ターゲットの必要性、確認、正規化されたパス、リトライ、タイムアウト、受け入れられる終了コード、バックグラウンドジョブIDの唯一の情報源です。未知のコマンドはデフォルトで拒否/書き込み/リトライなしとなります。

• 1つの不変のFigma Target Contextは、明示的なfileKey、貼り付けられたFigma URL、または暗黙的な単一ウィンドウターゲットをコマンドごとに一度解決し、その後、計画、監査、ジョブID、デーモン実行に付随します。1つの共有Asset Policyは、Design Captureの投影とエクスポートの両方のために、画像フィル、ベクターアート、ベクタークラスターを分類します。

• ランタイムプロトコルバリデーターは、トランスポート境界で不正な形式のHTTP実行ペイロードとプラグインフレームを拒否します。TypeScriptはJavaScriptの継ぎ目（Figmaプラグインを含む）をチェックし、決定論的なコンテキスト、ペイロード、中央値およびテールレイテンシ予算は、CIでアーキテクチャの回帰をキャッチし、短い共有ランナースケジューリングの一時停止を持続的な回帰として扱いません。

• デーモンは、localhost WebSocketを介してFigmaプラグインにコマンドを仲介します。2つのゲートがそれを保護します:

  • HTTPルート（/health、/exec）は、セッショントークン（0600ファイル）でキー付けされたリクエストごとのHMAC署名を必要とします。トークン自体は決してワイヤーを通過しません。

  • プラグインWebSocket（/plugin）はアクセスキーを必要とします: Origin/Host許可リストと、キーがHMACシークレットとしてのみ存在し、これも決してワイヤーを通過しない相互チャレンジレスポンスハンドシェイク。これにより、任意のローカルプロセスがプラグインソケットに接続してFigmaドキュメント内でコードを実行できるという上流のギャップ、およびローカルポートで応答するものが正当なプラグインを駆動できるという逆のギャップを閉じます。

ノードIDは、ユーザーが手元にあるすべての形式で受け付けられます：12:34、URL形式の 12-34、または完全なFigma URL（そのファイルキーは実際に開いているファイルと照合されます — 複数のファイルを同時に を参照）。

書き込みコマンドは、サーバーの環境で FIGMA_WRITE_CONFIRM=1 を設定することで、明示的な confirm:true のゲートをかけることができます。このゲートはサブコマンドレベルで機能します：node tree や component list のような読み取りは自由に通過し、node delete、combos、tokens spacing のような変更には確認が必要です。

ネイティブJSXインスタンスには、永続的なRegistry ID（entity と公開された key またはローカルの id）が必要です。編集可能なオーバーライドは、コンポーネントの実際のFigma構造を使用します：

<Instance entity="ui.card" key="..."
  prop:Selected="true"
  text:Title="New title"
  fill:StatusDot="var:status/healthy|#22c55e"
  swap:LeadingIcon="ui.icon.leaf" />

prop: はコンポーネントプロパティ定義を解決し、text: と fill: は名前付きの子孫を1つ解決します。swap: の値とINSTANCE_SWAPプロパティの値はデザインエンティティIDであり、figma-bridge.json から解決されます。コンポーネントの表示名はスワップIDとして意図的に受け付けられません。欠落、曖昧、またはリンクされていないターゲットは、最初のキャンバスノードが作成される前にプリフライトを停止します。

寸法とタイポグラフィは同じ var:name|fallback 形式を受け付けます。ネイティブエグゼキュータは、幅、高さ、最小/最大制約、フォントファミリー/スタイル、ウェイト、サイズ、行高、文字間隔、段落間隔、段落インデントをバインドします。ファミリー/スタイルはSTRING変数を使用し、その他のタイポグラフィと寸法フィールドはFLOAT変数を使用します。バインドされたフォントがない場合、プリフライトはサイレントに代替する代わりに、インストールまたは別のフォントを選択するメッセージで停止します。名前付きテキストスタイルもキャンバス作成前に調整されます：明示的な style="Typography/Eyebrow" は、その完全なタイポグラフィが一致する場合にのみ再利用され、競合する同名のスタイルは停止します。それ以外の場合、正確なタイポグラフィは再利用されるか、決定論的な Typography/Generated/... という名前で作成されます。Figmaのfloat32メトリック読み戻しは安定した比較のために正規化され、DM Sans/Manropeの SemiBold や ExtraBold などのファミリー固有のフェイスは、フォールバックファミリーの前に試行されます。成功したネイティブレンダリングは、参照、一意に再利用された変数、作成された変数、バインドされたプロパティの textStyleReport と variableReport のカウントを返します。曖昧またはサポートされていないプリフライトエラーは、対応するゼロ/非ゼロのカウントを含み、新しく作成された変数やキャンバスノードを残しません。

<Text> は編集可能なインラインリッチテキストも保持します。ネストされた <strong>/<b>、<em>/<i>、<u>、<Span ...>、<a href="..."> マークアップはネイティブのFigma範囲になります。HTMLエンティティはUTF-16範囲オフセットが計算される前にデコードされます。Spanランは font、fontStyle、weight、italic、size、color、letterSpacing、underline/decoration、安全なリンクをサポートします：

<Text font="Inter" size="14">
  Hello <strong>bold <em>and italic</em></strong>
  <Span color="#ef4444" size="18">red</Span>
  <a href="https://example.com">link</a>
</Text>

プラグインウィンドウ

Figma Bridgeプラグインウィンドウは、接続ステータス以上のものです：

• アクティビティ — エージェントが実行するすべてのコマンドを、ライブで、所要時間とok/エラーとともに表示します。書き込みは強調表示されます。折りたたまれた行には集計（12 ok · 1 failed）が表示され、接続ポートとラウンドトリップレイテンシはタイトルバーに表示されます。

• エージェントを一時停止 — キルスイッチ：一時停止中、プラグインはすべての着信エージェントコマンドを明示的なエラーで拒否します。

• バージョンを保存 — エージェントを解放する前に、手動の復元ポイントとして、ラベル付きエントリをFigma自身のバージョン履歴（Figma Bridge — <timestamp>）に書き込みます。プラグイン用の復元APIはありません。Figmaのバージョン履歴パネルからロールバックします。

• 選択範囲の読み出し — ユーザーが選択したものはすべて自動的に（デバウンスされて）エージェントにプッシュされ、「Agent sees: …」として表示されるため、ユーザーは常に figma_selection が返すものを確認できます。フレームを選択し、「これを構築して」と言うだけで、ノードIDをコピーする必要はありません。

• セットアップ — アクセスキーとオプションのRESTトークン。ブリッジが接続されているかどうかに関係なく、常にアクセス可能です。

デザインからコードへのワークフロー

デザインが完全な仕様です — ツールはそれを解釈するよりもコピーすることを容易にします。Figmaから画面を6つのステップで構築します：

ターゲットプロジェクトのフレームワークとスタイリングシステムを維持します。画面のためだけにTailwind、UIキット、アイコンライブラリを追加せず、エクスポートされたFigmaアートワークを便利な近似値に置き換えないでください。プロジェクトコンポーネントは、そのレンダリングされたデザインと状態が実際に一致する場合にのみ再利用します。

1. figma_screenshot を対象フレームに対して実行し、保存されたPNG（視覚的な正解データ）を読み取ります。ノードツリーのみから構築してはいけません。

2. figma_spec と phase: "structure" を組み合わせて、マークアップの骨格を構築します。実際のテキスト文字、解決されたアイコン/コンポーネント名（インスタンスは内部まで展開されるため、オーバーライドと実際のメインコンポーネント名が表示されます）、階層構造、フレックス方向を含みます。テキストとアイコンはそのままコピーします。layout:inferred (Figma heuristic — verify) というマーカーは、作成者が指定したAuto Layoutではなく、ヒューリスティックによる推測を示します。これをコンポーネントの契約として扱う前に、階層構造を確認してください。

3. トークンのエクスポート（figma_run に ["export","css"] または ["export","dtcg"] を指定）を行い、CSS変数/テーマとして配線します。出力には元のFigmaファイル名が記載されています。構築中のファイルと一致していることを確認してください。

4. アセットのエクスポート（figma_run に ["export","assets","<nodeId>","-o","/abs/path/src/assets"] を指定）を行います。スペック内の → assets/… という参照はすべて、このコマンドが書き出すファイルを指しています。絶対パスを渡してください。大規模なエクスポートはバックグラウンドで実行され続けます（"still RUNNING" と表示）。同じ呼び出しを再実行してポーリングしてください。assets.json は実行ごとにマージされ、バイト単位で同一のアセットは重複排除されます。各エントリには配置データ（x/y オフセット、parent 名パス、parentId、absolutePosition、overhang）が含まれているため、マニフェストだけでオーバーレイの配置が可能であり、スペックの相互参照は不要です。エクスポートのサマリーには、絶対配置およびオーバーハングしているファイルが明示的にリストされます。これらはビルドで失われるファイルです。大きすぎるPNGは、デフォルトでFigma上での最大使用サイズの2倍（Retina密度相当）にダウンサンプリングされます。アップスケーリングは行われず、エンコード後のファイルサイズが小さくなる場合のみ適用されます。アスペクト比、マニフェスト上の配置、CSSのクロップ動作は変更されません。元のPNGバイトを保持するには --raster-scale 0 を渡してください。

5. figma_spec と phase: "style" を組み合わせて、サイズ、ギャップ、パディング、配置、フィル/ハグサイズ、グラデーションを含むペイント（→ var(name) はデザイントークンのバインディングを示します）、角丸、シャドウ、タイポグラフィ、opacity、clip（オーバーフロー非表示）、abs 配置を適用します。装飾的なベクターは vector art → assets/… の行として配置データとともに表示されます。エクスポートされたSVGを配置し、CSSで近似してはいけません。

   構造化されたYAML/JSONでは、さらに正確なコンポーネントプロパティの定義と値（INSTANCE_SWAPやSLOTを含む）、プロパティ参照、推奨値、直接オーバーライド、公開されたインスタンス、スロット違反が保持されます。変数バインディングには、コレクションの識別情報、作成者が指定したスコープ、明示的/解決済みモード、codeSyntax.WEB、解決済みの値が含まれます。inferredVariables は提案のみの証拠として別途出力されます。

   大きなセクションの場合は、最初に depth:0 をリクエストしてください。これは、セクションコンテナ自体（背景、ボーダー、角丸、レイアウトを含む）の完全な契約であり、子孫は含みません。その後、子ノードIDを制限された呼び出しでリクエストします。繰り返しのカード/リストには dedup:true を使用してください。共有された S<n> 参照はロスレスで維持され、同一のインスタンススタイルが結果の予算を消費し尽くすのを防ぎます。

6. 検証 — ビルドのスクリーンショットを撮り、ステップ1のPNGと比較した後、機械的なチェックを実行します。

   figma_run ["verify-build", "/abs/path/to/project"]

   これは、プロジェクト内を assets.json に対してgrepし、ビルドで参照されていないエクスポートファイルをすべてリストします（サイズ、オフセット、親情報付き。そのため、配置は1ステップで完了します）。さらに border-image のリントも行います（CSSの border-image は border-radius を無視します。角丸のボックスにグラデーションのストロークを適用するには、ラッパーまたはマスクパターンが必要です）。ファイルが不足している場合は終了コード1を返すため、CIゲートとしても機能します。

   ビルドのスクリーンショットがある場合は、ビジュアルパスも実行します。

   figma_run ["verify-build", "/abs/path/to/project", "--compare", "/abs/build.png"]

   参照レンダリングは、Figmaからライブで取得されるか（--node <id>、デフォルトはマニフェストのエクスポートルート）、オフラインで --design <png> を介して提供されます。両方の画像は共通の幅に正規化され、ピクセル差分が計算されます（アンチエイリアス耐性）。出力には、全体の差分パーセンテージ、高さの不一致の検出結果（ビルドが高すぎる/低すぎる = ブロックの挿入または削除）、ノードピクセル座標系（スペックや assets.json と同じ空間）での最も差分が大きい領域、および差分PNG（赤 = 差分あり、デザインは暗く表示）が含まれます。デフォルトは情報提供のみですが、--max-diff <pct> で終了コードを制御できます。

大画面の場合、セクションレベルのエージェントは、スクリーンショット、構造マップ、トークン、アセットが確定した後の、経過時間最適化のためのオプションです。これらは、コンポーネント/スタイルファイルが分離している実質的なセクションにのみ使用してください。コーディネーターは、共有シェル、トークン、assets.json、統合、最終的なピクセル差分の所有権を保持します。並列エージェントは通常、各エージェントがプロジェクトコンテキストを必要とするため、合計トークン消費量が増加します。そのため、トークンコストが実時間よりも重要な場合は、逐次処理を使用してください。

ビルドのスクリーンショットには、既存のブラウザツールまたはプロジェクトハーネスを使用してください。ユーザーの承認なしに、キャプチャのみを目的としてPlaywright（または他のブラウザ依存関係）をインストールしないでください。既に存在する場合は、Figma Bridgeの依存関係ではなく、有効なキャプチャメカニズムとして使用できます。

同じスペックは、figma_run ["export", "code-spec", "<nodeId>"] でも利用できます。デフォルトは読みやすいツリー形式です。正規モデルが必要な場合は、-f yaml または -f json を渡してください。

ロスレスな構造化スペック形式

figma_spec および export code-spec のデフォルトは format:"tree" で、エージェント向けの簡潔な行指向ビューであり、フッターには必要なアセットと忠実度アクションが記載されています。バージョン管理された正規モデルが必要な場合は、明示的に yaml または整形された json を使用してください。どちらの構造化形式も同じモデルをシリアライズします。構文のみが異なります。ラウンドトリップテストでは、すべてのフィールド（テキスト、ID、レイアウトの出所、ペイント、タイポグラフィ、モード対応変数、アセット、コンポーネント契約、Bridgeインテント、ネイティブアノテーション、キャプチャの完全性、忠実度チェック）が正確に維持される必要があります。ミニファイされたJSONは提供されません。実際のエージェントテストでは、同じ生のフィールドを持っていても、1行が非常に長いと処理が著しく困難になることが示されたためです。

モデルの capture フィールドは、リクエストされた/実際の深さ、ペイロードの完全性、非表示ノードのポリシー、およびリクエストされた深さが子孫を切り落としたかどうかを明示的に報告します。ツール結果の暗黙的な切り捨てはありません。スペックが設定された出力予算を超える場合、呼び出しは complete:false を返し、セクションごとの再試行レシピを提供し、誤解を招く部分的なデザインを返しません。depth:0 は「リクエストされたノードのみ」を意図しており、完全であり、深さが切り詰められたツリーではありません。

IMAGE-fillのファイル名は、ローカルのレイヤー名/パスではなく、Figmaの安定したイメージハッシュによってキー付けされます。これにより、figma_spec、独立した子呼び出し、アセットエクスポート、assets.json が、たとえ「Frame 64」のような汎用的なレイヤーが異なるルートから到達された場合でも、同じファイル名を維持します。

MCPのデザインからコードへの呼び出しでは、dedup:false がデフォルトです。すべての可視レイヤーは、独自のID、ネイティブのFigma Inspect css{…}、レイアウト/ペイント/トークンの情報、完全なテキストを保持します。複合リッチテキストレイヤーは、個別のスタイル付き範囲を持ちます。フッターは、ライブの可視レイヤー数と、明示的な行、SVG内部、コンポーネント内部、非レンダリングヘルパーを調整します。深さ制限や説明のつかないレイヤーによって推測が強制される場合、スタイルプロジェクションは拒否されます。構造マップのノードIDで分割してください。dedup:true は、共有された S<n> スタイルと繰り返し参照を使用したコンパクトな概要の場合にのみ設定してください。

繰り返しの明示的ノード呼び出しの場合、phase、format、重複排除によって、別の完全なFigmaウォークがトリガーされることはありません。インメモリのDesign Captureキャッシュは、デフォルトで8エントリ/8 MiBに制限されています（DESIGN_CAPTURE_CACHE_ENTRIES および DESIGN_CAPTURE_CACHE_BYTES）。ヒットするたびにライブドキュメントのリビジョンがプローブされます。TTLやstale-while-revalidateパスはありません。

コード ↔ Figma デザインメモリ

重要なコンポーネント、画面、フレームごとに、永続的なデザインエンティティIDを割り当ててください。IDは現在の場所ではなく概念を説明するものであるべきです。ui.button、ui.account-card、screen.settings などの名前を使用してください。

Figmaノードを選択または識別した後、エージェントは以下の方法でリンクを作成できます。

figma_run {args:["link","set","9:9","screen.settings","--kind","screen","--source","src/routes/settings.tsx","--export","SettingsScreen","--story","screens-settings--default"], confirm:true}

これにより、2つの小さなアダプターが収束します。

• figma-bridge.json は、コミットされレビュー可能なレジストリであり、リポジトリ相対のコードパスと、オプションのStorybookおよびFigmaハンドルを含みます。

• Figmaは、ノードのプラグインデータとして {version,id,kind} のみを保存します。ローカルパス、認証情報、マシン固有の状態は含まれません。

figma_run ["link","inspect","9:9"] を使用してノードを解決し、figma_run ["link","list"] を使用してFigmaを読み取らずにリポジトリメモリを検査します。リンクされると、figma_selection と figma_spec は自動的に同じIDとレジストリのコード/Storybookターゲットを公開します。エージェントは、類似の外観を作成する代わりに、そのコードコンポーネントを再利用または編集する必要があります。同じ set コマンドを繰り返しても安全であり、書き込みが中断された場合にどちらかの側を修復します。

コードとFigmaが視覚的に対応していることを確認した後、現在のフィンガープリントを明示的に記録します。画面エンティティには、実際のブラウザスクリーンショットと合格するピクセルしきい値が必要です。

figma_run ["link","accept","screen.settings","--compare","/abs/build.png","--max-diff","5"]

ソースコードはレジストリに保存されません。初期コードアダプターは、リンクされたファイル全体とそのエクスポートIDをハッシュします。そのため、共有ファイル内の無関係な編集がコード変更として保守的に報告される可能性がありますが、実際の変更が隠されることはありません。Figmaアダプターは、正規化されたリンクされたサブツリーをハッシュします。Code-to-Figmaノードの場合、各ユニークな figmaBridge.semanticPath とそのノードのサブツリーハッシュも保存します。後続の link status は、追加、削除、または変更された正確なセマンティックパスをリストし、ノードスコープのスペックを推奨できます。セマンティックマーカーのみを変更しても視覚的フィンガープリントは変わりません。重複したパスは、推測される代わりに曖昧として報告されます。

figma_run ["link","status","screen.settings"]
figma_run ["link","context","screen.settings"]

link context は、リンクが存在した後の推奨エージェントエントリポイントです。これは、最小限の関連プロジェクション（エンティティ、コード/エクスポート、Figmaルート、Storybookストーリー、現在のラウンドトリップ計画、発見された DESIGN.md/トークンファイル、正確な次の読み取り）を返します。これはオンデマンドで生成され、別のメモリファイルとして永続化されません。link accept は figma-bridge.json のみを書き込みます。Figmaやコードを変更することはありません。画面の場合、測定された差分と両方の比較画像のSHA-256ハッシュも保存するため、構造的フィンガープリントだけでは視覚的に間違ったベースラインを認定できません。

従来の DESIGN.md、design/DESIGN.md、tokens.json、design/tokens.json の場所は自動的に検出されます。必要に応じて、カスタムのリポジトリ相対ロケーションを一度だけ設定します。

figma_run ["link","configure","--design-doc","docs/product-design.md","--tokens","src/theme/tokens.json"]

figma-bridge.json をコミットしてください。シークレット、絶対パス、生成された認証情報をそこに含めないでください。スキーマと競合ルールは docs/adr/0007-dual-anchor-design-entities.md に文書化されており、ベースラインとコンテキストの決定はADR-0008およびADR-0009にあります。

レビュー済み CSS ↔ Figma 境界戦略

セマンティックCode-to-Figmaは、暗黙の視覚的置換ではなく、安定したポリシーIDを使用します。minmax.native-grid、space-around.equal-slots、border.single-paint-native、sticky.metadata-only、filters.layer-stack、masks.vector-mask、font.named-faces、figma-effects.native などがあります。完全なマトリックスと残りのハードストップは、docs/css-figma-semantic-matrix.md にあります。

レビュー済みのロスフルポリシーは、影響を受ける正確なセマンティックノード上で、自動ネイティブFigmaアノテーションにオプトインできます。アノテーションは、サポートされていないCSSの事実を説明し、関連するFigmaプロパティにリンクし、将来のエージェントのためにバージョン管理された figmaBridge.fallbackAnnotations プラグインデータとしてミラーリングされます。同等のネイティブ変換は、レビューノイズを避けるためにアノテーションなしで残されます。最初のアクティブポリシーは border.single-paint-native です。Figmaは、最初に明示的にペイントされたCSSサイドを共有ネイティブストロークとして受け取り、4つのサイドの重みをすべて保持し、strokes と strokeWeight をマークします。ネイティブレンダリングは、追加されたフォールバックアノテーションの数、重複除外された数、またはサポートされていない数を報告します。

単一のDOMテキストはFigma HUGサイズにマッピングされます。絶対配置および複数行テキストは、測定されたボックスジオメトリを保持します。ブリッジは、折り返しを防ぐために任意のパーセンテージ幅の余白を追加しません。

可変フォント軸はキャプチャされますが、構造的なゲートは、レンダリング前に必要なフォントをインストールするか、利用可能な名前付きフェイスを使用するかを問い合わせます。ネイティブFigma Glassは、すべてのエフェクトパラメータを保持した編集可能なネイティブエフェクトのままです。FigmaのCSSエクスポートがそれらのGlassパラメータを公開しないため、CSS backdrop-filter として静かに扱われることはありません。

Storybookミラーリング

Figmaコンポーネントは、安定した公開キーを持ちます（ライブラリ公開後も存続します。ノードIDはファイルローカルです）。このキーは、figma_spec（正規の構造化モデル + 「使用されているコンポーネントセット」ツリートレーラー）、figma_selection、component list、figma_inspect、およびDESIGN.mdを介して流れます。

それらをコードミラーにリンクするには：

figma_run ["map", "storybook", "http://localhost:6006"]

これは、ファイルのコンポーネントを正規化された名前でStorybookインデックスと照合し、figma-map.json をプロジェクトに書き込みます。Figmaキー ↔ ストーリーID / インポートパス、一致ごとの confidence、および両方の不一致リストを含みます。エントリを手動で編集し、"matchedBy": "manual" を設定して固定します。固定されたエントリは再実行後も存続します。ファイルが存在する場合、figma_selection と figma_spec は自動的に ↔ ストーリー <id> (<importPath>) でコンポーネントに注釈を付けます。

figma-map.json はレガシー読み取りアダプターのままなので、既存のマッピングは引き続き機能します。新しい永続的なリンクは figma-bridge.json に属します。link set はレガシーローをそこにコピーすることはありません。コンポーネントに次に触れるときに、実際のDesign Entity IDを割り当て、--story を介してストーリーを渡すことで移行します。link list がまだ必要なすべてのマッピングを表示した後にのみ、レガシーファイルを削除してください。

独自のデザインシステムを持ち込む

このプロジェクトはデザインシステムを同梱しません — shadcn、Tailwindプリセット、アイコンパックはありません。これは意図的です。バンドルされたシステムは、誰か他の人の意見をあなたのファイルにレンダリングしたものだからです。代わりに提供するのは、あなたのシステムを1つのコマンドでエージェントに読み取り可能にする方法です：

figma_run ["kit", "init", "./my-app", "--storybook", "http://localhost:6006"]

4つの読み取り、1つのレポート：

最後に、何がまだ不足しているかを指定します — マッピングされていないStorybook、ストーリーのないコンポーネント、それらを同期させる tokens sync コマンド — なぜなら、マッピングが静かに欠けているセットアップは、エージェントが必要とするまで完了したように見えるからです。

DESIGN.mdはエージェントが最初に読むべきものです。tokens.json はエージェントがバインドするものです。

一度に複数のファイル

ブリッジは、プラグインを起動したFigmaウィンドウごとに1つの接続を保持します。これが同意モデルです。ファイルに到達できるのは、あなたがそれを開き、そこでプラグインを起動したからであり、フラグがスコープを広げたからではありません。

• 1つのウィンドウ — 変更はありません。コマンドはそこに送られます。

• 複数のウィンドウ — コマンドはターゲットを指定する必要があります。指定しない場合は、接続されているファイルのリストとともに失敗します：

  figma_status                                        # lists every connected window
  figma_run {args: ["canvas","info"], fileKey: "GY5SasBJ…"}
  figma_spec {nodeId: "12:34", fileKey: "GY5SasBJ…"}

  figma_render、figma_selection、figma_inspect、figma_screenshot、および figma_spec は同じ fileKey パラメータを受け入れます。完全なFigmaノードURLも、そのファイルキーを自動的に提供します。ターゲットがない場合、figma_selection は推測する代わりに、どのファイルが開いているかを示します。エンジンCLIでは、フラグは --figma-file であり、--file ではありません。eval と spec はすでにローカルパスに -f, --file を使用しています。

「すべてのファイル」オプションは意図的にありません。 すべての書き込みは1つのファイルを指定するため、誤ったコマンドがライブラリ全体に波及することはありません。同じファイル上の2つのウィンドウはルーティングで区別できないため、新しい方が引き継ぎ、古い方はブリッジを失ったことが通知されます。監査エントリはファイルキーを保持するため、複数のファイルが関係している場合でも figma_history は読み取り可能なままです。

開いていないファイルに到達することは範囲外です。FigmaのREST APIはドキュメントコンテンツを書き込むことができないため、30のライブラリファイルにわたる一括名前変更は、このツールが正直に提供できるものではありません。

FigJam

プラグインはFigJamボードでも、同じブリッジを介して実行されます。2番目のトランスポートも追加の権限もありません：

figma_run ["jam", "sticky", "Ship the handshake", "--color", "green"]
figma_run ["jam", "stickies", "[\"Discovery\",\"Build\",\"Ship\"]", "--columns", "3"]
figma_run ["jam", "shape", "Decide?", "--type", "DIAMOND"]
figma_run ["jam", "connector", "1:2", "3:4", "--text", "yes"]
figma_run ["jam", "table", "3", "4", "--data", "[[\"Step\",\"Owner\"],[\"Handshake\",\"Alex\"]]"]
figma_run ["jam", "board"]      # read everything back, with connectors
figma_run ["jam", "arrange"]    # arrange only the current selection
figma_run ["jam", "arrange", "--ids", "1:2,3:4"]
figma_run ["jam", "arrange", "--all"] # explicit: whole page

新しいノードは、--at x,y を渡さない限り、ボード上に既にあるものの右側に配置されます。そのため、人口の多いボードに追加するエージェントは、すべてを原点に積み重ねることはありません。すべてのコマンドは最初に figma.editorType をチェックし、「これはFigmaファイルであり、FigJamボードではありません」と表示して、未定義のAPIで失敗するのを防ぎます。figma_status は、ブリッジがどのエディターに接続されているかを報告します。

jam arrange は意図的に選択範囲スコープになっています。エージェントはユーザーの選択を変更せずに正確なノードIDを渡すことができます。ページ全体を再配置するには、可視の --all フラグが必要です。セクションとコネクタは、このコマンドによって移動されることはありません。公開サーフェスは2026-08-10にFigma Desktopでテストされました。メンテナーは、詳細なコマンドと読み返しの証拠を公開リポジトリの外部に保持します。

Figma Slidesベータ

Slidesは同じ認証済みプラグインブリッジを使用します。ベータサーフェスは、デッキ構造とネイティブスライドプロパティをカバーし、別のプレゼンテーションレンダラーは含みません：

figma_run ["slides", "inspect"]
figma_run ["slides", "create", "Agenda", "--row", "0", "--col", "1"]
figma_run ["slides", "duplicate", "Agenda", "--label", "Agenda alternative"]
figma_run ["slides", "move", "Agenda alternative", "1", "0"]
figma_run ["slides", "transition", "Agenda", "DISSOLVE", "--duration", "0.4"]
figma_run ["slides", "skip", "Appendix", "on"]
figma_run ["slides", "delete", "1:42"]

Figmaは、キャンバスグリッドが変更されるたびにネイティブスライド名を付け直します。create のオプション引数と duplicate の --label は、したがって、永続的なBridgeラベルをプラグインデータに保存します。inspect は、ネイティブの name と安定した label の両方を報告します。参照は、ID、完全一致のネイティブ名またはラベル、次に一意の部分文字列で解決されます。あいまいさはエラーであり、削除は常に明示的な参照を必要とし、重複/移動はFigmaのフォールバック配置を受け入れる代わりに、存在しないターゲット行を拒否します。すべての操作は、Slides専用APIに触れる前に figma.editorType === "slides" をチェックします。ベータを終了するための未解決の候補と基準は、docs/slides-roadmap.md にあります。エディターの受け入れは、公開リポジトリとは別にメンテナーが検証します。

トークン同期（双方向）

tokens import は常に作成のみを行うため、コードで編集された値が既存のFigma変数に到達することはなく、Figmaで編集された値がコードに到達することもありません。tokens sync がそのループを閉じます：

figma_run ["tokens", "sync", "src/tokens.json"]              # plan only
figma_run ["tokens", "sync", "src/tokens.json", "--apply"]   # write it

インポートサーフェスは同期サーフェスよりも広範です。ワンショットの import は、Tailwind v3設定、Tailwind v4/CSS、Storybookインデックス、DTCG/W3C JSON、およびStyle DictionaryとTokens StudioによってエクスポートされたDTCG互換トークン形状を受け入れます。この互換性には、Tokens Studioのテーマセマンティクスや任意のプリプロセッサは含まれません。$themes などのメタデータは無視され、トークンセットとエイリアスは読み取られます。

明示的な spacing/* または space/* 名前空間内の新しいFLOAT変数は、Figmaの GAP コンシューマーのみにスコープされます。radius/* および radii/* 変数は、CORNER_RADIUS のみにスコープされます。推論は意図的に名前空間に正確です。spacingFactor などの名前はFigmaのデフォルトスコープのまま残され、レンダリングは既存のユーザーまたはライブラリ変数のスコープを静かに変更しません。他の新しいCOLOR、FLOAT、またはSTRING変数は、互換性のあるFigma選択肢のみを含む SCOPE DECISION REQUIRED を表示します。エージェントはそれらを絞り込む前に問い合わせる必要があります。figma_reference {name:"variable-scopes"} でカタログを検査し、figma_run ["var","update","<name>","--collection","<collection>","--scopes","TEXT_FILL,STROKE_COLOR"] で回答を適用します。

安全な3方向同期は、DTCG / W3Cデザイントークン（.json、export dtcg が出力するもの）とCSSカスタムプロパティ（.css、export css が出力するもの）のみを受け入れます。Sassの $variables はCSSカスタムプロパティではなく、.scss は部分的に解析されるのではなく拒否されます。export dtcg はすべてのローカル変数を1つのファイルに書き込むのに対し、同期は1つのコレクションをターゲットにすることに注意してください。それに応じて --collection を渡してください。ファイル内のほとんどの名前がすでに別のコレクションに存在する場合、同期は重複を提案する代わりにその旨を伝えます。Tailwind設定はインポート元のみです。そのパーサーは値を色/間隔/半径にバケット化し、ラウンドトリップできないため、同期は理解しなかったトークンを静かにドロップするのではなく、名前で拒否します。

なぜロックファイルなのか。 メモリのない双方向同期は、「コードが変更された」と「Figmaが変更された」を区別できません。両者が異なることだけを認識し、どちらの方向を選んでも相手側の作業が破壊されます。figma-tokens.lock.json は、最後に成功した同期時の状態を記録するため、すべての決定は3方向比較になります：

競合は実行全体を停止します。一方の側を編集して解決するか、--ours（コードファイルが優先）/ --theirs（Figmaが優先、Figmaには何も書き込まれない）ですべてを一度に決定します。

削除には --prune が必要で、それでも同期自体が作成した変数にのみ触れます。追跡したことのない変数は未追跡として報告され、そのまま残されます。

ロックファイルは各変数のFigma IDも保存します。これにより、名前変更が、すべてのレイヤーバインディングをドロップする削除＋作成ではなく、1回の名前変更になります。ペアリングは値によって行われ、あいまいでない場合のみです。同じコミットでトークンの名前変更と値の変更を行うと、作成＋削除にフォールバックするため、バインディングが重要な場合は2つのステップとして行ってください。

--apply なしでは、変更が保留中の場合、コマンドは終了コード1で終了するため、「Figmaはリポジトリと同期しているか？」のCIチェックとして機能します。

バインディング、およびデザインが従うコレクションの切り替え

tokens sync はトークン値を書き込みます。意図的に行わない2つの隣接する事項：

figma_run ["node", "bind", "12:34", "radius", "radius/lg", "--collection", "TARGET_COLLECTION"]
figma_run ["tokens", "rebind", "TARGET_COLLECTION", "--node", "12:34"]            # plan
figma_run ["tokens", "rebind", "TARGET_COLLECTION", "--node", "12:34", "--apply"] # write

node bind は、既存のノードのプロパティ — fill、stroke、radius、gap、padding（または片側）、opacity、stroke-width、width、height — に変数をアタッチします。その読み取り対応は node bindings です。JSON配列とともに --batch を渡すと、1回の呼び出しで多くのプロパティまたはノードをバインドできます。

一意でない変数名は推測されず、拒否されます — このファイルには2つのコレクションに radius/lg があり、回答は両方に名前を付けるため、--collection で解決できます。変数の型は最初にプロパティに対してチェックされるため、radius 上のCOLORは、プラグインのスタックトレースではなく、文章で失敗します。

タイポグラフィ変数には、テキストが異なる文字スパンに異なるバインディングを持つことができるため、独自の範囲認識コマンドがあります：

figma_run ["font", "bind", "12:36", "fontWeight", "type/weight", "--collection", "Typography"]
figma_run ["font", "bind", "12:36", "line-height", "type/line-height", "--start", "0", "--end", "12"]
figma_run ["font", "unbind", "12:36", "lineHeight", "--start", "0", "--end", "12"]

バインド可能なフィールドは fontFamily、fontSize、fontStyle、fontWeight、letterSpacing、lineHeight、paragraphSpacing、paragraphIndent です。ケバブケースの表記も受け入れられます。既存のフォント（ファミリー/スタイル/ウェイトのバインディングについては、関連する利用可能なファミリースタイル）は、バインディングが変更される前に読み込まれます。変数名は曖昧な場合は拒否され、Figmaを呼び出す前に STRING と FLOAT がチェックされます。数値の fontWeight バインディングは、それでも一般的なバリアブルフォント軸セッターではありません。Figma はアクティブなフォントに対して有効なウェイトを選択します。

tokens rebind はテーマの切り替えです。サブツリーを走査し、すべてのバインディングをターゲットコレクション内の同じ名前の変数に再ポイントします。SOURCE_COLLECTION に対してカードをデザインし、TARGET_COLLECTION で rebind を実行すると、同じカードがターゲットコレクションの値に従います — 再デザインは不要です。デフォルトでは計画（plan）のみ行い、--apply で書き込みます。ターゲットに該当するものがないトークンはリストアップされ、元のまま残されるため、部分的なテーマは中途半端なデザインではなくレポートとして扱われます。

node set は既存のノードのプロパティ — fill、stroke、strokeWidth、radius、opacity、x、y、width/height、name、visible — を変更します。一度に1ノードずつ、または --batch で複数ノードを扱います。これは、バッチ形式が 1回 のラウンドトリップになるため重要です：

figma_run ["node", "set", "12:34", "--name", "Card", "--radius", "12"]
figma_run ["node", "set", "--batch", "[{\"node\":\"12:35\",\"fill\":\"var:sage/50\",\"name\":\"Badge\"}]"]

色は16進数または var:<name> で指定します。違いは見た目だけではありません。16進数は固定（frozen）され、var: 参照は バインド（bound） されたままになるため、後で tokens rebind で移動させることができます。

ローカルスタイル、変数メタデータ、モード

以前は手動のUI操作が必要だったローカルデザインシステムのプリミティブが、Figma Commands で第一級に扱えるようになりました。これらはRESTではなく、ライブのPlugin APIを使用します：

figma_run ["style", "list", "--type", "TEXT"]
figma_run ["style", "show", "Heading/H1"]
figma_run ["style", "create", "PAINT", "Brand/Primary", "--properties", "{\"paints\":[{\"type\":\"SOLID\",\"color\":{\"r\":0.1,\"g\":0.3,\"b\":0.9}}]}"]
figma_run ["style", "apply", "Brand/Primary", "12:34,12:35", "--field", "fill"]
figma_run ["style", "consumers", "Brand/Primary"]
figma_run ["style", "publish-status", "Brand/Primary"]
figma_run ["style", "bind-font", "Body", "fontSize", "--variable", "type/size/body"]
figma_run ["style", "unbind-font", "Body", "fontSize"]

style は、ローカルの PAINT、TEXT、EFFECT、GRID スタイルをカバーします。update は create と同じタイプ固有のJSONプロパティを受け入れます。apply はスタイルタイプを fill、stroke、text、effect、grid に対して検証します。名前のルックアップは曖昧さを拒否します。コンシューマーは getStyleConsumersAsync() から取得され、パブリッシュステータスは Figma の UNPUBLISHED、CURRENT、CHANGED のいずれかです。

変数は、トークンファイルの同期ではカバーされないメタデータとモード操作を公開します：

figma_run ["var", "show", "space/md", "--collection", "Primitives"]
figma_run ["var", "update", "space/md", "--description", "Medium spacing", "--scopes", "GAP"]
figma_run ["var", "set-value", "space/md", "12", "--mode", "Light"]
figma_run ["var", "set-value", "space/card", "--alias", "space/md", "--mode", "Light"]
figma_run ["var", "code-syntax", "space/md", "WEB", "var(--space-md)"]
figma_run ["var", "resolve", "space/md", "12:34"]
figma_run ["col", "mode-add", "Primitives", "Dark"]
figma_run ["col", "mode-rename", "Primitives", "Dark", "Dim"]
figma_run ["col", "extend", "Primitives", "Brand"]

var show はモード、スコープ、コード構文、コレクションメタデータ、パブリッシュステータスごとに値を返します。var resolve は意図的にコンシューマーノードを必要とします。エイリアスはそのノードの選択されたモードの下で異なる解決方法を取ることができるためです。コレクションの show、update、mode-add、mode-rename、mode-remove、publish-status は同じ ID/完全一致名/一意の部分文字列ルックアップポリシーに従います。モード数に関する Figma の計画制限は Figma によって強制され、エラーとして表示されます。コレクションの拡張は、ローカルコレクションには VariableCollection.extend() を、パブリッシュされたキーには extendLibraryCollectionByKeyAsync() を使用します。Figma はこの機能を Enterprise プランに制限しており、CLI は Figma のプランエラーをそのまま報告します。テキストスタイルのバインディングは、Figma がバインド可能なタイポグラフィフィールド（ファミリー、スタイル、ウェイト、サイズ、行の高さ、文字間隔、段落の値）のみを正確にサポートします。

有効化されたチームライブラリ

ライブラリの検出とインポートも、認証済みのプラグイントランスポート上で行われます：

figma_run ["library", "collections"]
figma_run ["library", "variables", "Acme/Primitives", "--type", "COLOR"]
figma_run ["library", "import-variable", "<published-variable-key>"]
figma_run ["library", "import-style", "<published-style-key>"]
figma_run ["library", "import-component", "<published-component-key>"]
figma_run ["library", "import-component-set", "<published-component-set-key>"]

collections と variables は読み取りです。4つの import-* コマンドは、パブリッシュされたアセットを現在のファイルに具体化するため、Capability Catalog では書き込みに分類されます。Figma は変数コレクションと変数についてのみ検出を公開します。パブリッシュされたスタイル、コンポーネント、コンポーネントセットは、その安定したキーが既にわかっている場合にインポートできますが、Plugin API はそれらを列挙できません。

ライブラリは、library collections がそれらを認識できるようにするには、Figma の UI で現在のファイルに対して有効化されている必要があります。Plugin API はライブラリを有効化できません。出荷済みのプラグインは、必要な teamlibrary 権限を既に宣言しています。名前のルックアップは、コレクションキー、完全一致のコレクション名、次に曖昧でないコレクションまたはライブラリ名の部分文字列を使用します。ライブラリの検出は、Bridge の期限よりも短い18秒のPlugin-APIタイムアウトを持ちます。そのため、Figma ライブラリリクエストが停止した場合、操作の名前を表示し、ライブラリが有効化されているかどうかを確認するよう提案し、一般的な実行タイムアウトに退化することを防ぎます。

プロトタイプ、Dev Mode の測定、アノテーション

これらのドキュメント機能も Plugin-API 優先です：

figma_run ["prototype", "inspect", "12:34"]
figma_run ["prototype", "add", "12:34", "--trigger", "click", "--navigate-to", "12:36"]
figma_run ["prototype", "set", "12:34", "--json", "[{\"trigger\":{\"type\":\"ON_CLICK\"},\"actions\":[{\"type\":\"BACK\"}]}]"]
figma_run ["measure", "add", "12:34:right", "12:36:left", "--offset", "16", "--text", "gap"]
figma_run ["annotate", "categories"]
figma_run ["annotate", "add", "Review spacing", "--node", "12:34", "--category", "Review", "--properties", "width,fontSize"]
figma_run ["annotate", "edit", "12:34", "0", "--text", "Resolved"]

prototype set --json は、Figma の複数のアクション（SET_VARIABLE、SET_VARIABLE_MODE、条件ブロック）に対するロスレス形式です。setReactionsAsync() を通じて書き込むため、動的ページマニフェストもサポートされます。測定の書き込みは Figma Dev Mode でガードされ、PageNode のネイティブ測定メソッドを使用します。アノテーションのインデックスは0ベースです。カスタムカテゴリの作成/編集/削除コマンドは categories と共に利用可能です。これらの手動レビューノートは、セマンティックレンダラーの自動 Boundary Fallback Annotations とは独立しています。後者は、明示的にオプトインしたロッシーマッピングポリシーによってのみ出力され、プラグインデータを通じて機械可読のままです。

2026 Plugin APIs: ビデオ、シェーダー、グリッド、スロット、Draw

現在の公式 Plugin API サーフェスは、REST 呼び出しではなく Figma Commands として公開されています：

figma_run ["export", "video", "12:34", "--format", "mp4", "--fps", "30", "-o", "/abs/demo.mp4"]
figma_run ["shader", "list"]
figma_run ["shader", "import", "<shader-id>"]
figma_run ["shader", "apply", "12:34", "<shader-id>", "--field", "fill", "--properties", "{\"definition-id\":0.8}"]
figma_run ["layout", "grid", "set", "12:34", "--rows", "2", "--columns", "3", "--row-gap", "12"]
figma_run ["layout", "grid", "auto-flow", "12:34", "--auto-tracks", "rows", "--positioning", "row_auto_flow"]
figma_run ["slot", "create", "12:37", "Content", "--settings", "{\"minChildren\":1,\"maxChildren\":3}"]
figma_run ["slot", "validate", "12:37"]
figma_run ["draw", "inspect", "12:38"]
figma_run ["draw", "text-path", "12:38", "--text", "Around the curve"]
figma_run ["draw", "stroke-profile", "12:38", "--preset", "TAPER"]
figma_run ["draw", "pattern", "12:38", "12:39", "--field", "fill"]

ビデオエクスポートは、選択された子孫をそのトップレベルのアニメーションフレームに解決し、Figma のフォーマット固有の FPS 値のみを受け入れます。シェーダープロパティは表示名ではなく定義IDでキー指定され、利用可能なシェーダーは適用される前にインポートされる必要があります。layout grid は自動レイアウトの GRID モデルを意味します。古いトップレベルの grid コマンドはレイアウトガイド管理のままです。スロットは GA の SlotSettings、推奨値、リセット、制限違反を公開します。JSX <Slot> は現在 ComponentNode.createSlot() を使用し、レンダリング後に設定された制限を検証します。Draw コマンドは、テキストパス、繰り返し変換グループ、ストレッチ/スキャッター/ダイナミックストローク、可変幅プロファイル、非同期パターンフィル/ストロークセッターをカバーします。馴染みのないドキュメントを変更する前に、対応する inspect/validate 読み取りを実行してください。

修正が必要な箇所を見つける

figma_run ["analyze", "lint", "--node", "12:34"]

デザインシステムレビューが対象とする4つの事項を1パスでチェック：既存の変数と一致するがバインドされていない色、デフォルト名のままのレイヤー、スタイルが適用されていないテキスト、12px未満のテキスト。--fail-on-issues で CI ゲートに、--kind で絞り込み、--json で切り捨てなし。

ハードコードされた色は、その正確な値を保持する変数が既に存在する場合 にのみ報告されます。そうでなければ、その発見は対処できないノイズです。一致がわかっているため、それぞれに修正コマンドが付随します：

unbound token colour — 1
  12:35    Badge  fill is #8a9a8d, which is sage/400
    fix: node bind 12:35 fill "sage/400" --collection "Sprout Primitives"

analyze colors|typography|spacing は依然として完全な全数調査（census）を提供します。Lint は、そもそも何かする必要があるかどうかを答えるパスです。

バリアブルフォントと OpenType の事実

Figma は Plugin API を通じて一般的なバリエーション軸タプルを公開しません。そのため、ブリッジは Figma が実際に報告する事実と、呼び出し元が明示的に記録する軸の意図を分離します：

figma_run ["font", "inspect", "12:36"]
figma_run ["font", "inspect", "12:36", "--start", "0", "--end", "12", "--all-open-type"]

font inspect は、スタイル付きテキスト範囲を、fontName、数値の読み取り専用 fontWeight、サイズ、有効化された OpenType 機能タグ、解決されたタイポグラフィ変数バインディングと共に返します。--all-open-type は false の機能値も含めます。結果は API の制限を明示的に示します：報告された fontWeight は一般的な wght/wdth/opsz/カスタム軸タプルではなく、OpenType 機能は読み取り専用です。

UI や他のフォントツールから正確な軸値がわかっている場合は、それらをテキストノードに範囲メタデータとして保存します：

figma_run ["font", "remember-axes", "12:36", "wght=357,wdth=82", "--start", "0", "--end", "12"]
figma_run ["font", "axes", "12:36"]
figma_run ["font", "forget-axes", "12:36", "--start", "0", "--end", "12"]
figma_run ["font", "forget-axes", "12:36"]  # clear every stored range

remember-axes はプラグインメタデータのみを変更します — フォントやレンダリングされたグリフは決して変更しません。そのため、Capability Catalog では書き込みに分類されます。figma_spec はこれらのレコードを axes-meta[start:end](tag=value,…) として、Figma が報告する fw… 値と有効化された ot(…) タグと共に保持します。これにより、デザインからコードへのキャプチャが文書化された意図を静かに破棄することがなくなります。

ネイティブ Plugin API の事実

2つの読み取りコマンドは、REST API に問い合わせずに Figma 自身の表現を公開します：

figma_run ["node", "css", "12:34"]
figma_run ["node", "css", "12:34", "--json"]
figma_run ["export", "node-json", "12:34"]
figma_run ["export", "node-json", "12:34", "-o", "facts/card.json"]

node css は getCSSAsync() を呼び出し、Figma がインスペクトパネルで公開する宣言を返します。これは、デザイントークンのカスタムプロパティをエクスポートする export css とは意図的に区別されています。export node-json は exportAsync({format:"JSON_REST_V1"}) を使用します。その形状は REST ファイルスキーマに似ていますが、データはライブのプラグインドキュメントから取得されるため、トークンもネットワークリクエストも必要としません。

バージョン履歴と差分

Figma のプラグイン API はバージョンを 書き込む ことはできますが、読み戻すことはできません。そのため、「今朝から何が変わったか」という質問には、ブリッジだけでは答えられません。history はクレデンシャルなしでこれを提供します：サブツリーの構造を記録し、後で再度記録し、その2つを差分します。

figma_run ["history", "save", "Before refactor", "--description", "Agent restore point"]
figma_run ["history", "snapshot", "--label", "before refactor"]
# … agent works …
figma_run ["history", "diff", "latest", "live"]

history save は saveVersionHistoryAsync() を通じて直接名前付きエントリを作成し、Figma の書き込みです。snapshot、list、diff はローカル/読み取り専用の Figma 操作のままです。Figma のネイティブなバージョン履歴を読み取るには、依然としてオプションの REST アドオンが必要です。

スナップショットはノードごとに1つの正規化されたレコードを保存します — ジオメトリ、レイアウト、ペイント、タイポグラフィ、コンポーネントキー — さらにコンテンツハッシュとサブツリーハッシュも保存するため、差分ツールは変更されていないセクションを歩かずに報告できます。これらは ~/.figma-bridge-mcp/snapshots/<fileKey>/ に gzip 圧縮されて保存され、最新20個が保持されます。

参照は latest、previous、history list のインデックス、ファイル名、または現在のドキュメントを指す live です。レポートは 追加（added）、削除（removed）、置換（replaced）、移動（moved）、変更（changed） を区別します — 最後の区別が実際に重要です：フレームを削除して再レンダリングするエージェントは名前パスを保持しますが、新しいノードIDを取得し、置換検出がないと、再レンダリングのたびに100件の削除として読み取られます。--changelog は代わりにマークダウンを出力します。diff は何か違いがあると終了コード1で終了するため、CI ゲートとしても機能します。

MCP 経由では、これは13番目のツールではなくパラメータです：

figma_history {diff: {from: "latest", to: "live"}}
figma_history {diff: {from: "version:1234", to: "version:5678"}}   # REST add-on

version: 参照は REST レイヤーを通過し、デザイナーが 保存した内容を同じ差分ツールで差分します。2つのソースを1つの差分で混在させることはできません。REST ドキュメントとプラグインスナップショットは異なるプロパティを公開するため、すべてのノードが変更されたように見えます — ツールはその旨を伝え、誤解を招く大量の出力を生成しません。

Motion

Figma Motion（Config 2026 Beta）は、figma_run の ["motion", …] を通じてアクセス可能です：キーフレームトラック（add）、JSON からの仕様全体（apply）、名前付きプリセット（preset）、ノード間の振り付けオフセット（stagger）、Figma のファーストパーティアニメーションスタイル（styles、style）、フレーム期間（timeline）、読み返し（inspect）、削除（clear）。

他のすべてのコマンドと同様に、プラグインブリッジ上で実行されます — 専用のトランスポートはありません。styles と inspect は読み取りです。それ以外のすべて（引数に応じて読み取り または 設定を行う timeline を含む）は、FIGMA_WRITE_CONFIRM=1 の下で書き込みとしてカウントされます。

Motion は Figma Beta フラグの背後で展開されています。アクセス権がない場合、コマンドは MOTION_DISABLED という名前のエラーで失敗し、一般的な API 障害ではなく Figma Desktop を更新するように指示します。

REST アドオン（オプション）

上記のすべては、Figma のクレデンシャルがゼロ で動作します。ローカルプラグインブリッジが構造的に到達できない3つのことがらは、Figma の REST API の背後にあり、個人アクセストークンでアンロックできます：

有効化 — トークンはマシンから出ません:

1. Figmaで個人アクセストークンを作成します（設定 → セキュリティ → 個人アクセストークン）。スコープは ファイルコンテンツ（読み取り）、ファイルバージョン（読み取り）、コメント（読み取りと書き込み） です。現在のユーザー（読み取り） はオプションで、figma_status にあなたのハンドルを表示するためだけに使われます。

2. Figma Desktopで Figma Bridgeプラグイン を開き、接続します（プラグインが認証されるとフィールドが表示されます）。「RESTトークン（オプション）」 を展開し、トークンを貼り付けて トークンを保存 します。

3. figma_status は、リモートリクエストを行わずにトークンが設定されていることを報告します。明示的な有効性チェックを行いたい場合は figma_status {validateRest:true} を実行します。オプションの 現在のユーザー スコープがない場合でも、ハンドルを報告するか、ファイルアクセスを検証します。

トークンはプラグインから 認証されたlocalhost WebSocket を経由してデーモンに送られ、デーモンはそれを ~/.figma-bridge-mcp/rest-token（モード0600）に保存します。トークンはチャットに入力されることはなく、MCPクライアント設定に保存されることもなく、どのツールからもエコーバックされることはなく、監査ログに書き込まれることもありません（REST呼び出しはメソッド＋パスのみがログに記録されます）。プラグインの トークンをクリア でファイルが削除されます。

ヘッドレス/CIの代替方法: FIGMA_REST_TOKEN 環境変数を設定します。これによりファイルが上書きされます。

スコープ: デフォルトでは、REST呼び出しは現在Figma Desktopで開いているファイルを対象とします（プラグインがファイルキーをプッシュします）。他のファイルには明示的な fileKey パラメータ（ベアキーまたは完全なFigma URL）が必要です。PAT自体はそのアカウントがアクセスできるすべてのファイルを読み取ることができるため、スコープは最小限に保ってください。

RESTクライアントは閉じた内部許可リストであり、汎用的なHTTPエスケープハッチではありません。トークンの健全性、バージョンリスト、バージョン固定のドキュメントコンテンツ、コメント、ファイル全体の公開コンポーネントメタデータを許可します。ベアの現在のファイル取得や、すべてのノード/CSS/エクスポート/変数/スタイル/Devリソースエンドポイントは、トークンが読み取られる前、またはネットワークに触れる前に拒否されます。これらの操作は、上記のローカルプラグインAPIコマンドを使用する必要があります。

セキュリティモデル

• Figma APIトークンは不要 — Figmaはローカルプラグインを通じて操作され、api.figma.com は使用しません。RESTアドオンは厳密にオプトインです。トークンがない場合、コードパスは無効です。トークンがある場合、トークンは0600ファイル（または自身の環境変数）に保存され、MCPクライアント設定には保存されません。

• バイナリパッチなし — Yolo/CDPモードはベンダーエンジンから削除されています。

• 機能ゲート付きコマンド — figma_run は機能カタログによって公開されたコマンドのみを受け入れます。connect は公開されていないため、セーフモードのみの接続が強制されます。同じ解決済みプランが書き込み確認ゲート、ターゲット要件、再試行ポリシーを駆動し、アダプターのずれを防ぎます。

• シェルなし — エンジンは execFile（shell:false）で起動されます。

• 二層のデーモン認証、ワイヤー上に秘密なし — 署名付きHTTPリクエスト（リクエストごとのHMAC、メソッド/パス/ボディをキーに、セッショントークンでキーイング、nonceリプレイガード）+ プラグインソケット上の相互チャレンジレスポンスハンドシェイク（Origin/Host 許可リスト）。セッショントークンもアクセスキーも、どちらの方向にも送信されることはありません — ハンドシェイク を参照。

• localhostロックされたプラグイン — plugin/manifest.json は networkAccess.allowedDomains を ws://127.0.0.1:3456–3460 に制限します。

• 分離された状態 — トークン、pid、キー、監査ログは ~/.figma-bridge-mcp/ の下にあり、上流のfigma-ds-cliインストールとは別です。

• 監査ログ — 実行されたすべてのコマンドは ~/.figma-bridge-mcp/audit.log に追記されます（タッチされたノードID、オプションのラベル、成功/失敗を記録する完了エントリを含む — figma_history のデータソース）。5MBでローテーション。1世代前（audit.log.1）が保持され、figma_history によって引き続き読み取られます。

ポートフォールバック。 デーモンは3456–3460の範囲で最初の空きポートにバインドし、そのポートを ~/.figma-bridge-mcp/daemon-port に公開します。CLI/MCPレイヤーは呼び出しごとにポートを解決します（env DAEMON_PORT > ポートファイル > 3456）。プラグインは範囲全体をスキャンするため、外部プロセスが3456を占有しても接続をブロックしなくなりました。占有チェックは 認証なし の /health プローブであり、認証済みリクエストはHMAC署名されています。範囲内のポートの占有者は、セッショントークンもリプレイ可能なものも見ることができません（署名はタイムスタンプ、nonce、メソッド、パス、ボディにバインドされており、デーモンは再利用されたnonceを拒否します）。プラグインソケットは、同じ理由で範囲内のどのポートでも安全です。以下のハンドシェイクは秘密を運ばず、実行されたポートにバインドされます。DAEMON_PORT を明示的に設定するとフォールバックが無効になります。3456–3460の範囲外の値はサポートされていません。プラグインマニフェストはFigmaによって強制され、それらに到達できません。

ハンドシェイク

プラグインソケットは相互チャレンジレスポンスを実行します（プロト2、engine/src/lib/plugin-handshake.js）:

daemon → plugin   {type:'challenge', proto:2, nonce:<dNonce>, port:<bound>}
plugin → daemon   {type:'hello', proto:2, nonce:<pNonce>, version, proof}
daemon → plugin   {type:'hello-ack', proof, restTokenConfigured}

ここで proof = HMAC-SHA256(access key, transcript) は両方のnonce、バインドされたポート、プラグインバージョンにわたるもので、方向ごとに異なるロールラベルとnonce順序が使用されるため、どちらの証明も他方としてリプレイできません。これにより3つの特性が得られます:

• キーはワイヤーを越えません。 デーモンの前に範囲ポートにバインドし、交換全体を記録するプロセスは、二度と見ることのないnonceに対する1つのHMACを学習します。これにより、以前のバージョンで文書化された、生のキーがプラグインが送信する最初のフレームであったという残留リスクが解消されます。

• デーモンも自身を証明します。 プロト2以前は、プラグインは応答するものを信頼し、送信された任意の eval を実行していました。デーモンを偽装するのにキーはまったく必要ありませんでした。パネルは、ackが検証されるまですべてのコマンドを拒否するようになりました。

• バインドされたポートはトランスクリプト内にあります。 3456の占有者が実際のデーモン（3457）に転送する場合、プラグインは3456に署名し、デーモンは3457を検証するため、リレーは崩壊します。

プロト1へのフォールバックはありません。figma_connect は実行のたびにインストールされたプラグインファイルを更新するため、アップグレード方法は次のとおりです: figma_connect を実行し、プラグインウィンドウを閉じて再度開きます。古いパネルは、静かに弱いハンドシェイクを行う代わりに、その旨を正確に示す名前付きエラーを取得します。

パネルは独自のSHA-256/HMAC実装を搭載しています。プラグインUIはサンドボックス化されたnullオリジンのiframeであり、WebCryptoの可用性は保証できません。認証ハンドシェイクにとって、より弱いものへの静かなフォールバックは最悪の結果です。tests/plugin-handshake.test.js は、出荷されたコードをNodeの crypto に対して実行し、2つの実装が乖離しないようにします。

既知の制限事項

• Figma Slidesはベータ版であり、意図的に制限されています。 グリッド検査、スライド作成/複製/移動/削除、スキップ状態、トランジションはサポートされています。スピーカーノート、インタラクティブな投票/埋め込み、プレゼンターコントロール、完全なコンテンツ作成ワークフローはサポートされていません。実行可能な候補とプラグインAPIの境界については、Slidesロードマップを参照してください。

• 非localhostネットワークアクションは少数で明示的です: api setup（figma_reference 用のFigma Plugin APIドキュメントミラーの1回限りのgitクローン。api gap は代わりにインストールされた公式 @figma/plugin-typings パッケージに対して測定します）、import/map storybook のStorybookインデックス取得（渡すURL/ディレクトリ）、そして — RESTアドオンをオプトインした場合のみ — api.figma.com への呼び出し。それ以外はネットワークと通信しません。上流のiconify/unsplash/remove.bg/screenshot-url統合は完全に削除されました。figma_render JSX内の <Icon> は名前付きプレースホルダーとしてレンダリングされます（実際のアイコンは export assets を介してFigmaファイルから取得されます）。

• 単一トランスポート、CDPの残骸なし。 すべてのコマンドは同じ方法でFigmaに到達します: エンジン → デーモン → プラグインeval。上流のChrome-DevToolsクライアント、その figma-use シェルラウンドトリップ、バイナリパッチ init ウィザード、figma-use 依存関係はすべて削除されました（約5,600行削除）。したがって、プラグインブリッジをバイパスする可能性のある2番目のコードパスはありません。

開発

npm run check:contracts       # static JavaScript seam + plugin contracts
npm run check:architecture-latency # warmed latency budget in an idle process
npm run measure:architecture  # context, payload and local latency baselines
npm test                      # all contracts and regression suites

現在のドメイン言語は CONTEXT.md に、承認されたアーキテクチャ上の決定は docs/adr/ に、APIカバレッジは docs/figma-plugin-api-coverage.md に、リリース手順は docs/releasing.md にあります。公開ドキュメントインデックスは docs/README.md です。

上流の figma-cli を同時に実行しないでください。デーモンは3456が使用中の場合は3456–3460の範囲内でフォールバックするようになったため、両方とも共存できますが、プラグインは範囲全体をスキャンし、2つのデーモンは異なるアクセスキーを使用します。プラグインがどちらに最初に到達するかはコイントスです。このビルドは、独自のトークン/pid/ポートファイルを ~/.figma-bridge-mcp/ の下に分離します。

ライセンス

figma-bridge-mcp は MITライセンス の下でリリースされています。これは「現状のまま」提供され、保証はありません。正確な保証と責任の条件はライセンス自体に記載されています。サードパーティの著作権およびライセンス表示は NOTICE および engine/LICENSE に保持されています。

インスピレーションと帰属

2つのプロジェクトが、それぞれ異なる形でこのプロジェクトを形成しました。

figma-cli（Sil Bormüller）は、engine/ ディレクトリの由来です。2026年7月にv2.1.0でベンダー化され、その後分岐しました。CDPトランスポートとバイナリパッチインストーラーは削除され、プラグインソケットは認証され、エンジンが現在行っていることのほとんどはここで書かれました。4つのファイルが上流とバイト単位で同一のままです。上流のMITライセンスは engine/LICENSE に完全に保持され、NOTICE は変更内容を記録しています。

figma-console-mcp は、コードではなくアイデアを提供しました。Figmaブリッジは真にローカルであり得るということです — ループバックインターフェース上のプラグインソケット、クラウドリレーなし、パッチされたバイナリなし。ここにあるものはそのソースから派生したものはありません。ツールサーフェス、トランスポート、プラグインは無関係です。このプロジェクトが異なる点は、ソケットが相手側の身元も証明することです。

プラグインID。 開発マニフェストは、製品に合わせたID figma-bridge-mcp と figma-bridge-mcp-dev を使用します。Figmaは clientStorage（ペアリングされたアクセスキーが保存される場所）をプラグインIDでキーイングします。したがって、0.5.0より前のインストールでは、マニフェストを再インポートし、既存のBridgeアクセスキーを1回貼り付ける必要があります。