清洗策略：不重做 Figma 也能擠出可信任的 token
2026-05-26
當設計檔本身就非常混亂，怎麼不重做 Figma 也能擠出可信任的 token
一開始我思考的是要不要先把這份混亂的 Figma file 變乾淨再繼續下一步。後來發現不對——把一份結構不佳、沒 auto layout、群組邏輯亂的 Figma 重做成乾淨版，等於在做設計師的工作，而不是我想交接的 AI pipeline。
這種 cleanup 是個無底洞——做到 80% 都很順，最後 20% 永遠在追細節。就算做完，下個接手的人若沒有相同紀律，三個月後又會回到原樣。
設計工程（Design Engineering）主張 token 應該住在 code 中（一份
tokens.json或 DTCG 檔案）。如果先把 Figma 弄乾淨、再從乾淨的 Figma 萃取 token，等於把 source of truth 留在 Figma。
因此把順序倒過來：以「整理 token」為目標，把現在的 Figma 當成「考古資料」而不是「源頭」。
流程會是：
- 從現有 Figma 抽出原始素材
- 在 code 裡定義乾淨的
tokens.json跟tokens.css - 生成 component 後確認符合設計
- 驗證是否可以搬到實際程式碼之中
這樣的好處是，即使接手的人不熟悉 Figma，只要 token 還在，AI 跟接手人都可以專心處理程式碼。
Token 如何輸出？
Figma 並沒有辦法直接輸出 JSON，只能輸出 PNG / SVG / PDF。不過如果是一份完整的 Figma，MCP / REST API 擷取之前其實就可以看出結構，但通常理想很豐滿、現實很骨感。
以下是拿到 JSON 的三條路：
1. Figma 桌面版 MCP
可以選取單一元件後在 Claude Code / Cowork 裡直接呼叫，如：
請用 figma-desktop MCP 抓選取元件的 raw 結構，存成 button-fresh-dump.json
2. REST API
如果 PAT 還沒 revoke，執行：
curl -H "X-Figma-Token: $TOKEN" \
"https://api.figma.com/v1/files/{file-key}/nodes?ids={node-id}" \
> button-fresh-dump.json
file-key 跟 node-id 從你在 Figma 右鍵「Copy link to selection」拿到的網址解析出來。
3. Plugin
在 Figma plugin 搜尋：Design Tokens
選元件 → 跑 plugin → 下載 JSON。
在後兩篇有使用的過程可以作為參考：
- #3_接通Figma：REST API——先講為什麼 API 不夠用
- #4_接通Figma：Figma MCP——再講後來 MCP 怎麼補上來
以這份設計稿的按鈕為例，該有的都有——大小、字型、文字顏色、背景色都在 Figma 裡標好了，但整理成 JSON 後卻是滿滿 hardcoded hex 跟散落的 style id：同一個綠色出現四個不同的色碼（hex）、該建成 style 的有些沒建。
對照組：整理過的 Figma file 應該長什麼樣
- 設計師有意識地建立 style / variable（colour、type、effect 都有對應的 style id）
- export JSON 帶出來的是「這個 fill 引用 style XYZ」的結構，而不只是最後渲染的 hex
- 拿著 style id 去 REST API 反查，可以撈出整個引用網絡：
- 這顆按鈕用的綠色是哪個 style？
- 同一個 style 還在哪些地方被用到？
對人來說兩種 Figma 看起來都一樣，但對機器來說落差非常大——「結構可用」才是 token 化能不能自動推導的關鍵。
這份 Figma File 卡在一個很微妙的階段
結構是有的但對機器來說不可用。
我選擇不重做它，而是把它當考古資料、把 source of truth 搬到 code。預期這個系列結束時，會留下一份敢拿給 agent 用的 tokens.json——不需要原設計師、不需要乾淨的 Figma，接手的人就能直接從 code 開始。