從設計系統建立/更新畫面與視圖
使用此技能在 Figma 中建立或更新畫面、視圖及多區塊 UI 容器,方法是重用已發布的設計系統:元件、變數與樣式,而非使用硬編碼值繪製基本形狀。這包括完整頁面、彈窗、對話框、抽屜、側邊欄、面板,以及任何由多個區塊組成的視圖。關鍵見解:Figma 檔案很可能有一個已發布的設計系統,包含與程式碼庫 UI 元件和令牌相對應的元件、顏色/間距變數及文字/效果樣式。尋找並使用這些資源,而非繪製帶有十六進位顏色的方框。
強制要求:在進行任何 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 的平行工作流程(僅限網頁應用)
當從可在瀏覽器中渲染的網頁應用建立畫面時,同時執行兩種方法可獲得最佳結果:
- 平行執行:
- 使用此技能的工作流程(use_figma + 設計系統元件)開始建立畫面
- 執行
generate_figma_design以擷取執行中網頁應用的像素級完美螢幕截圖
- 兩者都完成後: 更新 use_figma 的輸出,使其與
generate_figma_design擷取的像素級完美佈局相符。該擷取提供了您要達到的精確間距、尺寸和視覺處理,而您的 use_figma 輸出則具有連結到設計系統的正確元件實例。如果擷取中包含圖片,請從擷取的圖片填色中複製imageHash值,將其轉移到您的 use_figma 輸出中(詳見步驟 5)。 - 確認看起來不錯後: 刪除
generate_figma_design的輸出。它僅用作視覺參考。
這結合了兩者的優點:generate_figma_design 提供像素級完美的佈局準確性,而 use_figma 則提供保持連結且可更新的正確設計系統元件實例。
當來源包含圖片時,此平行工作流程是強制性的。 use_figma 外掛程式 API 無法擷取外部圖片 URL。它只能透過從檔案中已存在的節點複製 imageHash 值來設定圖片填色。generate_figma_design 會將所有可見圖片柵格化到 Figma 中,從而提供您所需的雜湊值。如果跳過存在圖片時的擷取,圖片框架將留空。
對於非網頁應用(iOS、Android 等)或更新現有畫面時,請使用下方的標準工作流程。
必要工作流程
請依序執行以下步驟。請勿跳過任何步驟。
硬性門檻,禁止捷徑:
- 禁止: 在 2a-i 完成且 2a-ii 已嘗試或記錄為「不適用」(例如「空檔案,無現有畫面」)之前,使用
search_design_system搜尋元件金鑰。- 禁止: 在下方檢查清單中所有步驟 2 的列都填寫完成之前,進行任何會改變畫布的
use_figma呼叫(步驟 3 以上)。
步驟 1:了解交付物
在觸碰 Figma 之前,了解您要建構的內容:
- 如果是從程式碼建構,請閱讀相關原始檔以了解結構、區塊以及使用了哪些元件。
- 識別視圖的主要區塊(例如,對於頁面:頁首、英雄區、內容面板、頁尾;對於彈窗:標題列、表單區塊、操作列;對於側邊欄:導航區、內容區、頁尾操作)。
- 對於每個區塊,列出涉及的 UI 元件(按鈕、輸入框、卡片、導航膠囊、手風琴等)。
- 檢查視圖是否包含任何圖片(例如
<img>、<Image>、背景圖片、產品照片、頭像、從 URL 載入的圖示)。如果是,且這是網頁應用,則您必須執行平行的generate_figma_design擷取工作流程,在步驟 2 的同時立即啟動它,以便在您發現元件時進行擷取。請參閱上方「與 generate_figma_design 的平行工作流程」。
步驟 2:收集元件金鑰、變數與樣式
您需要從設計系統取得三樣東西:元件(按鈕、卡片等)、變數(顏色、間距、圓角半徑)和樣式(文字樣式、效果樣式如陰影)。當設計系統令牌存在時,請勿硬編碼十六進位顏色或像素值。
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。針對程式庫檔案(檔案金鑰 ABC123,而非目標檔案)執行 use_figma 以解析金鑰:
const node = await figma.getNodeByIdAsync("609:35535");
const set = node?.parent?.type === "COMPONENT_SET" ? node.parent : node;
return { componentKey: set.key };
在單次呼叫中批次處理多個查詢。在步驟 4 中使用傳回的金鑰呼叫 importComponentSetByKeyAsync()。
標記已解析的元件。如果所有元件都已解析,請跳過 2a-ii 和 2a-iii。如果沒有任何需要的元件有 Code Connect 檔案,請繼續執行 2a-ii。
2a-ii. 如果仍有未解析的元件則必要:檢查現有畫面。 檢查目標檔案是否已包含使用相同設計系統的畫面。單次 use_figma 呼叫,遍歷現有框架的實例,即可為您提供精確且權威的元件對映:
// 唯讀發現,跳過實例內部的不可見內容(隱藏的變體等)
// 以實現數百倍快的 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 套件和組織程式庫)。每個條目都包含一個 libraryKey,您可以將其傳遞給 search_design_system 的 includeLibraryKeys 參數,以將搜尋範圍限定在特定程式庫,而不是搜尋所有內容。
// 步驟 1:發現可用的程式庫
get_libraries({ fileKey })
// 傳回:{
// libraries_added_to_file: [...],
// libraries_available_to_add: [...],
// libraries_available_to_add_next_offset: number | null
// }
// 步驟 2:使用其 libraryKey 在特定程式庫內搜尋
search_design_system({ query: "button", fileKey, includeLibraryKeys: ["lk-abc123..."] })
libraries_available_to_add 中的組織程式庫是分頁的(每頁 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(以及巢狀實例的屬性),然後移除該臨時實例。
包含屬性資訊的範例元件對映:
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:發現變數(顏色、間距、圓角半徑)
先檢查現有畫面(與元件相同)。或使用 search_design_system 搭配 includeVariables: true。
警告:兩種不同的變數發現方法,請勿混淆。
- 使用
figma.variables.getLocalVariableCollectionsAsync()的use_figma:僅傳回目前檔案中定義的本機變數。如果傳回空值,並不表示不存在變數。遠端/已發佈的程式庫變數對此 API 不可見。- 使用
includeVariables: true的search_design_system:搜尋所有連結的程式庫,包括遠端和已發佈的。這是發現設計系統變數的正確工具。永遠不要僅根據
getLocalVariableCollectionsAsync()傳回空值就得出「不存在變數」的結論。 在決定建立自己的變數之前,務必也執行帶有includeVariables: true的search_design_system以檢查程式庫變數。
查詢策略: search_design_system 匹配的是變數名稱(例如「Gray/gray-9」、「core/gray/100」、「space/400」),而非類別。並列執行多個簡短、簡單的查詢,而非一個複合查詢:
- 原始顏色:「gray」、「red」、「blue」、「green」、「white」、「brand」
- 語意顏色:「background」、「foreground」、「border」、「surface」、「text」
- 間距/尺寸:「space」、「radius」、「gap」、「padding」
如果初始搜尋傳回空值,請嘗試較短的片段或不同的命名慣例,因為不同程式庫之間的差異很大(「grey」與「gray」,「spacing」與「space」,「color/bg」與「background」)。
檢查現有畫面的繫結變數以獲得最權威的結果:
// 唯讀發現,跳過實例內部以加快速度。
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "Existing Screen");
// boundVariables 可以存在於任何場景節點上,列舉每個場景類型
// 以提供 findAllWithCriteria 大致上與 findAll(() => true) 相同
// 並且在腳本輸出中更嘈雜。
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:發現樣式(文字樣式、效果樣式)
使用 search_design_system 搭配 includeStyles: true 以及「heading」、「body」、「shadow」、「elevation」等術語搜尋樣式。或檢查現有畫面所使用的內容:
// 唯讀發現,跳過實例內部以加快速度。
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 存在於 TEXT 和 TEXT_PATH 上;effectStyleId 存在於大多數場景
// 形狀/容器類型上。使用 `in` 守衛來處理兩者,而無需
// 窮舉類型清單。
if ('textStyleId' in node && node.textStyleId) {
cons
…
[為翻譯而截斷]