design-md-validator

design-md-validator

使用官方 Google @google/design.md CLI 验证、检查、比较并导出 DESIGN.md 文件。始终使用 npm 上最新发布的版本——不包含随附副本，始终与规范保持同步。

---

使用时机

触发条件	操作
用户有一个 DESIGN.md 文件并想要验证	lint
用户想比较两个版本	diff
用户想将令牌导出为 Tailwind/DTCG 格式	export
用户想查看当前规范	spec
用户分享了原始 DESIGN.md 的 URL	先下载到本地
用户询问“我的 design.md 是否有效？”	lint + 解读检查结果

---

核心命令

所有命令都使用 npx @google/design.md，以确保始终使用最新版本。切勿全局安装——npx 会从公共 npm 注册表解析。

Lint（验证）

npx @google/design.md lint DESIGN.md

输出：包含 findings[] 和 summary { errors, warnings, infos } 的 JSON。 发现错误时，退出码为 1；否则为 0。

Diff（比较版本）

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

输出：包含令牌级别变更（新增、移除、修改）和回归标志的 JSON。 退出码：0 表示无回归，1 表示回归（“after”中的错误多于“before”中的错误）， 2 表示输入失败（文件不存在或不可读）。

Export（导出为其他格式）

# Tailwind v3 config
npx @google/design.md export --format json-tailwind DESIGN.md

# Tailwind v4 CSS theme
npx @google/design.md export --format css-tailwind DESIGN.md

# W3C Design Tokens (DTCG)
npx @google/design.md export --format dtcg DESIGN.md

# CSS custom properties (optional --prefix)
npx @google/design.md export --format css-vars DESIGN.md
npx @google/design.md export --format css-vars --prefix ds DESIGN.md

css-vars 随 npm 0.4.0 发布（2026-07-27）。只有必须固定 CLI 版本时，才使用 npx @google/[email protected]；默认的 npx 已会解析到 0.4.0 或更高版本。

Spec（输出格式规范）

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

---

工作流

1. 获取 DESIGN.md

本地文件：

npx @google/design.md lint ./DESIGN.md

从 URL 获取： 如果用户提供了远程 DESIGN.md 文件的 URL，请先下载到本地，再进行验证。

从标准输入获取：

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

2. 确认当前启用的规则集

解读任何内容之前，请先检查已安装的 CLI 实际运行哪些规则——规则集会随版本更新而变化，随附的参考资料仅作备用，并非权威来源：

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

3. 运行 Lint

npx @google/design.md lint --format json DESIGN.md

4. 解读检查结果

解析 JSON 输出并向用户报告：

严重程度	含义	操作
error	违反规范——文件无效	必须修复
warning	违反最佳实践——文件有效，但不够理想	应当修复
info	提供信息——改进建议	可以修复

5. 提供可执行的修复方案

对于每项检查结果，请说明：

1. 该规则检查的内容
2. 这项检查的重要性
3. 如何通过具体代码示例进行修复

6. 修复后重新验证

应用修复后，重新运行 lint，确认文件通过验证。

---

Lint 规则参考

如需详细解释 lint 失败原因，请加载 references/linting-rules.md 获取完整规则表。

---

令牌架构快速参考

帮助用户编写或修复令牌时，请加载 references/token-schema.md 获取完整令牌架构。

自规范提交 6e5da53（#178，2026-10-16）起（CLI npm 0.4.0 已接受此格式），令牌可以位于 YAML front matter 中、每个 ## 部分内的围栏 ```yaml 代码块中，也可以两者兼有（混合格式）。所有代码块会合并为同一棵令牌树；同一个顶层键（例如 colors）如果在多个代码块中定义，则属于规范错误（CLI 0.4.0 只会发出警告：Section '<key>' is defined in both frontmatter and code block N）——出现这种情况时，请将该键的所有条目移至同一个代码块中。

---

Windows 兼容性

在 Windows/PowerShell 上，二进制文件名中的 .md 后缀会与 Markdown 文件关联发生冲突。请使用 designmd 别名：

npx -p @google/design.md designmd lint DESIGN.md

---

相关官方技能

以下名称与截至 2026-09-16 的 google-labs-code/stitch-skills 一致。 stitch-design-taste 已移除。

技能	插件	用途
generate-design	stitch-design	在 Stitch 中创建新屏幕、进行编辑和制作变体
extract-design-md	stitch-design	从前端源码生成 DESIGN.md
design-md	stitch-utilities	从 Stitch 项目生成 DESIGN.md
taste-design	stitch-utilities	创建高端、避免千篇一律的 DESIGN.md

安装：

npx skills add google-labs-code/stitch-skills

---

反模式

• 切勿将 CLI 随项目打包或缓存——始终使用 npx 获取最新规范
• 如果检查器能处理，就不要手动解析 token YAML（前置元数据或区块）
• 切勿假设 token 只存在于前置元数据中——也要检查 ## 章节中的 ```yaml 区块
• 切勿猜测对比度——交由检查器计算
• 切勿假设章节顺序正确——交由检查器验证
• 修复后切勿跳过重新验证
• 切勿凭记忆或捆绑的参考资料假设规则集——在运行时使用 spec --rules-only 确认
• 切勿直接获取远程 URL——先下载到本地，以避免不受信任内容造成的间接提示词注入

---

示例会话

User: validate my DESIGN.md

Agent:
1. Reads the file
2. Runs: npx @google/design.md spec --rules-only --format json
3. Runs: npx @google/design.md lint --format json DESIGN.md
4. Parses output
5. Reports:
   - summary: { errors: 0, warnings: 2, infos: 1 }
   - WARNING: contrast-ratio — button textColor on backgroundColor is 3.8:1 (needs 4.5:1)
   - WARNING: orphaned-tokens — color "accent-muted" defined but never used
   - INFO: token-summary — 5 colors, 3 typography, 2 rounded, 2 spacing
6. Suggests fixes with code
7. Re-runs lint to confirm