# Figma Verify

> Figma 對齊 / 視覺比對 / UI ship gate — 任何提到 figma、Figma 對齊、Figma vs local、Figma vs code、設計稿比對、視覺差異、screenshot diff、UI 對齊、UX 對齊、文案對齊、design token 對齊，或 UI / 文案 PR 即將 ship、code 出現 placeholder / follow-up / 待 designer 確認字串時觸發。流程：Figma MCP 抓真規格 → Playwright MCP headed 抓 local → token + 文案逐項對齊表 → /goal 內建 Haiku 評估者做純視覺 gate（不另起 Agent(model=haiku) subagent）。

- Skill: `ashe-li/figma-verify` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ashe-li/figma-verify`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ashe-li/figma-verify/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: ashe-li (https://skillmd.com/u/ashe-li)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ashe-li/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）

```ts
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 → 程式碼」對應表逐項對齊

| 屬性 | Figma 規格 | 程式碼欄位 | 一致？ |
|---|---|---|---|
| bg token | `Color/Success/L-06` (`#eaf5f4`) | `bg-(--Color-Success-L-06)` | ✅ |
| label 文字 | `待曝光` | `label: "待曝光"` | ✅ |

任何 ❌ 都必須處理 — 不可「先 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 兩張圖貼進對話：

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

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

### 4.5b — 下 `/goal` 啟動 visual gate

```text
/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）

| 模型 | 視覺發現（評估者 reason） | 推測根因（主 turn diagnose） |
|---|---|---|
| haiku（`/goal` 評估者，純視覺比對 2 張 screenshot） | 視覺差異明顯，Figma 偏粗 vs local 偏細 | weight 設定錯誤（推測）+ 字體 fallback |

任一行 ❌ → **不可進入 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 配方

```bash
# 找 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 必跑