Figma Verify

/figma-verify — Figma vs local 對齊與 ship gate

UI / 文案 PR 在 mark ready-for-review、merge、production deploy 之前的最後一道把關，Step 4.5 用內建 /goal 評估者做視覺 gate（細節見該步驟）。

何時用 / 何時不用

✅ 用：

• 動到 visual token / 文案 / icon / spacing / layout 的 PR
• ticket / PR description 帶 Figma 連結
• code 出現「placeholder」「temp」「follow-up」「沿用 XX」disclaimer
• mark ready-for-review / merge / deploy 之前的最後檢查

❌ 不用：

• 純後端 / 純 logic PR，零視覺/文案改動
• 設計系統明寫「工程可自行調整 X 範圍」
• Bug fix（z-index、布局壓蓋）非設計參數變更，但仍應 PR 註記讓設計師看到

Step 1：拿到 Figma node-id

從 ticket / PR / Slack thread 找 figma.com/design/<fileKey>/...?node-id=<id>：

https://figma.com/design/I8foiMEfn9ngF44UGEIrUL/...?node-id=18374-19281
                         └── fileKey ─────┘                 └─ nodeId (- → :) ─┘
                                                              => "18374:19281"

沒有 node-id 不可動 UI / 文案。

Step 2：用 Figma MCP 抓真規格（並行四個 call）

mcp__figma__get_design_context({ nodeId, fileKey })   // Tailwind code + token names
mcp__figma__get_variable_defs({ nodeId, fileKey })    // token → hex map
mcp__figma__get_screenshot({ nodeId, fileKey })       // 視覺 reference（Step 4.5 用）
mcp__figma__get_metadata({ nodeId, fileKey })         // 結構 + x/y/w/h

未授權 → 先跑 mcp__figma__authenticate 或請使用者跑 OAuth flow。

Step 3：fallback — Playwright MCP headed + 已登入 Figma session

Figma MCP 不可用時：

• 必 headed（Figma SPA + CSR + bot detection；headless 卡登入頁）
• 必已登入 Figma session（headless 預設 session 沒登入）
• 不可 WebFetch（figma.com 在 webfetch-blocklist 黑名單）
• 開頁面 → browser_resize ≥1600×1000 → browser_take_screenshot fullPage:true → 量距 / 抓 token name

Step 4：列「Figma → 程式碼」對應表逐項對齊

任何 ❌ 都必須處理 — 不可「先 ship 等 follow-up」。

Step 4.5：/goal 內建 Haiku 評估者做視覺 gate

token / 文案表通過後不可直接 ship。token name 對的也可能視覺渲染不同（font weight fallback、icon size、spacing rendered with 1px diff）。本步驟把「修到視覺一致」變成自動續跑的 gate。

4.5a — 把兩張 screenshot surface 進 transcript

/goal 評估者是小快模型（預設 Haiku），但它不能呼叫工具，只讀 transcript 既有內容。主 turn 必須先把 Figma + local 兩張圖貼進對話：

mcp__figma__get_screenshot({ nodeId, fileKey })
mcp__playwright__browser_take_screenshot({ fullPage: true })  // 已 resize ≥1600×1000

兩張圖都進 transcript 後，Haiku 評估者就能直接做「純視覺比對」。

4.5b — 下 /goal 啟動 visual gate

/goal Figma screenshot 與 local headed screenshot 視覺一致
      （font weight / spacing / color 無肉眼可辨偏差），
      且 Step 4 的「Figma → 程式碼」對齊表全部 ✅
      OR stop after 5 turns

• 不一致 → 評估者回 reason（例：「Figma 偏粗 vs local 偏細」），自動啟動下一輪修正
• 一致 → 自動 clear goal，進入 Step 5

4.5c — 3 欄診斷表（評估者每輪 reason 即「視覺發現」欄，整理成下表貼進 PR description）

任一行 ❌ → 不可進入 Step 5。一次性產出表格走 /goal，整理評估者 reason；只有需要 Haiku 呼叫工具或多路並行才用顯式 Agent(model="haiku") subagent（/goal 評估者本身已是 Haiku，重複開等於重造輪子）。

Step 5：ship 前最後一道對齊

ready-for-review / merge / production deploy 前 — 開 Figma 字面值對 git diff，逐項勾掉。

真的不能等的合法選項

設計師「真的」還沒給 spec（極少發生）：

1. 拆 PR：只 ship 後端邏輯 / status mapping / route gate，不 ship 視覺/文案
2. TODO 常數 + lint gate：const TODO_TOKEN = "TODO_DESIGN_TOKEN_AWAITING_SPEC"; + lint rule 擋 production build
3. block on designer：PR description 寫「block on designer spec, do not merge」+ 不點 ready-for-review
4. dev-only flag：環境 gate 視覺/文案；production 完全不顯示

❌ 禁止：自選 token / 自編文案 merge 到 main → production。「沿用同類狀態」「placeholder」「之後修」都不能當免責詞。

Audit grep 配方

# 找 placeholder / follow-up disclaimer（PR 內最可疑訊號）
grep -rnE "placeholder|TODO|待\s*designer|follow-up|沿用.*配色|借\s+.*token" \
  features/ components/ src/ --include="*.tsx" --include="*.ts" \
  | grep -vE "node_modules|\.test\."

# 找 PR description 自承 placeholder
gh pr view <num> --json body | grep -iE "placeholder|follow-up|沿用|借"

See Also

• Claude Code /goal 官方文件：https://code.claude.com/docs/en/goal

設計依據

• /goal 評估者預設 Haiku：官方原文 "the conversation so far are sent to your configured small fast model, which defaults to Haiku"
• Designer spec 不可單方修改：自選 token / 自編文案 = unilateral edit，無論 placeholder 標記是否清楚
• Token 名對 ≠ 視覺對：font weight fallback、字體載入失敗、平台渲染差異會讓 token-correct 的程式碼看起來仍與 Figma 不符 — 視覺 gate 必跑