figma-generate-design

デザインシステムから画面／ビューを作成・更新する

このスキルは、ハードコードした値でプリミティブを描画するのではなく、公開済みのデザインシステム（コンポーネント、変数、スタイル）を再利用して、Figma で画面、ビュー、複数セクションから成る UI コンテナーを作成または更新するために使用します。これには、ページ全体、モーダル、ダイアログ、ドロワー、サイドバー、パネル、複数のセクションを組み合わせたあらゆるビューが含まれます。重要なのは、Figma ファイルには、コードベースの UI コンポーネントやトークンに対応するコンポーネント、カラー／スペーシング変数、テキスト／エフェクトスタイルを含む、公開済みのデザインシステムがある可能性が高いという点です。16 進数のカラー値でボックスを描くのではなく、それらを見つけて使用してください。

必須：use_figma を呼び出す前に、必ず figma-use も読み込んでください。このスキルには、作成するすべてのスクリプトに適用される重要なルール（カラー範囲、フォントの読み込みなど）が記載されています。

**このスキルで use_figma を呼び出す際は、必ず skillNames: "figma-generate-design" を渡してください。**これはログ用のパラメーターであり、実行には影響しません。

スキルの適用範囲

• 成果物がデザインシステムのコンポーネントインスタンスで構築された複合 Figma ビュー（新規または更新）である場合に、このスキルを使用します。ページ全体の画面、モーダル、ダイアログ、ドロワー、サイドバー、パネル、複数セクションから成るコンテナーなどが該当します。
• 新しい再利用可能なコンポーネントやバリアントを作成する場合は、figma-use を直接使用してください。
• Code Connect のマッピングを作成する場合は、figma-code-connect に切り替えてください。

前提条件

• Figma MCP サーバーが接続されていること
• 対象の Figma ファイルに、コンポーネントを含む公開済みのデザインシステムがあること（またはチームライブラリへのアクセス権があること）
• ユーザーから次のいずれかが提供されていること：
  • 作業対象の Figma ファイル URL／ファイルキー
  • または、対象ファイルに関する情報（エージェントがページを特定できます）
• 作成または更新する画面／ビューのソースコードまたは説明

generate_figma_design との並行ワークフロー（Web アプリのみ）

ブラウザーでレンダリングできるWeb アプリから画面を作成する場合は、次の 2 つの方法を並行して実行すると、最良の結果が得られます。

1. 並行して実行します：
   • このスキルのワークフロー（use_figma とデザインシステムのコンポーネント）を使って画面の作成を開始します
   • generate_figma_design を実行し、起動中の Web アプリのピクセル単位で正確なスクリーンショットを取得します
2. 両方が完了したら： generate_figma_design のキャプチャにあるピクセル単位で正確なレイアウトに合うよう、use_figma の出力を更新します。キャプチャからは目標とする正確なスペーシング、サイズ、視覚的な表現がわかり、use_figma の出力ではデザインシステムにリンクされた適切なコンポーネントインスタンスを使用できます。キャプチャに画像が含まれている場合は、キャプチャの画像塗りつぶしから imageHash の値をコピーして use_figma の出力に引き継いでください（詳細はステップ 5 を参照）。
3. 見た目に問題がないことを確認したら： generate_figma_design の出力を削除します。これは視覚的な参照としてのみ使用しています。

この方法を組み合わせることで、それぞれの長所を活かせます。generate_figma_design はピクセル単位で正確なレイアウトを実現し、use_figma はリンクを維持して更新可能な、適切なデザインシステムのコンポーネントインスタンスを作成します。

ソースに画像が含まれる場合、この並行ワークフローは必須です。 use_figma の Plugin API は外部画像 URL を取得できず、ファイル内の既存ノードから imageHash の値をコピーすることでしか画像塗りつぶしを設定できません。generate_figma_design は表示されているすべての画像を Figma にラスタライズし、必要なハッシュを提供します。画像があるにもかかわらずキャプチャを省略すると、画像フレームが空のままになります。

Web 以外のアプリ（iOS、Android など）や、既存の画面を更新する場合は、以下の標準ワークフローを使用してください。

必須のワークフロー

以下の手順を順番に実行してください。手順を省略しないでください。

厳守事項 — 禁止されている近道：

• 禁止： 2a-i を完了し、2a-ii を試すか、該当なしとして記録する（例：「ファイルが空で、既存の画面がありません」）までは、コンポーネントキーに対して search_design_system を使用しないでください。
• 禁止： 以下のチェックリストにある Step 2 のすべての行を埋めるまでは、キャンバスを変更する use_figma の呼び出し（Step 3 以降）を行わないでください。

Step 1：成果物を把握する

Figma に触れる前に、何を作成するのかを把握してください。

1. コードから作成する場合は、関連するソースファイルを読んで、構成、セクション、使用されているコンポーネントを把握してください。
2. ビューの主要なセクションを特定してください（例：ページの場合は、ヘッダー、ヒーロー、コンテンツパネル、フッター。モーダルの場合は、タイトルバー、フォームセクション、アクションバー。サイドバーの場合は、ナビゲーション、コンテンツ領域、フッターアクション）。
3. 各セクションで使用する UI コンポーネント（ボタン、入力欄、カード、ナビゲーションピル、アコーディオンなど）を列挙してください。
4. ビューに画像が含まれているか確認してください（例：<img>、<Image>、背景画像、製品写真、アバター、URL から読み込まれるアイコン）。画像が含まれていて、これがウェブアプリの場合は、並列の generate_figma_design キャプチャワークフローを必ず実行してください。キャプチャの実行中にコンポーネントを調べられるよう、Step 2 と並行してすぐに開始してください。詳しくは、上記の「generate_figma_design との並列ワークフロー」を参照してください。

Step 2：コンポーネントキー、変数、スタイルを収集する

デザインシステムから、コンポーネント（ボタン、カードなど）、変数（色、間隔、角丸）、スタイル（テキストスタイル、影などのエフェクトスタイル）の 3 つを取得する必要があります。デザインシステムのトークンがある場合は、色の 16 進数値やピクセル値をハードコードしないでください。

2a：コンポーネントを特定する

2a-i — 必須：必要なコンポーネントの Code Connect を確認します。 ステップ 1 で作成したコンポーネント一覧をもとに、各コンポーネントに対応する Code Connect ファイルがコードベースにあるか確認します。Code Connect ファイルはコンポーネントのソースファイルと同じ場所にあり、プラットフォームごとに次の名前が付けられています。

• TypeScript/JS：*.figma.ts、*.figma.js
• React（パーサーベース）：*.figma.tsx
• Kotlin/Compose：@FigmaConnect を含む .kt ファイル
• Swift：FigmaConnect を含む .swift ファイル

必要な各コンポーネント（例：Button、Card、Input）について、Code Connect ファイルを検索します。コンポーネント名で glob または grep を使用してください（例：**/Button.figma.tsx、**/Card.figma.ts）。実際に必要なコンポーネントに一致するファイルのみを読み取ります。

一致した各 Code Connect ファイルから、Figma コンポーネントの URL を取得します。URL から fileKey と nodeId を解析します（ハイフンをコロンに変換します：123-456 → 123:456）。次に、use_figma を使ってコンポーネントキーを解決します。

例： Code Connect ファイルに // url=https://figma.com/design/ABC123/File?node-id=609-35535 と記載されている場合、fileKey = ABC123、nodeId = 609:35535 と解析します。ライブラリファイル（対象ファイルではなく、fileKey ABC123）に対して use_figma を実行し、キーを解決します。

const node = await figma.getNodeByIdAsync("609:35535");
const set = node?.parent?.type === "COMPONENT_SET" ? node.parent : node;
return { componentKey: set.key };

複数の検索は 1 回の呼び出しにまとめます。返されたキーは、ステップ 4 で importComponentSetByKeyAsync() に使用します。

解決済みのコンポーネントに印を付けます。すべてのコンポーネントが解決された場合は、2a-ii と 2a-iii をスキップします。必要なコンポーネントに Code Connect ファイルがない場合は、2a-ii に進みます。

2a-ii — 未解決のコンポーネントが残っている場合は必須：既存の画面を調べます。 対象ファイルに、同じデザインシステムを使った画面がすでに含まれているか確認します。既存のフレームのインスタンスをたどる use_figma の呼び出しを 1 回行うだけで、正確で信頼できるコンポーネントマップを取得できます。

// Read-only discovery — skip invisible content inside instances (hidden
// variants etc.) for the hundreds-of-times-faster findAllWithCriteria.
figma.skipInvisibleInstanceChildren = true;

const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
const uniqueSets = new Map();
frame.findAllWithCriteria({ types: ["INSTANCE"] }).forEach(inst => {
  const mc = inst.mainComponent;
  const cs = mc?.parent?.type === "COMPONENT_SET" ? mc.parent : null;
  const key = cs ? cs.key : mc?.key;
  const name = cs ? cs.name : mc?.name;
  if (key && !uniqueSets.has(key)) {
    uniqueSets.set(key, { name, key, isSet: !!cs, sampleVariant: mc.name });
  }
});
return [...uniqueSets.values()];

結果を未解決のコンポーネントと照合します。新たに解決されたコンポーネントに印を付けます。すべて解決された場合は、2a-iii をスキップします。

2a-iii — 最終手段：search_design_system。 2a-i と 2a-ii の両方を完了しても未解決のコンポーネントが残る場合にのみ使用します。

検索の前に get_libraries を呼び出し、ファイルで利用できるライブラリを確認します。これにより、ファイルに追加済みのライブラリと、追加可能なライブラリ（コミュニティ UI キットと組織のライブラリ）の 2 つのリストが返されます。各項目には libraryKey が含まれており、includeLibraryKeys パラメーターを介して search_design_system に渡すことで、すべてを横断して検索する代わりに、特定のライブラリに絞って検索できます。

// Step 1: Discover available libraries
get_libraries({ fileKey })
// Returns: {
//   libraries_added_to_file: [...],
//   libraries_available_to_add: [...],
//   libraries_available_to_add_next_offset: number | null
// }

// Step 2: Search within a specific library using its libraryKey
search_design_system({ query: "button", fileKey, includeLibraryKeys: ["lk-abc123..."] })

libraries_available_to_add の組織ライブラリはページ分割されており、1 ページあたり 20 件です。libraries_available_to_add_next_offset が null でない場合は、さらに組織ライブラリがあるため、その値を offset に設定して get_libraries を再度呼び出し、次のページを取得します。コミュニティ UI キットは最初のページにのみ表示されます。ユーザーが指定したライブラリが現在のページに見当たらない場合は、検索を諦める前にさらにページを確認します。

ファイルに多くのライブラリがあり、対象を絞った結果を得たい場合（たとえば、すべてのライブラリから一致するものを取得するのではなく、「iOS 26」や「Material 3」のみを検索する場合）に特に便利です。

幅広く検索します — 複数の用語や同義語を試してください（例：「button」、「input」、「nav」、「card」、「accordion」、「header」、「footer」、「tag」、「avatar」、「toggle」、「icon」など）。コンポーネントに絞るには includeComponents: true を使用します。

コンポーネントのプロパティをマップに含めます — テキストのオーバーライドに使える TEXT プロパティを各コンポーネントがどれだけ公開しているかを把握する必要があります。一時的なインスタンスを作成し、その componentProperties（およびネストされたインスタンスの componentProperties）を読み取った後、一時インスタンスを削除します。

プロパティ情報を含むコンポーネントマップの例：

Component Map:
- Button → key: "abc123", type: COMPONENT_SET
  Properties: { "Label#2:0": TEXT, "Has Icon#4:64": BOOLEAN }
- PricingCard → key: "ghi789", type: COMPONENT_SET
  Properties: { "Device": VARIANT, "Variant": VARIANT }
  Nested "Text Heading" has: { "Text#2104:5": TEXT }
  Nested "Button" has: { "Label#2:0": TEXT }

2b: 変数を確認する（色、スペーシング、角丸）

まず既存の画面を確認してください（コンポーネントの場合と同様です）。または、includeVariables: true を指定して search_design_system を使用します。

警告：変数を確認する方法は2つあります。混同しないでください。

• use_figma と figma.variables.getLocalVariableCollectionsAsync() の組み合わせでは、現在のファイル内で定義されたローカル変数のみが返されます。結果が空でも、変数が存在しないという意味ではありません。リモートまたは公開済みのライブラリ変数は、この API からは確認できません。
• includeVariables: true を指定した search_design_system では、リモートや公開済みのものも含むリンク済みのすべてのライブラリが検索されます。デザインシステムの変数を確認するには、こちらのツールを使用してください。

getLocalVariableCollectionsAsync() の結果が空であることだけを根拠に、「変数が存在しない」と判断しないでください。 独自に作成することを決める前に、必ず includeVariables: true を指定した search_design_system も実行して、ライブラリ変数を確認してください。

検索方法： search_design_system はカテゴリではなく、変数名（例：「Gray/gray-9」、「core/gray/100」、「space/400」）を検索します。複合的なクエリを1つ使うのではなく、短くシンプルなクエリを複数、並行して実行してください。

• プリミティブカラー： 「gray」、「red」、「blue」、「green」、「white」、「brand」
• セマンティックカラー： 「background」、「foreground」、「border」、「surface」、「text」
• スペーシング／サイズ： 「space」、「radius」、「gap」、「padding」

最初の検索で結果が空の場合は、より短い語句や異なる命名規則を試してください。ライブラリによって命名は大きく異なります（「grey」と「gray」、「spacing」と「space」、「color/bg」と「background」など）。

最も信頼性の高い結果を得るには、既存画面にバインドされている変数を確認してください。

// Read-only discovery — skip invisible instance interiors for speed.
figma.skipInvisibleInstanceChildren = true;

const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");

// boundVariables can live on any scene node — enumerating every scene type
// just to feed findAllWithCriteria is roughly the same as findAll(() => true)
// and is much noisier in script output.
const uniqueIds = new Set(
  frame.findAll(() => true).flatMap(n =>
    Object.values(n.boundVariables ?? {})
      .flatMap(b => Array.isArray(b) ? b : [b])
      .map(b => b?.id)
      .filter(Boolean)
  )
);
const variables = await Promise.all(
  [...uniqueIds].map(id => figma.variables.getVariableByIdAsync(id))
);
return variables
  .filter(Boolean)
  .map(v => ({ name: v.name, id: v.id, key: v.key, type: v.resolvedType, remote: v.remote }));

ライブラリ変数（remote = true）は、figma.variables.importVariableByKeyAsync(key) でキーを指定してインポートします。ローカル変数は、figma.variables.getVariableByIdAsync(id) を直接使用します。

バインド方法については、variable-patterns.md を参照してください。

2c: スタイルを確認する（テキストスタイル、エフェクトスタイル）

includeStyles: true を指定した search_design_system を使い、「heading」、「body」、「shadow」、「elevation」などの語句でスタイルを検索します。または、既存画面で使用されているスタイルを確認します。

// Read-only discovery — skip invisible instance interiors for speed.
figma.skipInvisibleInstanceChildren = true;

const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
const styles = { text: new Map(), effect: new Map() };

for (const node of frame.findAll(() => true)) {
  // textStyleId is on TEXT and TEXT_PATH; effectStyleId is on most scene
  // shape/container types. Use `in` guards to handle both without an
  // exhaustive type list.
  if ('textStyleId' in node && node.textStyleId) {
    const s = figma.getStyleById(node.textStyleId);
    if (s) styles.text.set(s.id, { name: s.name, id: s.id, key: s.key });
  }
  if ('effectStyleId' in node && node.effectStyleId) {
    const s = figma.getStyleById(node.effectStyleId);
    if (s) styles.effect.set(s.id, { name: s.name, id: s.id, key: s.key });
  }
}

return {
  textStyles: [...styles.text.values()],
  effectStyles: [...styles.effect.values()]
};

figma.importStyleByKeyAsync(key) でライブラリスタイルをインポートしてから、node.textStyleId = style.id または node.effectStyleId = style.id で適用します。

詳しくは、text-style-patterns.md と effect-style-patterns.md を参照してください。

ステップ 3：最初にラッパーフレームを作成する

セクションをページの最上位の子として作成し、後から親を変更してはいけません。 use_figma の呼び出しをまたいで appendChild() でノードを移動すると、エラーが表示されないまま失敗し、孤立したフレームが作成されます。代わりに、最初にラッパーを作成し、その中に各セクションを直接作成してください。

専用の use_figma 呼び出しでラッパーを作成します。既存コンテンツから離れた位置に配置し、その ID を返します。

// Find clear space
let maxX = 0;
for (const child of figma.currentPage.children) {
  maxX = Math.max(maxX, child.x + child.width);
}

const wrapper = figma.createAutoLayout("VERTICAL");

// --- Size the wrapper based on container type ---
// Full page:       wrapper.resize(1440, 100); wrapper.name = "Homepage";
// Modal/dialog:    wrapper.resize(640, 100);  wrapper.name = "Settings Modal";
// Drawer/sidebar:  wrapper.resize(360, 100);  wrapper.name = "Navigation Drawer";
// Panel:           wrapper.resize(400, 100);  wrapper.name = "Details Panel";
// Adapt width to match the source code's actual dimensions.

wrapper.name = "VIEW_NAME";
wrapper.primaryAxisAlignItems = "CENTER";
wrapper.counterAxisAlignItems = "CENTER";
wrapper.resize(WIDTH, 100);
wrapper.layoutSizingHorizontal = "FIXED";
wrapper.x = maxX + 200;
wrapper.y = 0;

return { success: true, wrapperId: wrapper.id };

ステップ 4：各セクションをラッパー内に作成する

ここが最も重要なステップです。 各セクションを1つずつ、それぞれ専用の use_figma 呼び出しで作成します。各スクリプトの冒頭で ID を使ってラッパーを取得し、新しいコンテンツをそこに直接追加してください。

const createdNodeIds = [];

// Resolve the wrapper and import every design system dependency in parallel.
// Sequential awaits here serialize N independent IPC round-trips at the top
// of every section build; one Promise.all is dramatically faster.
const [wrapper, buttonSet, bgColorVar, spacingVar, shadowStyle] = await Promise.all([
  figma.getNodeByIdAsync("WRAPPER_ID_FROM_STEP_3"),
  figma.importComponentSetByKeyAsync("BUTTON_SET_KEY"),
  figma.variables.importVariableByKeyAsync("BG_COLOR_VAR_KEY"),
  figma.variables.importVariableByKeyAsync("SPACING_VAR_KEY"),
  figma.importStyleByKeyAsync("SHADOW_STYLE_KEY"),
]);
const primaryButton = buttonSet.children.find(c =>
  c.type === "COMPONENT" && c.name.includes("variant=primary")
) || buttonSet.defaultVariant;

// Build section frame with variable bindings (not hardcoded values)
const section = figma.createAutoLayout();
section.name = "Header";
section.setBoundVariable("paddingLeft", spacingVar);
section.setBoundVariable("paddingRight", spacingVar);
const bgPaint = figma.variables.setBoundVariableForPaint(
  { type: 'SOLID', color: { r: 0, g: 0, b: 0 } }, 'color', bgColorVar
);
section.fills = [bgPaint];

// Apply the effect style imported above
section.effectStyleId = shadowStyle.id;

// Create component instances inside the section
const btnInstance = primaryButton.createInstance();
section.appendChild(btnInstance);
createdNodeIds.push(btnInstance.id);

// Append section to wrapper
wrapper.appendChild(section);
section.layoutSizingHorizontal = "FILL"; // AFTER appending

createdNodeIds.push(section.id);
return { success: true, createdNodeIds };

各セクションの作成後、次に進む前に get_screenshot で検証してください。テキストの切り抜き（行の高さによるコンテンツの欠け）や要素の重なりがないか、よく確認してください。これらは最もよく発生する問題で、ひと目では見落としやすいものです。

setProperties()でインスタンスのテキストを上書きする

コンポーネントのインスタンスには、プレースホルダーテキスト（「Title」「Heading」「Button」）が設定されています。ステップ2で確認したコンポーネントのプロパティキーを使って、setProperties()でテキストを上書きしてください。これはnode.charactersを直接操作するより確実です。詳しいパターンについては、component-patterns.mdを参照してください。

独自のTEXTプロパティを公開しているネストされたインスタンスでは、そのネストされたインスタンスに対してsetProperties()を呼び出します。

// Use the type-indexed criteria for the type filter, then narrow by name.
const nestedHeading = cardInstance
  .findAllWithCriteria({ types: ["INSTANCE"] })
  .find(n => n.name === "Text Heading");
if (nestedHeading) {
  nestedHeading.setProperties({ "Text#2104:5": "Actual heading from source code" });
}

コンポーネントプロパティで管理されていないテキストに限り、最後の手段としてnode.charactersを直接操作してください。

ソースコードのデフォルト値を慎重に確認する

コードコンポーネントをFigmaインスタンスに変換する際は、明示的に渡された値だけでなく、ソースコード内のコンポーネントのデフォルトのプロパティ値も確認してください。たとえば、variantプロパティが指定されていない<Button size="small">Register</Button>の場合、コンポーネント定義を確認して、デフォルト値がvariant = "primary"であることを特定します。誤ったvariant（NeutralではなくPrimaryなど）を選択すると、見落としやすい視覚的な不整合が生じます。

手動で作成するものとデザインシステムからインポートするもの

手動で作成	デザインシステムからインポート
ラッパーフレーム	コンポーネント：ボタン、カード、入力欄、ナビゲーションなど
セクションコンテナーフレーム	変数：色（塗り、線）、間隔（パディング、間隔）、角丸
レイアウトグリッド（行、列）	テキストスタイル：見出し、本文、キャプションなど
	エフェクトスタイル：シャドウ、ぼかしなど

デザインシステムの変数がある場合、16進数の色やピクセル単位の間隔をハードコードしないでください。間隔や角丸にはsetBoundVariableを、色にはsetBoundVariableForPaintを使用してください。テキストスタイルはnode.textStyleIdで、エフェクトスタイルはnode.effectStyleIdで適用します。

ステップ5：全体を検証して画像を転送する

すべてのセクションを構成したら、ラッパーフレームに対してget_screenshotを呼び出し、ソースと比較します。問題があれば、対象を絞ったuse_figma呼び出しで修正してください。ビュー全体を作り直す必要はありません。

全体だけでなく、個々のセクションもスクリーンショットに撮ってください。 解像度を下げた全体のスクリーンショットでは、テキストの切れ、誤った色、上書きされていないプレースホルダーテキストが見えにくくなります。各セクションのノードIDを指定してスクリーンショットを撮り、次の問題を確認してください。

• 切り抜かれた／クリップされたテキスト — 行の高さやフレームサイズが原因で、ディセンダー、アセンダー、または行全体が切れている
• コンテンツの重なり — サイズ設定の誤りやオートレイアウトの不足により、要素が互いに重なっている
• プレースホルダーテキストが残っている（「Title」「Heading」「Button」）
• レイアウトサイズの不具合によるコンテンツの切り詰め
• コンポーネントのvariantが誤っている（NeutralボタンとPrimaryボタンの取り違えなど）
• 画像プレースホルダーが空白になっている — 画像がない場合は、generate_figma_designのキャプチャから転送する必要があります（以下を参照）

generate_figma_designのキャプチャから画像を転送する

generate_figma_designを並行して実行した場合（ソースに画像が含まれている場合は必須）、キャプチャした画像をデザインシステムの出力に転送します。

1. type === "IMAGE"の塗りを検索して、キャプチャ出力内のすべての画像ノードを見つけます。

   // Read-only image inventory — skip invisible instance interiors for speed.
   figma.skipInvisibleInstanceChildren = true;
   
   const capture = await figma.getNodeByIdAsync("CAPTURE_NODE_ID");
   const imageNodes = capture.findAll(() => true).flatMap(n => {
     if (!Array.isArray(n.fills)) return [];
     const imageFill = n.fills.find(f => f.type === "IMAGE");
     return imageFill ? [{ name: n.name, id: n.id, imageHash: imageFill.imageHash }] : [];
   });
   return imageNodes;
   

2. キャプチャした各画像を、use_figmaの出力内の対応するフレームに（位置、名前、または順序で）対応付けます。
3. 画像のハッシュを対象フレームに適用します。

   targetFrame.fills = [{ type: "IMAGE", imageHash: "hash_from_capture", scaleMode: "FILL" }];
   

4. すべての画像を転送した後、generate_figma_designのキャプチャ出力を削除します。

ステップ6：既存のビューを更新する

新規作成ではなく更新する場合：

1. get_metadataを使用して、既存の画面構造を確認します。
2. 更新が必要なセクションと、そのまま使用できるセクションを特定します。
3. 変更が必要な各セクションについて：
   • IDまたは名前で既存のノードを見つける
   • デザインシステムのコンポーネントが変更されている場合は、コンポーネントインスタンスを置き換える
   • 必要に応じてテキストコンテンツ、variantプロパティ、またはレイアウトを更新する
   • 廃止されたセクションを削除する
   • 新しいセクションを追加する
4. 変更のたびにget_screenshotで検証します。

// Example: Swap a button variant in an existing screen.
// Batch the node lookup and component-set import in parallel — they are
// independent and awaiting them sequentially serializes two IPC round-trips.
const [existingButton, buttonSet] = await Promise.all([
  figma.getNodeByIdAsync("EXISTING_BUTTON_INSTANCE_ID"),
  figma.importComponentSetByKeyAsync("BUTTON_SET_KEY"),
]);
if (existingButton && existingButton.type === "INSTANCE") {
  const newVariant = buttonSet.children.find(c =>
    c.name.includes("variant=primary") && c.name.includes("size=lg")
  ) || buttonSet.defaultVariant;
  existingButton.swapComponent(newVariant);
}
return { success: true, mutatedNodeIds: [existingButton.id] };

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

API の詳細なパターンや注意点については、必要に応じて figma-use の以下のリファレンスを読み込んでください。

• component-patterns.md — キーによるインポート、バリアントの検索、setProperties、テキストの上書き、インスタンスの操作
• variable-patterns.md — 変数の作成／バインド、ライブラリ変数のインポート、スコープ、エイリアス、既存変数の検出
• text-style-patterns.md — テキストスタイルの作成／適用、ライブラリのテキストスタイルのインポート、タイプスケール
• effect-style-patterns.md — エフェクトスタイル（シャドウ）の作成／適用、ライブラリのエフェクトスタイルのインポート
• gotchas.md — レイアウトの落とし穴（HUG／FILL の相互作用、counterAxisAlignItems、サイズ設定の順序）、塗り／色の問題、ページコンテキストのリセット

エラーからの復旧

figma-use のエラー復旧プロセスに従ってください。

1. エラーが発生したら停止し、すぐに再試行しないでください。
2. エラーメッセージを注意深く読み、何が問題だったのかを把握してください。
3. エラーが不明瞭な場合は、get_metadata または get_screenshot を呼び出して、現在のファイルの状態を確認してください。
4. エラーメッセージに基づいてスクリプトを修正してください。
5. 修正したスクリプトを再試行してください。失敗したスクリプトはアトミックに実行されるため（エラーが発生した場合は何も作成されません）、安全に再試行できます。

このスキルは段階的に（1 回の呼び出しにつき 1 セクション）動作するため、エラーの範囲は自然に単一のセクションに限定されます。成功した呼び出しで作成された前のセクションはそのまま残ります。

ベストプラクティス

• 作成する前に必ず検索してください。 必要なコンポーネント、変数、スタイルはデザインシステムにある可能性が高いです。手動での作成や値のハードコーディングは、例外としてください。
• 幅広く検索してください。 同義語や部分一致の語句を試してください。「NavigationPill」は「pill」、「nav」、「tab」、「chip」などで見つかる場合があります。変数については、「color」、「spacing」、「radius」などで検索してください。
• ハードコードした値よりデザインシステムのトークンを優先してください。 色、スペーシング、角丸には変数のバインドを使用してください。タイポグラフィにはテキストスタイルを使用してください。シャドウにはエフェクトスタイルを使用してください。これにより、画面をデザインシステムに連携した状態に保てます。
• 手動での作成よりコンポーネントインスタンスを優先してください。 インスタンスはソースコンポーネントとの連携を維持し、デザインシステムの進化に合わせて自動的に更新されます。
• セクションごとに作業してください。 1 回の use_figma 呼び出しで、複数の主要セクションを作成しないでください。
• すべての呼び出しでノード ID を返してください。 セクションを組み合わせるときや、エラーから復旧するときに必要になります。
• 各セクションの後に視覚的に検証してください。 get_screenshot を使用して、問題を早期に発見してください。
• 既存の規約に合わせてください。 ファイルにすでに画面がある場合は、名前、サイズ、レイアウトのパターンを合わせてください。