Brief 的品質，決定了建置結果的品質
你第一次請 Claude Code 在 Figma 建置設計概念時，結果可能讓你失望： 元件用了錯的 Variant、顏色沒有套用品牌 Token、圖片比例跟設計規範不符。 問題不在 AI 的能力，而在 Brief 傳遞的資訊。
「你提供的資訊品質，決定了 AI 能建出什麼。Brief 寫得愈精準，AI 愈能在對的地方做對的決策。」
這篇文章從最根本的問題開始：AI 工具在你的設計系統裡能看見什麼、不能看見什麼？ 理解這條邊界，才能寫出讓 AI 正確執行的 Brief——而不是把 AI 不需要的資訊塞進去， 或遺漏了它真正需要的上下文。
先理解 AI 工具看得見什麼
Claude Code 透過 Figma MCP 讀取你的設計系統。它看見的是兩類結構化知識： Design Token（設計語意變數）和Component 定義（元件規格）。 理解這兩類知識的邊界，是寫好 Brief 的前提。
Design Token：AI 自行查詢的顏色語言
Design Token 是有名字的設計變數。Claude Code 能直接從 Figma 讀取 Token 名稱和對應色值， 不需要你在 Brief 裡指定 hex 值。
核心規則
Brief 中不要提供 hex 色碼。寫 purple-100 即可，Claude Code 自行從 Token 查詢對應色值。提供 hex 反而會造成混淆，讓 AI 用 hardcode 值取代 Token 引用。
Component 定義：Variant 的正確選用
每個 Figma Component 都有預定義的 Variant（變體）。Claude Code 讀取 spec.md 後， 知道特定情境應使用哪個 Variant。Brief 中不需要指定 Variant 名稱——那是 spec.md 的工作， 不是 Brief 的工作。
| 元件 | Variant：Fill=False（錯誤） | Variant：Fill=True（正確） |
|---|---|---|
| Image Fallback | 輪廓形圖示，視覺上像「空框」 | 實心圖示，品牌規範標準 |
| 判斷依據 | Brief 沒有說明 → AI 用預設值 | spec.md 明確定義 → AI 從規範讀取 |
正確的 Component 選用取決於 spec.md 文件的完整性，而非 Brief 的詳細程度。 在建置前確認 spec.md 已正確記錄各元件的標準 Variant，才是防止這類錯誤的根本方法。
Claude Code 自行處理
不需要在 Brief 中提供
顏色 hex 值（從 Token 查詢）· 間距數字（從 4px 格線計算）· Icon 名稱（從 sprite.svg grep）· Component key · Figma API 語法
設計師負責提供
必須在 Brief 中明確說明
設計概念與情境描述 · 畫面的主要行動 · Section 的排列順序與層次 · 內容細節（真實文案、商品名稱、數字）· 設計約束（固定項目 vs. 可探索項目）
設計師 vs. AI 分工：各司其職
AI 協作最常見的失誤，是設計師在 Brief 裡提供了大量 AI 不需要的技術細節， 卻省略了它真正需要的設計判斷。理解分工邊界，避免這個方向的錯誤。
分工模型 · 設計師提供判斷，AI 負責執行
概念 + 判斷
結構化說明
元件規範
Figma 建置
| 任務 | 設計師負責 | Claude Code 負責 |
|---|---|---|
| 顏色 | 決定語意（「背景用品牌輕色」） | 查詢 Token，套用正確 hex |
| 間距 | 描述關係（「Section 之間需明顯分隔」） | 依 4px 格線選擇合適數值 |
| 元件 Variant | 確認 spec.md 已記錄正確規範 | 讀取 spec.md，選用正確 Variant |
| Icon | 描述圖示語意（「購物車圖示」） | 從 sprite.svg grep 找正確檔名 |
| 內容文案 | 提供真實內容（商品名、價格） | 依 Brief 填入指定位置 |
三層資訊優先順序：什麼要說、什麼不說
Brief 的資訊量不是愈多愈好。過多的技術細節會讓 AI 混淆， 遺漏關鍵的設計意圖才是真正的問題。以下三個層次幫助你判斷每筆資訊是否應該出現在 Brief 裡。
必須提供（Must-have）
設計概念核心：這個畫面解決什麼問題、使用者處於什麼情境、主要行動是什麼。
Section 清單與順序：畫面由哪些區塊組成，從上到下的排列邏輯。
內容細節：真實的商品名稱、文案、數字（不是佔位符 Lorem ipsum）。
設計約束：哪些是必須遵守的規格，哪些可以由 AI 自行發揮。
高價值補充（High-value）
設計假說：為什麼這個設計方向能解決問題（幫助 AI 理解意圖而非只執行指令）。
差異化說明：這個設計與現有解決方案的不同之處。
Token 語意引用：使用 Token 名稱描述顏色（如「背景 purple-100」），不提供 hex。
不需要提供（Don't-provide）
hex 色碼：Claude Code 從 Token 自行查詢，你提供 hex 反而可能造成 hardcode。
間距數字：Claude Code 依 4px 格線自行計算，你的數字可能與格線系統衝突。
Icon 檔名：Claude Code 從 sprite.svg grep，你指定的名稱可能不是正確檔名。
Figma API 語法：Claude Code 的內部實作語言，設計師不需要也不應該管。
五條 Brief 寫作原則
這五條原則來自實際 Claude Code × Figma 協作過程中反覆出現的問題。 每一條都對應一種常見的 Brief 寫作失誤。
用設計語意，不用技術規格
寫「背景使用品牌淺紫（purple-100）」而非「背景 #e4deff」。 前者是設計意圖，後者是技術實作——AI 會自行把意圖轉成正確的技術規格。 提供技術規格反而侵入了 AI 的工作範疇。
Section 清單依視覺優先順序排列
從上到下列出所有 Section，每項說明「這個 Section 的主要功能是什麼」。 不要只列名稱。「AI 搭配推薦 — bg purple-100，包含 header + product card × 2」 比「AI 搭配推薦 Section」給 AI 更多可以執行的資訊。
內容細節用真實資料，不用佔位符
提供真實的商品名稱、價格、文案。佔位符（「商品名稱」「NT$ XXX」） 讓 AI 無法決定視覺比例和文字截斷行為。真實資料讓建置結果更接近最終產品， 也能提早發現版面問題。
明確區分「固定」和「探索」
設計約束分兩類：固定（不可更改的品牌規範）和探索（可以嘗試多種做法的空間）。 不明確區分這兩類，AI 會在你不想讓它發揮的地方「創意」， 在你希望它探索的地方卻死板遵循。
說明主要行動，讓 CTA 位置有意義
每個畫面的主要行動（Primary Action）告訴 AI 哪個 CTA 最重要、 應放在最顯眼的位置。沒有明確的主要行動，AI 會均等對待所有按鈕， 失去視覺層次。
標準 Brief 模板
以下是單一畫面 Brief 的標準結構。每個欄位對應一個設計判斷層次， 缺少任何一個都可能讓 AI 在那個節點使用預設值而非你的意圖。
完整填寫範例：購物車 × AI 搭配推薦
以下是一個完整的 Brief 範例，對應「購物車頁面，加入 AI 搭配推薦功能」的設計概念。 注意每個欄位如何傳遞設計意圖，而不是技術細節。
Figma 建置結果截圖（images/screenshot-cart.png）
Build Result · 購物車 × AI 搭配推薦
上方 Brief 送出後的建置結果。AI 推薦 Section 背景使用 Token purple-100（非 hardcode hex）、
商品名稱 Sony WH-1000XM5、特賣價 $2,490、搭配推薦商品——
所有內容細節從 Brief 直接映射，AI 沒有使用佔位符或猜測。
Brief 中標注「固定」的項目（結帳 CTA 在第一屏可見、AI 推薦背景 purple-100）
都被正確執行；「探索」項目（推薦文案、card 詳細程度）由 AI 自行決定。
▲ Claude Code 根據上方 Brief 建置的購物車畫面。AI 推薦 Section 背景 Token purple-100、header icon 顏色依 Design Token 自動套用。
下游執行提示
這份 Brief 送出後，Claude Code 會依序：① 讀取 spec.md 確認 Image Fallback 和 product-card 的 Variant 規範 → ② 從 Token 查詢 purple-100 的 hex 值 → ③ 從 sprite.svg grep 確認 AI icon 名稱 → ④ 建置各 Section → ⑤ 截圖確認各元件是否符合規範。 設計師在 Layer 2（建置中）截圖確認時，重點檢查 Image Fallback 的 icon 顏色是否為 purple-100。