figma-use

use_figma — Figma Plugin API スキル

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

利用できる場合は、ファイルの読み取りや編集を行う前に、fileKey と description を指定して create_session を呼び出してください（必要であれば、先にファイルを作成してください）。その後、返された sessionId は、後続の呼び出しやファイルをまたいだ作業を含め、受け付けるすべての呼び出しに変更せず渡してください。

use_figma の呼び出しでは、カンマ区切りの skillNames パラメーターに必ず figma-use を含めてください。このスキルが MCP リソース経由で読み込まれた場合は、名前の先頭に resource: を付ける必要があります（例：resource:figma-use）。 これはスキルの使用状況を追跡するためのログ用パラメーターであり、実行には影響しません。

Figma MCP ツールが遅延読み込みツールとして表示される場合は、select: 構文を使い、単一の ToolSearch 呼び出しですべてのスキーマを一括読み込みしてください（例：ToolSearch query="select:use_figma,get_screenshot,get_metadata,create_new_file"）。6 回に分けて往復するより、一度で済ませる方が効率的です。

表示されるデザインを変更する場合は必須です： 最初に変更を加える use_figma 呼び出しを行う前に、このスキルとあわせて figma-generate-design を読み込み、変更を加えるすべての呼び出しの skillNames に両方の名前を含めてください。対象は、単一の表示プロパティや要素から、ページ、画面、複数セクションで構成されるビュー全体までです。ユーザーがそのビューをコンポーネントと呼んでいる場合も同様です。figma-use は Plugin API のルールを、figma-generate-design は search_design_system によるデザインシステムの調査、アセットのインポート、段階的な組み立て方法を提供します。

再利用可能なライブラリに関する例外： 主な成果物が、再利用または公開を目的とする再利用可能なコンポーネント、コンポーネントセット、バリアントシステム、変数／トークンコレクション、スタイル基盤、その他のライブラリアセットである場合は、代わりに figma-generate-library を読み込んでください。これは、figma-use だけではカバーできない、変数の基盤、バリアントセット、デザイントークンのバインディングを含むコンポーネント作成ワークフローを提供します。ライブラリアセットと、それを使った組み合わせデザインの両方を含むタスクでは、両方の補助スキルを読み込んでください。読み取り専用の use_figma 呼び出しでは、どちらも必要ありません。

作業を始める前に、plugin-api-standalone.index.md を読み込み、何ができるかを把握してください。Plugin API のコードを書くよう求められた場合は、このコンテキストを踏まえて plugin-api-standalone.d.ts を検索し、関連する型、メソッド、プロパティを確認してください。これは API の仕様を確認するための決定的な情報源です。型定義ファイルは大きいため、すべてを一度に読み込まず、必要に応じて関連するセクションを検索してください。

重要：デザインシステムを扱う場合は必ず、まず 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. ノード ID を返し、ワークフローの状態は Figma ファイルの外部で保持します。 人が読めるコンポーネントの目的と使用方法は、node.description に設定する場合、COMPONENT または COMPONENT_SET のみに設定してください。フレームやインスタンスには設定しないでください。 3b. 型固有のプロパティにアクセスする前に、型を絞り込みます。 node.type を確認するか、"characters" in node のような機能ガードを使うか、findAllWithCriteria で事前に絞り込んでください。characters を使えるのはテキスト対応ノードだけです。オプショナルチェーンを使っても、未対応プロパティへのアクセスは保護されません。
4. console.log() の出力は返されません。出力には return を使ってください。
5. 安全に再試行できるように構築処理の単位を決め、得られた結果に基づいて検証します。 検証のチェックポイントを作ることだけを理由に、動作する処理を分割しないでください。スクリプトを安全に再試行できるなら、関連する処理をまとめてください。セクション全体またはページ全体を1回の呼び出しで構築してもかまいません。ページコンテキストをまたぐ場合、部分実行からの復旧が難しい場合、または実際に失敗したため対象を絞った再試行が必要な場合に分割します。書き込みごとに、影響を受けた ID と関連する数、名前、または境界を返してください。これを構造的な検証として扱えます。必要な証拠が不足している場合、または関連する変更を加えた後に限り、別途構造チェックを実行します。通常、レイアウト後にスクリーンショットを1枚撮り、視覚的な修正後にもう1枚撮ります。最後の合格済みスクリーンショットを最終チェックとし、関連する変更がない限り撮り直さないでください。要件を満たしたら終了します。
6. 色は 0～1の範囲（0～255ではありません）です。{r: 1, g: 0, b: 0} は赤です。Paint の color オブジェクトに使えるのは {r, g, b} のみで、a フィールドは使えません。不透明度は Paint のレベルで指定します（{ type: 'SOLID', color: {...}, opacity: 0.5 }）。
7. 塗りと線は 読み取り専用の配列です。複製して変更し、再代入してください。
8. テキストを編集する際は、必ず正規の手順に従ってください。フォントを読み込む → await → 変更 → 影響を受けたノード ID を返す。 読み込みを省略すると、Cannot write to node with unloaded font "<family> <style>" がスローされます。このルールは characters だけでなく、未読み込みフォントを使用するノードに対するあらゆる操作に適用されます（appendChild、insertChild、setBoundVariable、setExplicitVariableModeForCollection、setValueForMode、テキストに触れる findAll コールバック）。既存のテキストを変更する場合は、ハードコードしたデフォルト値ではなく、getStyledTextSegments(['fontName']) を使って現在のフォントを読み込んでください。ほとんどの環境では Inter がプリロードされているため、他のファミリーのほうがこの問題が表面化しやすいですが、すべてのフォントで手順は同じです。スタイル文字列が未検証の場合は、まず await figma.listAvailableFontsAsync() を使い、決して推測しないでください（"SemiBold" と "Semi Bold" の違いはよくある落とし穴です）。FONT_FAMILY スコープの変数では、setBoundVariable("fontFamily", …)、setValueForMode、または setExplicitVariableModeForCollection の前に、関連するすべてのモードの値を読み込んでください。lineHeight／letterSpacing には、数値だけでなく {unit, value} を指定します。正規のテキスト編集手順を参照してください。
9. ページは段階的に読み込まれます。 ページを切り替えてそのコンテンツを読み込むには、await figma.setCurrentPageAsync(page) を使います。同期待機なしのセッター figma.currentPage = page は 動作せず、"Setting figma.currentPage is not supported" がスローされます。すべての use_figma 呼び出しの開始時に、ページコンテキストは 最初のページ にリセットされるため、呼び出しごとに切り替え直してください。1回の呼び出しでの切り替えは最大1回にし、複数ページの処理は並列に分けてください。ページのルールおよびgotchas.mdを参照してください。
10. setBoundVariableForPaint は 新しい Paint を返すため、受け取って再代入する必要があります。
11. createVariable はコレクションの オブジェクトまたは ID 文字列を受け付けます（オブジェクトを推奨）。
12. layoutSizingHorizontal/Vertical の値は構造的なコンテキストによって制限されます。FIXED は常に使えますが、HUG と FILL は使えない場合があります。 'HUG' が有効なのは、自動レイアウトフレーム自体、またはその子である TEXT のみです。'FILL' が有効なのは、自動レイアウトフレームの子のうち、絶対位置指定ではなく、変更不可のフレーム内になく、キャンバスグリッドの子でもないノードのみです。実際には、まず自動レイアウトの親に追加し、その後で HUG／FILL を設定します。新しく作成したノードや親のないノードは、まだルールを満たせません。このプロパティ自体はすべての SceneNode にあります。エラーは「そのプロパティが存在しない」という意味ではなく、値が拒否されたことを示します。Gotchasを参照してください。 12a. 関連する子を含むコンテナーには、自動レイアウトを使います。 子に構造的な関係（縦積み、横並び、整列、間隔、内容に合わせたサイズ）がある場合は、絶対的な x／y を設定した figma.createFrame() ではなく、figma.createAutoLayout() で囲んでください。絶対座標はキャンバス上でコンテナーを配置する場所を決め、自動レイアウトはコンテナー内で子同士がどう関係するかを決めます。コンテナーを省略すると、テキストの再フロー、コンテンツの変更、重なりに対する保護がなくなります。 12b. layoutSizing* と *AxisSizingMode は異なる列挙型です。混同しないでください。 layoutSizingHorizontal／layoutSizingVertical（子に設定）で指定できる値は 'FIXED'|'HUG'|'FILL'、primaryAxisSizingMode／counterAxisSizingMode（フレーム自体に設定）で指定できる値は 'FIXED'|'AUTO' です。そのため、layoutSizingVertical = 'AUTO' は無効です（'HUG' を使ってください）。また、counterAxisSizingMode = 'FILL' は Expected 'FIXED' | 'AUTO', received 'FILL' をスローします（'FIXED'／'AUTO' を使ってください）。同じセッターで発生する次の2つのエラー、Error: in set_layoutSizingHorizontal: node must be an auto-layout frame or a child of an auto-layout frame と Error: in set_layoutSizingHorizontal: FILL can only be set on children of auto-layout frames は、ノードがまだ自動レイアウトのコンテキストにないことを意味します。推奨される対処法：親を自動レイアウト（figma.createAutoLayout()）にし、設定前にノードを appendChild してください（ルール12を参照）。Gotchasを参照してください。 12c. resize() はサイズ設定モードを FIXED にリセットするため、layoutSizing* の設定前に呼び出します。 折り返しが必要な TEXT ブロックには、textAutoResize = 'HEIGHT' と明示的な FIXED 幅（resize()）が必要です。FILL だけでは不十分です。デフォルトの WIDTH_AND_HEIGHT モードは FILL を無視し、ノードをほぼ幅ゼロの細い状態に縮めてしまいます。その後、node.width > 0 であることを確認してください。
13. 新しいトップレベルノードは (0,0) から離して配置します。 ページに直接追加したノードは、デフォルトで (0,0) に配置されます。figma.currentPage.children を走査して空いている位置を見つけてください（例：最も右にあるノードの右側）。これはページレベルのノードにのみ適用されます。ほかのフレームや自動レイアウトコンテナー内にネストされたノードの位置は、親によって決まります。Gotchasを参照してください。
14. use_figma でエラーが発生した場合は、safeToRetryWithoutCanvasRead に従ってください。 true の場合は、エラーを修正して再試行します。false の場合は、キャンバスを読み取って変更内容を確認してから、変更を加えてください。エラー復旧を参照してください。
15. 作成または変更したノード ID はすべて必ず return してください。 スクリプトでキャンバス上に新しいノードを作成したり、既存のノードを変更したりする場合は、影響を受けたノード ID をすべて集め、構造化オブジェクトで返してください（例：return { createdNodeIds: [...], mutatedNodeIds: [...] }）。後続の呼び出しでそれらのノードを参照、検証、または削除するために不可欠です。use_figma の呼び出し間で状態は保持されないため、前回の呼び出しで取得した ID は変数ではなく文字列リテラルとして渡してください。手順を追った複数ステップの例は、common-patterns.mdを参照してください。
16. 変数を作成するときは、必ず variable.scopes を明示的に設定してください。 デフォルトの ALL_SCOPES はすべてのプロパティピッカーを不要に汚してしまうため、ほとんどの場合、望ましい設定ではありません。背景には ["FRAME_FILL", "SHAPE_FILL"]、テキスト色には ["TEXT_FILL"]、間隔には ["GAP"] など、用途に合ったスコープを指定してください。スコープの完全な一覧はvariable-patterns.mdを参照してください。
17. すべての Promise を await してください。 Promise を await せずに残さないでください。await を付けない非同期呼び出し（例：figma.loadFontAsync(...) や figma.setCurrentPageAsync(page)）は実行を待たずに進むため、通知されない失敗や競合状態を引き起こします。非同期処理の完了前にスクリプトが戻り、データが欠落したり、変更が途中までしか反映されなかったりする可能性があります。
18. バリアントコンポーネントから componentPropertyDefinitions を読み取らないでください。 先に所有者を絞り込みます。ノード自体が COMPONENT_SET の場合はそのノードを使い、親が COMPONENT_SET でない場合にのみ COMPONENT を使い、それ以外の場合はバリアントの COMPONENT を親セットに昇格させます。オプショナルチェーンを使っても、ゲッターは安全になりません。コンポーネントプロパティの所有者の絞り込みを参照してください。

各ルールの詳細な誤った例／正しい例については、Gotchas & Common Mistakesを参照してください。

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

非同期専用のセッターと呼び出しごとのコンテキストリセットについては、ルール 9 で説明しています。このセクションでは、実例が必要な唯一のルールを詳しく説明します。スクリプトごとのページ切り替えは最大 1 回にし、複数ページにまたがる作業は並列に振り分けてください。

figma.root.children をループして、ループ内でページを切り替えることは避けてください。切り替えるたびにファイルが再読み込みされます。複数ページにまたがる作業では、対象ページごとに 1 件、合計 N 件の use_figma 呼び出しに分割し、並列で実行してください。つまり、N 個の use_figma ツール使用ブロックを 1 つのアシスタントメッセージに含めます。ハーネスがそれらを並行して実行し、各スクリプトは currentPage をちょうど 1 回設定します。

明示的な指示： 複数の呼び出しに分ける場合は、N 件のツール呼び出しを1 つのメッセージで必ず発行してください。複数ターンに分けて送信しないでください。次の呼び出しを発行する前に、1 つ目の完了を待たないでください。ページごとの逐次呼び出しでは、分割によるメリットが完全に失われます。

// AVOID — switches pages N times in one script, reloads the file each time
for (const page of figma.root.children) {
  await figma.setCurrentPageAsync(page);
  // ... touch this page ...
}

// PREFER — read-only discovery call to get page IDs, then in the NEXT message
// emit N parallel use_figma tool calls (one per page), each setting currentPage once.

複数ページにまたがる作業では、読み取りと書き込みのどちらも、既定で並列に振り分けてください。use_figma を複数回呼び出して、段階的に作業することもできます（たとえば、既存ノードのメタデータを return し、その後のスクリプトで変更します）。詳しい理由については、gotchas.md → Set current page once per use_figma call を参照してください。

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

エージェントに見えるのは、return した値のみです。console.log() は表示されず（ルール 4）、スローされたエラーは自動的に取得されます（そのまま伝播させるか、明示的に throw してください）。必須要件はルール 15 に記載されています。キャンバスノードを作成または変更するスクリプトはすべて、影響を受けたノード ID と、対応可能なステータスを構造化オブジェクトで必ず返してください。例：return { createdNodeIds: [...], mutatedNodeIds: [...], count: 5, errors: [] }。これにより、後続の呼び出しで参照、検証、またはクリーンアップできます。

4. エディターモード

use_figma はデザインモード（editorType が "figma"。既定値）で動作します。FigJam（"figjam"）と Slides（"slides"）では利用できるノードタイプが異なります。FigJam ではほとんどのデザインノードがブロックされ、Slides では FigJam 専用ノードがブロックされます。

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() は Design ファイル（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 の「まず調査する」パターンを参照）。また、視覚的なコンテキストには get_screenshot / await node.screenshot() を使用してください。Slides 専用の API ガイダンスについては、figma-use-slides スキルを読み込んでください。

5. 効率的な API — 冗長な代替手段より優先してください

これらの API を使うと、定型コードが減り、順序によるエラーを防ぎ、トークン出力を圧縮できます。冗長な代替手段より、常にこれらを優先してください。

node.query(selector) — CSS のようなノード検索

CSS のようなセレクターを使用して、サブツリー内のノードを検索します。冗長な findAll とフィルターループを置き換えます。

// BEFORE — verbose traversal
const texts = frame.findAll(n => n.type === 'TEXT' && n.name === 'Title')

// AFTER — one-liner with 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（和集合）
• ワイルドカード：*（任意のタイプ）

QueryResult のメソッド：

メソッド	説明
.length	一致したノードの数
.first()	最初に一致したノード（または null）
.last()	最後に一致したノード（または null）
.toArray()	通常の配列に変換
.each(fn)	コールバックを使って反復し、チェーン用に this を返します
.map(fn)	新しい配列にマッピング
.filter(fn)	新しい QueryResult にフィルター
.values(keys)	プロパティ値を抽出：.values(['name', 'x', 'y']) → [{name, x, y}, ...]
.set(props)	一致したすべてのノードにプロパティを設定（下記の node.set() を参照）
.query(selector)	一致したノード内をサブクエリー
for...of	反復可能 — for ループで使用できます

スコープ： node.query() はそのノードのサブツリー内を検索します。ページ全体を検索するには、figma.currentPage.query('...') を使用します。グローバルな figma.query() はありません。

例：

// Recolor all text inside cards
figma.currentPage.query('FRAME[name^=Card] TEXT').set({
  fills: [{type: 'SOLID', color: {r: 0.2, g: 0.2, b: 0.8}}]
})

// Get names and positions of all frames
return figma.currentPage.query('FRAME').values(['name', 'x', 'y'])

// Find the first component named "Button"
const btn = figma.currentPage.query('COMPONENT[name=Button]').first()

// Find all instances of a specific component
figma.currentPage.query(`INSTANCE[mainComponent=${compId}]`)

// Find nodes with solid fills using dot-path traversal
figma.currentPage.query('[fills.0.type=SOLID]')

node.set(props) — プロパティの一括更新

1 回の呼び出しで複数のプロパティを設定します。チェーン用に this を返します。

// BEFORE — one line per property
frame.opacity = 0.5
frame.cornerRadius = 8
frame.name = "Card"

// AFTER — single call
frame.set({ opacity: 0.5, cornerRadius: 8, name: "Card" })

優先キーの順序： オブジェクトのキーの順序にかかわらず、layoutMode は常にほかのプロパティ（width／height など）より先に適用されます。これにより、layoutMode が設定されているかどうかによって resize() の動作が異なるという、よくある不具合を防ぎます。

幅／高さの処理： width と height は自動的に node.resize() に渡されます。たとえば、{ width: 200 } を設定すると、resize(200, currentHeight) が呼び出されます。

query とのチェーン：

// Find all rectangles named "Divider" and update them
figma.currentPage.query('RECTANGLE[name=Divider]').set({
  fills: [{type: 'SOLID', color: {r: 0.9, g: 0.9, b: 0.9}}],
  cornerRadius: 2
})

figma.createAutoLayout(direction?, props?) — 自動レイアウトフレーム

自動レイアウトが有効で、両軸がコンテンツに合わせて伸縮するフレームを作成します。子要素同士に構造的な関係がある場合、常にこれをデフォルトのコンテナーとして使用します（ルール 12a を参照）。

// BEFORE — manual setup, easy to get ordering wrong
const frame = figma.createFrame()
frame.layoutMode = 'VERTICAL'
frame.primaryAxisSizingMode = 'AUTO'
frame.counterAxisSizingMode = 'AUTO'
frame.layoutSizingHorizontal = 'HUG'
frame.layoutSizingVertical = 'HUG'

// AFTER — one call, layout ready
const frame = figma.createAutoLayout('VERTICAL')

子要素を追加した直後から layoutSizingHorizontal/Vertical = 'FILL' を使用できます。サイズ設定モードを手動で設定する必要はありません。

最初または 2 番目の引数として、オプションの props オブジェクトを受け取ります：

figma.createAutoLayout({ name: 'Card', itemSpacing: 12 })               // HORIZONTAL + props
figma.createAutoLayout('VERTICAL', { name: 'Column', itemSpacing: 8 })  // VERTICAL + props

node.placeholder — AI の処理中を示すシマーオーバーレイ

処理中であることを示すシマーオーバーレイをノードに設定します。完了したら、必ずシマーを削除してください。シマーが残っているとユーザーを混乱させ、作業が未完了であることを示します。

// Mark as in-progress
frame.placeholder = true

// ... build out the content ...

// MUST remove when done — never leave shimmers on finished nodes
frame.placeholder = false

複雑なレイアウトを構築する際は、セクションに要素を追加する前に placeholder = true を設定し、各セクションが完成したら placeholder = false に設定します。

await node.screenshot(opts?) — インラインスクリーンショット

ノードを PNG としてキャプチャし、レスポンスにインラインで返します。別途 get_screenshot を呼び出す必要がなくなります。

// Take a screenshot of a frame (returned inline in the tool response)
await frame.screenshot()

// Custom scale (default auto-scales: 0.5x or capped so max dimension ≤ 1024px)
await frame.screenshot({ scale: 2 })

// Include overlapping content from sibling nodes
await frame.screenshot({ contentsOnly: false })

使用するタイミング： ルール 5 に従ってください。視覚的な証拠が必要な場合は、構成全体のスクリーンショットを撮影します。視覚的な修正を行った場合は、修正後のスクリーンショットを 1 枚撮影します。そのスクリーンショットが合格なら、それを最終版とします。変更のない「最終」スクリーンショットを追加で撮影しないでください。

自動命名： 画像のキャプションにはノードのメタデータ（"Card (300x150 at 0,60).png"）が含まれるため、画像を解析しなくても空間的なコンテキストを把握できます。

デフォルトのスケーリング： 0.5x のスケールを使用しますが、出力の最大寸法が 1024px を超えないように自動調整されます。明示的な { scale: N } を指定すると、この上限は適用されません。

6. 段階的なワークフロー（バグを避ける方法）

無駄が生じる最も一般的な原因は、不必要な分割、冗長な検証、安全に再試行できないスクリプトです。ルール 5 の安全な再試行と、証拠に基づく検証の契約に従ってください。

主なルール

• 検証の頻度ではなく、復旧可能性を基準に呼び出しの境界を決めます。 安全に行える場合は、関連する作成、プロパティの更新、親子関係の設定、および対象を絞った診断をまとめて実行します。ページ全体を 1 回の呼び出しで作成しても構いません。各セクションを検証するためだけに、ヘッダー、コンテンツ、フッターの呼び出しに分割しないでください。Slides の例外： Slides ファイルでは、各スライドは独立したサブツリーです。重要なのはスライドごとの複雑さであり、スライド間のノード総数ではありません。新しいスライドを 3～5 枚まとめて作成しても安全です。また、フッターの追加や見出しの色変更など、同じ編集をデッキ内のすべてのスライドに 1 回の呼び出しで適用しても安全です。デッキの作成ワークフローについては、figma-use-slides を参照してください。
• プレースホルダーから始めて、上から下へ構築します。 まず各セクションに placeholder = true を設定して外側の構造を作成し、その後の呼び出しでプレースホルダーを実際のコンテンツに段階的に置き換えます。

手順

1. 最初に調査します。 作成を始める前に、読み取り専用の use_figma を実行して、ファイル内にすでに存在するもの（ページ、コンポーネント、変数、命名規則）を確認します。既存の内容に合わせてください。
2. 骨組みを作成します。 プレースホルダーのセクションを使って、最上位の構造を作成します。各セクションに placeholder = true を設定し、ユーザーが進捗を確認できるようにします。
3. 安全に再試行できる単位でコンテンツを埋めます。 操作を安全に再試行できる場合は、関連する複数のセクションをまとめて入力しても構いません。完了した各セクションには placeholder = false を設定します。
4. すべての呼び出しで ID を返します（ルール 15）。後続の呼び出しで、作成したノード、変数、コレクションの ID を入力として使用する必要があります。
5. 書き込み処理では検証の証拠を返します。 ID と、関連する件数、名前、階層、または境界を返します。証拠が不足している場合や、変更によって以前の証拠が無効になった場合に限り、別途監査を追加します。視覚的なチェックについてはルール 5 に従ってください。
6. 先に問題を修正します。 検証で問題が見つかった場合は、次の手順に進む前に修正します。壊れた土台の上に構築しないでください。

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

Step 1: Inspect file — discover existing pages, components, variables, conventions
Step 2: Create tokens/variables (if needed)
       → return collection, variable, and mode counts
Step 3: Create individual components
       → return component IDs and relevant child/variant counts
Step 4: Compose layouts from component instances
       → return layout IDs/bounds + take a composition screenshot
Step 5: Apply a targeted visual fix only if needed
       → take one post-fix screenshot; this is final
Step 6: Stop if nothing relevant changed

各手順で検証する項目

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

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

use_figma でエラーが発生した場合は、safeToRetryWithoutCanvasRead（ルール 14）に従ってください。true の場合は、特定されたエラーを修正し、診断目的のキャンバス読み取りを追加せずに再試行します。false の場合は、キャンバスを読み取り、何が変わったかを判断してから変更します。同じ API またはプロパティのエラーが 2 回発生した場合は、その定義を一度確認し、再試行する前に根本原因を修正してください。同じ無効な変更を回避するために操作を分解し続けてはいけません。修正方法がすでに重要なルールとして示されているエラーについては、そこで診断します。"not implemented"（figma.notify、ルール 3）、layoutSizing* の HUG／FILL に関する拒否（ルール 12、12b）、"Setting figma.currentPage is not supported"（ルール 9）、バリアントの componentPropertyDefinitions（ルール 18）、および誤ったノードタイプに対する characters／description（ルール 3a、3b）が該当します。以下の表では、契約に記載されていないエラーを取り上げます。

エラーメッセージ	考えられる原因	修正方法
プロパティ値が範囲外です	色チャンネルが 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 が変わった	安定した（インスタンスではない）親フレームからたどって、ノードを再検出します

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

構造の正しさ（階層、数、位置）を確認するには get_metadata を、視覚的な正しさを確認するには get_screenshot を呼び出します。特に、テキストの切り抜き／クリッピング（行の高さによってコンテンツが切れている状態）や、要素の重なりをよく確認してください。これらはよく発生し、見落としやすい問題です。不一致が構造上のものか視覚上のものかを特定してから、壊れている部分だけを変更する対象を絞った修正スクリプトを作成します。すべてを作り直してはいけません。

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

8. 事前チェックリスト

use_figma の呼び出しを送信する前に、スクリプトをセクション 1の運用契約と照らし合わせて必ず読み直してください。以前ここに列挙されていたチェック項目はすべて、現在はそこに記載されています。以下のいずれかに違反するスクリプトは送信できる状態ではありません。

• 出力 — return を使用している（figma.closePlugin() ではない）、非同期 IIFE でラップされていない、出力に console.log() を使用していない。作成／変更したすべてのノード ID を含む構造化データを return している（ルール 1、2、4、15）
• 色と塗り — 値の範囲が 0～1。ペイントの color は {r, g, b} のみ（a は含めない）。塗りと線は新しい配列として再代入している（ルール 6、7）
• 型の絞り込み — characters、description、componentPropertyDefinitions にアクセスする前に、ガード／絞り込みを行っている（ルール 3a、3b、18）
• ページ — ページ切り替えには await figma.setCurrentPageAsync(page) を使用し、1 回の呼び出しにつき最大 1 回としている（ルール 9）
• レイアウトとサイズ指定 — 関連する子要素を figma.createAutoLayout() 内に配置している。最上位ノードを (0,0) から離れた位置に配置している。appendChild の後に HUG／FILL を設定している。サイズモードの前に resize() を呼び出している。折り返す TEXT には textAutoResize='HEIGHT' と FIXED 幅を使用している（ルール 12、12a、12b、12c、13）
• テキスト — 標準のフォント設定手順を使用し、listAvailableFontsAsync() でスタイル名を確認している。lineHeight／letterSpacing を {unit, value} として指定している。FONT_FAMILY 変数では、すべてのモードの値を先に読み込んでいる（ルール 8）
• 非同期処理と状態 — すべての Promise に await を付けている。複数ステップで使用する ID を文字列リテラルとして渡している（ルール 15、17）

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

作成を始める前に、必ず Figma ファイルを確認してください。 ファイルによって、命名規則、変数の構成、コンポーネントのパターンは異なります。コードは新たな規約を押し付けず、既存の規約に合わせてください。

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

クイック確認スクリプト

すべてのページと最上位ノードを一覧表示する：

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

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

search_design_system は公開済みコンポーネント向けのオプションです。キャンバス上のコンポーネントには、2段階のファンアウトを使用してください。1つのスクリプト内でページをループしないでください。

ステップ 1：読み取り専用の use_figma を1回実行して、ページ ID を取得します：

return figma.root.children.map(p => ({ id: p.id, name: p.name }));

ステップ 2：次のアシスタントのターンで、ページごとに1つの use_figma を並行して出力します（N 個のツール呼び出しブロックを含む1つのメッセージ）。それぞれで以下を実行します：

const page = await figma.getNodeByIdAsync(PAGE_ID);
await figma.setCurrentPageAsync(page);
// findAllWithCriteria uses an indexed type lookup — hundreds of times faster
// than the findAll(n => n.type === '…') side-effect-in-predicate antipattern.
const matches = page.findAllWithCriteria({ types: ['COMPONENT', 'COMPONENT_SET'] });
return matches.map(n => ({ page: page.name, name: n.name, type: n.type, id: n.id }));

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

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;

10. 参照ドキュメント

タスクの内容に応じて、必要なものを読み込んでください：

ドキュメント	読み込むタイミング	内容
gotchas.md	use_figma を実行する前	既知の落とし穴を、誤ったコード／正しいコードの例とともにすべて掲載しています。まずテキスト編集の標準手順を確認してください
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	テキストスタイルを作成／適用するとき	文字スタイルの段階、listAvailableFontsAsync によるフォントの検出、スタイルの一覧表示、ノードへのスタイル適用
effect-style-patterns.md	エフェクトスタイルを作成／適用するとき	ドロップシャドウ、スタイルの一覧表示、ノードへのスタイル適用
plugin-api-standalone.index.md	API 全体の仕様を把握する必要があるとき	Plugin API のすべての型、メソッド、プロパティの索引
plugin-api-standalone.d.ts	型シグネチャの正確な内容が必要なとき	型定義ファイル全体。特定のシンボルを grep で検索し、すべてを一度に読み込まないでください

11. スニペットの例

このドキュメント全体で、スニペットを紹介しています。これらのスニペットには、再利用できる便利な Plugin API コードが含まれています。そのまま使うか、作業を始める際のひな形として活用してください。汎用的なスニペットとして記録するのに適した重要な概念があれば、明記してディスクに保存し、今後再利用できるようにしてください。