DESIGN.md 是什麼，以及我為何密切關注它

每次我請 AI agent 在這個網站新增元件，它總會有些微妙地不符合品牌。間距比其他地方緊一點；它選了一個我從不用的藍色；圓角半徑不一致。程式碼可以運作——只是看起來不像我的網站。於是我手動修正，agent 到下一個 session 又忘記，我們再重複一次這段舞步。

DESIGN.md 正是為了解決這段舞步。 它是 Google Labs（Stitch 團隊）推出的開放檔案格式，用一份可攜式 Markdown 檔向 AI agent 描述你的整套設計系統。如果你用過 CLAUDE.md 教 agent 認識 repo 的慣例——就像我在這裡仰賴 MCP、Skills 與 Workflows 讓 Claude 開始工作——那麼這就是同一個概念套用到設計上：一份耐久的單一真相來源，讓 agent 不必每次 prompt 都重新猜測顏色和間距。

20 秒版本

接下來會談檔案實際包含什麼、唯一值得讀的獨立壓力測試，以及它是否值得在這個規模的網站採用。

DESIGN.md 檔案裡有什麼？

規格最聰明之處，在於它把兩種讀者放進同一份檔案：

1. 機器可讀的 tokens——一個結構化區塊，放著精確數值：hex 色碼、字級、間距尺度、圓角半徑，以及逐元件的樣式（也包含 hover、active、pressed 等變體，並各自有對應項目）。這是 agent 為了行動而讀的部分。
2. 人類可讀的文字——Markdown 說明這些數值為何存在、又該在何時套用。這一部分能阻止 agent 做出技術正確卻不對勁的選擇。

目前的規格大致分成九個預先定義的區段——例如 Visual Theme & Atmosphere（整體調性與品牌意圖），以及 Color Palette & Roles（以 primary、surface、accent、error 等語意角色標記的色彩）。固定區段名稱的目的，是讓 agent 知道確切該去哪裡找，而不是猜測；結構本身就是契約。

每個元件 token 都把名稱對應到一組屬性——backgroundColor、textColor、typography、rounded、padding、size——互動狀態則有自己的 keyed entries。因此，「主按鈕在 pressed 時長什麼樣子」有一個 agent 可以讀到的明確答案，而不是由它即興決定。

真正說服我的是 CLI

規格只是一種約定；工具才讓它變得真實。DESIGN.md 提供一個 npx CLI，其中有三個重要指令：

# 驗證結構、找出壞掉的 token reference，
# 並自動檢查 WCAG AA 對比率
npx @google/design.md lint
 
# 比較兩個版本，並標示 token 層級的退步
npx @google/design.md diff
 
# 直接從 tokens 產生 Tailwind theme.extend
npx @google/design.md tailwind

最後一項就是它不只是好奇心研究、而是特別適合這個網站的原因。正如我在〈打造這個網站〉寫過，這個 blog 使用 Tailwind v4 與 CSS-first 的 @theme——我的 tokens 已經手動存在 CSS 裡。design.md tailwind 能從規格產生正好這一層，這表示 DESIGN.md 可以成為 Tailwind theme 的上游來源，而不是讓兩份真相逐漸漂移。lint 的對比檢查也是很好的額外好處：無障礙退步會變成失敗的指令，而不是三週後才被我發現。

單一檔案方法有問題嗎？Atlassian 的發現

多數文章在這裡就停了，因為這套規格在抽象層面聽起來很棒。但 Atlassian 發表了一篇非常有價值的壓力測試——他們在真實設計系統中，讓 DESIGN.md 與自家的 MCP-based 設計工具較勁，取捨確實存在：

有三項發現值得內化：

• 靜態檔案每次都會載入全部內容。 因為 DESIGN.md 不是按需抓取，agent 每次任務都得吸收整套系統——相較於只拉取相關內容的 MCP 方法，多了約 92% 的 tokens。
• 可攜性迫使內容壓縮。 為了把大型設計系統塞進一份可分享檔案，他們不得不刪除「許多可能有用的細節」；使用指引一旦消失，LLM 的準確度反而更低。
• 沒有程式碼層級指引，agent 會重建而非重用。 若沒有指向既有元件實作的線索，agent 更可能從 tokens 重新實作一個元件，而不是 import 你已維護的那個——這是可維護性的陷阱。

他們的結論——我認為是正確的——是 DESIGN.md 很適合一次性的原型與面向客戶的主題設計，但在大型、成熟的正式系統中表現不如更豐富的工具。

那麼，這裡值得用嗎？

關鍵在於：Atlassian 遇到的每個限制都是大型系統的問題。 而這個網站恰好相反。

• 「多 92% tokens」的成本取決於系統大小。我的 token 集很小，全部載入也很便宜。
• 「有損壓縮」只在系統大到必須犧牲內容才能塞下時才會發生。我的系統可以完整、舒適地放進去。
• 「沒有 MCP server 可比較」這點對我反而有利：我沒有 design MCP server，因此靜態檔並不是輸了一場比較——它是目前唯一可用的結構化選項。
• 當可重用元件本來就不多時，「重建而不重用」的風險最小。

換句話說，擁有小型、穩定設計系統的個人網站，幾乎就是 DESIGN.md 的理想案例——剛好是 Atlassian 發現摩擦場景的反面。這個網站最核心的價值是「minimal and clean——優雅的簡潔」（我先前寫過的克制與微小細節），但目前這種美感是隱含的，存在我腦中並散落在各元件裡。DESIGN.md 能把它變成明確且機器可讀的內容，讓下一次 agent 編輯能預設遵循它，而不是靠猜測後讓我修正。

我還沒有在這個 repo 採用它——但這是我見過第一個值得投入心力的 agent 設計格式，而 Tailwind generator 讓遷移路徑變得明顯。等我真正接上它，會再寫一篇文章：實際檔案、lint 輸出，以及 design.md tailwind 是否真的能取代手寫的 theme。如果你正在與 AI agent 一起打造產品，而且在意成品的視覺，現在值得認真研究，而不是等它成為標準後才開始。

Sources

• 什麼是 DESIGN.md？——Stitch 文件
• Stitch 的 DESIGN.md 現已開源——blog.google
• DESIGN.md 格式參考——Stitch 文件
• 測試可攜式設計脈絡後學到什麼——Atlassian