use_figma. Figma Plugin API スキル
use_figma ツールを使用して、Plugin API を介して Figma ファイル内で JavaScript を実行します。詳細なリファレンスドキュメントはすべて references/ にあります。
use_figma を呼び出す際は、常に skillNames: "figma-use" を渡してください。 これはスキルの使用状況を追跡するためのログパラメータです。実行には影響しません。
Figma MCP ツールが遅延ツールとして表示される場合は、ToolSearch 呼び出しで select: 構文を使用して、すべてのスキーマを一度にバッチロードしてください。 例: ToolSearch query="select:use_figma,get_screenshot,get_metadata,create_new_file"。1 回のラウンドトリップで 6 回の呼び出しを節約できます。
タスクが Figma でコードから完全なページ、画面、または複数セクションのレイアウトを構築または更新することを含む場合は、figma-generate-design もロードしてください。 これにより、search_design_system を介したデザインシステムコンポーネントの発見、インポート、および画面の段階的な組み立てのワークフローが提供されます。両方のスキルが連携します: このスキルは API ルールを、あのスキルは画面構築ワークフローを担当します。
タスクが Figma でコンポーネント(単一のコンポーネントでも)を作成または構築することを含む場合は、figma-generate-library もロードしてください。 これにより、コンポーネント作成ワークフロー、変数の基礎、バリアントセット、デザイントークンのバインディングが提供されます。figma-use だけではカバーされません。
まず、plugin-api-standalone.index.md をロードして、何が可能かを理解してください。プラグイン API コードの作成を求められた場合は、このコンテキストを使用して plugin-api-standalone.d.ts を grep し、関連する型、メソッド、プロパティを探してください。これが API サーフェスの信頼できる情報源です。これは大きな型定義ファイルなので、一度にすべてをロードせず、必要に応じて関連するセクションを grep してください。
重要: デザインシステムを操作するときは、まず working-with-design-systems/wwds.md から始めて、Figma のデザインシステムを操作するための主要な概念、プロセス、ガイドラインを理解してください。その後、必要に応じてコンポーネント、変数、テキストスタイル、エフェクトスタイルに関するより具体的なリファレンスをロードしてください。
1. 重要なルール
- データを返すには
returnを使用してください。 戻り値は自動的に JSON シリアライズされます(オブジェクト、配列、文字列、数値)。figma.closePlugin()を呼び出したり、コードを async IIFE でラップしたりしないでください。これらは自動的に処理されます。 - トップレベルの
awaitとreturnを使用して、プレーンな JavaScript を記述してください。 コードは自動的に非同期コンテキストでラップされます。(async () => { ... })()でラップしないでください。 figma.notify()は「not implemented」をスローします。絶対に使用しないでください。 3a.getPluginData()/setPluginData()はuse_figmaではサポートされていません。使用しないでください。代わりにgetSharedPluginData()/setSharedPluginData()(これらはサポートされています)を使用するか、ノード ID を返して後続の呼び出しに渡すことで追跡してください。console.log()は返されません。出力にはreturnを使用してください。- 小さなステップで段階的に作業を進めてください。 大規模な操作は複数の
use_figma呼び出しに分割してください。各ステップの後に検証してください。これはバグを避けるための最も重要なプラクティスです。 - 色は 0-1 の範囲(0-255 ではありません)です:
{r: 1, g: 0, b: 0}= 赤 - 塗り/ストロークは読み取り専用の配列です。クローン、変更、再割り当てを行ってください。
- すべてのテキスト編集は、次の標準的なレシピに従います: フォントをロード →
await→ 変更 → 影響を受けたノード ID を返す。 ロードをスキップすると、Cannot write to node with unloaded font "<family> <style>"がスローされます。このルールはcharactersだけではありません。フォントがロードされていないノードに対する操作(appendChild、insertChild、setBoundVariable、setExplicitVariableModeForCollection、setValueForMode、テキストに触れるfindAllコールバック)にも適用されます。既存のテキストを変更する場合は、ハードコードされたデフォルトではなく、getStyledTextSegments(['fontName'])を介してノードの現在のフォントをロードしてください。Inter はほとんどの環境でプリロードされているため、他のファミリでこのバグがより頻繁に発生します。レシピはすべてのフォントで同じです。スタイル文字列が未確認の場合は、最初にawait figma.listAvailableFontsAsync()を使用してください。標準的なテキスト編集レシピ を参照してください。 - ページは段階的にロードされます:
await figma.setCurrentPageAsync(page)を使用してページを切り替え、そのコンテンツをロードしてください。同期セッターfigma.currentPage = pageは機能せず、スローされます(以下のページルールを参照)。 setBoundVariableForPaintは新しいペイントを返すため、キャプチャして再割り当てする必要があります。createVariableはコレクションオブジェクトまたは ID 文字列を受け入れます(オブジェクト推奨)。layoutSizingHorizontal/Verticalは構造的コンテキストによって値が制限されます。FIXEDは常に機能しますが、HUGとFILLは機能しません。'HUG'は、オートレイアウトフレーム自体、またはそのテキスト子要素でのみ有効です。'FILL'は、オートレイアウトフレームの子要素で、かつ絶対配置されておらず、不変フレーム内になく、キャンバスグリッドの子要素でもない場合にのみ有効です。実用的な結果: 最初にオートレイアウトの親に追加し、次にHUG/FILLを設定します。新しく作成された、または親のないノードはまだルールを満たすことができません。このプロパティ自体はすべてのSceneNodeに存在します。エラーは「そのようなプロパティはありません」ではなく、値の拒否です。Gotchas を参照してください。 12a. 関連する子要素を含むコンテナにはオートレイアウトを使用してください。 子要素が構造的な関係(積み重ね、横並び、整列、間隔、ハグ)を持つ場合は、絶対的なx/yを持つfigma.createFrame()ではなく、figma.createAutoLayout()でラップしてください。絶対座標はキャンバス上のコンテナの位置を決定します。オートレイアウトは内部の子要素の関係を決定します。コンテナをスキップすると、テキストのリフロー、コンテンツの変更、または重なりから保護されなくなります。- 新しいトップレベルノードは (0,0) から離して配置してください。 ページに直接追加されたノードはデフォルトで (0,0) になります。
figma.currentPage.childrenをスキャンして、明確な位置(例: 右端のノードの右側)を見つけてください。これはページレベルのノードにのみ適用されます。他のフレームやオートレイアウトコンテナ内にネストされたノードは、その親によって配置されます。Gotchas を参照してください。 use_figmaエラーが発生した場合は、STOP してください。すぐに再試行しないでください。 失敗したスクリプトはアトミックです: スクリプトがエラーになると、まったく実行されず、ファイルに変更は加えられません。エラーメッセージを注意深く読み、スクリプトを修正してから再試行してください。エラーリカバリ を参照してください。- 作成または変更したすべてのノード ID を
returnする必要があります。 スクリプトがキャンバス上に新しいノードを作成したり、既存のノードを変更したりする場合は常に、影響を受けるすべてのノード ID を収集し、構造化されたオブジェクト(例:return { createdNodeIds: [...], mutatedNodeIds: [...] })で返してください。これは、後続の呼び出しがそれらのノードを参照、検証、またはクリーンアップするために不可欠です。 - 変数を作成するときは、常に
variable.scopesを明示的に設定してください。 デフォルトのALL_SCOPESはすべてのプロパティピッカーを汚染するため、ほとんどの場合望ましくありません。背景には["FRAME_FILL", "SHAPE_FILL"]、テキスト色には["TEXT_FILL"]、間隔には["GAP"]などの特定のスコープを使用してください。完全なリストは variable-patterns.md を参照してください。 - すべての Promise を
awaitしてください。 Promise を未 await のままにしないでください。await されていない非同期呼び出し(例:awaitなしのfigma.loadFontAsync(...)やawaitなしのfigma.setCurrentPageAsync(page))は、ファイアアンドフォーゲットになり、サイレント障害や競合状態を引き起こします。スクリプトは非同期操作が完了する前に戻り、データの欠落や変更の半適用につながる可能性があります。
各ルールの詳細な WRONG/CORRECT の例については、Gotchas & Common Mistakes を参照してください。
2. ページルール(重要)
ページコンテキストは use_figma 呼び出しの間でリセットされます: figma.currentPage は毎回最初のページから始まります。
ページの切り替え
await figma.setCurrentPageAsync(page) を使用してページを切り替え、そのコンテンツをロードしてください。同期セッター figma.currentPage = page は機能しません: use_figma で "Setting figma.currentPage is not supported" をスローします。常に非同期メソッドを使用してください。
// 特定のページに切り替える(コンテンツをロードする)
const targetPage = figma.root.children.find((p) => p.name === "My Page");
await figma.setCurrentPageAsync(targetPage);
// targetPage.children にデータが入る
setCurrentPageAsync は use_figma の 1 回の呼び出しで最大 1 回呼び出し、複数ページの作業は並列に分散する
1 つのスクリプトでページを切り替えるのは最大 1 回です。 figma.root.children をループし、ループ内でページを切り替えないでください。
作業が複数のページにまたがる場合は、N 個の use_figma 呼び出し(ターゲットページごとに 1 つ)に分割し、並列に発行してください: 1 つのアシスタントメッセージに N 個の use_figma ツール使用ブロックを含めます。ハーネスはそれらを同時に実行します。各スクリプトは currentPage を正確に 1 回設定します。
明示的な指示: ファンアウトする場合、N 個のツール呼び出しを1 つのメッセージで発行する必要があります。複数のターンにわたって送信しないでください。1 つを発行してから次を待たないでください。シーケンシャルなページごとの呼び出しは、このルールが置き換えるループ内パターンよりも遅く、分割の利点をすべて無駄にします。
// 避けるべき: 1 つのスクリプトで N 回ページを切り替え、そのたびにファイルをリロードする
for (const page of figma.root.children) {
await figma.setCurrentPageAsync(page);
// ... このページに触れる ...
}
// 推奨: 読み取り専用の検出呼び出しでページ ID を取得し、次のメッセージで
// N 個の並列 use_figma ツール呼び出し(ページごとに 1 つ)を発行し、それぞれが currentPage を 1 回設定する
複数ページの作業では、読み取りと書き込みの両方で、デフォルトで並列ファンアウトを使用してください。完全な理論的根拠については、gotchas.md → Set current page once per use_figma call を参照してください。
スクリプト実行間
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")と Slides("slides")では、利用可能なノードタイプのセットが異なります。ほとんどのデザインノードは FigJam でブロックされ、FigJam 専用ノードは Slides でブロックされます。
URL からエディタを判別してください: Design = figma.com/design/...、FigJam = figma.com/board/...、Slides = figma.com/slides/...。API が利用可能であると仮定する前に確認してください。
デザインモードで利用可能: Rectangle、Frame、Component、Text、Ellipse、Star、Line、Vector、Polygon、BooleanOperation、Slice、Page、Section、TextPath。
デザインモードでブロック: Sticky、Connector、ShapeWithText、CodeBlock、Slide、SlideRow、SlideGrid、InteractiveSlideElement、Webpage。
Slides モードで利用可能: Rectangle、Frame、Component、Text、Ellipse、Star、Line、Vector、Polygon、BooleanOperation、Slice、Section、TextPath、Slide、SlideRow、SlideGrid、InteractiveSlideElement。
Slides モードでブロック: Sticky、Connector、ShapeWithText、CodeBlock、Webpage、Page。
デザイン専用 API(ノードタイプだけでなく): figma.createPage() はデザインファイル(figma.com/design/...)でのみ使用できます。FigJam(figma.com/board/...)と Slides(figma.com/slides/...)の両方で、TypeError: figma.createPage no such property 'createPage' on the figma global object をスローします。FigJam または Slides のワークフローで figma.createPage() を発行しないでください。
Slides に関する注意: Slides ファイル用の専用の読み取りツールはまだありません。検査には
use_figmaを読み取り専用スクリプト(セクション 6「Inspect first」パターンを参照)で使用し、視覚的なコンテキストにはget_screenshot/await node.screenshot()を使用してください。Slides 固有の API ガイダンスについては、figma-use-slides スキルをロードしてください。
5. 効率的な API。冗長な代替手段よりもこれらを優先する
これらの API はボイラープレートを削減し、順序エラーを排除し、トークン出力を圧縮します。冗長な代替手段よりも常にこれらを優先してください。
node.query(selector): CSS ライクなノード検索
CSS ライクなセレクタを使用して、サブツリー内のノードを見つけます。冗長な findAll + フィルタループを置き換えます。
// 以前: 冗長なトラバーサル
const texts = frame.findAll(n => n.type === 'TEXT' && n.name === 'Title')
// 以後: query によるワンライナー
const texts = frame.query('TEXT[name=Title]')
セレクタ構文:
- タイプ:
FRAME、TEXT、RECTANGLE、ELLIPSE、COMPONENT、INSTANCE、SECTION(大文字小文字を区別しない) - 属性完全一致:
[name=Card]、[visible=true]、[opacity=0.5] - 属性部分一致:
[name*=art](含む)、[name^=Header](前方一致)、[name$=Nav](後方一致) - ドットパス:
[fills.0.type=SOLID]、[fills.*.type=SOLID](ワイルドカードインデックス) - インスタンスマッチング:
[mainComponent=nodeId]、[mainComponent.name=Button] - コンビネータ:
FRAME > TEXT(直接の子)、FRAME TEXT(任意の子孫)、A + B(隣接兄弟)、A ~ B(一般兄弟) - 疑似クラス:
:first-child、:last-child、:nth-child(2)、:not(TYPE)、:is(FRAME, RECTANGLE)、:where(TEXT, ELLIPSE) - ノード ID:
#nodeIdまたはベア GUID - カンマ:
TEXT, RECTANGLE(OR)
// 複合例
const buttons = page.query('FRAME[name*=Button] > TEXT[name=Label]');
const firstIcon = frame.query(':first-child');
const solidFills = frame.query('RECTANGLE[fills.0.type=SOLID]');
const specificComponent = page.query('INSTANCE[mainComponent=123]');
figma.createXxx ヘルパー
ノード作成を簡素化するファクトリ: figma.createRectangle()、figma.createText()、figma.createFrame()、figma.createAutoLayout()。createAutoLayout は layoutMode が HORIZONTAL または VERTICAL に設定されたフレームを作成します。
自動レイアウトのプロパティ
itemSpacing、paddingLeft、paddingRight、paddingTop、paddingBottom、layoutAlign(親にINHERIT、子にSTRETCH)、primaryAxisAlignItems、counterAxisAlignItems。
6. エラーリカバリと自己修正
use_figma エラー時の動作
use_figma がエラーを報告した場合、スクリプトはアトミックに失敗しています。ファイルは変更されていません。すぐに再試行しないでください。エラーメッセージを注意深く読み、根本原因を特定してから再試行してください。
デバッグワークフロー
- エラーメッセージを読む
- 不明な場合は、
references/gotchas.mdの関連ルールを参照する - スクリプトを修正する
- 修正されたスクリプトで新しい
use_figma呼び出しを発行する
「Inspect first」パターン
書き込みスクリプトを作成する前に、短い読み取り専用スクリプトを使用して既存のノード構造を検査します。
// 書き込む前にページ上の既存のノードを検査する
const pageInfo = figma.currentPage.children.map(n => ({
id: n.id,
name: n.name,
type: n.type
}));
return { pageName: figma.currentPage.name, children: pageInfo };
これにより、不意にノードを上書きするのを防ぎ、後続の呼び出しが正しい ID をターゲットにできるようになります。
共通エラーパターン
| エラーメッセージ | 原因 | 解決策 |
|---|---|---|
Cannot read properties of null | ID のノードが見つからない | ノード ID が有効であることを確認する |
Cannot write to node with unloaded font | 変更前にフォントがロードされていない | figma.loadFontAsync を呼び出す |
Setting figma.currentPage is not supported | 同期セッターの使用 | await figma.setCurrentPageAsync() を使用する |
figma.createPage no such property | 間違ったモード(FigJam/Slides) | URL を確認してモードを特定する |
ALL_SCOPES is not allowed | 変数スコープが広すぎる | 明示的なスコープを使用する |
7. 参照
- Gotchas & Common Mistakes: WRONG/CORRECT の例
- Variable Patterns: 変数の作成とバインディング
- Working With Design Systems: デザインシステムの概念
- Plugin API Types: 完全な API 型定義(必要に応じて grep)
- Plugin API Index: API 機能の概要