figma-use

use_figma — Figma Plugin API Skill

使用 use_figma 工具透過 Plugin API 在 Figma 檔案中執行 JavaScript。所有詳細的參考文件均位於 references/ 中。

呼叫 use_figma 時，務必在以逗號分隔的 skillNames 參數中包含 figma-use。如果此 skill 是透過 MCP 資源載入的，你必須在名稱前加上 resource: 前綴（例如 resource:figma-use）。 這是用於追蹤 skill 使用情況的紀錄參數，不會影響執行結果。

如果 Figma MCP 工具顯示為延遲載入工具（deferred tools），請使用 select: 語法在單一 ToolSearch 呼叫中批次載入其所有 Schema — 例如 ToolSearch query="select:use_figma,get_screenshot,get_metadata,create_new_file"。單次往返操作比分六次處理更加高效。

如果任務涉及從程式碼在 Figma 中建置或更新完整的頁面、畫面或多區塊版面配置，請一併載入 figma-generate-design。它提供了透過 search_design_system 搜尋設計系統元件、匯入元件並逐步組裝畫面的工作流程。這兩個 skill 相互配合：本 skill 負責 API 規則，該 skill 負責畫面建置工作流程。

如果任務涉及在 Figma 中建立或建置元件（即使只是單一元件），請一併載入 figma-generate-library。它提供了元件建立工作流程 — 變數基礎架構、變體集 (Variant sets)、設計 Token 綁定 — 這些是僅靠 figma-use 無法涵蓋的。

在開始任何操作之前，請先載入 plugin-api-standalone.index.md 以瞭解所有可行操作。當要求你撰寫 Plugin API 程式碼時，請利用此 context 去 grep plugin-api-standalone.d.ts 中相關的型別、方法與屬性。這是 API 規格最權威的資料來源。由於這是一個大型型別定義檔，請勿一次載入全部內容，請依需求 grep 相關區段。

重要事項：每當處理設計系統時，請先閱讀 working-with-design-systems/wwds.md，瞭解在 Figma 中使用設計系統的核心概念、流程與規範。接著再根據需要載入針對元件、變數、文字樣式及效果樣式的具體參考文件。

1. 核心規則

1. 使用 return 將資料傳回。 傳回值會自動進行 JSON 序列化（物件、陣列、字串、數字）。切勿呼叫 figma.closePlugin() 或將程式碼包裹在非同步 IIFE 中 — 系統會自動為你處理。
2. 撰寫純 JavaScript，並在最外層使用 await 與 return。 程式碼會自動包裹在非同步 (async) 情境中。切勿包裹在 (async () => { ... })() 中。
3. figma.notify() 會拋出 "not implemented" 錯誤 — 切勿使用。
   3a. use_figma 中不支援 getPluginData() / setPluginData() — 請勿使用。請改用 getSharedPluginData() / setSharedPluginData()（這些有支援），或是透過傳回節點 ID 並將其傳遞給後續呼叫來追蹤節點。
4. console.log() 不會傳回內容 — 請使用 return 輸出結果。
5. 採小步漸進方式作業。 將大型操作拆分為多次 use_figma 呼叫。每一步完成後進行驗證。這是避免 Bug 最重要的一項做法。
6. 顏色數值範圍為 0–1（而非 0–255）：{r: 1, g: 0, b: 0} = 紅色。
7. 填色 (Fills) 與線條 (Strokes) 為唯讀陣列 — 需先複製、修改後再重新賦值。
8. 所有文字編輯均須遵循標準流程：載入字型 → await → 修改內容 → 傳回受影響的節點 ID。 若跳過載入步驟，會拋出 Cannot write to node with unloaded font "<family> <style>"。此規則不限於 characters — 也適用於對未載入字型節點執行的任何操作（appendChild、insertChild、setBoundVariable、setExplicitVariableModeForCollection、setValueForMode、觸及文字的 findAll 回呼）。修改現有文字時，請透過 getStyledTextSegments(['fontName']) 載入該節點目前使用的字型，而非使用硬編碼的預設字型。Inter 在多數環境中已預先載入，因此其他字型系列更容易觸發此 Bug — 但處理任何字型時流程完全相同。若樣式字串未經驗證，請先使用 await figma.listAvailableFontsAsync()。詳見 Canonical text-edit recipe。
9. 頁面為漸進式載入 — 請使用 await figma.setCurrentPageAsync(page) 切換頁面並載入其內容。同步設定語法 figma.currentPage = page 無法運作且會拋出錯誤（詳見下方頁面規則）。
10. setBoundVariableForPaint 會傳回新的 Paint 物件 — 必須接收並重新賦值。
11. createVariable 接受 Collection 物件或 ID 字串（偏好傳入物件）。
12. layoutSizingHorizontal/Vertical 的數值受到結構情境限制 — FIXED 始終有效，HUG 與 FILL 則有限制。 'HUG' 僅在自動布局框 (Auto-layout frame) 本身，或其內部的文字 (TEXT) 子節點上有效。'FILL' 僅在自動布局框的子節點上有效，且該子節點不得為絕對定位、不得位於不可變框 (Immutable frame) 內，亦不得為 Canvas 網格 (Canvas-grid) 子節點。實際操作建議：先將節點新增 (append) 至自動布局父容器中，再設定 HUG/FILL — 新建立或尚未設定父容器的節點無法符合此規則。該屬性本身存在於每個 SceneNode 上；拋出的錯誤是數值退回/拒絕，而非「無此屬性」。詳見 Gotchas。
    12a. 針對具有相關性的子節點容器，請使用自動布局 (Auto-layout)。 當子節點存在結構上的關係 — 例如垂直堆疊、橫向並排、對齊、設定間距或適應內容 (Hug) — 請將它們包裹在 figma.createAutoLayout() 中，而非使用帶有絕對座標 x/y 的 figma.createFrame()。絕對座標決定容器在畫布 (Canvas) 上的位置；自動布局則控制其內部子節點的排列關係。若跳過自動布局容器，文字換行、內容變更或重疊時將無法獲得任何保護。
    12b. layoutSizing* 與 *AxisSizingMode 是不同的 Enum — 切勿混用。 layoutSizingHorizontal/layoutSizingVertical（設定於子節點上）接收 'FIXED'|'HUG'|'FILL'；primaryAxisSizingMode/counterAxisSizingMode（設定於框 (Frame) 本身）接收 'FIXED'|'AUTO'。因此 layoutSizingVertical = 'AUTO' 無效，而 counterAxisSizingMode = 'FILL' 會拋出 Expected 'FIXED' | 'AUTO', received 'FILL'（應改用 'FIXED'/'AUTO'）。同一個 Setter 引發的另外兩個錯誤 — 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。
13. 將新建的頂層節點擺放在遠離 (0,0) 的位置。 直接新增至頁面的節點預設座標為 (0,0)。請掃描 figma.currentPage.children 找到未被佔用的位置（例如最右側節點的右方）。這僅適用於頁面層級的節點 — 巢狀於其他 Frame 或 Auto-layout 容器內部的節點會由其父容器進行定位。詳見 Gotchas。
14. 發生 use_figma 錯誤時，請立即停止，切勿直接重試。 失敗的 Script 具備原子性 (Atomic) — 如果 Script 發生錯誤，將完全不會執行，也不會對檔案做任何修改。請仔細閱讀錯誤訊息，修正 Script 後再重新嘗試。詳見 錯誤恢復。
15. 必須傳回所有新建/修改的節點 ID。 每當 Script 建立新節點或修改畫布上的既有節點時，請收集所有受影響的節點 ID 並以結構化物件傳回（例如 return { createdNodeIds: [...], mutatedNodeIds: [...] }）。這對於後續呼叫進行引用、驗證或清理這些節點至關重要。
16. 建立變數時務必明確設定 variable.scopes。 預設的 ALL_SCOPES 會污染每一個屬性選擇器 — 這幾乎絕非你所期望的。背景請使用特定 Scope，如 ["FRAME_FILL", "SHAPE_FILL"]；文字顏色使用 ["TEXT_FILL"]；間距使用 ["GAP"] 等。完整清單請參閱 variable-patterns.md。
17. 對每一個 Promise 使用 await。 切勿遺漏 await — 未使用 await 的非同步呼叫（例如未加 await 的 figma.loadFontAsync(...) 或 figma.setCurrentPageAsync(page)）會以 fire-and-forget 方式執行，導致隱形失敗或 Race condition。Script 可能在非同步操作完成前就已傳回，進而導致資料遺失或變更僅部分生效。

關於每條規則的詳細錯誤/正確範例，請參閱 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 此時已載入內容

每次 use_figma 調用最多呼叫 setCurrentPageAsync 一次 — 以平行方式展開多頁面作業

單一 Script 切換頁面的次數最多只能有一次。 切勿在迴圈中走訪 figma.root.children 並在迴圈內部切換頁面。

如果作業跨越多個頁面，請將其拆分為 N 個 use_figma 呼叫（每個目標頁面一個），並平行發送 — 在單一 Assistant 訊息中包含 N 個 use_figma 工具呼叫區塊。執行環境會發起平行處理；每個 Script 各自設定 currentPage 正好一次。

明確指示： 展開平行呼叫時，你必須在單一訊息中發送這 N 個工具呼叫。切勿跨多個回合發送，也不要在發送下一個之前等待前一個完成。逐頁順序呼叫比此規則所替代的迴圈模式更慢，且會完全浪費拆分帶來的效益。

// 避免 — 在單一 Script 中切換頁面 N 次，每次都會重新載入檔案
for (const page of figma.root.children) {
  await figma.setCurrentPageAsync(page);
  // ... 處理此頁面 ...
}

// 推薦 — 先發起唯讀探索呼叫取得頁面 ID，然後在下一次訊息中
// 同時發送 N 個平行的 use_figma 工具呼叫（每個頁面一個），每個僅設定 currentPage 一次。

無論讀取還是寫入，對於任何多頁面作業預設均使用平行展開處理。完整原理說明請參閱 gotchas.md → 每次 use_figma 呼叫僅設定 current page 一次。

跨 Script 執行

在每次 use_figma 呼叫開始時，figma.currentPage 都會重置為第一頁。如果你的工作流程跨越多次呼叫且目標為非預設頁面，請在每次呼叫的開頭呼叫 await figma.setCurrentPageAsync(page)。

你可以多次呼叫 use_figma 以在檔案狀態上漸進式建置，或在撰寫下一個 Script 之前先檢索資訊。例如，先撰寫一個 Script 來取得既有節點的 Metadata 並 return 該資料，接著在後續 Script 中使用該資料來修改這些節點。