design.md 把品牌 token 變成可執行 UI 規格
4 個重點看 design.md 如何讓 coding agent 長期記住設計系統，並檢查 token、對比與回歸。
design.md 把品牌 token、設計意圖和檢查規則放進同一份檔案，讓 coding agent 能直接讀、驗、比、匯出。
讀完這 5 項，你可以判斷 design.md 是否適合當作團隊的設計系統單一來源，並決定要先用 lint、diff，還是 export 進入工作流。
| 項目 | 用途 | 重點 |
|---|---|---|
| design.md 格式 | 保存 token 與說明 | YAML front matter + Markdown |
| lint | 檢查結構與對比 | 錯誤時回傳 exit code 1 |
| diff | 比較兩版設計 | 標示 token 級回歸 |
| export | 輸出到其他系統 | 可轉 Tailwind、CSS、DTCG |
| Windows CLI | 避免執行衝突 | 建議用 designmd alias |
1. design.md 檔案格式
訂閱 AI 趨勢週報
每週精選模型發布、工具應用與深度分析，直送信箱。不定期，不騷擾。
不會寄垃圾信，隨時可取消。
design.md 的核心不是單一命令，而是一種把設計系統寫成檔案的方式。它把可機器讀取的 token 和可供人閱讀的設計說明放在一起，讓 agent 不必猜測品牌規則。
這種結構適合把顏色、字體、圓角、間距與元件語意一起保存，因為 token 是可執行的，文字則負責交代意圖。
- YAML front matter 放精確 token
- Markdown 章節寫 Overview、Colors、Typography、Components
- 可包含
{colors.primary}、{rounded.sm}這類引用
2. lint 檢查
design.md 的 lint 會檢查檔案結構、token 是否能解析，以及對比是否符合 WCAG。對 agent 來說，這比讀一段自然語言規範可靠得多，因為結果是結構化 JSON。
它也能直接看出哪個元件在深色背景上對比不足，並在有錯誤時回傳 exit code 1，方便接到 CI 或腳本。
npx @google/design.md lint DESIGN.md
cat DESIGN.md | npx @google/design.md lint -- 輸出可供腳本處理的 JSON
- 支援 stdin
- 可標出 errors、warnings、info
3. diff 比對版本
如果團隊常改品牌系統，diff 會是最實用的保護網。它比較兩份 DESIGN.md，列出新增、刪除與修改的 token，還會告訴你新版是否在錯誤或警告上退步。
這讓設計審查不只看視覺，也能看規格有沒有被悄悄改壞。像是顏色從 tertiary 改成 accent，這種變動會被清楚攔下。
- 輸入是 before / after 兩份檔案
- 輸出是 token 層級變更報告
- 可標示 regression true
4. export 匯出到別的系統
design.md 的另一個價值，是把同一份來源轉成不同前端格式。export 可以輸出 Tailwind v3 的 theme.extend、Tailwind v4 的 CSS theme block，或 DTCG 相容 JSON。
這表示設計 token 可以維持單一真源，不必每個框架手動重寫一次。對需要跨專案維護品牌一致性的團隊，這比複製貼上可靠得多。
npx @google/design.md export --format json-tailwind DESIGN.md
npx @google/design.md export --format css-tailwind DESIGN.md
npx @google/design.md export --format dtcg DESIGN.md5. Windows 與腳本細節
這個專案也處理了命令列的實務問題。在 Windows 上，直接叫 design.md 可能和 Markdown 檔案關聯衝突，所以文件建議在 package.json script 裡用 designmd alias。
這種小細節很重要，因為自動化最怕不是功能不夠，而是執行環境卡住。若安裝失敗，文件也提醒先檢查 npm registry 設定。
- 腳本中可用
designmd lint DESIGN.md - 安裝異常時檢查
npm config get registry - 套件名稱是
@google/design.md
哪種適合你
如果你要的是一份能讓 agent 長期記住設計規則、又能被 CI 驗證的規格，design.md 很適合。它特別適合已經在管 token、對比與版本回歸的團隊。
如果你只是想寫一份靜態 style guide，這套系統可能偏重；但如果你需要把品牌意圖接到實作流程，先從檔案格式和 lint 開始最穩。