Communitygithub.com

code-to-figma

將正在執行的網頁應用程式畫面重建為 Figma 原生可編輯圖層(Auto Layout、元件、實例),並與瀏覽器截圖比對差異——不是匯入截圖或產生 Code 圖層。當使用者要求「將此頁面轉成 Figma」、「從程式碼轉 Figma」、「將此畫面推送至 Figma」或「在 Figma 中重建 UI」時使用。

code-to-figma 是什麼?

Code to Figma 是一個 AI 代理技能,專門用於從執行中的 Web 應用程式提取 DOM 結構,並在 Figma 中重建為可編輯的原生圖層,包含 Auto Layout、元件與實例。它支援多種框架:Vue 3 及 React(包含 React 18/19、Next.js App Router 伺服器元件,React 16/17 理論上相容但未測試),其他框架則僅支援重複節點偵測。此工具主要用於單一或批量畫面重建,產出為可編輯圖層而非截圖或 Code 圖層。工作流程包含:設定專案與畫面、執行 al-capture.cjs 進行捕捉、透過 al-diff.py 比對瀏覽器截圖、執行審計腳本,並遵守嚴格的寫入規則(如分批處理、避免記憶體爆炸等)。已知限制包括:僅支援開發模式下抓取名稱、特定 CSS 效果(如 mask-image)無法完美轉換、字型替代可能導致字元寬度差異等。整體而言,它為開發者與設計師提供了從程式碼到設計工具的無縫橋樑,特別適用於 UI 重建與比對場景。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/byby325/code-to-figma-ui-states/tree/HEAD/skills/code-to-figma

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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.mdMCP 呼叫預算與檔案記憶體的閾值與停止條件;開始前請先閱讀
troubleshooting.md常見陷阱對照表;當結果錯誤時查閱
examples/四種專案類型的捕捉設定範本:內建 mock、Playwright 固定測試、Nuxt 開發模式、攔截後端 API
evals/trials.json迴歸測試案例與基準線;修改工具後請重新執行全部案例

步驟

  1. 確認輸入:專案及其執行方式、哪些畫面、每個畫面的視埠與高度類型、目標 Figma 檔案,以及要綁定的設計系統。由使用者決定主題與範圍;請勿自行挑選。取得 Figma 連結後,先執行 create_session 加上一次唯讀的 use_figma,確認已登入的帳號能夠讀寫該檔案(若無法開啟檔案,使用 whoami 說明是哪個帳號以及應與誰共用檔案)。接著依 scale-guard.md「MCP 呼叫預算」估算此工作所需的呼叫次數;若預算不足,請先告知
  2. 啟動專案、撰寫設定、進行捕捉:依照 web-capture.md 執行 al-capture.cjs
  3. 先為每種裝置建立一個代表性畫面,與瀏覽器截圖比對,僅在相符後再批次處理
  4. 批次處理後比對每個畫面:執行 al-diff.py;同時截圖並檢查元件區段
  5. 審計:執行 audit-screens.js

完成條件:每個畫面都有重建結果,每個畫面的根框架寬度等於視埠寬度,每種裝置的代表性畫面包含參考截圖層;issues 為空,或每個條目都附有原因說明;元件區段已在截圖中檢查完畢。

寫入 Figma 的嚴格規則

Figma 檔案的記憶體可能在瞬間暴增超過限制,即使靜態用量很低也是如此,而且已爆炸的檔案不一定能復原(scale-guard.md「事故」)。請在每個專案中遵守以下規則:

  1. 在寫入現有檔案前,要求使用者儲存版本,包括在刪除或重建你先前建立的畫面之前。在使用者回覆已儲存之前,請勿開始操作。當目標頁面上除了你自己建立的內容外空無一物(新檔案、空白頁面)時,可跳過此步驟;請在報告中說明
  2. 一次只傳送一個畫面:上傳此畫面的圖片與資料 SVG、建立它、確認 ALDATA- 與 ALIMG- 臨時框架已刪除,然後再進行下一個。請勿先上傳整個批次
  3. 若使用者回報紅色警告或復原模式,立即停止。在使用者確認檔案正常之前,即使執行唯讀的 use_figma 也不可以
  4. 達到呼叫限制時停止:若任何 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 格式呈現一行說明

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

figma-library-binding

Bind Figma screens to a design system library — tokens only on exact value matches, swap icons and components for library versions, and list unmatched values for designers instead of snapping to the nearest token. Use when the user asks to "bind tokens", "use library components" or "find unbound colors". 把 Figma 畫面綁到專案的 design system library:顏色、圓角、邊框、間距、字級完全相同才綁 token,圖示和元件換成 library 版本,沒有對應的值列給設計決定,不取最近值。Use when 使用者要「綁 library」「綁 token」「換成 design system 元件」「檢查沒綁 variable 的顏色」,或 code-to-figma、figma-state-board 的畫面要綁 design system。

figma-state-board

Inventory every UI state of a feature from its code and lay them out on one Figma canvas (a state board) — real screens for states the prototype already handles, plus a gap check of missing error, empty and loading states, split into spec-required and suggested. Use when the user asks for a "state board", "all states of this feature in Figma", "which error screens are missing", or to update an existing board. 從任何產品專案的程式碼盤點一個功能的所有狀態,在 Figma 產出或更新「情境稿」:原型(通常是 mock data 做的)已經有的狀態畫真實畫面,原型缺的狀態全列進「缺漏檢查」,再分「規格有寫」(規格要求、原型漏做)和「建議補」(規格和原型都沒提的錯誤、空狀態、載入等)。Use when 使用者要「做情境稿」「把所有狀態/狀況畫到 Figma」「state board」「檢查缺了哪些 error 畫面」,或要依新規則增修既有情境稿。只要狀態清單用 state-discovery,只要把畫面轉進 Figma 用 code-to-figma。

相關技能