figma-generate-library

Name: figma-generate-library
Author: figma

設計系統建構者 — Figma MCP 技能

在 Figma 中建立與程式碼匹配的專業級設計系統。此技能協調跨 20–100+ 次 use_figma 呼叫的多階段工作流程，強制執行來自真實世界設計系統（Material 3、Polaris、Figma UI3、Simple DS）的品質模式。

先決條件：每次 use_figma 呼叫都必須同時載入 figma-use 技能。它提供 Plugin API 語法規則（return 模式、頁面重置、ID 回傳、字型載入、顏色範圍）。此技能提供設計系統領域知識和工作流程協調。

執行此技能時，務必在 use_figma 的逗號分隔 skillNames 參數中包含 figma-generate-library。如果此技能是透過 MCP 資源載入，則必須在名稱前加上 resource:（例如 resource:figma-generate-library）。這是記錄參數——不影響執行。

1. 最重要的唯一規則

對於每個階段，請遵循此溝通契約。

開始階段前：

發布一個面向使用者的檢查清單，標題為 Phase N Checklist。
包含該階段將嘗試的每個任務/子任務。
包含階段退出條件。
在發布此檢查清單之前，請勿開始該階段的變更工作。
如果該階段需要明確批准，請在檢查清單後請求批准並等待。

執行期間：

在每個主要子區段之前，發布一個簡短更新，說明正在處理的確切區段名稱，格式如下：
Working on Phase N.X: <section name>
保持更新簡潔，但讓當前工作可見。
當子區段完成時，如果介面支援檢查清單/狀態更新，則在執行中的檢查清單中標記為已完成；否則在下一次進度更新中提及完成。

每個階段結束時：

發布 Phase N Summary，包含：
- 完成的任務
- 建立或變更的 Figma 物件
- 執行的驗證
- 解決的決策或衝突
- 剩餘風險或後續事項
然後顯示該階段所需的階段產出物，並自動繼續。
僅在 Phase 0 之後或出現真正的決策分歧時才請求明確批准（參見第 6 節）。對於 Phase 1–4，預設是在摘要後自動繼續。

穩定的任務 ID

在所有地方使用統一的任務 ID 格式：P{phase}.{step}。

規則：

僅使用字母步驟 ID：P0.a、P0.b、P1.a、P3.d。
請勿使用純項目符號作為任務清單。
每個階段檢查清單、進度更新、驗證註記和階段摘要都必須引用相同的任務 ID。

沒有設定例外： 建立新的 Figma 檔案、匯入程式庫、建立頁面、變數、集合、樣式或元件都算作建立/變更。請勿將它們視為無害的設定。

這絕非一次性任務。 建立設計系統需要跨多個階段的 20–100+ 次 use_figma 呼叫，並且它們之間必須有強制性的進度。任何嘗試在單一呼叫中建立所有內容的行為都將產生損壞、不完整或無法復原的結果。將每個操作分解為最小的有用單元，進行驗證，獲取回饋，然後繼續。

2. 強制性工作流程

按順序完成各個階段。在當前階段的必要操作和驗收檢查完成之前，請勿進入下一階段。如果某個階段無法通過，請停止並報告阻礙因素。除非使用者明確批准該限制，否則請勿近似、跳過或延遲失敗的階段。不得進行最佳努力替代、靜默近似、或在缺少來源真相、缺少視覺真相、偽造素材、近似排版、損壞互動或未經驗證狀態的情況下移交。

Phase 0：探索（始終優先——尚無 `use_figma` 寫入）

[ ] 0a. 分析程式碼庫 → 提取代碼記號、元件、命名慣例
[ ] 0b. 檢查 Figma 檔案 → 頁面、變數、元件、樣式、現有慣例
[ ] 0c. 搜尋已訂閱的程式庫 → 使用 search_design_system 尋找可重複使用的素材
[ ] 0d. 鎖定 v1 範圍 → 在建立任何內容之前記錄確切的代碼記號集 + 元件清單
[ ] 0e. 對應程式碼 → Figma → 解決並記錄每個衝突（程式碼與 Figma 不一致）
[ ] 0f. 在對話中列印差距分析：程式碼中有但 Figma 中沒有的內容、Figma 中有但程式碼中沒有的內容，以及來自 0e 的每個衝突及其解決方案

Phase 1：基礎（代碼記號優先——始終在元件之前）

[ ] 1a. 建立變數集合和模式
[ ] 1b. 建立原始變數（原始值，1 種模式）
[ ] 1c. 建立語意變數（別名到原始變數，感知模式）
[ ] 1d. 在所有變數上設定範圍（絕不使用 ALL_SCOPES）
[ ] 1e. 在所有變數上設定程式碼語法
[ ] 1f. 建立效果樣式（陰影）和文字樣式（排版）
[ ] 1g. 在對話中列印變數摘要：N 個集合、M 個變數、K 種模式，按集合細分
[ ] 1h. 在對話中列印樣式清單：建立的每個效果樣式和文字樣式及其名稱
[ ] 退出條件滿足：已同意計劃中的每個代碼記號都存在，所有範圍已設定，所有程式碼語法已設定

Phase 2：檔案結構（在元件之前）

[ ] 2a. 建立頁面骨架：封面 → 入門 → 基礎 → --- → 元件 → --- → 工具
[ ] 2b. 建立基礎文件頁面（色票、字體範例、間距條）
[ ] 2c. 為每個基礎頁面擷取 get_screenshot，並在對話中列印頁面清單以及螢幕截圖
[ ] 退出條件滿足：所有計劃的頁面都存在，基礎文件可導覽

Phase 3：元件（一次一個——絕不批次）

對於每個元件（按依賴順序：原子先於分子），執行以下檢查清單。在開始下一個元件之前完成當前元件。

[ ] 3a. 建立專用頁面
[ ] 3b. 使用自動佈局 + 完整變數綁定建立基礎元件
[ ] 3c. 建立所有變體組合（combineAsVariants + 網格佈局）
[ ] 3d. 新增元件屬性（TEXT、BOOLEAN、INSTANCE_SWAP）
[ ] 3e. 將屬性連結到子節點
[ ] 3f. 新增頁面文件（標題、描述、使用說明）
[ ] 3g. 驗證：get_metadata（結構）+ get_screenshot（視覺）
[ ] 3h. 可選：趁上下文清晰時進行輕量級 Code Connect 對應
[ ] 退出條件滿足：變體數量正確，所有綁定已驗證，螢幕截圖看起來正確

Phase 4：整合 + 品質保證（最終檢查）

[ ] 4a. 完成所有 Code Connect 對應
[ ] 4b. 無障礙審計（對比度、最小觸控目標、焦點可見性）
[ ] 4c. 命名審計（無重複、無未命名節點、一致的大小寫）
[ ] 4d. 未解析綁定審計（無殘留的硬編碼填色/描邊）
[ ] 4e. 每個頁面的最終審查螢幕截圖

3. 關鍵規則

Plugin API 基礎（來自 use_figma 技能——此處也強制執行）：

使用 return 將資料傳回（自動序列化）。請勿包裝在 IIFE 中或呼叫 closePlugin。
在每個回傳值中回傳所有已建立/變更的節點 ID
每次呼叫時頁面上下文會重置——始終在開始時使用 await figma.setCurrentPageAsync(page)。每個腳本最多呼叫一次：每個元件或文件頁面都是自己的 use_figma 呼叫。切勿在變更腳本中遍歷 figma.root.children 並切換頁面——將該工作拆分為每個目標頁面一個專注的呼叫（參見 figma-use → gotchas.md → 每次 use_figma 呼叫設定一次當前頁面）
figma.notify() 會拋出錯誤——切勿使用
顏色範圍為 0–1，而非 0–255
在任何文字寫入之前必須載入字型：await figma.loadFontAsync({family, style})。使用 await figma.listAvailableFontsAsync() 來發現可用的字型並驗證確切的樣式字串——如果載入失敗，查詢可用字型以找到正確的名稱或備用字型。

設計系統規則：

變數在元件之前——元件綁定到變數。沒有代碼記號 = 沒有元件。
建立前先檢查——執行唯讀的 use_figma 以發現現有慣例。與它們匹配。
每個元件一個頁面 （預設）——例外：緊密相關的系列（例如，輸入 + 輔助元件）可以共用一個頁面，但需有清晰的區段分隔。
將視覺屬性綁定到變數 （預設）——填色、描邊、內距、半徑、間距。例外：故意固定的幾何形狀（圖示像素網格尺寸、靜態分隔線）。
每個變數都設定範圍——絕不保留為 ALL_SCOPES。背景：FRAME_FILL, SHAPE_FILL。文字：TEXT_FILL。邊框：STROKE_COLOR。間距：GAP。圓角：CORNER_RADIUS。原始變數：[]（隱藏）。
每個變數都設定程式碼語法——WEB 語法必須使用 var() 包裝：var(--color-bg-primary)，而非 --color-bg-primary。使用來自程式碼庫的實際 CSS 變數名稱。ANDROID/iOS 不使用包裝。
將語意別名到原始變數——{ type: 'VARIABLE_ALIAS', id: primitiveVar.id }。切勿在語意層中重複原始值。
在 combineAsVariants 之後定位變體——它們堆疊在 (0,0)。手動進行網格佈局 + 調整大小。
圖示使用 INSTANCE_SWAP——切勿為每個圖示建立一個變體。限制變體矩陣：如果 Size × Style × State > 30 種組合，則拆分為子元件。
確定性命名——使用一致、唯一的節點名稱以實現冪等清理和可恢復性。透過回傳值和狀態帳本追蹤已建立的節點 ID。
無破壞性清理——清理腳本透過命名慣例或回傳的 ID 來識別節點，而非猜測。
繼續前先驗證——切勿建立在未經驗證的工作之上。每次建立後執行 get_metadata，每個元件後執行 get_screenshot。
絕不平行化 use_figma 呼叫——Figma 狀態變更必須嚴格依序進行。即使你的工具支援平行呼叫，也絕不同時執行兩個 use_figma 呼叫。
絕不憑空想像節點 ID——始終從先前呼叫回傳的狀態帳本中讀取 ID。切勿從記憶中重建或猜測 ID。
使用輔助腳本——將 scripts/ 中的腳本嵌入到你的 use_figma 呼叫中。不要從頭開始編寫 200 行的內聯腳本。

4. 狀態管理（長時間工作流程必備）

getPluginData() / setPluginData() 在 use_figma 中不受支援。 請改用 getSharedPluginData() / setSharedPluginData()（這些受支援），或使用基於名稱的查詢和狀態帳本（回傳的 ID）。

實體類型	冪等鍵	如何檢查存在性
場景節點（頁面、框架、元件）	`setSharedPluginData('dsb', 'key', value)` 或唯一名稱	`node.getSharedPluginData('dsb', 'key')` 或 `page.findOne(n => n.name === 'Button')`
變數	集合內的名稱	`(await figma.variables.getLocalVariablesAsync()).find(v => v.name === name && v.variableCollectionId === collId)`
樣式	名稱	`getLocalTextStyles().find(s => s.name === name)`

在建立後立即標記每個已建立的場景節點：

node.setSharedPluginData('dsb', 'run_id', RUN_ID);        // 識別此建構執行
node.setSharedPluginData('dsb', 'phase', 'phase3');        // 哪個階段建立的
node.setSharedPluginData('dsb', 'key', 'component/button');// 唯一的邏輯鍵

狀態持久化：不要僅依賴對話上下文來維護狀態帳本。將其寫入磁碟：

/tmp/dsb-state-{RUN_ID}.json

在每次輪次開始時重新讀取此檔案。在長時間工作流程中，對話上下文可能會被截斷——檔案是真相來源。

維護一個追蹤以下內容的狀態帳本：

{
  "runId": "ds-build-2024-001",
  "phase": "phase3",
  "step": "component-button",
  "entities": {
    "collections": { "primitives": "id:...", "color": "id:..." },
    "variables": { "color/bg/primary": "id:...", "spacing/sm": "id:..." },
    "pages": { "Cover": "id:...", "Button": "id:..." },
    "components": { "Button": "id:..." }
  },
  "pendingValidations": ["Button:screenshot"],
  "completedSteps": ["phase0", "phase1", "phase2", "component-avatar"]
}

每次建立前的冪等檢查：按名稱 + 狀態帳本 ID 查詢。如果存在，則跳過或更新——絕不重複。

恢復協定：在會話開始或上下文截斷後，執行唯讀的 use_figma 以按名稱掃描所有頁面、元件、變數和樣式，重建 {key → id} 對應。然後從磁碟重新讀取狀態檔案（如果可用）。

繼續提示（在恢復到新對話時提供給使用者）：

"我正在繼續一個設計系統建構。執行 ID：{RUN_ID}。載入 figma-generate-library 技能，並從最後完成的步驟繼續。"

5. 程式庫探索與 search_design_system — 重複使用決策矩陣

在 Phase 0 中先搜尋，然後在每個元件建立之前立即再次搜尋。

從 get_libraries 開始，以了解在盲目搜尋之前有哪些程式庫可用：

// 發現檔案可存取的所有程式庫
get_libraries({ fileKey })
// 回傳：
//   libraries_added_to_file: [{ name, libraryKey, description, source }, ...]
//   libraries_available_to_add: [{ name, libraryKey, description, source }, ...]
//   libraries_available_to_add_next_offset: number | null

使用回傳的 libraryKey 值，透過 includeLibraryKeys 將搜尋範圍限定到特定程式庫。這可以避免在許多程式庫可用時產生雜亂的結果。

如果 libraries_available_to_add_next_offset 非 null，則有更多組織程式庫可用——使用 offset 設定為該值再次呼叫 get_libraries。組織程式庫以每批 20 個分頁；社群 UI 套件僅出現在第一頁。

// 搜尋所有程式庫（預設）
search_design_system({ query, fileKey, includeComponents: true, includeVariables: true, includeStyles: true })

// 僅在特定程式庫內搜尋
search_design_system({ query, fileKey, includeLibraryKeys: ["lk-abc123..."], includeComponents: true })

重複使用如果以下所有條件成立：

元件屬性 API 符合你的需求（相同的變體軸、相容的類型）
代碼記號綁定模型相容（使用相同或可別名的變數）
命名慣例與目標檔案匹配
元件可編輯（未鎖定在你未擁有的遠端程式庫中）

重建如果以下任一條件成立：

API 不相容（不同的屬性名稱、錯誤的變體模型）
代碼記號模型不相容（硬編碼值、不同的變數結構）
所有權問題（無法修改程式庫）

包裝如果視覺匹配但 API 不相容：

將程式庫元件作為巢狀實例匯入到新的包裝元件中
在包裝器上公開一個乾淨的 API

優先順序：本地現有 → 已訂閱的程式庫匯入 → 來自 libraries_available_to_add 的未訂閱 UI 套件程式庫（尤其是圖示）→ 建立新的。

6. 決策分歧

當路徑分歧時詢問使用者——當存在兩個或多個合理的答案，且程式碼庫、Figma 檔案或鎖定的計劃中沒有明確的贏家時。不要靜默地使用預設值。呈現每個選項及其權衡和你的建議；僅在使用者指引後才選擇。

何時不詢問： 如果從真相來源（程式碼、Figma 檔案、已同意的計劃）中明確只有一條路徑是正確的，則採用它。本節適用於真正的歧義，而非將每個決策都推卸出去。

分歧情況	要呈現的內容	範例詢問
程式碼 ≠ Figma 在代碼記號、元件或值上	兩個版本並排顯示，附帶來源（檔案/行 vs 節點）	"程式碼說 `--color-bg-primary = #FFFFFF`，Figma 有 `color/bg/primary = #FAFAFA`。哪個勝出？"
已訂閱的程式庫有接近但不完全匹配的項目	程式庫元件摘要 + 差距清單	"程式庫有 `Button`，但沒有 `loading` 狀態。重複使用並在本地包裝，還是從頭重建？"
計劃鎖定時範圍不明確（0d）	明確包含的內容、明確排除的內容、不明確的內容	"規格列出了 `Button` 和 `Input`；`Field` 被引用但未定義。在 v1 中包含還是排除？"

如果使用者拒絕你已經建立在之上的選項： 在繼續之前修正。切勿建立在被拒絕的工作之上。

7. 命名慣例

匹配現有檔案慣例。如果從頭開始：

變數（斜線分隔）：

color/bg/primary     color/text/secondary    color/border/default
spacing/xs  spacing/sm  spacing/md  spacing/lg  spacing/xl  spacing/2xl
radius/none  radius/sm  radius/md  radius/lg  radius/full
typography/body/font-size    typography/heading/line-height

原始變數：blue/50 → blue/900，gray/50 → gray/900

元件名稱：Button、Input、Card、Avatar、Badge、Checkbox、Toggle

變體名稱：Property=Value, Property=Value——例如 Size=Medium, Style=Primary, State=Default

頁面分隔線：---（最常見）或 ——— COMPONENTS ———

完整命名參考：naming-conventions.md

8. 代碼記號架構

複雜度	模式
< 50 個代碼記號	單一集合，2 種模式（淺色/深色）
50–200 個代碼記號	標準：原始變數（1 種模式）+ 顏色語意（淺色/深色）+ 間距（1 種模式）+ 排版（1 種模式）
200+ 個代碼記號	進階：多個語意集合，4–8 種模式（淺色/深色 × 對比度 × 品牌）。參見 token-creation.md 中的 M3 模式

標準模式（建議起點）：

集合："Primitives"    模式：["Value"]
  blue/500 = #3B82F6, gray/900 = #111827, ...

集合："Color"         模式：["Light", "Dark"]
  color/bg/primary → Light：別名 Primitives/white, Dark：別名 Primitives/gray-900
  color/text/primary → Light：別名 Primitives/gray-900, Dark：別名 Primitives/white

集合："Spacing"       模式：["Value"]
  spacing/xs = 4, spacing/sm = 8, spacing/md = 16, ...

9. 各階段反模式

Phase 0 反模式：

❌ 在使用者鎖定範圍之前開始建立任何內容
❌ 忽略現有檔案慣例並強加新慣例
❌ 在規劃元件建立之前跳過 search_design_system

Phase 1 反模式：

❌ 在任何變數上使用 ALL_SCOPES
❌ 在語意層中重複原始值而非使用別名
❌ 未設定程式碼語法（破壞開發者模式和往返）
❌ 在同意代碼記號分類之前建立元件代碼記號

Phase 2 反模式：

❌ 跳過封面頁或基礎文件
❌ 將多個不相關的元件放在一個頁面上

Phase 3 反模式：

❌ 在基礎存在之前建立元件
❌ 在元件中硬編碼任何填色/描邊/間距/半徑值
❌ 為每個圖示建立一個變體（改用 INSTANCE_SWAP）
❌ 在 combineAsVariants 之後未定位變體（它們全部堆疊在 0,0）
❌ 建立超過 30 個變體的矩陣而不拆分（變體爆炸）
❌ 匯入遠端元件後立即分離它們

一般反模式：

❌ 在未先理解錯誤的情況下重試失敗的腳本
❌ 使用名稱前綴匹配進行清理（會刪除使用者擁有的節點）
❌ 建立在來自上一步驟未經驗證的工作之上
❌ 平行化 use_figma 呼叫（始終依序）
❌ 從記憶中猜測/憑空想像節點 ID（始終從狀態帳本讀取）
❌ 編寫大型內聯腳本而非使用提供的輔助腳本
❌ 因為使用者說「建立按鈕」就開始 Phase 3，而未完成 Phase 0-2

10. 參考文件

按需載入——每個參考對其階段具有權威性：

使用你的檔案閱讀工具在需要時閱讀這些文件。不要從檔案名稱假設其內容。

文件	階段	必備/可選	何時載入
discovery-phase.md	0	必備	開始任何建構——程式碼庫分析 + Figma 檢查
token-creation.md	1	必備	建立變數、集合、模式、樣式
documentation-creation.md	2	必備	建立封面頁、基礎文件、色票
component-creation.md	3	必備	建立任何元件或變體
code-connect-setup.md	3–4	必備	設定 Code Connect 或變數程式碼語法
naming-conventions.md	任何	可選	命名任何內容——變數、頁面、變體、樣式
error-recovery.md	任何	錯誤時必備	腳本失敗、多步驟工作流程恢復、清理遺棄的工作流程狀態

11. 腳本

可重複使用的 Plugin API 輔助函式。嵌入到 use_figma 呼叫中：

腳本	用途
inspectFileStructure.js	發現所有頁面、元件、變數、樣式；回傳完整清單
createVariableCollection.js	建立一個具名集合及其模式；回傳 `{collectionId, modeIds}`
createSemanticTokens.js	從代碼記號對應建立別名語意變數
createComponentWithVariants.js	從變體矩陣建立元件集；處理網格佈局
bindVariablesToComponent.js	將設計代碼記號綁定到所有元件視覺屬性
createDocumentationPage.js	建立包含標題 + 描述 + 區段結構的頁面
validateCreation.js	驗證已建立的節點是否符合預期數量、名稱、結構
cleanupOrphans.js	按名稱慣例或狀態帳本 ID 移除孤立節點
rehydrateState.js	按名稱掃描檔案中的所有頁面、元件、變數；回傳完整的 `{key → nodeId}` 對應用於狀態重建

您可能也喜歡

songsee

385Kdesign-ui

Generate spectrograms and feature-panel visualizations from audio with the songsee CLI.

steipete

獲取

ui-to-vue

237Kdesign-ui

Use when the user has UI screenshots or design exports that need batch conversion into Vue 3 components, especially with Vant, Element Plus, or Ant Design Vue.