用 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	在末尾追加当前生效的 lint 规则表
--rules-only	boolean	false	只输出 lint 规则表
--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