用途：在把 DESIGN.md 作为设计系统事实来源使用前进行校验，并可将 JSON 结果解读为具体修复动作。主要能力包括单文件校验、扫描当前目录中可能的 DESIGN.md 文件、对比两个版本以发现回归。
使用方式：脚本为 Node/npx 包装器，调用 npx --yes @google/design.md，需要本机具备 Node/npm。单文件校验：node .codex/skills/design-md-validator/scripts/validate_design_md.mjs DESIGN.md；扫描目录：node .codex/skills/design-md-validator/scripts/validate_design_md.mjs --discover .；版本对比：node .codex/skills/design-md-validator/scripts/validate_design_md.mjs DESIGN.md --diff-before DESIGN.old.md。包装器不可用时可直接用 npx @google/design.md lint --format json <file>。存在 error 时返回非零；配合 --strict-warnings 时存在 warning 也返回非零。
结果处理：errors 大于 0 视为阻断，先修 error 再处理 warning；warning 应解释为设计系统质量风险而非语法错误。迁移或更新时用 --diff-before，regression: true 视为阻断，除非用户明确接受。常见修复：broken-ref 错误需补定义缺失 token 或更新引用路径；未知组件子 token 警告建议改用 backgroundColor、textColor、typography、rounded、padding、size、height、width；missing-primary 建议补充 colors.primary；missing-typography 建议至少加入含 fontFamily 与 fontSize 的排版 token；contrast-ratio 建议调整组件 backgroundColor 或 textColor 以满足普通文本 WCAG AA 4.5:1；section-order 建议按规范顺序重排 ## 分区；orphaned-tokens 建议在组件中引用或删除未用 token。
限制与已知问题：CLI 摘要字段实际为 errors、warnings、infos（复数），上游文档写作 info，直接解析 JSON 时应兼容 summary.infos ?? summary.info ?? 0；components.* 中的颜色可为 rgba(...) 字面量，不应视为 broken，而 colors.* 仅允许 #RRGGBB；npx --yes @google/design.md 首次运行会安装，冷缓存可能延迟 5-30 秒，遇到固定超时可重试一次再判定不可达。离线或沙箱环境可参考 references/spec-checklist.md 手动检查。详细 schema、规范分区顺序、允许的组件属性与 lint 规则修复配方见 references/ 下文档。