用 CLI 驗證

@google/design.md CLI 會依照規範驗證你的設計系統、找出失效的 token 參照、檢查 WCAG 對比度，並將 token 匯出成其他格式——全部以代理程式可據以行動的結構化 JSON 呈現。

安裝

npm install @google/design.md

或不安裝、直接執行：

npx @google/design.md lint DESIGN.md

所有命令都接受檔案路徑，或以 - 代表 stdin。輸出預設為 JSON。

對 DESIGN.md 執行 lint

驗證 DESIGN.md 檔案的結構是否正確。Linter 會解析 YAML front matter、解析所有 token 參照、執行 8 條 lint 規則，並回報檢查結果。

npx @google/design.md lint DESIGN.md

輸出範例：

{
  "findings": [
    {
      "severity": "warning",
      "path": "colors",
      "message": "No 'primary' color defined. The agent will auto-generate key colors, reducing your control over the palette."
    },
    {
      "severity": "info",
      "message": "Design system defines 4 colors, 3 typography scales, 2 rounding levels."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "infos": 1 }
}

如果你是以程式化方式產生 DESIGN.md 檔案，可以從 stdin 輸入：

cat DESIGN.md | npx @google/design.md lint -

選項	型別	預設	說明
file	positional	required	DESIGN.md 的路徑（或以 - 代表 stdin）
--format	json	text	json

發現錯誤時退出碼為 1，否則為 0。

比較兩個版本

偵測兩份 DESIGN.md 檔案之間的 token 層級變更。diff 命令會回報哪些 token 被新增、移除或修改，並標示回歸情形（「after」檔案中有更多錯誤或警告）。

npx @google/design.md diff DESIGN.md DESIGN-v2.md

輸出範例：

{
  "tokens": {
    "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
    "typography": { "added": [], "removed": [], "modified": [] }
  },
  "findings": {
    "before": { "errors": 0, "warnings": 1 },
    "after": { "errors": 0, "warnings": 2 },
    "delta": { "errors": 0, "warnings": 1 }
  },
  "regression": true
}

選項	型別	預設	說明
before	positional	required	「before」DESIGN.md 的路徑
after	positional	required	「after」DESIGN.md 的路徑
--format	json	text	json

偵測到回歸時，退出碼為 1。

匯出 token

將 DESIGN.md 的 token 轉換成其他格式，以便在程式碼庫中使用。

Tailwind CSS

產生 theme.extend 設定物件：

npx @google/design.md export --format tailwind DESIGN.md

輸出是一個 JSON 物件，其中的 colors、fontFamily、fontSize、borderRadius 與 spacing 對應你的設計 token。將它放進你的 tailwind.config.js 即可。

DTCG (W3C Design Tokens)

產生符合 W3C Design Tokens Format Module 的 tokens.json：

npx @google/design.md export --format dtcg DESIGN.md

選項	型別	預設	說明
file	positional	required	DESIGN.md 的路徑
--format	tailwind	dtcg	required

檢視規範

輸出 DESIGN.md 格式規範。這對於把規範脈絡注入代理程式的提示詞很有用，讓代理程式確切知道該產出什麼結構。

npx @google/design.md spec
npx @google/design.md spec --rules
npx @google/design.md spec --rules-only --format json

選項	型別	預設	說明
--rules	boolean	false	附加使用中的 linting 規則表
--rules-only	boolean	false	僅輸出 linting 規則表
--format	markdown	json	markdown

程式化 API

Linter 也以 TypeScript 函式庫的形式提供：

import { lint } from '@google/design.md/linter';

const report = lint(markdownString);

console.log(report.findings);      // Finding[]
console.log(report.summary);       // { errors, warnings, infos }
console.log(report.designSystem);  // Resolved DesignSystemState
console.log(report.tailwindConfig); // Generated Tailwind theme