什麼是 DESIGN.md？讓 AI 代理讀懂設計系統的檔案

DESIGN.md 是 Google Stitch 開源的 AI 程式碼代理設計系統檔案規範，整理 YAML 權杖、Markdown 本文、lint·export CLI，以及在 Claude Code·Cursor 中的串接方式與限制。

SeokWoo Lee資深 iOS 軟體工程師發佈 2026年8月9日更新 2026年8月27日閱讀 6 分鐘

如果你曾讓 AI 代理製作 UI，應該遇過這種情況：昨天做的是藍色圓角按鈕，今天新工作階段卻變成紫色漸層和直角按鈕。同一個專案的每個畫面逐漸像不同品牌的 App，只好每次把「品牌色是 #2563EB、圓角是 8px……」貼進提示詞。

DESIGN.md 是針對這個問題的檔案規範。Google Labs 將自家 AI UI 設計工具 Stitch 使用的格式於 2026 年 4 月 21 日開源（Google 官方公告）。簡單說，它是**「向程式碼代理說明視覺識別的格式規格」**。在專案儲存庫放一個 Markdown 檔，讓代理每次製作 UI 時讀取它。

為什麼是檔案，而不是提示詞

把品牌規則放進提示詞的弱點在於短暫性。工作階段結束就消失，團隊成員也會各自帶著不同版本的規則。提交到儲存庫的檔案則不同。

**可進行版本控制。**設計規則的變更會留在 Git 歷史中，並成為 PR 審查對象。
**與程式碼放在一起。**代理讀取程式碼的位置也有設計規則，因此不需額外工具或連結，就能納入上下文。
**與工具無關。**它是純文字，因此 Claude Code、Cursor、Copilot 等任何代理都能讀取。

這個想法並不陌生。讓代理遵循行為規則的 CLAUDE.md·AGENTS.md 已經以相同原理運作。DESIGN.md 則將這項慣例擴展到設計系統。CLAUDE.md 說明「如何在此專案工作」，DESIGN.md 說明「產品應呈現什麼樣子」。為什麼 CLAUDE.md 應該簡短詳細討論了如何設計常駐載入的上下文。

有一點容易混淆。在規格驅動開發工作流程中，依 requirements.md → design.md → tasks.md 建立的「技術設計文件 design.md」，只是名稱相同的另一種東西。本文的 DESIGN.md 不是架構設計文件，而是設計系統檔案。

檔案結構：機器讀取的權杖＋人類閱讀的散文

根據官方規格，DESIGN.md 由兩部分組成：前方以 YAML 前置資料提供機器讀取的設計權杖，後方以 Markdown 本文記錄人類可讀的設計意圖。

---
name: My Product
version: alpha
colors:
  primary: "#2563EB"
  surface: "#FFFFFF"
  onSurface: "#0F172A"
typography:
  headline:
    fontFamily: Pretendard
    fontSize: 28px
    fontWeight: 700
spacing:
  sm: 8px
  md: 16px
rounded:
  card: 12px
components:
  button:
    backgroundColor: "{colors.primary}"
    rounded: 8px
---

## Overview
沉穩且值得信賴的金融服務。比華麗裝飾更重視資訊清晰度.

## Colors
primary僅謹慎用於行動呼籲元素。畫面中的 80%維持 surface 系列.
...

設計的核心就在這裡：權杖是規範，散文是上下文。 colors.primary: "#2563EB"這個值是代理必須照做的標準答案。「primary 僅謹慎用於行動呼籲元素」則是判斷何時何處使用它的依據。只提供色碼，代理可能到處塗用；只描述氛圍，代理又會任意選色。因此兩者被放在同一檔案中。

列出規格中的幾項規則：

前置資料中的name為必填，且至少要定義一個primary色彩。
權杖之間以路徑參照連結，例如{colors.primary}。按鈕背景色參照 primary 時，只要修改 primary 就會連鎖更新。
本文定義 8 個區段：Overview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components、Do’s and Don’ts。全部選填，但已加入的區段必須遵守此順序。
不處理的領域可在omitted欄位中連同原因註明，讓代理區分「未撰寫」和「刻意排除」。

Google Stitch 公開 DESIGN.md 的公告圖片與編輯器中開啟的檔案畫面 — 這是 Stitch 團隊公開的公告圖片。重點是它就是能在編輯器中開啟的普通 Markdown 檔案。

為什麼連驗證工具都有

公開的不只是格式規格，還有官方 CLI 工具（@google/design.md，Apache-2.0 授權）。共有四個指令。

指令	功能
`lint`	驗證檔案結構＋檢查權杖參照＋檢查 WCAG 對比度
`diff`	比較兩個版本並回報權杖層級的變更
`export`	將權杖轉換為 Tailwind 設定或 W3C DTCG 格式
`spec`	輸出完整規格——用於注入代理提示詞

lint 的有趣之處在於，它會將色彩值轉為內部 sRGB，再檢查 WCAG（Web Content Accessibility Guidelines，網頁內容無障礙指引）對比度。即使代理產生「看起來合理」的配色，只要不符合無障礙標準，就會被機械式攔截。也就是把設計規則的遵循從代理是否認真，轉成可在 CI 驗證的形式；Google 也在公開文件中特別強調這點。借用官方公告的說法，目標是讓代理不靠猜測，而是「確切知道色彩的用途，並能依 WCAG 無障礙規則驗證選擇」。

實務上，能用 export 產生 Tailwind 設定也很重要。這讓 DESIGN.md 成為單一來源，實際 CSS 設定則由它衍生。

實際上怎麼用

開始方式有兩種。

**在 Stitch 中產生。**在Stitch中完成設計後，可匯出為 DESIGN.md。先設計幾個畫面，將其視覺語言擷取成檔案，再交給程式碼代理。

**手動撰寫。**它是普通 Markdown，也能直接在編輯器中建立。若團隊已有整理好的設計權杖，可將既有權杖移到前置資料，再把設計指南中說明「為什麼」的內容移到本文區段。

建立檔案後放在儲存庫根目錄，讓代理參照。要注意的是，DESIGN.md 不像 CLAUDE.md，不會由代理自動載入工作階段。它仍是 alpha 階段的新規範，因此最好在 CLAUDE.md 或 AGENTS.md 加上一行「進行 UI 工作時先讀取 DESIGN.md 並遵循權杖」。沒有 UI 工作的工作階段不必讓整個設計系統佔用上下文；需要時再讀取，也更節省上下文成本。

DESIGN.md 的 YAML 權杖與 Markdown 本文，連結至程式碼代理和 CLI 驗證的流程圖 — 權杖與散文在同一檔案中，分流到代理端與 CLI 驗證端。

限制與展望

也有一些地方需要冷靜看待。

目前仍是 alpha。 規格的 version 值本身就是「alpha」，欄位結構仍可能變更。現在導入就必須準備好追蹤規格變更。

**代理遵循規則仍是機率性的。**即使檔案中的權杖寫得再精確，也無法保證代理完全遵循，畢竟那是 LLM 執行指令。原理就像 CLAUDE.md 的指示偶爾會被忽略。因此 lint 等確定性驗證工具才會成套提供。實務上應把「檔案指示＋CI 驗證」視為一體。

**涵蓋範圍仍窄。**目前規格以色彩、字體、間距、圓角和元件為主。動態效果、圖示集、回應式斷點等領域雖可用本文散文描述，卻沒有權杖結構。

即使如此，方向很清楚。將提供給代理的上下文從提示詞移到儲存庫中受版本控制的檔案，繼 CLAUDE.md、AGENTS.md 之後，如今也延伸到設計領域。即使工具更換，檔案仍會保留，因此也是不依賴特定代理的投資。如果你一直為了解決 UI 一致性而把品牌規則貼進提示詞，不妨先把內容移到一個 DESIGN.md。

來源與驗證

Stitch's DESIGN.md format is now open-sourceGoogle (2026-04-21) · 官方公告 · 查核 2026年8月8日依據: DESIGN.md 開源事實、公開目的（讓代理了解色彩用途並可進行 WCAG 驗證）、Stitch 的產生支援
google-labs-code/design.mdGoogle Labs · 官方文件 · 查核 2026年8月8日依據: Apache-2.0 授權、alpha 狀態，以及 @google/design.md CLI 的 lint·diff·export·spec 指令與功能
DESIGN.md SpecificationGoogle Labs · 標準或規範 · 查核 2026年8月8日依據: 前置資料欄位（name 必填、primary 色彩必填）、本文 8 個區段、權杖參照語法、omitted 欄位、WCAG 對比度檢查方式