Code to Figma
執行專案,在瀏覽器中提取 DOM 並轉換為版面樹,接著在 Figma 中重建為可編輯的 Auto Layout 與元件。
適用於 Web 前端。元件邊界設有 Vue 3 與 React 的適配器(已測試 React 18 與 19,包含 Next.js App Router 伺服器元件;React 16 與 17 具有相同 fiber 結構但未測試)。其他框架僅支援重複節點偵測。原生應用程式與完全在 Canvas/WebGL 中繪製的畫面不在範圍內;請改用設計檔或線框稿。
| 檔案 | 內容 |
|---|---|
| web-capture.md | 完整流程;開始前請先閱讀 |
| screen-structure.md | 輸出必須符合的結構規則 |
| scale-guard.md | MCP 呼叫預算與檔案記憶體的閾值與停止條件;開始前請先閱讀 |
| troubleshooting.md | 常見陷阱對照表;當結果錯誤時查閱 |
| examples/ | 四種專案類型的捕捉設定範本:內建 mock、Playwright 固定測試、Nuxt 開發模式、攔截後端 API |
| evals/trials.json | 迴歸測試案例與基準線;修改工具後請重新執行全部案例 |
步驟
- 確認輸入:專案及其執行方式、哪些畫面、每個畫面的視埠與高度類型、目標 Figma 檔案,以及要綁定的設計系統。由使用者決定主題與範圍;請勿自行挑選。取得 Figma 連結後,先執行
create_session加上一次唯讀的use_figma,確認已登入的帳號能夠讀寫該檔案(若無法開啟檔案,使用whoami說明是哪個帳號以及應與誰共用檔案)。接著依 scale-guard.md「MCP 呼叫預算」估算此工作所需的呼叫次數;若預算不足,請先告知 - 啟動專案、撰寫設定、進行捕捉:依照 web-capture.md 執行
al-capture.cjs - 先為每種裝置建立一個代表性畫面,與瀏覽器截圖比對,僅在相符後再批次處理
- 批次處理後比對每個畫面:執行
al-diff.py;同時截圖並檢查元件區段 - 審計:執行
audit-screens.js
完成條件:每個畫面都有重建結果,每個畫面的根框架寬度等於視埠寬度,每種裝置的代表性畫面包含參考截圖層;issues 為空,或每個條目都附有原因說明;元件區段已在截圖中檢查完畢。
寫入 Figma 的嚴格規則
Figma 檔案的記憶體可能在瞬間暴增超過限制,即使靜態用量很低也是如此,而且已爆炸的檔案不一定能復原(scale-guard.md「事故」)。請在每個專案中遵守以下規則:
- 在寫入現有檔案前,要求使用者儲存版本,包括在刪除或重建你先前建立的畫面之前。在使用者回覆已儲存之前,請勿開始操作。當目標頁面上除了你自己建立的內容外空無一物(新檔案、空白頁面)時,可跳過此步驟;請在報告中說明
- 一次只傳送一個畫面:上傳此畫面的圖片與資料 SVG、建立它、確認
ALDATA-與ALIMG-臨時框架已刪除,然後再進行下一個。請勿先上傳整個批次 - 若使用者回報紅色警告或復原模式,立即停止。在使用者確認檔案正常之前,即使執行唯讀的
use_figma也不可以 - 達到呼叫限制時停止:若任何 Figma 工具回傳「已達到 Figma MCP 工具呼叫限制」,請勿重試,也勿切換工具以繞過此限制。列出已完成的畫面以及仍在畫布上的臨時框架節點 ID
已知限制
- 元件邊界設有 Vue 3 與 React 的適配器;兩者都需要開發模式(生產版本沒有元件名稱,且
stats.json會發出警告)。Svelte、Angular 與其他框架僅支援重複節點偵測;若要支援某個框架,請在al-extract.js的ADAPTERS中加入項目 - React 元件命名規則:只有當 DOM 節點是元件唯一的根節點時,才視為邊界,名稱取自最外層的元件。僅傳遞子元件的元件(Provider、Tooltip、ErrorBoundary)、styled-components/emotion 樣式元件,以及路由與框架內部元件不計入。Next.js 伺服器元件名稱需要 React 19 開發版本(Next 15 以上);使用 React 18 時僅能擷取客戶端元件
- React:Vite + Radix + Tailwind 4 示範專案具有 Figma 重建基準線(四個畫面,與瀏覽器差異 0.02–0.12%)。Next.js App Router 專案僅通過擷取與打包驗證
- 使用 SVG 作為
mask-image且無子元素的圖示(例如 frappe-ui、UnoCSS 的lucide-*類別)會轉換為向量並以背景色上色。其他mask-image用途(漸變淡入、點陣遮罩)與clip-path無法對應;淡化邊緣與斜角切割將變為完整形狀 - 顏色:支援
rgb()以及 Chrome 可能回傳的其他格式,如oklch()、color(srgb …)、lab()與hsl();後者會透過 canvas 轉換為 sRGB,每個通道可能誤差 1(8 位元四捨五入) - Plugin API 無法變更實例內部的框架寬度。唯一子元素若撐滿父框架會改為 Fill;撐滿父框架的子元素透過內距調整;資料中為 Hug 的 Auto Layout 框架會改為 Hug;其他情況下尺寸遵循主要元件,且
log.boxes會列出它們 - 小型元素若具有巢狀 z-index 可能會被遮蓋;圖層樹無法將單一子元素移出其父元素
- 系統字型(
ui-sans-serif)會替換為 Inter;字元寬度會有細微差異 font-variant-numeric: tabular-nums(等寬數字)在 Figma 中無法啟用:Plugin API 的openTypeFeatures是唯讀屬性。日期、時間與金額的寬度比瀏覽器中窄,後續文字會偏移 5–8px;log.drift會列出這些情況- 旋轉與 CSS 三角形僅針對無子元素的元素(勾選標記、分頁三角形、小方塊)處理,這些會轉換為向量;包含子元素的旋轉容器會根據其邊界框排列,內容不會旋轉
報告
- 結構:Auto Layout 容器比例、元件/變體數量;哪些區域為絕對定位(疊層、滾動中內容)
- 比對結果:文字偏移、差異比例最高的畫面,以及無法重現的已知問題。請根據上下文解讀差異比例:漸層或點陣
mask-image會推高比例,因此請說明原因;當stats.json警告圖示為空白時,先允許圖示來源並重新擷取。當整個畫面幾乎沒有顏色時,首先檢查__alBuild回傳的stat是否捕捉到任何顏色(troubleshooting.md) - 參考截圖僅放置於代表性畫面;其餘保留在本機輸出資料夾中
- 若已綁定程式庫,請依照 figma-library-binding 的「報告」區段撰寫此部分;若無程式庫,顏色與字型大小為硬編碼值
- 畫面是從模擬資料重建;說明哪些區域使用了即時截圖填補,以及哪些文案在模擬中做了修改
- 當 Figma 沒有產品字型時,說明使用了哪種替代字型
- 規模:以 scale-guard.md 格式呈現一行說明