接通 Figma REST API：連線、抓 metadata、為什麼不只是 export JSON

連線、抓 metadata、為什麼不只是 export JSON

對人來說畫面都長得一樣，但對機器來說將會導致產生的程式碼嚴重失真，因此首要任務就是拆解設計稿，挑一個核心元件如 button，試試看能抽出多乾淨的 metadata？這個實驗結果會直接告訴你：你需不需要清理、要清理多少。如果結果意外可用，整個 cleanup 階段就可以跳過；如果完全慘不忍睹，再決定範圍。

---

前置作業

首先要確認兩件事：

1. 確認團隊方案

• 確認原始檔所在團隊方案不是免費（Starter）方案
• Figma 的 Dev Mode（以及 Dev Mode MCP）需要 Professional 以上才能用

2. Enable Dev Mode MCP server

這個功能超級難找，還好有搜尋功能

1. 點左上角像葡萄的 figma icon，用 Actions 搜尋 Dev
2. Switch to Dev Mode

---

下面是嘗試和 Claude Cowork 一起接通 REST API 的過程，REST API 比 MCP 更原始，但官方文件齊全、權限模型也清楚。

Step 1｜用 API 抓 metadata

首先需要開通權限，流程是：

1. 打開 Figma（瀏覽器或桌面都可以）

2. 右上角頭像 → Settings

3. 左側選 Security 那一欄

4. 找到「Personal access tokens」區塊 → 按 Generate new token

5. 名稱取 design-token-experiment（隨便）

6. Expiration 選 90 天就夠

7. Scopes 勾這些就好：

   • File content → Read-only
   • Library content → Read-only（如果有這選項）
   • Library assets → Read-only（如果有這選項）
   • 按 Generate
   • token 會顯示一次而已，立刻整串複製貼回給 Claude Cowork

Claude Cowork 拿到 token 後做了幾件事，並提醒我把 token revoke。

後續請它確認這份 JSON 檔案，並把它整理成結構化分析檔案。

關於 revoke 這件事：Cowork 提醒得很對，PAT 本來就該用完就丟。但這次我刻意先不 revoke — 後面還要回頭再抓 Secondary、Disabled、Input field 等元件來補資料，這個 token 還會用到。等實驗整個跑完才會撤掉。

給未來的接手人：如果你看到這篇時 PAT 還活著，請幫忙 revoke。

Step 2｜選一個元件

1. 把 primary button 的 Figma 連結貼給 Claude Cowork

2. 選取 Figma file 中的 primary button

3. 右鍵 → 複製/貼上為 → 複製選取項目的連結（Copy/Paste as → Copy link to selection）

   也可以用快捷鍵：選中元件後 Ctrl + L（Windows）/ Cmd + L（Mac）。

   複製出來的連結長這樣：

https://www.figma.com/design/{file-key}/Mockup原始檔...?node-id={node-id}

---

第一次撈到的資料長什麼樣

抓回來的是 button 頁面整頁的 raw metadata（檔案另外存了一份，叫 button-page-dump.json，1.36 MB）。把這份 dump 丟回給 Cowork 做結構化分析，第一輪有幾個觀察：

1. 62% styled / 37% hardcoded

這份 Figma 不是完全沒整理過 — 三個 style 都有用到（color/primary/主色、color/gray/白色、綠色按鈕-陰影）。原設計師有 token 化的意識，或許這就是大多數 design file 的真實狀態：做了一半。

而「整理到一半」其實比「完全沒整理」更難處理，因為它讓人以為有規則，又處處違反規則。後面 token 推導的時候要假設任何一個值都有可能是脫隊的，不能因為它看起來像 style 就照單全收。

2. 命名系統災難

過去將這份設計稿整理成程式碼的時候，就有發現色碼很亂且不符顏色對比綠⋯

• 白色被歸在 gray 底下（color/gray/白色）。這個分類錯誤如果被 agent 讀到，agent 在生成 dark mode 時會跟著反轉，產出醜到不行的結果
• 有四種綠：#69B076（主色）、#429952（主色暗）、#00A061（出現 4 次的孤兒綠）、#21BA52（出現 2 次的孤兒綠），前兩個是設計師有意識的，後兩個是脫隊的。

---

用 API 驗證 token：消耗問題浮現

在 Claude Cowork 的幫助下，我開始整理 primitive.tokens.json 和 semantic.tokens.json 兩個檔案。但很快就發現了瓶頸——Cowork 每次對話的 token 消耗太多了。一個 1.36 MB 的 JSON dump 拆分和討論起來，光是環境初始化的成本就很高。

決定改變策略：在專案中建立一個 Vue x Vite 環境，直接用程式碼來驗證和組織這些 token，而不是靠 AI 一步步整理。這樣做有兩個好處：

1. 避免重複的 token 消耗
2. 可以即時看到組件實際長什麼樣

---

API 的侷限：為什麼結構對機器不友好

從 Vue 組件庫開始構建後，我逐漸體會到這份 Figma 的問題所在。每當我想驗證一個設計決策時，就會發現——REST API 給我的數據只是最終渲染結果，看不到設計意圖。

具體例子：

• Style reference 丟失：API 返回的是解析後的最終色碼（#69B076），而不是「這個按鈕用了 color/primary/主色 這個 style」
• Variant 信息缺失：無法看到元件的 variant 結構，只能看到一堆獨立的 frame
• Auto layout 參數看不到：spacing、padding 的設計邏輯全是 hardcoded 數字，無法提取規則

這導致了一個悖論：設計稿看起來完整，但 API 吐出的結構對於 token 化和 AI 理解來說沒有作用。

想要從這些 raw data 推導出可信任的 token，需要大量的人工驗證和假設——這恰好是我試圖避免的。

---

下一步：試試 Figma MCP

既然 REST API 的侷限很清楚了，是時候測試 Figma MCP 能不能改善這個狀況。Figma MCP 號稱能直接存取設計檔的完整結構——不只是渲染結果，而是設計的完整元數據。

如果 MCP 能看到 style reference、variant 邏輯、auto layout 參數，那麼整個 token 推導流程就有救了。下一篇我會記錄這個實驗的過程。

Next: #4_接通Figma：Figma MCP