DESIGN.md 進 CI：用 lint 驗證設計規範
DESIGN.md 的工程化指南：YAML 值與 Markdown 意圖的雙層結構、官方 lint/diff/export/spec 四命令、WCAG AA 驗證邊界、exit code 陷阱與完整 CI 接入範例。
過去一年，「讓 Agent 寫出風格一致的 UI」成為一個真實存在的工程問題。答案正在收斂到一個樸素的方案：用純文字檔案把設計規範寫下來，讓 Agent 在動手前先讀它。
DESIGN.md 是這個方案裡最受關注的一個。它來自 Google Labs 官方開源儲存庫（Apache-2.0 授權，目前處於 alpha 階段），並且配套一個可以獨立執行的官方 CLI：支援 lint、diff、export、spec 四個命令，最新的 v0.4.0 已在 10 月上旬被社群反覆實測。
更重要的是它的定位變化：DESIGN.md 不再只是「給 Agent 看的說明文件」，而是可以 lint、可以 diff、可以進 CI 攔截的工程製品。設計 token 的治理，第一次有了官方可執行的工具鏈。
注意：DESIGN.md 格式目前仍是 alpha，規範未來會變化；接入 CI 時請鎖定 CLI 版本。本文以 v0.4.0 的行為為準。
一、從「給 Agent 看的文件」到「可驗證的工程製品」
Agent 時代正在形成一套約定：不同職責交給不同的純文字規範檔案。
| 檔案 | 管什麼 | 核心作用 |
|---|---|---|
| CLAUDE.md | 行為 | 告訴 Agent 如何完成任務、遵循哪些流程 |
| DESIGN.md | 視覺 | 定義顏色、字型、間距、元件規則等設計意圖 |
| AGENTS.md | 協作 | 定義多個 Agent 或工具之間的協作約定 |
社群裡流傳的一句總結很準確：CLAUDE.md 管行為，DESIGN.md 管視覺，AGENTS.md 管協作。
DESIGN.md 真正的價值在於可驗證：你的顏色對比度、token 引用、章節完整性，都可以用一條命令檢查，並且把檢查接入 CI，讓不合規的設計規範無法合併進主分支。
二、DESIGN.md 格式速覽：YAML 值 + Markdown 意圖
DESIGN.md 採用雙層結構：
- YAML frontmatter：放規範值（token），例如色值、字型名、字級比例。
- Markdown 內文：放設計意圖，解釋這些值為什麼這樣定義、該如何使用。
這樣分工的意義是：機器讀 YAML 做驗證和匯出，人和 Agent 讀 Markdown 理解脈絡。
固定章節順序
官方規範要求章節按固定順序組織，lint 工具依賴這個順序做完整性檢查：
- Overview
- Colors
- Typography
- Layout
- Elevation & Depth
- Shapes
- Components
- Do's and Don'ts
寫 Prompt 型設計規範、或讓 Agent 生成 DESIGN.md 草稿時，按照這個順序組織，才能順利通過驗證。
結構示意
下面是一個最小結構示意（欄位以實際規範為準）：
---
colors:
primary: "#1a1a1a"
background: "#ffffff"
accent: "#2563eb"
typography:
base: "Inter"
scale: "1.25"
---
## Overview
這是一個文件型產品，強調可讀性與克制的強調色……
## Colors
primary 用於內文與主按鈕，accent 只用於連結與焦點態……
三、官方 CLI 四命令：lint / diff / export / spec
四個命令覆蓋了設計規範的完整生命週期：
| 命令 | 作用 |
|---|---|
lint | 按規則驗證 DESIGN.md，包含 WCAG AA 對比度檢查 |
diff | 比較兩份規範或兩個版本之間的差異 |
export | 匯出為 Tailwind config 或 W3C DTCG 設計 token |
spec | 輸出規範化說明，便於團隊對齊格式 |
本機跑一次驗證：
npx @google/design.md lint DESIGN.md
lint 的規則與 WCAG AA 邊界
lint 內建 8 條驗證規則，其中最有存在感的是對比度檢查：按 WCAG AA 的 4.5:1 標準核對文字與背景的組合。
需要明確它的邊界：lint 不檢查焦點態、不檢查語意結構、也不檢查動效。它能擋住的是「硬傷」，不能替代設計評審。
exit code 陷阱：為什麼對比度問題不會讓 CI 失敗
這是最容易踩的坑：lint 發現對比度問題時只告警、不報錯，行程仍然以 exit 0 結束。也就是說，直接把 lint 掛進 CI，對比度不合格的規範依然會通過。
要在 CI 裡嚴格攔截，需要讀取 lint 的 JSON 輸出，自行判斷並回傳非零退出碼。下面的檢查邏輯是示意（以實際輸出格式為準）：
# 示意：把 lint 結果儲存下來，出現對比度告警時手動讓 CI 失敗
npx @google/design.md lint DESIGN.md > lint-result.json
if grep -qi "contrast" lint-result.json; then
echo "對比度驗證未通過"
exit 1
fi
四、實戰：把 DESIGN.md 驗證接入 CI 管線
一個可直接參考的 GitHub Actions 設定。注意兩點：使用官方 workaround 中的 designmd 命令名，並鎖定版本：
name: design-lint
on: [pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- name: Lint DESIGN.md
run: npx -p @google/design.md@0.4.0 designmd lint DESIGN.md
嚴格模式：解析 JSON 輸出
如果團隊要求「對比度不達標必須阻塞合併」，在上面基礎上增加一步：儲存 JSON 輸出、檢查是否存在對比度告警、命中則以非零退出碼結束。思路與上一節的示意一致，關鍵是把「告警」翻譯成 CI 語意裡的「失敗」。
五、匯出到 Tailwind config 與 DTCG：設計 token 的落地路徑
lint 保證規範「寫得對」，export 解決規範「用得起來」：
- 匯出為 Tailwind config：讓前端工程直接取用設計 token，配色和字型不再散落在元件裡。
- 匯出為 W3C DTCG 格式：與更廣泛的設計工具鏈互通。
值得一提的是：DESIGN.md 的 CLI 是獨立執行的，不需要 Stitch 帳號。即使團隊不打算使用 Stitch 生成介面，也可以單獨把它當作設計規範的驗證與匯出工具。
六、故障排除：三類常見問題
| 現象 | 原因 | 處理 |
|---|---|---|
| ENOVERSIONS | 依賴或版本解析失敗 | 鎖定 CLI 版本，清理快取後重裝 |
| Windows 下無輸出 | design.md 命令與檔案關聯衝突 | 使用 workaround 命令 |
| broken-ref | 規範內引用了不存在的 token 或章節 | 按報錯行號修正引用 |
Windows / PowerShell 使用者遇到命令衝突時，改用：
npx -p @google/design.md designmd lint DESIGN.md
七、常見問題（FAQ）
Q1：不用 Stitch 帳號，能單獨使用 DESIGN.md 和這個 CLI 嗎？
可以。格式規範與 CLI 都是獨立專案，本機執行、進 CI 都不依賴 Stitch 雲端服務。
Q2：為什麼對比度問題不會讓 CI 失敗？
lint 對對比度問題只輸出告警並以 exit 0 結束；嚴格攔截需要解析 JSON 輸出並自行回傳非零退出碼。
Q3：團隊剛開始用，最小可行的做法是什麼？
兩步：在 AGENTS.md 裡加一行「任何 UI 工作前先讀 DESIGN.md」，然後給儲存庫加一條 lint 的 CI 檢查。規範內容可以邊用邊補。
八、總結
DESIGN.md 把「設計規範」從口頭約定變成了工程製品：可寫、可驗證、可匯出、可攔截。對於已經有 CI 習慣的團隊，它幾乎是零成本導入——一條命令檢查，一條流水線守住底線。
繼續閱讀：
- 想看 CLI 如何串起設計與程式碼：Stitch CLI 完全指南
- 想知道設計系統如何擷取：用 URL 擷取整套設計系統
- 想從提示詞開始學起：Stitch 提示詞教學