網站轉 Figma 設計檔
將正在運行的網頁應用程式轉換為設計師可以真正重新設計的 Figma 檔案：包含真實的文字、真實的圖示、支援明暗模式的色彩與間距變數、文字樣式、可重複使用的元件，以及每個由這些元件實例組成的頁面。螢幕截圖僅供參考，絕非最終交付物。
此技能建立在 Figma 外掛自身的技能之上。在任何 use_figma 呼叫之前，請先載入 figma-use 和 figma-generate-design；在建立元件或變數時，請載入 figma-generate-library。
使用時機
- "把我的網站放進 Figma，讓我重新設計"
- "在 Figma 中重建這些頁面" / "將這個應用程式推送至 Figma"
- 為以此方式建立的 Figma 檔案加入行動框架或新頁面
步驟
1. 讀取真實來源
- 正在運行的應用程式及全域樣式表優先於設計文件。文件在重新設計過程中可能出現偏差；若發現不一致請明確指出。
- 收集：主題變數（亮色與暗色）、字型家族與粗細、佈局網格（邊距、欄軌道、欄寬），以及每個頁面區塊背後的元件檔案。
- 在寫入樣式前，使用
figma.listAvailableFontsAsync()檢查字型是否存在於 Figma 中。切勿在不告知的情況下直接退回使用 Inter 字型。
2. 使用 Playwright 擷取參考螢幕截圖，而非頁面擷取
在每個目標寬度（例如 1440 和 390）使用 scripts/ref-screenshots.mjs。它會設定 reducedMotion: "reduce"，因此滾動顯示與入場動畫不會隱藏內容。
generate_figma_design 頁面擷取在此任務中不可靠：位於檢視區動畫後方的內容會被擷取為空白，且在背景瀏覽器分頁中開啟的擷取經常永遠處於 pending 狀態。如果你非要使用它們，請一次只開啟一個分頁，並在該擷取完成參考用途後立即刪除。如果你將擷取腳本注入到應用程式中，請在之後將其移除。
3. 從程式碼庫匯出真實資料與圖示
編寫一個一次性 tsx 腳本（位於儲存庫外部，或使用後刪除），該腳本匯入應用程式自己的資料模組，並使用 react-dom/server 的 renderToStaticMarkup 將圖示元件渲染為 SVG 字串。然後：
- 將
currentColor替換為真實顏色，並為每個 SVG 設定明確的width/height。圖示庫會產生1em，而 Figma 無法調整其大小。 - 根據路徑資料對圖示進行去重。品牌對應檔經常將許多名稱別名對應到同一個標誌。
- 使用 CMS 用戶端擷取 CMS 內容（標題、摘要、分類），而不是手動重新輸入。
4. 先建立基礎架構
每次呼叫一個任務，並回傳所有建立的 ID：
- 頁面：基礎、元件、每個中斷點一個頁面。
- 變數集合：主題色（亮色/暗色模式）、分類或品牌色、佈局標記（桌面/行動模式）。設定明確的
scopes和 WEB 程式碼語法。 - 每個字型角色的文字樣式，以及顯示尺寸的行動版變體。
- 任何共用陰影的效果樣式。
5. 建立元件，從最小的開始
圖示，然後是基本元件（按鈕、連結、磁磚、徽章、籌碼），接著是複合元件（頁首、頁尾、英雄區、卡片）。公開 TEXT、BOOLEAN 和 INSTANCE_SWAP 屬性，以便頁面可以不經分離就填入內容。為響應式元件提供 Breakpoint 變體，而不是在實例上覆寫尺寸。每組完成後截圖一次，修正問題後再繼續。
6. 從實例組裝頁面
- 每個頁面一次
use_figma呼叫，放置在固定的畫布位置上，以便頁面可以平行建立。 - 使用自動佈局的內邊距（例如軌道和邊距）來鏡像 CSS 網格，而非使用絕對位置。
- 明確地將每行卡片的高度設為一致；Figma 不會像 CSS 網格那樣自動拉伸同層元素。
- 將每個頁面的總高度和螢幕截圖與參考進行比較。高度相差在幾個百分比內表示間距是正確的。
7. 將元件回連至程式碼
Code Connect 僅在 Organization 和 Enterprise 方案中有效。請先檢查 whoami。在其他方案中，將來源路徑、元件名稱和屬性對應寫入每個元件的 description，並將 documentationLinks 設定為 GitHub 上的檔案。開發者模式會同時顯示這兩者。請勿將 .figma.ts 檔案加入無法發布它們的儲存庫；在沒有 Code Connect 套件的情況下，它們會使 tsc 編譯失敗。
8. 清理
刪除參考擷取、移除任何注入的腳本、停止你啟動的開發伺服器，並確認 git status 是乾淨的。
常見陷阱
在撰寫元件或頁面腳本之前，請先閱讀 references/plugin-api-pitfalls.md。它列出了最耗時的失敗情況，每個情況都附有解決方法：邊界繪製的不透明度、resize() 鎖定自動佈局尺寸、屬性鍵被重新索引、複製變體時遺失參考、每次呼叫的大小限制，以及更多問題。
references/helpers.md 包含一些小幫助函式，值得貼在每個頁面建置腳本的頂部。