AI 精準輸出的設計工作流：從 Token 到設計文件
有了 Design Token，只完成了一半。這篇文章說明設計師還需要準備哪些文件，才能讓 AI 的輸出從「顏色正確」進化到「設計意圖正確」，以及如何一步一步把這套文件寫出來。
「Vibe coding」這個詞最近在設計師圈越來越常出現，但大多數人對它的想像是： 「用 AI 快速做設計稿，隨便一句 prompt 就能出結果。」 這只是 vibe coding 的表象，不是它的核心。
真正的 vibe coding，是你描述設計意圖，AI 輸出的結果符合你的設計系統規範、品牌調性、和視覺語言——不需要你在 prompt 裡說「這個按鈕用 #7759FF」，不需要一個一個交代顏色，不需要在 AI 輸出後一個一個修正 token 名稱。
「Vibe coding 的終點不是『快』，是『精準』。你說一句『幫我做商品列表頁』，AI 輸出的結果，設計師看得出來是 SHP 的風格。」
要做到這件事，AI 需要三層知識——而 Design Token 只提供了第一層。 這篇文章說明剩下兩層是什麼，為什麼缺了它們 AI 只能「猜」，以及設計師如何一步一步把這兩層補起來。
讓 AI 精準輸出設計畫面，需要三層不同層次的知識。每一層都有特定的來源，缺少任何一層，AI 就只能靠猜。
--shp-text-icon-basic-primary、
--shp-surface-element-brand……
全部 136 個 CSS 變數的存在，以及 light / dark 兩套值。
basic 系列、
按鈕文字用 element 系列；
surface 四層結構；功能色限制；dark mode 例外規則……
Token 選用的通用判斷邏輯。
Layer 1 + Layer 2 讓 AI 輸出「token 正確」的結果。 加上 Layer 3，AI 才能輸出「設計意圖正確」的結果。 兩者都正確，才是真正的 vibe coding 精準輸出。
Layer 3 是設計師的工作
Layer 1 和 Layer 2 由工程師和設計系統負責人建立，設計師不需要從頭建。 Layer 3 是設計師對 AI 說的話——只有你知道這個畫面要表達什麼，只有你能寫這一層。 而且，寫 Layer 3 的過程，本身就是一次設計思考的整理。
SHP 已有 npm token 套件（Layer 1）和 CLAUDE.md（Layer 2）。 對設計師的日常工作，這已經解決了幾個明確的痛點，但也還有一個清晰的缺口。
已經解決的問題
| 以前的痛點 | 現在的狀態 |
|---|---|
| AI 生成時自己猜顏色，不符合設計系統 | ✓ 解決 npm token 提供所有 --shp-* 變數 |
| Dark mode 要在 prompt 裡額外說明 | ✓ 解決 CLAUDE.md 規則讓 AI 自動套用正確 token |
| 每次 prompt 都要貼一堆顏色值 | ✓ 解決 AI 直接用 token 名稱，不依賴 hex 值 |
| 工程師和設計師的顏色兜不攏 | ✓ 解決 同一份 npm token，兩邊同步更新 |
還缺的一哩路
CLAUDE.md 給的是通用規則，但 AI 仍不知道：
視覺重心在哪
設計決策層
這個頁面的主要 CTA 是什麼？哪個元素需要最高視覺強度？哪裡應該要低調讓路？AI 不知道你的設計意圖，只能套用「品牌按鈕用 brand 色」這種通用規則。
有哪些狀態需要處理
互動完整性
Loading？Empty state？Error？Disabled？AI 不知道你的元件在什麼情境下會出現哪些狀態，沒有說明就不會主動處理，輸出結果通常只有「正常狀態」。
這個場景的例外
設計系統例外處理
這個頁面的 header 要 always-light（導覽列始終深色背景）？這個元件的文字不能跟著 dark mode 反轉？通用規則處理不了針對特定場景的設計決策。
元件的視覺層次關係
頁面結構
頁面上的元件哪個是主角、哪個是配角、哪個是背景？這個資訊決定了 surface 層的選用——但 AI 不知道你的頁面設計邏輯。
加入 Layer 3 之後，差別有多大
FIG.01 · 有無設計規格 MD 的 prompt 輸出差異
設計規格 MD 讓 prompt 從一個描述變成一個可執行的設計說明書
Layer 3 不是一份文件，而是一套文件體系。根據你要做的設計任務類型，有三種對應的文件格式。 每種文件服務不同的 AI 任務，不需要全部都建立，按需求逐步累積。
元件規格文件
Component Spec · 10–20 分鐘
說明一個可重複使用的元件：結構層次、每個元素對應的 token、所有互動狀態。 高頻元件（商品卡片、按鈕、輸入框）優先寫，投資報酬率最高。
product-card.md頁面規格文件
Page Spec · 15–30 分鐘
說明一個頁面的視覺層次架構、每個區域的 token 配置、主要 CTA、空狀態。 適合在進入頁面開發前完成，讓 AI 一次生成就接近目標。
product-list-page.md設計探索文件
Concept Doc · 5–10 分鐘
設計早期的輕量文件：說明這次探索要驗證什麼問題、視覺方向、範圍限制。 每次新的設計探索前 5 分鐘寫完，讓 AI 的第一個輸出就在正確的方向上。
concept-[名稱].md另一個工具：CLAUDE.md（已存在）
CLAUDE.md 是 Layer 2 的載體，已經存在於 SHP npm 專案中。 它記錄的是整個設計系統的通用選用規則，不是針對特定畫面的規格——設計師不需要修改 CLAUDE.md，也不需要重新寫它。 你需要做的是：為你負責的每個元件、頁面、探索稿，分別建立上面三種文件之一。
進階：Claude Code Skills
如果你的團隊頻繁用 Claude Code 生成設計稿，可以建立「設計指令捷徑」（Claude Code Skills）：
在 .claude/skills/ 目錄新增 design-component.md，定義一個 /design-component 指令，
讓 Claude Code 每次執行這個指令時，自動讀取對應的元件規格文件並生成。
這是進階功能，需要有 CLAUDE.md 和元件規格文件作為基礎，再考慮引入。
設計規格文件和一般的設計說明最大的差別，是它的閱讀對象是 AI，不是人。 AI 需要具體的、可執行的資訊，不需要形容詞或情緒性描述。以下五個原則幫助你寫出 AI 能精準執行的文件。
描述「目的」，不描述「外觀」
AI 知道顏色規則，但不知道這個元素的設計角色。
告訴 AI 這個元素要達成什麼，AI 自己選對的 token。
不好：「背景是淺灰色」
好：「頁面背景 surface/background/bg-grey，建立最底層的閱讀環境」
不好：「按鈕用紫色」
好：「主要行動按鈕 surface/element/brand，是這個頁面唯一的強調色」
Token 名稱優先，顏色值永遠不出現在文件裡
只要 token 名稱出現，AI 自動處理 light + dark mode，你不需要說明兩遍。
顏色值（#7759FF）一出現，AI 就把它當成硬編碼的顏色，dark mode 壞掉。
不好：「品牌色 #7759FF」
好：「surface/element/brand」
說明「不要用什麼」比說明「要用什麼」更精準
AI 最容易在邊界情境選錯 token。明確排除，比正面規定更能防止錯誤。
例：「brand 按鈕上的文字不要用 text--icon/basic/invert
（invert 是深色背景上的白色文字，不是按鈕內文字）；
要用 text--icon/element/primary」
「禁止事項」區塊是設計規格文件最有效的部分之一。
狀態要列完整，不能只描述「正常狀態」
設計意圖最容易在邊緣狀態出現分歧——因為這些狀態沒有寫明，AI 就自己猜。
每個互動元件都要說明：
Default（正常）→ Hover（滑入）→ Pressed（點擊）→ Disabled（停用）→ Loading（載入中）→ Empty（空狀態）→ Error（錯誤）
不是每個元件都有所有狀態，但你要明確決定哪些需要處理、哪些不需要。
每份文件只負責一個功能單元
不要在一份文件裡同時說明整個商品詳情頁的所有元件。
把「商品詳情頁」分成：頁面結構（page spec）+ 商品卡片（component spec）+ 加入購物車按鈕（component spec）。
文件越細，AI 在執行特定任務時的精準度越高。
寬泛的文件讓 AI 難以聚焦；拆細的文件讓每個 prompt 都有清楚的執行範圍。
不需要一次把所有文件都建立起來。按照下面的順序，每完成一份就立刻有效益—— 不用等到全部完成才能感受到 vibe coding 的精準輸出。
從最高頻的元件開始：product-card.md
商品卡片幾乎出現在所有列表頁面，是使用頻率最高的元件。 第一份文件寫這個，立刻讓所有用到商品卡片的 AI prompt 都受益。 使用範本 A，預計 15 分鐘完成。
寫按鈕規格：button-spec.md
按鈕是最容易出現 token 錯誤的元件——
surface/element/brand vs surface/basic/level1，
text--icon/element/primary vs text--icon/basic/invert。
把所有按鈕種類（Primary、Secondary、Ghost、Danger）和狀態（default、hover、disabled）一次寫清楚。
再寫輸入框規格：input-spec.md
輸入框的狀態最多（default、focus、filled、error、disabled）， 也是 AI 最常生成不完整的元件。 重點說明 focus state 的 border token，以及 error state 的顏色來源。
核心頁面逐步建立
有了元件文件之後，開始寫頁面規格。建議優先順序： 首頁（視覺層次最複雜）→ 商品列表頁（元件組合）→ 商品詳情頁（狀態最多）。 每份頁面規格文件用範本 B，重點放在視覺層次架構和主要 CTA 的說明。
設計探索：每次開始前 5 分鐘寫 concept doc
每次新的設計探索——不管是改版、新功能、還是概念提案—— 都在開始前用範本 C 寫一份探索文件。 5 分鐘整理你的設計問題和方向假設，讓 AI 的第一個輸出就在正確的方向上， 避免生成一堆「方向完全不對」的結果再修正。
起步最快的方式
直接複製 Block 06 的範本，把 [placeholder] 欄位填入你的設計決策。
一份文件 15 分鐘內可以完成草稿版，然後隨著設計的推進慢慢補充。
文件不需要完美才有效——有 70% 的資訊，AI 的輸出就已經大幅提升精準度。
以下三份範本涵蓋三種文件類型。每份範本都有說明欄位的用途，以及對應的 AI Prompt 範本。
複製後存為 [元件名稱].md 或 [頁面名稱]-page.md 放在你的設計專案目錄。
範本 A · 元件規格文件
適用：商品卡片、按鈕、輸入框、標籤、任何可重複使用的 UI 元件
component-spec-template.md
# [元件名稱] 元件規格 最後更新：YYYY-MM-DD | 撰寫者：[名字] ## 元件目的 這個元件在產品中的角色是什麼？它幫助使用者完成什麼任務？ 例：商品卡片的目的是在列表頁傳遞「商品吸引力」， 讓使用者在 3 秒內判斷是否值得點進去查看詳情。 ## 元件結構（由外到內） | 層級 | 元素 | Token | 說明 | |------|-------------|-------------------------------------|------------------------| | 容器 | 卡片背景 | surface/basic/level1 | 與頁面底色分層，輕微層次感 | | 媒體 | 商品圖片 | — | 佔卡片上方 56% 高度 | | 內容 | 主標題 | text--icon/basic/primary | 最多兩行，H3 層級 | | 內容 | 副標題 | text--icon/basic/tertiary | Caption，單行 | | 功能 | 主要功能色 | [依用途：price-promote / liked / …] | 填入你的元件對應 | | 功能 | 次要 icon | text--icon/basic/secondary | | ## 互動狀態 | 狀態 | 觸發條件 | 視覺變化 | Token 說明 | |----------|-----------|----------------------|--------------------------| | Default | 正常顯示 | — | — | | Hover | 滑鼠移入 | 陰影加深，輕微上移 | box-shadow，非 token | | Pressed | 點擊 | scale(0.98) | — | | Loading | 資料載入中 | Skeleton 佔位 | surface/basic/level2 | | Empty | 無資料 | 佔位說明 + icon | text--icon/basic/tertiary | | Disabled | 功能停用 | 降低不透明度 0.4 | opacity，非 token | ## 禁止事項 # 列出這個元件最容易出現的 token 選用錯誤 - 不要用 surface/element/* 作為卡片背景（那是按鈕背景） - 不要用 text--icon/element/* 作為頁面文字（那是元件內文字） - [在這裡加入你這個元件的特定限制] ## AI Prompt 範本 ``` 根據 [檔案名稱].md 的規格，用 @tofuydesign/shp-react token 生成 [元件名稱]，需要處理：default、loading（skeleton）、 hover 三種狀態。使用 HTML + CSS custom property 輸出。 ```
範本 B · 頁面規格文件
適用：首頁、列表頁、詳情頁、任何完整的產品頁面
page-spec-template.md
# [頁面名稱] 頁面規格 最後更新：YYYY-MM-DD | 撰寫者：[名字] ## 頁面目的 這個頁面在產品流程中的定位，以及使用者核心任務。 例：商品列表頁的目的是讓使用者快速找到感興趣的商品， 核心任務是觸發點擊進入商品詳情頁。 ## 使用者核心任務（優先順序） 1. [主要任務] 2. [次要任務] 3. [低頻任務，不需要視覺強調] ## 視覺層次架構 # 從最底層開始往上列，說明每層的用途 頁面底色 surface/background/bg-grey 最底層，整頁底色 ├─ 導覽列 surface/basic/level1 固定在頂部 ├─ [區塊] surface/basic/level1 / level2 說明這個區塊的用途 └─ [區塊] surface/element/* 元件層（按鈕、標籤等） ## 頁面 Token 對應表 | 區域 | 元素 | Token | 備註 | |-------|-----------|-------------------------------|----------------------| | 頁面 | 背景 | surface/background/bg-grey | | | 導覽列 | 背景 | surface/basic/level1 | | | 導覽列 | 頁面標題 | text--icon/basic/primary | | | 導覽列 | 返回 icon | text--icon/basic/primary | | | 導覽列 | 底部分隔線 | divider--border/basic/default | | | [區域] | [元素] | [token] | [補充說明] | ## 主要 CTA # 說明這個頁面的主要行動按鈕或互動點 例：主要 CTA 是「加入購物車」按鈕，使用 surface/element/brand。 這是全頁唯一的 brand 色使用，其他區域不再出現品牌色。 ## 空狀態 / 錯誤狀態 | 情境 | 說明文字 | 顯示元素 | |---------|-----------------|--------------------------------------| | 無資料 | "目前還沒有內容" | 說明文字 + 次要行動按鈕 | | 載入失敗 | "載入失敗，請重試" | 說明文字 + 重試按鈕 | | 搜尋無結果 | "找不到相關結果" | 說明文字 + 清除搜尋連結 | # 空狀態說明文字 token：text--icon/basic/tertiary # 次要行動按鈕：surface/element/neutral-subtle ## 這個頁面的限制 # 列出這個頁面的特殊設計決策或例外 - [例：導覽列背景不跟隨 dark mode，始終使用 surface/basic/level1] - [例：這個頁面沒有主要 CTA，主要互動是點商品卡片] ## AI Prompt 範本 ``` 根據 [檔案名稱].md 的頁面規格， 用 @tofuydesign/shp-react token 生成 [頁面名稱] 的 HTML prototype。 需要包含：[主要區域列表]，以及搜尋無結果的空狀態。 ```
範本 C · 設計探索文件
適用：設計改版、新功能概念發展、視覺方向探索，任何設計早期階段
concept-doc-template.md
# [概念名稱] 設計探索 日期：YYYY-MM-DD | 目的：[一句話說明這次探索想驗證什麼] ## 設計問題 這次探索要回答的核心設計問題是什麼？ 例：在商品詳情頁，如何讓「立即購買」CTA 在不破壞品牌感的 情況下更突出——同時不讓頁面變得太「促銷感」？ ## 設計假設 # 你對解法的假設，不需要已經確定 - 假設 1：減少頁面上其他品牌色的使用，讓 CTA 更突出 - 假設 2：用留白強調 CTA 的存在感，而不是增加對比 ## 視覺調性方向 # 描述你想要的設計感，並說明對應的 token 選擇策略 # 以下三種方向選一個，或自己描述： 沉穩信任感 → surface/basic/* 系列為主，brand 色只用在單一 CTA 活潑品牌感 → theme/* 色作為裝飾背景，搭配 surface/element/brand CTA 極簡清晰感 → 大量 background/bg-grey，content 高度集中 ## 本次探索範圍 聚焦：[說明這次只看哪個部分，例：商品詳情頁的 CTA 區域] 不在這次範圍：[明確排除的部分，例：商品圖片區、規格選擇區] ## AI Prompt 範本 ``` 幫我用 @tofuydesign/shp-react token 做一個 [概念名稱] 的設計探索稿。 視覺方向：[一句話，例：沉穩品牌感，brand 色集中在 CTA] 聚焦：[主要元素 3–5 個] 不需要處理：[排除的部分] 輸出為 HTML prototype，要支援 dark mode 自動切換。 ```
範本的正確使用方式
範本的 [placeholder] 欄位是需要你填入的設計決策，不是可以留空的格式裝飾。
每一個欄位代表一個 AI 在生成時需要知道的決定。
如果某個欄位你還沒有答案，那通常意味著這個設計決策還沒做——寫文件的過程就是逼你把設計想清楚的過程。
文件都備齊之後，怎麼實際啟動？根據設計任務的性質，有兩條路徑可以走。 兩條路徑都從同一套設計規格 MD 出發，差別在於輸出的形式和交付的對象。
情境一 · 設計畫面路徑
Figma Make → 設計畫面 ＋ Design Spec
從設計規格 MD 出發，在 Figma 建置完整設計畫面。 完成設計的同時，MD 文件就是工程師的 design handoff spec。
情境二 · 原型設計路徑
Claude Code → 原型 / 設計提案 / 產品代碼
從設計規格 MD 出發，用 Claude Code 生成 HTML prototype。 可作為設計提案展示、互動原型，或直接銜接產品開發。
情境一：在 Figma 建置設計畫面，同時完成 Design Spec
這條路徑的核心洞察是：你在設計前寫的規格 MD，就是設計完成後要交給工程師的 design spec。 不需要在設計完成後再另外寫文件——MD 裡已有 token 名稱、元件結構、互動狀態， 工程師需要的都在裡面。
確認設計規格文件已備齊
確認你有：元件規格 MD（product-card.md、button-spec.md 等）
和 頁面規格 MD（product-list-page.md 等）。
CLAUDE.md 由工程師側維護，設計師直接使用不需修改。
在 Figma Make 中引用設計規格 MD 作為 prompt
打開 Figma Make，將設計規格 MD 的內容貼入作為 context，再下具體指令：
根據以下設計規格，在 Figma 中建置商品列表頁：
[貼入 product-list-page.md 的內容]
使用 @tofuydesign/shp-react token，需要包含：
· 導覽列（含搜尋 icon）
· 篩選列（含已選取標籤狀態）
· 商品卡片列表（3 × 2 格）
· 搜尋無結果的空狀態
AI 在 Figma 中建置畫面，設計師做 QA
Figma Make 根據規格建置畫面。設計師 QA 的工作： 對照 MD 的 Token 對應表確認 token 選用正確， 確認 loading、empty、hover 等所有狀態都有被處理。 修改的是設計意圖，不是顏色值。
將設計規格 MD 直接交付工程師作為 design spec
設計完成後，把 MD 文件連結給工程師。MD 已包含他需要的所有資訊：
token 名稱（不是 hex 值）、元件層次、互動狀態、禁止事項。
工程師 npm install @tofuydesign/shp-react，token 名稱和 Figma 一致，不需要對色。
這條路徑的核心優勢
傳統流程：設計 → 交設計稿 → 工程師對色 → 不一致 → 來回確認。
這條路徑：設計規格 MD = design spec = 工程師的 token 對照表。
因為 Figma 畫面和工程師代碼都用同一份 npm token，「設計稿上的顏色」和「代碼裡的顏色」是同一個 CSS 變數——不存在對色問題。
情境二：設計提案、原型，以及銜接產品開發
這條路徑用 Claude Code 直接生成 HTML prototype， 根據你在設計流程中的位置，有三種使用方式：
2A · 設計提案 & 概念說明
用設計探索文件（範本 C）快速生成視覺提案，用在設計評審或向利害關係人說明方向， 或同時生成多個方向讓對方選擇。目的是「讓人理解設計方向」，速度比精確性重要。
完成設計探索文件（5 分鐘）
用範本 C 寫出：設計問題、方向假設、視覺調性、探索範圍。 不需要完整的 token 對應表，方向和限制說清楚就夠了。
根據 concept-newcta.md 的設計探索，
用 @tofuydesign/shp-react token 生成商品詳情頁 CTA 區域的探索稿。
視覺方向：沉穩品牌感，brand 色集中在「立即購買」按鈕。
輸出 HTML 單一檔案，支援 dark mode 自動切換。
用瀏覽器直接展示給利害關係人
Claude Code 輸出可以在瀏覽器打開的 HTML 檔案。
在展示現場切換 data-theme="dark" 即時呈現 dark mode，
不需要另外製作展示素材。
要同時展示多個方向？執行多次 prompt，每次改變視覺調性的描述即可。
2B · 完整互動原型
當提案通過、需要更完整的互動原型時（用戶測試或細節設計評審）， 從頁面規格文件出發，生成包含所有狀態的完整原型。 此時精確性比速度重要，規格文件要完整。
確認頁面規格 MD 和元件規格 MD 的狀態清單完整
互動原型需要所有狀態都有明確定義。在下 prompt 前， 確認規格文件的「互動狀態」欄位沒有空格。缺少任何狀態，Claude Code 就會自己猜。
根據 product-list-page.md 和 product-card.md 的設計規格，
用 @tofuydesign/shp-react token 生成商品列表頁的完整互動原型。
需要包含：hover 狀態、loading skeleton 動畫、空狀態（搜尋無結果）。
輸出 HTML 單一檔案，支援 dark mode，加入頁面載入動畫。
在瀏覽器測試，更新規格 MD 後重新生成
直接在瀏覽器測試所有互動狀態。發現不對的地方， 先更新設計規格 MD（更新設計決策），再用相同 prompt 重新生成。 規格文件是設計決策的紀錄，修改的永遠是規格，不是 hex 值。
2C · 設計原型直接銜接產品開發
Claude Code 生成的 HTML 使用真實的
--shp-* CSS 變數，
和工程師在產品中使用的 token 完全相同。
設計師生成的原型，可以直接作為工程師的開發起點，不需要重新建 UI，只需要接資料層。
根據 product-list-page.md 和 product-card.md 的規格，
用 @tofuydesign/shp-react token 生成商品列表頁的 React 元件。
要求：TypeScript interface、CSS 使用 var(--shp-*) 不 hardcode hex、
所有狀態（default / loading skeleton / empty state）。
將生成的元件交給工程師整合
工程師收到的 React 元件已使用正確的 --shp-* token，dark mode 自動處理，
元件結構符合設計規格。他需要做的是整合進產品的路由和資料層，而不是重新建 UI。
開發成本從「建 UI + 對色 + 對設計」縮減為「接資料」。
設計師和工程師用同一份規格 MD 對齊
開發過程中有任何設計疑問，設計師和工程師都查看同一份 MD 文件—— 不是去翻 Figma 找某個不知道在哪個 frame 的顏色， 而是直接看 token 名稱和狀態說明。 設計規格 MD 是整個開發周期裡最穩定的設計語言。
兩條路徑的選擇指南
| 考量點 | 情境一 · Figma 路徑 | 情境二 · 原型路徑 |
|---|---|---|
| 主要輸出 | Figma 設計稿 + MD design spec | HTML / React 原型或元件 |
| 適合的設計階段 | 正式 UI 設計建置 | 提案、探索、快速驗證、直接開發 |
| 工程師接手方式 | 讀 MD spec，自行根據規格實作 | 直接使用或擴充 Claude Code 的輸出 |
| 設計迭代速度 | 中等（Figma 建置有時間成本） | 快（改規格 MD → 重新生成） |
| dark mode 支援 | 自動（npm token 已對齊） | 自動（CLAUDE.md 規則 + npm token） |
| 需要的文件 | 元件規格 + 頁面規格 | 探索文件（2A）/ 頁面 + 元件規格（2B / 2C） |
兩條路徑可以混用，也可以接力
常見的實際組合： 先用情境二 2A（設計探索）快速確認方向 → 方向確認後切換到情境一（Figma 建置正式稿） → 正式稿完成後用情境二 2C 生成工程師可用的 React 元件。 設計規格 MD 在整個過程中只寫一次，三個步驟都在使用它。
當你按照前面的步驟完成了 tokens.css、CLAUDE.md、設計規格 MD， 第一次執行 vibe coding 生成 HTML prototype，通常會遇到一個讓人沮喪的結果： 顏色用對了，但元件的樣子不像 Figma。 卡片的圓角不對、內距太大、字體大小不一樣……你開始手動調整、重新下 prompt、再調整—— 這個往返修正的過程，抵銷了 vibe coding 帶來的速度優勢。
設計挑戰診斷：問題出在哪一層
這個問題讓人困惑，因為你明明做了所有「正確的事」——token 正確、CLAUDE.md 完整、設計規格 MD 也寫了。 問題的根源不在你的設計決策，而在工作流程本身缺少了一個資訊層。
--shp-surface-element-brand = 品牌紫，
dark mode 自動切換。所有語意色 token，AI 完全掌握。
這不是 AI 能力的問題，也不是你 prompt 的問題。 是工作流程要求 AI 同時做兩件事——其中一件它做不好：
Task 1 · 套用正確 token
AI 做得到 ✓
顏色、語意、dark mode——AI 從 tokens.css 和 CLAUDE.md 完全知道，執行得精準。
Task 2 · 重建元件骨架
AI 只能猜 ✗
border-radius、padding、font-size——這些結構資訊在 Figma，但 token 無法傳遞。AI 每次都在猜，有時猜中，更多時候猜錯。
曾探索過的三條路：能解決問題嗎
面對這個挑戰，設計師通常會先想到幾條路。以下是對這三條路的真實評估—— 包括它們的效果，以及在這套工作流程中是否真的適用。
路徑 A · 手動補視覺規格到 spec MD
可行，但有維護負擔
從 Figma Inspect 讀取 padding、border-radius 等數值，填進設計規格 MD 的視覺結構表格。
AI 讀取後能還原元件。
問題：Figma 設計稿每次更新，你都要手動重新填一遍 MD。
元件越多，維護工作量越大。
路徑 B · Figma MCP 自動讀取
效率提升，但仍需每次執行
用 Figma MCP 工具，讓 Claude Code 直接從 Figma 元件讀取視覺規格，
自動填入 spec MD 的視覺結構區塊。比路徑 A 省時。
問題：每個元件都要跑一次，Figma 有更新就要重跑。
本質上仍是「先讀後填」的手動流程。
路徑 C · Figma Code Connect
不適用這個工作流程
Figma 官方的設計稿→代碼橋接機制，讓 Figma 元件直接對應代碼中的元件。
問題：Code Connect 需要代碼端有對應的 React 元件（<Button>、<Card>）。
你的 npm 套件是 CSS token 包，沒有預建元件——沒有對應目標，Code Connect 無從連結。
關鍵洞察：這三條路都在解決「症狀」，而不是根本問題
路徑 A 和 B 的本質是：AI 先猜元件骨架，你再給它正確數值讓它重猜。 根本問題是：AI 被要求「製作元件」，但它做不好這件事。 解法不是讓 AI 猜得更準，而是讓 AI 不需要猜——直接給它現成的元件定義。
設計工作原則：讓 AI 從「製作元件」變成「取用元件」
FIG.02 · AI 角色轉換
components.css 是從 Figma 提取的元件 CSS 定義，不是 AI 猜的——是設計師確認過的視覺真相
元件骨架只從 Figma 提取，不靠 AI 每次重建
border-radius、padding、font-size——這些是設計師做過的設計決策，存在於 Figma。 這些值應該被提取出來永久保存，讓 AI 直接使用，而不是每次從零「推算」。
顏色語意和元件骨架分層管理，各有來源
顏色語意由 tokens.css 管理；元件骨架由 components.css 管理。
兩套資訊各有清楚的來源，AI 不需要把兩件事混在一起「想像」，
輸出結果才能同時做到顏色正確和骨架正確。
元件定義做一次，之後永遠取用
一旦你為商品卡片建立了 .shp-card 的 CSS 定義，
之後每次需要商品卡片，AI 直接使用這個 class。
Figma 更新元件 → 重新提取 → 更新 components.css → 所有 prototype 自動正確。
Figma 是元件視覺的唯一真相來源
不是設計師的記憶，不是 AI 的推算，不是 spec MD 裡手填的數字。 只有 Figma 設計稿的數值，才是元件視覺的唯一真相。 工作流程的設計，要讓這個真相能夠直達 AI 的生成過程。
解決方案：擴充 Layer 1，加入 components.css
你的 npm 套件目前只包含 tokens.css（顏色語意）。
在同一個套件中新增 components.css（元件骨架 CSS），
就完成了 AI 生成精準 prototype 所需的全部資訊。
AI 不再需要猜元件的樣子，因為元件的 CSS 定義已經在那裡了。
.shp-card、
.shp-btn、
.shp-input……
每個 Figma 元件對應一個 CSS class，包含 border-radius、padding、font-size、hover 狀態。
從 Figma 提取，不是 AI 猜的。
.shp-card；
告訴 AI 生成 HTML 時直接使用這些 class，不要重新定義元件 CSS。
components.css 負責，設計規格 MD
只需說明：用哪些元件、設計意圖是什麼、需要哪些狀態。
src/components.css — 從 Figma 提取的元件骨架（示例）
/* ── 商品卡片 ─────────────────────────── */ .shp-card { background: var(--shp-surface-basic-level1); border-radius: 12px; /* 從 Figma Inspect 讀取，不是猜的 */ overflow: hidden; } .shp-card__body { padding: 16px 12px; /* 從 Figma 讀取 */ display: flex; flex-direction: column; gap: 4px; } .shp-card__title { font-size: 14px; line-height: 1.4; color: var(--shp-text-icon-basic-primary); } .shp-card:hover { box-shadow: 0 4px 12px rgba(0,0,0,0.12); } .shp-card--loading .shp-card__title { background: var(--shp-surface-basic-level2); color: transparent; border-radius: 4px; } /* ── 主要按鈕 ─────────────────────────── */ .shp-btn { padding: 12px 20px; border-radius: 8px; font-size: 14px; font-weight: 500; border: none; cursor: pointer; } .shp-btn.shp-btn--brand { background: var(--shp-surface-element-brand); color: var(--shp-text-icon-element-primary); }
前置工作流程：五步驟，一次完成，之後不再往返修正
以下是建立 components.css 並整合進工作流程的完整步驟。
這是一次性的前置投資——完成後，每次生成 prototype 都從正確的元件定義出發，
不再需要往返修正元件骨架。
確認前置工具就緒
確認 @tofuydesign/shp-react 已安裝、tokens.css 可讀取、
CLAUDE.md 存在於專案根目錄。
如果你有 Figma MCP 工具，確認它已連結 Figma 帳號（推薦用 MCP，速度快很多）。
整理元件清單，高頻優先
列出你的 prototype 需要用到的元件。不需要一次建立所有元件—— 先完成高頻元件就立刻有效益： 商品卡片 → 主要按鈕 → 次要按鈕 → 輸入框 → 導覽列，再逐步補充。
從 Figma 提取元件 CSS，建立 src/components.css
對每個元件在 Claude Code 中執行以下 prompt：
讀取 Figma 元件 [貼入元件 URL]，
提取完整視覺規格：border-radius、padding、font-size、
line-height、gap、box-shadow（含 hover 狀態）。
顏色值全部替換成對應的 --shp-* token 變數。
按照 .shp-[元件名]__[子元素] 命名規則，
輸出為 src/components.css 的 CSS class 定義，
包含 default、hover、loading、dark mode 狀態。
更新 CLAUDE.md：加入元件 class 對照表
在 CLAUDE.md 中新增以下內容，告訴 AI 哪個元件用哪個 class：
## 元件 Class 對照（src/components.css）
生成 HTML 時，使用以下預定義 class，不要自行重新定義元件 CSS：
| 元件 | Class | 狀態 modifier |
|---------|----------------------------|------------------------|
| 商品卡片 | .shp-card | .shp-card--loading |
| 主要按鈕 | .shp-btn.shp-btn--brand | :disabled |
| 次要按鈕 | .shp-btn.shp-btn--neutral | |
| 輸入框 | .shp-input | .shp-input--error |
執行完整流程測試：第一個 prototype
用設計規格 MD + 更新後的 CLAUDE.md，生成並驗證第一個 prototype：
根據 specs/components/product-card-spec.md 的設計意圖，
使用 CLAUDE.md 元件對照表中的 class（.shp-card、.shp-btn 等），
生成商品列表頁 HTML prototype。
引入 @tofuydesign/shp-react 的 tokens.css 和 components.css，
不要重新定義元件 CSS。
輸出到 prototypes/20260612-product-list/index.html
後續維護：Figma 元件視覺更新時
Figma 中某個元件的視覺有調整時：
對更新元件重新執行 Step 3 的 prompt → 更新 src/components.css 對應的 class →
執行 npm version patch + git push --follow-tags。
不需要修改每個 HTML prototype，只更新 components.css 一次，所有取用該元件的 prototype 自動正確。
完整前置環境驗證清單
Layer 1a tokens.css 已就緒，npm install 成功
Layer 1b components.css 已建立，高頻元件（卡片、按鈕）有對應 class
Layer 2 CLAUDE.md 已更新，有元件 class 對照表且明確禁止 AI 重定義元件 CSS
Layer 3 設計規格 MD 已就緒（不再需要視覺結構表格，只寫設計意圖）
測試 第一個 prototype 生成完成，對照 Figma 確認元件骨架正確
很多設計師一聽到「還要寫文件」就退縮，覺得這是工程師的工作，或者是「讓開發更麻煩」的事。 但設計規格文件的存在，不是為了讓開發更嚴謹，而是讓你的設計意圖能被執行。
不管是人工工程師還是 AI，在執行你的設計時，他們只能根據你給的資訊做決定。 資訊不夠，他們就猜。猜出來的結果，你看了不對勁，然後一個一個改。 這個來回修正的成本，遠遠超過提前寫一份 15 分鐘的規格文件。
「npm token 讓 AI 知道有哪些顏色。CLAUDE.md 讓 AI 知道顏色的用法規則。設計規格 MD 讓 AI 知道你的設計意圖。三層都有，一句 prompt 就能精準輸出。」
Vibe coding 的「vibe」不是「隨便說說」，而是「設計意圖高密度傳遞」。 當你有完整的三層知識體系，你對 AI 說一句「幫我做商品列表頁」， AI 輸出的結果，設計師看得出來是 SHP 的設計語言，工程師看得出來是可以直接上線的 token 結構。
這不是替代設計，是讓設計意圖真的可以被執行。