google-labs-code/design.md
A format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.
這是什麼
DESIGN.md 是一個讓 coding agent 讀懂「視覺識別」的格式規範：它把 YAML front matter 的設計 token 與 Markdown 的設計 rationale 放在同一個檔案裡。前者提供精確值，例如顏色、字體、圓角、間距、元件屬性；後者解釋這些值為什麼存在、應該如何被套用。README 的例子很直接：agent 讀到主色、背景色、字體與「Boston Clay」這類互動色後，就能更穩定地產生符合品牌語氣的 UI，而不是每次靠提示詞臨場猜測。
它的重點不是取代 Figma 或完整設計系統，而是提供一個 agent 可持久引用的輕量介面。規範要求 token 是標準值，文字說明則補足語境；同時也定義 section 順序、元件 token、未知內容的處理方式，以及 lint 規則，讓人與機器都能檢查同一份設計描述。
為什麼上榜
這個專案日榜新增約 1,475 stars、總星數已到 19,134，爆紅點很清楚：當越來越多人把前端交給 coding agent 生成，真正的瓶頸不再只是「能不能寫 React」，而是「能不能長期維持同一套視覺語言」。DESIGN.md 把這個問題具體化：不是再寫一段籠統的「請做得高級、簡潔」，而是把色彩、排版、元件與設計意圖結構化。
和一般 design token JSON 相比，它的差異在於 同時保留機器可讀與人類可讀。token 給 agent 硬約束，Markdown 給它設計判斷依據；CLI 又提供 lint、diff、export，讓格式不只是概念文件，而可以進到專案流程中。README 也誠實標示目前仍是 alpha，因此它更像是一個正在成形的 agent 設計系統協定，而不是已完全定型的標準。
適合誰，可以拿來做什麼
DESIGN.md 最適合正在把 AI coding agent 放進前端工作流的團隊：例如需要 agent 產生 landing page、元件樣式、後台 UI，卻又不希望每次輸出都偏離品牌的人。設計師可以用它描述 品牌語氣與 token，工程師可以把它放進 repo，agent 則能在修改 UI 時參考同一份檔案。
它也適合想把設計系統從「文件」推向「可檢查資產」的專案。README 提到的 lint 可以抓 token reference 錯誤、WCAG 對比、結構問題；diff 可以比較兩版 DESIGN.md 的 token 變動與 regression；export 則能輸出 Tailwind v3、Tailwind v4 CSS theme 或 DTCG tokens。上手門檻主要是熟悉 Markdown、YAML 與基本設計 token；若本來已有 Tailwind 或 token 流程，導入會更自然。
上手
README 提供了 npm / npx 的 CLI 用法。最小起步是建立一份 DESIGN.md，前半段寫 YAML token，後半段用 Markdown 說明 Overview、Colors、Typography、Layout、Components 等區段，然後用 linter 檢查：
npx @google/design.md lint DESIGN.md
若要安裝套件：
npm install @google/design.md
也可以比較兩個版本的設計系統：
npx @google/design.md diff DESIGN.md DESIGN-v2.md
或輸出成 Tailwind / DTCG 格式：
npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
npx @google/design.md export --format dtcg DESIGN.md > tokens.json
README 特別提醒 Windows / PowerShell 可能因為 design.md 這個 bin 名稱和 Markdown 檔案關聯衝突，建議使用 designmd alias：
npx -p @google/design.md designmd lint DESIGN.md
README 重點摘要
- DESIGN.md 由 YAML token + Markdown rationale 組成；token 是標準值，文字說明提供如何套用的設計語境。
- Token schema 涵蓋 colors、typography、rounded、spacing、components，component 屬性包含 backgroundColor、textColor、typography、rounded、padding、size、height、width。
- CLI 支援 lint、diff、export、spec；輸出預設是 JSON，方便 agent 或 CI 流程接續處理。
- export 可轉為 Tailwind v3 JSON、Tailwind v4 CSS theme、DTCG tokens.json，讓 DESIGN.md 不只是一份說明文件。
- 專案目前標示為 alpha；spec、token schema 與 CLI 仍在主動開發中，導入時要預期格式可能調整。