figma-generate-design

依據設計系統建立 / 更新畫面與檢視

使用此 Skill，可透過重用已發布的設計系統（包含元件、變數與樣式）在 Figma 中建立或更新畫面、檢視與多區塊 UI 容器，避免以硬編碼數值繪製基礎形狀。這涵蓋完整頁面、彈窗（modal）、對話框（dialog）、抽屜（drawer）、側邊欄（sidebar）、面板（panel）以及任何由多個區塊組合而成的檢視。核心重點在於：Figma 檔案中通常已有已發布的設計系統，其元件、顏色/間距變數、文字/效果樣式皆與程式碼庫中的 UI 元件和 Token 相對應。請務必找出並使用這些資源，而不是手動繪製填滿 Hex 色碼的矩形。

強制要求：在呼叫任何 use_figma 之前，您必須先載入 figma-use。該 Skill 包含適用於您所編寫的每一個腳本的關鍵規則（顏色範圍、字型載入等）。

當作為此 Skill 的一部分呼叫 use_figma 時，請務必在以逗號分隔的 skillNames 參數中包含 figma-generate-design。如果此 Skill 是透過 MCP 資源載入的，您必須在名稱前加上 resource: 前綴（例如 resource:figma-generate-design）。 此參數僅用於紀錄記錄（logging），不會影響實際執行。

Skill 適用邊界

• 當交付物是由設計系統元件實例（component instances）組裝而成的 Figma 組合檢視（新建或更新）時（如完整頁面、彈窗、對話框、抽屜、側邊欄、面板或任何多區塊容器），請使用此 Skill。
• 如果使用者想建立新的可重用元件或變體（variants），請直接使用 figma-use。
• 如果使用者想撰寫 Code Connect 對映關係，請切換至 figma-code-connect。

先決條件

• 必須已連線 Figma MCP 伺服器
• 目標 Figma 檔案必須包含已發布且帶有元件的設計系統（或具備團隊元件庫存取權限）
• 使用者必須提供目標 Figma 檔案（URL 或 fileKey）。若目前尚未有檔案，請先呼叫 /figma-create-new-file（或呼叫 create_new_file），並重用傳回的 file_key。use_figma 和 generate_figma_design 皆需要既有的 fileKey。
• 要建立/更新之畫面/檢視的原始碼或文字描述

與 generate_figma_design 的平行工作流程（僅限 Web App）

當建置來自可在瀏覽器中轉譯（render）之 Web App 的畫面時，同時平行執行兩種方式可獲得最佳效果：

1. 平行執行：
   • 針對目標 Figma 檔案 (fileKey)，開始使用此 Skill 的工作流程 (use_figma + 設計系統元件) 建立畫面。
   • 針對相同的 fileKey 執行 generate_figma_design，以擷取運行中 Web App 像素級精準的截圖並寫入該檔案。generate_figma_design 隨時都需要 fileKey——若使用者尚未提供 Figma 檔案，請先呼叫 /figma-create-new-file（或呼叫 create_new_file MCP 工具）以取得檔案，並在本地流程與截圖流程中重用該 file_key。
2. 兩者皆完成後： 更新 use_figma 的輸出結果，使其符合 generate_figma_design 擷取出的像素級精準版面配置。截圖提供了精準的間距、尺寸與視覺呈現參考目標，而 use_figma 輸出則具備連結至設計系統的正確元件實例。如果擷取內容中包含圖片，請複製截圖中圖片填色（image fills）的 imageHash 數值並轉移至 use_figma 輸出（詳情請參閱步驟 5）。
3. 確認視覺效果良好後： 刪除 generate_figma_design 的輸出內容——該輸出僅作為視覺對照參考。

這結合了兩者的優勢：generate_figma_design 帶來像素級精準的版面配置，而 use_figma 則帶來能保持連結且可隨時更新的設計系統元件實例。

當來源包含圖片時，此平行工作流程為強制要求。 use_figma Plugin API 無法存取外部圖片 URL——它只能透過複製檔案中現有節點（node）的 imageHash 數值來設定圖片填色。generate_figma_design 會將所有可見圖片點陣化（rasterize）並載入至 Figma 中，提供您所需的 hash 值。若在包含圖片的情況下跳過擷取步驟，圖片圖框將會保持空白。

對於非 Web App（如 iOS、Android 等）或更新現有畫面時，請使用下方標準工作流程。

必要工作流程

請依序執行下列步驟，切勿跳過任何步驟。

硬性門檻 — 嚴禁捷徑：

• 嚴禁： 在完成 2a-i 且已嘗試 2a-ii 或記錄為不適用（例如「空白檔案，無現有畫面」）之前，使用 search_design_system 搜尋元件 key。
• 嚴禁： 在填妥下表步驟 2 所有項目之前，發起任何會變更畫布（Canvas）的 use_figma 呼叫（步驟 3+）。

步驟 1：理解交付標的

在操作 Figma 之前，請先釐清要建置的內容：

1. 若是根據程式碼建置，請閱讀相關原始碼檔案，以理解結構、區塊以及使用了哪些元件。
2. 識別檢視畫面的主要區塊（例如頁面包含：Header、Hero、Content Panels、Footer；彈窗包含：Title Bar、Form Sections、Action Bar；側邊欄包含：Navigation、Content Area、Footer Actions）。
3. 針對每個區塊，列出涉及的 UI 元件（按鈕、輸入框、卡片、導覽膠囊/Pills、折疊面板/Accordions 等）。
4. 從原始碼中確認產品所使用的字型家族（font family），切勿預設使用 Inter。 在撰寫任何腳本前，請先查明產品使用哪種字體。關於要在何處查找（CSS 變數、元件檔案）以及如何處理 Figma 中複雜的字型名稱，請參閱 references/discover-product-font.md。
5. 檢查檢視畫面中是否包含任何圖片（例如 <img>、<Image>、背景圖片、商品照片、頭像、從 URL 載入的圖示）。若包含圖片且此為 Web App，您必須執行平行的 generate_figma_design 擷取工作流程——請在執行步驟 2 的同時立即啟動截圖，以便在您探索元件時同步進行截圖。詳情請參閱上方「與 generate_figma_design 的平行工作流程」。

步驟 2：收集元件 Key、變數與樣式

您需要從設計系統中取得三樣資源：元件（按鈕、卡片等）、變數（顏色、間距、圓角/radii）與樣式（文字樣式、陰影等效果樣式）。只要設計系統 Token 存在，就切勿硬編碼 Hex 顏色或像素數值。

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 解析元件 key：

範例： Code Connect 檔案中包含 // url=https://figma.com/design/ABC123/File?node-id=609-35535。解析得到 fileKey = ABC123，nodeId = 609:35535。針對元件庫檔案（fileKey 為 ABC123，而非目標檔案）執行 use_figma 以解析 key：

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

在單次呼叫中批次進行多筆查詢。在步驟 4 中將傳回的 key 與 importComponentSetByKeyAsync() 配合使用。

標記已解析的元件。若所有元件皆已解析，請跳過 2a-ii 與 2a-iii。若所需的元件皆無 Code Connect 檔案，請繼續進行 2a-ii。

2a-ii — 若仍有未解析元件則為必要步驟：檢查現有畫面。 檢查目標檔案中是否已有使用相同設計系統的畫面。只需呼叫一次 use_figma 來遍歷現有 Frame 的實例，即可取得精準且具權威性的元件地圖：

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 套件與組織元件庫）。每個項目皆包含一個 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 中的組織元件庫採用分頁處理（每頁 20 筆）。當 libraries_available_to_add_next_offset 不為 null 時，表示有更多組織元件庫可用——請再次呼叫 get_libraries 並將 offset 設定為該數值以取得下一頁。社群 UI 套件僅會出現在第一頁。若使用者指定了您在目前頁面中未看到的特定元件庫，請繼續翻頁查找，切勿過早放棄。

當檔案連結了許多元件庫且您希望精準搜尋時（例如僅在「iOS 26」或「Material 3」內搜尋，而非取得所有元件庫的比對結果），此功能特別實用。

進行廣泛搜尋——嘗試多個關鍵字與同義詞（例如 "button"、"input"、"nav"、"card"、"accordion"、"header"、"footer"、"tag"、"avatar"、"toggle"、"icon" 等）。使用 includeComponents: true 來鎖定元件搜尋。

在您的元件地圖中包含元件屬性（component properties）——您需要知道每個元件暴露了哪些 TEXT 屬性，以便進行文字覆寫（text overrides）。建立一個臨時實例，讀取其 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": VARIA