figma-use

use_figma — Figma Plugin API スキル

use_figma MCP を使用して、Plugin API 経由で Figma ファイル内の JavaScript を実行します。詳細なリファレンスドキュメントはすべて references/ にあります。

use_figma の呼び出し時は、必ず skillNames: "figma-use" を渡してください。 これはスキルの使用状況を追跡するためのログ用パラメーターであり、実行には影響しません。

コードから Figma でページ全体、画面、または複数セクションのレイアウトを作成または更新するタスクの場合は、 figma-generate-design も読み込んでください。デザインシステムのコンポーネントを search_design_system で検索してインポートし、画面を段階的に組み立てるワークフローを提供します。2 つのスキルは連携して機能します。こちらは API のルールを、もう一方は画面構築のワークフローを扱います。

何よりも先に、plugin-api-standalone.index.md を読み込み、何ができるのかを把握してください。Plugin API コードの作成を依頼された場合は、このコンテキストをもとに plugin-api-standalone.d.ts を grep して、関連する型、メソッド、プロパティを確認してください。これは API の仕様を確認するための決定版の情報源です。型定義ファイルは大きいため、一度にすべて読み込まず、必要に応じて関連する箇所を grep してください。

重要：デザインシステムを扱う場合は、まず working-with-design-systems/wwds.md を読み込み、Figma でデザインシステムを扱う際の主要な概念、プロセス、ガイドラインを把握してください。その後、必要に応じてコンポーネント、変数、テキストスタイル、エフェクトスタイルに関する詳細なリファレンスを読み込んでください。

1. 重要なルール

1. データを返すには return を使用してください。 戻り値は自動的に JSON にシリアライズされます（オブジェクト、配列、文字列、数値）。figma.closePlugin() を呼び出したり、コードを非同期 IIFE で囲んだりしないでください。これらは自動的に処理されます。
2. トップレベルの await と return を使って、プレーンな JavaScript を記述してください。 コードは自動的に非同期コンテキストでラップされます。(async () => { ... })() で囲まないでください。
3. figma.notify() は 「not implemented」エラーをスローします。絶対に使用しないでください。 3a. getPluginData() / setPluginData() は use_figma では サポートされていません。使用しないでください。代わりに getSharedPluginData() / setSharedPluginData() を使用してください（これらはサポートされています）。または、ノード ID を返し、後続の呼び出しに渡して追跡してください。
4. console.log() の出力は返されません。出力には return を使用してください。
5. 小さな手順で段階的に作業してください。 大きな操作は複数の use_figma 呼び出しに分割してください。各手順の後に検証してください。バグを避けるうえで、これが最も重要な実践事項です。
6. 色の範囲は 0～1 です（0～255 ではありません）。{r: 1, g: 0, b: 0} は赤です。
7. 塗りと線は 読み取り専用の配列 です。複製して変更し、再割り当てしてください。
8. テキスト操作の前に、必ずフォントを読み込んでください：await figma.loadFontAsync({family, style})
9. ページは段階的に読み込まれます。await figma.setCurrentPageAsync(page) を使用してページを切り替え、そのコンテンツを読み込んでください（以下の「ページのルール」を参照）。
10. setBoundVariableForPaint は 新しい ペイントを返すため、受け取って再割り当てする必要があります。
11. createVariable はコレクションの オブジェクトまたは ID 文字列 を受け取ります（オブジェクトを推奨）。
12. layoutSizingHorizontal/Vertical = 'FILL' は parent.appendChild(child) の後に設定する必要があります。前に設定するとエラーになります。自動レイアウトではないノードに対する 'HUG' も同様です。
13. 新しいトップレベルノードは (0,0) から離れた位置に配置してください。 ページに直接追加したノードは、既定で (0,0) に配置されます。figma.currentPage.children をスキャンして、空いている位置（例：最も右にあるノードの右側）を見つけてください。これはページレベルのノードにのみ適用されます。ほかのフレームや自動レイアウトコンテナー内にネストされたノードの位置は、親によって決まります。落とし穴を参照してください。
14. use_figma でエラーが発生したら、停止してください。すぐに再試行しないでください。 失敗したスクリプトは アトミック です。スクリプトでエラーが発生すると、スクリプトは実行されず、ファイルに変更は加えられません。エラーメッセージをよく読み、スクリプトを修正してから再試行してください。エラーからの復旧を参照してください。
15. 作成または変更したすべてのノード ID を必ず return してください。 スクリプトでキャンバス上に新しいノードを作成したり、既存のノードを変更したりする場合は、影響を受けたノード ID をすべて収集し、構造化オブジェクトで返してください（例：return { createdNodeIds: [...], mutatedNodeIds: [...] }）。後続の呼び出しでこれらのノードを参照、検証、またはクリーンアップするために不可欠です。
16. 変数の作成時は、必ず variable.scopes を明示的に設定してください。 既定の ALL_SCOPES はすべてのプロパティ選択メニューを煩雑にします。ほとんどの場合、これは望ましくありません。背景には ["FRAME_FILL", "SHAPE_FILL"]、テキストの色には ["TEXT_FILL"]、間隔には ["GAP"] など、具体的なスコープを使用してください。すべてのスコープの一覧は variable-patterns.md を参照してください。
17. すべての Promise を await してください。 Promise を await せずに残さないでください。await を付けない非同期呼び出し（例：await を付けない figma.loadFontAsync(...) や figma.setCurrentPageAsync(page)）は、処理が完了するのを待たずに実行されるため、気付かれない失敗や競合状態を引き起こします。非同期処理の完了前にスクリプトが戻り、データの欠落や変更が部分的にしか適用されない可能性があります。

各ルールの詳しい誤った例／正しい例については、落とし穴とよくある間違いを参照してください。

2. ページのルール（重要）

use_figma の呼び出しごとにページコンテキストはリセットされます。そのため、毎回 figma.currentPage は最初のページから始まります。

ページの切り替え

await figma.setCurrentPageAsync(page) を使用して、ページを切り替え、そのコンテンツを読み込んでください。同期セッターの figma.currentPage = page は、use_figma の実行環境では エラーをスローします。

// Switch to a specific page (loads its content)
const targetPage = figma.root.children.find((p) => p.name === "My Page");
await figma.setCurrentPageAsync(targetPage);
// targetPage.children is now populated

// Iterate over all pages
for (const page of figma.root.children) {
  await figma.setCurrentPageAsync(page);
  // page.children is now loaded — read or modify them here
}

スクリプト実行間

figma.currentPage は、各 use_figma 呼び出しの開始時に最初のページにリセットされます。ワークフローが複数回の呼び出しにまたがり、デフォルト以外のページを対象とする場合は、各呼び出しの開始時に await figma.setCurrentPageAsync(page) を呼び出してください。

use_figma は、ファイルの状態を段階的に構築したり、別のスクリプトを書き込む前に情報を取得したりするために、複数回呼び出せます。たとえば、既存のノードに関するメタデータを取得するスクリプトを書き、そのデータを return してから、後続のスクリプトでそのノードを変更できます。

3. return は出力チャネルです

エージェントに見えるのは、return した値のみです。それ以外はすべて表示されません。

• ID の返却（重要）：キャンバスノードを作成または変更するすべてのスクリプトは、影響を受けたノードの ID をすべて返す必要があります。例：return { createdNodeIds: [...], mutatedNodeIds: [...] }。これは必須要件であり、任意ではありません。
• 進行状況の報告：return { createdNodeIds: [...], count: 5, errors: [] }
• エラー情報：スローされたエラーは自動的に捕捉され、返されます。そのまま伝播させるか、明示的に throw してください。
• console.log() の出力がエージェントに返されることはありません
• 後続の呼び出しで作成済みオブジェクトを参照できるよう、ID、件数、状態など、常に次の操作に活用できるデータを返してください

4. エディターモード

use_figma はデザインモード（editorType "figma"、デフォルト）で動作します。FigJam（"figjam"）では利用可能なノードタイプが異なり、ほとんどのデザインノードは使用できません。

デザインモードで使用可能：Rectangle、Frame、Component、Text、Ellipse、Star、Line、Vector、Polygon、BooleanOperation、Slice、Page、Section、TextPath。

デザインモードで使用不可：Sticky、Connector、ShapeWithText、CodeBlock、Slide、SlideRow、Webpage。

5. 段階的なワークフロー（バグを防ぐ方法）

バグの最も一般的な原因は、1 回の use_figma 呼び出しで多くのことをしようとすることです。小さな手順に分け、各手順の後で検証してください。

推奨パターン

1. まず調査します。 何かを作成する前に、読み取り専用の use_figma を実行して、ファイルにすでに存在するページ、コンポーネント、変数、命名規則を確認します。既存の内容に合わせてください。
2. 1 回の呼び出しにつき 1 つの作業を行います。 1 回の呼び出しで変数を作成し、次の呼び出しでコンポーネントを作成し、別の呼び出しでレイアウトを構成します。1 つのスクリプトですべての画面を構築しようとしないでください。
3. 各呼び出しで ID を返します。 作成したノード ID、変数 ID、コレクション ID は、常にオブジェクトとして return してください（例：`return { createdNodeIds: [...] }）。後続の呼び出しで入力値として必要になります。
4. 各手順の後で検証します。 構造（件数、名前、階層、位置）の確認には get_metadata を使用します。大きな作業の区切りでは get_screenshot を使用して、視覚的な問題を見つけます。
5. 先に問題を修正します。 検証で問題が見つかった場合は、次の手順に進む前に修正してください。問題のある土台の上に構築しないでください。

複雑なタスクで推奨する手順

Step 1: Inspect file — discover existing pages, components, variables, conventions
Step 2: Create tokens/variables (if needed)
       → validate with get_metadata
Step 3: Create individual components
       → validate with get_metadata + get_screenshot
Step 4: Compose layouts from component instances
       → validate with get_screenshot
Step 5: Final verification

各手順で検証する内容

実行後...	get_metadata で確認	get_screenshot で確認
変数の作成	コレクション数、変数数、モード名	—
コンポーネントの作成	子の数、バリアント名、プロパティ定義	バリアントが表示されていること、折りたたまれていないこと、グリッドが読みやすいこと
変数のバインド	ノードのプロパティにバインドが反映されていること	色やトークンが正しく解決されていること
レイアウトの構成	インスタンスノードに mainComponent があり、階層が正しいこと	テキストが切り取られていないこと、要素が重なっていないこと、間隔が適切であること

6. エラーからの復旧と自己修正

use_figma はアトミックです。スクリプトが失敗すると、変更は実行されません。 スクリプトでエラーが発生した場合、ファイルには変更が加えられません。ファイルは呼び出し前と同じ状態のままです。つまり、失敗したスクリプトによる中途半端なノードや孤立した要素は残らず、修正後に安全に再試行できます。

use_figma がエラーを返した場合

1. 停止してください。 すぐにコードを修正して再試行してはいけません。
2. エラーメッセージを注意深く読んでください。 何が問題だったのか（API の使い方の誤り、フォントの不足、無効なプロパティ値など）を正確に把握します。
3. エラーが不明瞭な場合は、 get_metadata または get_screenshot を呼び出して、現在のファイルの状態を把握します。
4. エラーメッセージに基づいてスクリプトを修正します。
5. 修正したスクリプトを再試行します。

よくある自己修正のパターン

エラーメッセージ	考えられる原因	修正方法
"not implemented"	figma.notify() を使用した	削除してください。出力には return を使用します
"node must be an auto-layout frame..."	オートレイアウトの親に追加する前に FILL／HUG を設定した	appendChild を layoutSizingX = 'FILL' より前に移動します
"Setting figma.currentPage is not supported"	同期ページセッターを使用した	await figma.setCurrentPageAsync(page) を使用します
プロパティ値が範囲外	色チャンネルが 1 を超えている（0～1 ではなく 0～255 を使用した）	255 で割ります
"Cannot read properties of null"	ノードが存在しない（ID が間違っている、またはページが違う）	ページのコンテキストを確認し、ID を検証します
スクリプトが停止する／応答がない	無限ループ、または解決されない Promise	while(true) や await の不足がないか確認し、コードが終了することを確かめます
"The node with id X does not exist"	子の detachInstance() によって親インスタンスが暗黙的に切り離され、ID が変わった	安定した（インスタンスではない）親フレームからたどって、ノードを再検出します

スクリプトは成功したが、結果が正しく見えない場合

1. get_metadata を呼び出して、構造が正しいか（階層、数、位置）を確認します。
2. get_screenshot を呼び出して、見た目が正しいかを確認します。テキストの切り抜き／クリッピング（行の高さによって内容が見切れていないか）や、要素の重なりをよく確認します。これらはよく起こり、見落としやすい問題です。
3. どのような不一致かを特定します。構造上の問題（階層が間違っている、ノードがない）ですか、それとも見た目の問題（色が違う、レイアウトが崩れている、内容が見切れている）ですか。
4. 問題のある箇所だけを変更する、対象を絞った修正スクリプトを作成します。すべてを作り直してはいけません。

検証ワークフローの全体については、検証とエラーからの復旧を参照してください。

7. 事前チェックリスト

use_figma を呼び出す前に、必ず次の項目を確認してください。

• データの返却に return を使用している（figma.closePlugin() は使用していない）
• コードを async IIFE でラップしていない（自動的にラップされます）
• return 値に、実用的な情報（ID、数）を含む構造化データが含まれている
• figma.notify() をどこでも使用していない
• 出力に console.log() を使用していない（代わりに return を使用する）
• すべての色が 0～1 の範囲を使用している（0～255 ではない）
• 塗りと線をその場で変更せず、新しい配列として再代入している
• ページの切り替えに await figma.setCurrentPageAsync(page) を使用している（同期セッターは例外を発生させます）
• layoutSizingVertical/Horizontal = 'FILL' を parent.appendChild(child) の後に設定している
• テキストプロパティを変更する前に loadFontAsync() を呼び出している
• lineHeight／letterSpacing に {unit, value} 形式を使用している（数値のみではない）
• サイズモードを設定する前に resize() を呼び出している（resize() によってサイズモードは FIXED にリセットされます）
• 複数ステップのワークフローでは、前回の呼び出しで取得した ID を変数ではなく文字列リテラルとして渡している
• 新しい最上位ノードを (0,0) から離れた位置に配置し、既存のコンテンツと重ならないようにしている
• 作成／変更したすべてのノード ID を収集し、return 値に含めている
• すべての非同期呼び出し（loadFontAsync、setCurrentPageAsync、importComponentByKeyAsync など）に await を付けている（Promise を放置していない）

8. 作成前に規約を確認する

何かを作成する前に、必ず Figma ファイルを調べてください。 ファイルごとに、命名規則、変数の構造、コンポーネントのパターンは異なります。新たな規約を持ち込むのではなく、既存のものにコードを合わせてください。

規約（命名、スコープ、構造など）が不明な場合は、まず Figma ファイルを確認し、次にユーザーのコードベースを確認します。どちらにも情報がない場合に限り、一般的なパターンを使用してください。

クイックインスペクションスクリプト

すべてのページとトップレベルのノードを一覧表示する：

const pages = figma.root.children.map(p => `${p.name} id=${p.id} children=${p.children.length}`);
return pages.join('\n');

すべてのページにある既存のコンポーネントを一覧表示する：

const results = [];
for (const page of figma.root.children) {
  await figma.setCurrentPageAsync(page);
  page.findAll(n => {
    if (n.type === 'COMPONENT' || n.type === 'COMPONENT_SET')
      results.push(`[${page.name}] ${n.name} (${n.type}) id=${n.id}`);
    return false;
  });
}
return results.join('\n');

既存の変数コレクションとその規則を一覧表示する：

const collections = await figma.variables.getLocalVariableCollectionsAsync();
const results = collections.map(c => ({
  name: c.name, id: c.id,
  varCount: c.variableIds.length,
  modes: c.modes.map(m => m.name)
}));
return results;

9. リファレンスドキュメント

タスクの内容に応じて、必要なドキュメントを読み込んでください。

Doc	読み込むタイミング	内容
gotchas.md	use_figma を使う前	WRONG/CORRECT のコード例を含む、既知の落とし穴すべて
common-patterns.md	動作するコード例が必要なとき	スクリプトのひな形：図形、テキスト、オートレイアウト、変数、コンポーネント、複数ステップのワークフロー
plugin-api-patterns.md	ノードを作成・編集するとき	塗り、線、オートレイアウト、エフェクト、グループ化、複製、スタイル
api-reference.md	正確な API の範囲が必要なとき	ノード作成、変数 API、主要なプロパティ、動作するものとしないもの
validation-and-recovery.md	複数ステップの書き込みやエラー復旧を行うとき	get_metadata と get_screenshot のワークフロー、必須のエラー復旧手順
component-patterns.md	コンポーネント／バリアントを作成するとき	combineAsVariants、コンポーネントのプロパティ、INSTANCE_SWAP、バリアントのレイアウト、既存コンポーネントの検索、メタデータのトラバーサル
variable-patterns.md	変数を作成・バインドするとき	コレクション、モード、スコープ、エイリアス、バインドパターン、既存変数の検索
text-style-patterns.md	テキストスタイルを作成・適用するとき	タイプスケール、フォントの確認、スタイルの一覧表示、ノードへのスタイル適用
effect-style-patterns.md	エフェクトスタイルを作成・適用するとき	ドロップシャドウ、スタイルの一覧表示、ノードへのスタイル適用
plugin-api-standalone.index.md	API の全範囲を把握する必要があるとき	Plugin API のすべての型、メソッド、プロパティのインデックス
plugin-api-standalone.d.ts	正確な型シグネチャが必要なとき	型定義ファイル全体。特定のシンボルを grep し、一度にすべてを読み込まないでください

10. スニペットの例

このドキュメントには、各所にスニペットが含まれています。これらのスニペットには、再利用できる便利な Plugin API コードが含まれています。そのまま使うか、作業を進める際の出発点として使ってください。汎用的なスニペットとして記録するのが適している重要な概念があれば、今後再利用できるように書き出してください。