WaveSpeedAI
← 部落格

什麼是 design.md？給程式碼代理的設計系統規範

design.md 為程式碼代理提供了一種理解設計系統的結構化方式，說明這對 AI 生成的 UI 工作流程為何至關重要。

By Dora 3 min read
什麼是 design.md？給程式碼代理的設計系統規範

我是 Dora。上週我請 Claude Code 為一個側專案新增三個畫面。到了第二個畫面，按鈕圓角開始偏移、標題字體悄悄改變，而「次要」灰色也換成了另一種灰。提示結構相同、模型相同、對話相同。輸出就是不在乎之前發生過什麼。

這正是編碼代理用的 design.md 想要消除的摩擦。這是一個純 Markdown 檔案，以 AI 代理每次生成 UI 時都能讀取的形式保存你的設計系統——不是一次性提示，而是持久的上下文。Stitch 讀它、Claude Code 讀它、Cursor 讀它，任何會從儲存庫根目錄讀取上下文檔案的工具也都讀它。

design.md 是什麼，為什麼 Google Labs 發佈了它

檔案格式與設計系統角色

DESIGN.md 檔案是兩層堆疊成一份文件。頂部是 YAML 前置資料——顏色、字體排版、間距、圓角、元件——以結構化 token 的形式撰寫。下方是說明這些 token 用途及使用方式的 Markdown 散文。Token 給代理精確數值，散文告訴它這些數值存在的原因。

以下是前置資料的大致樣貌，取自 GitHub 上的官方 DESIGN.md 規範：

yaml

---
version: alpha
name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
rounded:
  sm: 4px
spacing:
  sm: 8px
  md: 16px
---

下方依序是 ## Overview、## Colors、## Typography 等純 Markdown 章節。章節順序固定——Overview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components、Do’s and Don’ts。章節可以省略，但出現的章節必須按此順序排列。重複的章節標題屬於錯誤，會導致檔案被拒絕。

Token 參照語法來自 W3C Design Tokens Format Module——大括號路徑如 {colors.primary}。參照必須指向原始值（而非群組），但在 components 章節內，允許對字體排版 token 進行複合參照。目前規範中，顏色值僅限 SRGB 十六進位。Display P3 和 Oklch——兩者都受 W3C DTCG 2025.10 穩定規範支援——目前尚未受 DESIGN.md 支援，儲存庫以 version: alpha 標記公開說明了這一點。如果你維護寬色域 token，這一點值得注意。

該格式附帶一個 CLI——npm 上的 @google/design.md。npx @google/design.md lint 對解析後的檔案執行七條規則。我最常碰到的兩條：broken-ref（錯誤嚴重性）捕捉無法解析的 token 參照；contrast-ratio（警告）根據 WCAG AA 的 4.5:1 最低標準檢查元件的 backgroundColor/textColor 配對。另外三條——missing-primary、orphaned-tokens 和結構規則——能發現大多數團隊在編輯檔案一週內就會引入的問題。CLI 還提供 diff（版本之間的 token 層級回歸）和 export（Tailwind v3 設定、Tailwind v4 @theme CSS 或 W3C DTCG JSON）功能。

為什麼持久的視覺上下文對編碼代理如此重要

問題很簡單。生成 UI 的代理對你的設計系統毫無記憶，除非你給它結構化的內容可以讀取。你可以在提示中描述你的調色板，取得一個按鈕，然後請它生成一張卡片，結果看著間距邏輯重置。模型不是不擅長寫程式碼，它只是沒有錨點。

design.md 就是錨點。Stitch 在每次生成請求時都會將它作為上下文傳入。Claude Code 和 Cursor 讀取它的方式，與讀取 CLAUDE.md 或 AGENTS.md 相同——一個在儲存庫根目錄供代理在回答前讀取的檔案。Google 在開源公告中的說法是，這讓代理「能確切知道一種顏色的用途」，而不是從提示中猜測意圖。

我在兩個專案中都測試了這一點。流程如下：在根目錄放入 DESIGN.md，重新生成我之前已出現偏移的五個畫面（首頁、定價、註冊、儀表板、設定），然後對照前置資料計算 token 違規次數。有了該檔案，Claude Code 在 5/5 個畫面中都使用了精確的 primary 和 tertiary 十六進位值，以及聲明的 rounded.sm。Cursor 產出 4/5——儀表板在卡片上持續將 rounded.sm（4px）覆蓋為 rounded.md（8px），而 DESIGN.md 的散文並未明確禁止這一點。在「Do’s and Don’ts」新增一行「卡片圓角使用 rounded.sm，絕不使用 rounded.md」——下次重新生成時就修好了。

它真正解決的 AI UI 生成問題

跨畫面與迭代的一致性

先前對話中出問題的不是某個畫面的品質。每個單獨的畫面看起來都很好。第二個畫面不知道第一個畫面做了什麼決定。每次生成都從對「你的品牌」略有不同的詮釋開始。

這正是 design.md 針對的失敗模式。不是「讓 UI 更漂亮」——而是讓它在跨代之間成為相同的 UI。Token 具有規範性。當前置資料寫著 tertiary: "#B8422E" 時，代理沒有空間將其詮釋為「暖橘色」。要麼是那個十六進位值，要麼就是錯的，lint 會這樣告訴你。

對於高頻率工作流程——每週生成五、十、二十個畫面並有人維護它們——這比首次輸出品質更重要。大規模下每個畫面一個不一致，就會變成一項清理工作。編碼代理的設計 token，在一個檔案中定義一次，在問題開始之前就消滅了那項清理工作。

為什麼散文加 token 比單獨使用 token 更強

我差點忽略這部分。當十六進位值已經在 YAML 中時，為什麼還要寫「Boston Clay 是互動的唯一驅動力」這樣的段落？

因為代理使用散文來做 token 無法涵蓋的判斷。Token 說 tertiary 是 #B8422E。散文說這個顏色僅用於互動——不用於裝飾性重點，不用於標題。當提示模糊時（「新增通知徽章」），散文決定徽章是使用互動顏色還是中性色。在上面的 Cursor 執行中，缺少的散文限制正是儀表板出現偏移的原因。

同樣的邏輯適用於 Do’s and Don’ts——「卡片上絕不使用投影」或「按鈕標籤始終使用句首大寫」等明確的護欄。負面約束具有純 token 無法表達的重量。這是給代理的設計規範，不是 CSS 檔案。

該格式不受限於 Stitch。規範採用 Apache 2.0 授權，CLI 在 npm 上，DTCG 匯出意味著 token 可以流入任何讀取 W3C 標準的工具，社群已經在行動。VoltAgent 的品牌啟發 DESIGN.md 檔案精選集 awesome-design-md 在發佈數週內突破了 71,000 個 GitHub 星標，design-md 的 GitHub 主題現在列出了完全來自 Google 以外的提取工具、Chrome 擴充功能和配套的 SKILL.md 登錄庫。採用率是判斷一個格式是否真實存在的指標。

誰應該關注 design.md

誠實地說明邊界，因為 design.md 並非普遍適用。

以下情況值得使用：

  • 你至少每週使用編碼代理生成 UI，跨越一個以上的畫面
  • 你有一個設計系統——哪怕很精簡——想要在各代生成中保持一致
  • 你使用多個代理或工具，希望在所有工具中使用相同的品牌上下文
  • 你厭倦了在每個提示中貼上「記住我們的調色板是 X、Y、Z」

以下情況不值得使用：

  • 你生成一次性原型並丟棄它們
  • 你的「設計系統」就是代理這次生成的任何東西
  • 你處於以 Figma 為主導、透過 Style Dictionary 或類似工具擁有成熟 DTCG 管道的工作流程中——design.md 比你擁有的更輕量，你會是在降級
  • 你今天就需要寬色域顏色（Display P3、Oklch）——目前的 alpha 規範僅支援 SRGB

對於與其他 AI 工作流程檔案（CLAUDE.md、AGENTS.md）並行運行 design.md 的 AI 原生產品團隊，它嵌入得很順暢。每個關注點一個 Markdown 檔案。無需建置步驟。無需對抗 JSON 結構描述。嘗試它的成本是在儲存庫根目錄放一個檔案並執行一條 lint 指令。

對於正在建置代理驅動生成介面的平台——包括在多個模型間路由請求、需要品牌上下文在每次調用中保持一致的統一 AI 生成層——design.md 是生態系統中最接近品牌與代理之間可攜式契約的東西。根據 Google Labs 公告，該格式的設計初衷就是可在各工具之間匯出和匯入。可攜性才是重點。

常見問題

design.md 的用途是什麼？

這是一個 Markdown 檔案，為編碼代理提供關於設計系統的持久上下文——顏色、字體排版、間距、元件，以及說明如何應用它們的散文。代理每次生成 UI 時都會讀取它，因此輸出在跨畫面和對話中保持一致，無需你在每個提示中重新說明品牌規則。

它只適用於 Google Stitch 工作流程嗎？

不。該格式起源於 Stitch，但 Google 以 Apache 2.0 授權開源了規範。任何讀取上下文檔案的 AI 工具——Claude Code、Cursor、GitHub Copilot、Antigravity、Gemini CLI——都可以使用它。CLI 可匯出為 Tailwind 設定、CSS 變數或 W3C DTCG JSON，因此 token 也能流入非代理工具。

為什麼 AI 生成的 UI 需要設計系統檔案？

因為模型在各代生成之間對你的品牌毫無記憶。沒有結構化的 AI 設計系統檔案，每個提示都從頭重新詮釋你的設計語言。有了它，token 作為硬性約束，散文涵蓋判斷性決策。差異在大規模使用時最為明顯——使用 design.md 生成的五個畫面保持風格一致；沒有它生成的五個畫面則會出現偏移。

哪些團隊應該最先嘗試？

已經每週使用編碼代理生成 UI 的團隊。使用 Claude Code 或 Cursor 的獨立開發者和小型產品團隊能獲得最快的回報——放入檔案、重新生成、看到一致性。擁有成熟 Figma + Style Dictionary 管道的大型組織應將 design.md 視為補充而非替代：用它為代理提供現有系統的可消化子集。

結論

design.md 不是革命性的檔案格式。它是一個頂部帶有 YAML 的 Markdown 檔案。這正是重點——LLM 讀得最好的格式，是它們訓練最多的格式，那就是純文字。

它真正做到的，是將問題從「我如何在這個提示中描述我的設計」轉移到「我的設計存在哪裡，讓每個代理都能讀取它」。一個檔案、一個位置，每個讀取它的工具都得到相同的答案。少一件需要重新說明的事。聽起來微不足道，累積起來效果顯著。

我已經在兩個專案中使用它一週了。它有效。長期來看——團隊是否會像維護真實設計系統一樣嚴格維護這些檔案，或者它們是否會像 README 一樣腐爛——還有待驗證。在你自己的專案上試試看，那會比我說的任何話都更能說明問題。

過往文章：

分享