實作設計
概觀
此技能提供一套結構化的工作流程,能將 Figma 設計轉換為像素級精準的正式程式碼。它確保與 Figma MCP 伺服器的一致整合、正確使用設計代碼,並實現與設計的 1:1 視覺一致。
技能邊界
- 當最終產出物是使用者儲存庫中的程式碼時,使用此技能。
- 若使用者要求在 Figma 內部建立/編輯/刪除節點,請切換至 figma-use。
- 若使用者要求從程式碼或描述在 Figma 中建立或更新整頁畫面,請切換至 figma-generate-design。
- 若使用者只要求 Code Connect 對應,請切換至 figma-code-connect-components。
- 若使用者要求撰寫可重複使用的代理規則(
CLAUDE.md/AGENTS.md),請切換至 figma-create-design-system-rules。
先決條件
- Figma MCP 伺服器必須連線且可存取
- 使用者必須提供 Figma 網址,格式為:
https://figma.com/design/:fileKey/:fileName?node-id=1-2:fileKey是檔案金鑰1-2是節點 ID(要實作的特定元件或框架)
- 或者使用
figma-desktopMCP 時:使用者可直接在 Figma 桌面應用程式中選取節點(無需網址) - 專案最好有已建立的設計系統或元件庫
必要工作流程
請依序執行以下步驟,不可跳過。
步驟 1:取得節點 ID
選項 A:從 Figma 網址解析
當使用者提供 Figma 網址時,從中擷取檔案金鑰和節點 ID,以作為 MCP 工具的參數。
網址格式: https://figma.com/design/:fileKey/:fileName?node-id=1-2
擷取:
- 檔案金鑰:
:fileKey(/design/後面的段落) - 節點 ID:
1-2(node-id查詢參數的值)
注意: 使用本機桌面 MCP(figma-desktop)時,fileKey 不會作為參數傳遞給工具呼叫。伺服器會自動使用目前開啟的檔案,因此只需 nodeId。
範例:
- 網址:
https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15 - 檔案金鑰:
kL9xQn2VwM8pYrTb4ZcHjF - 節點 ID:
42-15
選項 B:從 Figma 桌面應用程式使用目前選取內容(僅限 figma-desktop MCP)
使用 figma-desktop MCP 且使用者未提供網址時,工具會自動使用桌面應用程式中開啟的 Figma 檔案內目前選取的節點。
注意: 基於選取內容的提示僅適用於 figma-desktop MCP 伺服器。遠端伺服器需要一個指向框架或圖層的連結才能擷取上下文。使用者必須開啟 Figma 桌面應用程式並選取一個節點。
步驟 2:擷取設計上下文
使用擷取到的檔案金鑰和節點 ID 執行 get_design_context。
get_design_context(fileKey="檔案金鑰", nodeId="1-2")
這會提供結構化資料,包含:
- 佈局屬性(Auto Layout、約束、尺寸)
- 字體規格
- 色彩值與設計代碼
- 元件結構與變體
- 間距與留白值
若回應內容過大或被截斷:
- 執行
get_metadata(fileKey="檔案金鑰", nodeId="1-2")以取得高階節點對應 - 從元資料中找出需要的特定子節點
- 使用
get_design_context(fileKey="檔案金鑰", nodeId="子節點ID")擷取個別子節點
步驟 3:擷取視覺參考
使用相同的檔案金鑰和節點 ID 執行 get_screenshot 以取得視覺參考。
get_screenshot(fileKey="檔案金鑰", nodeId="1-2")
此截圖將作為視覺驗證的唯一依據。請在實作過程中保持其可存取。
步驟 4:下載所需素材
下載 Figma MCP 伺服器回傳的所有素材(圖片、圖示、SVG)。
重要: 請遵循以下素材規則:
- 若 Figma MCP 伺服器對圖片或 SVG 回傳
localhost來源,請直接使用該來源 - 請勿匯入或新增新的圖示套件——所有素材應來自 Figma 的酬載
- 如果提供了
localhost來源,請勿使用或建立佔位符 - 素材透過 Figma MCP 伺服器內建的素材端點提供
步驟 5:轉換為專案慣例
將 Figma 輸出轉換為此專案的框架、樣式與慣例。
關鍵原則:
- 將 Figma MCP 輸出(通常是 React + Tailwind)視為設計與行為的表示,而非最終程式碼風格
- 用專案偏好的公用程式類別或設計系統代碼取代 Tailwind 工具類別
- 重複使用現有元件(按鈕、輸入框、排版、圖示包裝器),而非複製功能
- 一致地使用專案的色彩系統、字體比例與間距代碼
- 尊重現有的路由、狀態管理與資料擷取模式
步驟 6:達到 1:1 視覺一致
力求與 Figma 設計達到像素級精準的視覺一致。
指引:
- 優先追求 Figma 忠實度,以完全符合設計
- 避免使用硬編碼值——盡可能使用 Figma 的設計代碼
- 當設計系統代碼與 Figma 規格衝突時,優先採用設計系統代碼,但可微調間距或尺寸以符合視覺效果
- 遵循 WCAG 無障礙需求
- 視需要加入元件文件
步驟 7:對照 Figma 驗證
在標記完成之前,請將最終 UI 與 Figma 截圖進行比對驗證。
驗證清單:
- 佈局相符(間距、對齊、尺寸)
- 排版相符(字型、大小、粗細、行高)
- 色彩完全相符
- 互動狀態按設計運作(懸停、作用中、停用)
- 響應式行為符合 Figma 約束
- 素材正確呈現
- 符合無障礙標準
實作規則
元件組織
- 將 UI 元件置於專案指定的設計系統目錄中
- 遵循專案的元件命名慣例
- 除非動態值確實需要,否則避免使用行內樣式
設計系統整合
- 盡可能使用專案設計系統中的元件
- 將 Figma 設計代碼對應到專案設計代碼
- 當有相符的元件時,應擴充它,而非建立新的
- 記錄任何新增到設計系統的元件
程式碼品質
- 避免硬編碼值——將其提取為常數或設計代碼
- 保持元件的可組合性與可重複使用性
- 為元件 props 加入 TypeScript 型別
- 為匯出的元件加入 JSDoc 註解
範例
範例 1:實作按鈕元件
使用者說:「請實作這個 Figma 按鈕元件:https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15」
動作:
- 解析網址,擷取 fileKey=
kL9xQn2VwM8pYrTb4ZcHjF與 nodeId=42-15 - 執行
get_design_context(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15") - 執行
get_screenshot(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")作為視覺參考 - 從素材端點下載按鈕圖示
- 檢查專案是否有現成的按鈕元件
- 若有,則以新變體擴充;若無,則使用專案慣例建立新元件
- 將 Figma 色彩對應到專案設計代碼(例如
primary-500、primary-hover) - 對照截圖驗證內距、邊框圓角、排版
結果: 按鈕元件符合 Figma 設計,並整合至專案設計系統。
範例 2:建立儀表板佈局
使用者說:「請建立這個儀表板:https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Dashboard?node-id=10-5」
動作:
- 解析網址,擷取 fileKey=
pR8mNv5KqXzGwY2JtCfL4D與 nodeId=10-5 - 執行
get_metadata(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")以了解頁面結構 - 從元資料中識別主要區塊(頁首、側邊欄、內容區域、卡片)及其子節點 ID
- 對每個主要區塊執行
get_design_context(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="子節點ID") - 對整個頁面執行
get_screenshot(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5") - 下載所有素材(標誌、圖示、圖表)
- 使用專案的佈局基本元素建立佈局
- 盡可能使用現有元件實作每個區塊
- 驗證響應式行為是否符合 Figma 約束
結果: 完整的儀表板符合 Figma 設計,並具備響應式佈局。
最佳做法
始終從上下文開始
切勿根據假設進行實作。務必先擷取 get_design_context 和 get_screenshot。
逐步驗證
在實作過程中頻繁驗證,而非僅在最後進行。這樣可以及早發現問題。
記錄偏差
若必須偏離 Figma 設計(例如基於無障礙或技術限制),請在程式碼註解中說明原因。
重複使用而非重新建立
在建立新元件前務必檢查現有元件。程式碼庫的一致性比完全複製 Figma 更重要。
設計系統優先
在不確定時,優先採用專案的設計系統模式,而非逐字翻譯 Figma。
常見問題與解決方案
問題:Figma 輸出被截斷
原因: 設計過於複雜或巢狀圖層過多,無法在單一回應中完整回傳。
解決方案: 使用 get_metadata 取得節點結構,再以 get_design_context 個別擷取特定節點。
問題:實作後設計不符
原因: 實作的程式碼與原始 Figma 設計之間存在視覺差異。 解決方案: 與步驟 3 的截圖並排比對。檢查設計上下文資料中的間距、色彩與排版值。
問題:素材無法載入
原因: Figma MCP 伺服器的素材端點無法存取,或網址被修改。
解決方案: 確認 Figma MCP 伺服器的素材端點可存取。伺服器會以 localhost 網址提供素材。請直接使用這些網址,無需修改。
問題:設計代碼值與 Figma 不同
原因: 專案的設計系統代碼值與 Figma 設計中指定的值不同。 解決方案: 當專案代碼與 Figma 值不同時,優先採用專案代碼以保持一致性,但可調整間距/尺寸以維持視覺忠實度。
了解設計實作
Figma 實作工作流程建立了一套可靠的流程,可將設計轉換為程式碼:
對設計師而言: 確信實作結果將以像素級精準度符合其設計。 對開發者而言: 結構化的方法消除了猜測,並減少來回修改。 對團隊而言: 一致且高品質的實作,能維護設計系統的完整性。
遵循此工作流程,可確保每個 Figma 設計都以相同的細心與關注度進行實作。