DESIGN.md：为编码代理提供设计系统持久结构化理解，支持多格式转换

1. 简介DESIGN.md 为编码代理提供了对设计系统持久且结构化的理解。该文件将机器可读的设计标记YAML 前置元数据与人类可读的设计原理Markdown 文本相结合。标记为代理提供精确的值而文本则解释这些值存在的原因以及如何应用它们。2. 文件示例以下是一个 DESIGN.md 文件的示例---name: Heritagecolors:primary: #1A1C1Esecondary: #6C7278tertiary: #B8422Eneutral: #F7F5F2typography:h1:fontFamily: Public SansfontSize: 3rembody-md:fontFamily: Public SansfontSize: 1remlabel-caps:fontFamily: Space GroteskfontSize: 0.75remrounded:sm: 4pxmd: 8pxspacing:sm: 8pxmd: 16px---3. 概述建筑简约风格与新闻严肃性相融合。用户界面营造出高级哑光质感犹如高端报纸或现代画廊。4. 颜色调色板基于高对比度的中性色和单一强调色。- 主色 (#1A1C1E)用于标题和核心文本的深墨色。- 次色 (#6C7278)用于边框、标题和元数据的精致石板色。- 第三色 (#B8422E)“波士顿陶土色”唯一用于交互的颜色。- 中性色 (#F7F5F2)温暖的石灰石底色比纯白色更柔和。读取此文件的代理将生成一个用户界面其中标题使用 Public Sans 字体呈现深墨色背景为温暖的石灰石色行动呼吁按钮为波士顿陶土色。5. 快速开始5.1 验证文件根据规范验证 DESIGN.md 文件捕获损坏的标记引用检查 WCAG 对比度并以结构化的 JSON 形式呈现结构检查结果供代理使用。npx google/design.md lint DESIGN.md示例输出{findings: [{severity: warning,path: components.button-primary,message: textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA.}],summary: {errors: 0,warnings: 1,info: 1}}5.2 比较版本比较设计系统的两个版本以检测标记级和文本的回归。npx google/design.md diff DESIGN.md DESIGN-v2.md示例输出{tokens: {colors: {added: [accent],removed: [],modified: [tertiary]},typography: {added: [],removed: [],modified: []}},regression: false}6. 规范6.1 文件结构DESIGN.md 文件有两层YAML 前置元数据是机器可读的设计标记位于文件顶部由 --- 分隔Markdown 正文是人类可读的设计原理组织成 ## 标题的部分。标记是规范性的值文本则为如何应用这些值提供上下文。6.2 标记模式version: # 可选当前为 alphaname:description: # 可选colors::typography::rounded::spacing::components:::6.3 标记类型| 类型 | 格式 | 示例 || ---- | ---- | ---- || 颜色 | 任何 CSS 颜色十六进制、rgb()、oklch()、命名等 | #1A1C1E, oklch(62% 0.18 250) || 尺寸 | 数字 单位px、em、rem | 48px, -0.02em || 标记引用 | {path.to.token} | {colors.primary} || 排版 | 包含 fontFamily、fontSize、fontWeight、lineHeight、letterSpacing、fontFeature、fontVariation 的对象 | 见上文示例 |6.4 章节顺序章节使用 ## 标题可以省略但存在的章节必须按以下顺序出现1. 概述品牌与风格2. 颜色3. 排版4. 布局布局与间距5. 高度与深度高度6. 形状7. 组件8. 注意事项6.5 组件标记组件将名称映射到一组子标记属性components:button-primary:backgroundColor: {colors.tertiary}textColor: {colors.on-tertiary}rounded: {rounded.sm}padding: 12pxbutton-primary-hover:backgroundColor: {colors.tertiary-container}有效组件属性包括backgroundColor、textColor、typography、rounded、padding、size、height、width。变体悬停、激活、按下以相关键名的单独组件条目表示。6.6 未知内容的处理行为| 场景 | 行为 || ---- | ---- || 未知章节标题 | 保留不报错 || 未知颜色标记名称 | 如果值有效则接受 || 未知排版标记名称 | 视为有效排版 || 未知组件属性 | 接受并发出警告 || 重复章节标题 | 报错拒绝文件 |7. CLI 参考7.1 安装npm install google/design.md在 Windows 上如果你的 shell 对 有特殊处理如 PowerShell 或某些终端请引用包名npm install google/design.md或者直接运行始终从公共 npm 注册表解析npx google/design.md lint DESIGN.md在 Windows/PowerShell 上直接运行可能无输出或在 Markdown 编辑器中打开 DESIGN.md因为 design.md 二进制文件名中的 .md 后缀在命令解析时与 Windows 的 Markdown 文件关联冲突。可使用无点的 designmd 别名npx -p google/design.md designmd lint DESIGN.mddesignmd 代理指向相同的入口点在所有平台上工作方式相同。如果遇到 npm error ENOVERSIONS (“No versions available for google/design.md”)这通常意味着 npm 未查询公共注册表.npmrc 中的自定义 registry、未同步此包的企业镜像或 google 作用域的错误配置 google:registry。检查有效注册表npm config get registry正常从互联网安装时应为 https://registry.npmjs.org/。修复配置后如果缓存了过时的 404可使用 npm cache clean --force 重试。所有命令接受文件路径或 - 表示标准输入输出默认格式为 JSON。Windows 提示从 package.json 脚本直接调用 CLI 时使用 designmd 别名而非 design.md原二进制文件名中的 .md 后缀会使 Windows 命令解析与 Markdown 文件关联混淆。{scripts: {design:lint: designmd lint DESIGN.md}}7.2 命令- lint验证 DESIGN.md 文件的结构正确性。npx google/design.md lint DESIGN.mdnpx google/design.md lint --format json DESIGN.mdcat DESIGN.md | npx google/design.md lint -| 选项 | 类型 | 默认值 | 描述 || ---- | ---- | ---- | ---- || file | 位置参数 | 必需 | DESIGN.md 文件的路径或 - 表示标准输入 || --format | 选项参数 | json | 输出格式 |如果发现错误退出代码为 1否则为 0。- diff比较两个 DESIGN.md 文件并报告标记级别的变化。npx google/design.md diff DESIGN.md DESIGN-v2.md| 选项 | 类型 | 默认值 | 描述 || ---- | ---- | ---- | ---- || before | 位置参数 | 必需 | “之前”的 DESIGN.md 文件路径 || after | 位置参数 | 必需 | “之后”的 DESIGN.md 文件路径 || --format | 选项参数 | json | 输出格式 |如果检测到回归“之后”的文件中错误或警告更多退出代码为 1。- export将 DESIGN.md 标记导出为其他格式。npx google/design.md export --format json-tailwind DESIGN.md tailwind.theme.jsonnpx google/design.md export --format css-tailwind DESIGN.md theme.cssnpx google/design.md export --format dtcg DESIGN.md tokens.json| 选项 | 类型 | 默认值 | 描述 || ---- | ---- | ---- | ---- || file | 位置参数 | 必需 | DESIGN.md 文件的路径或 - 表示标准输入 || --format | 选项参数 | 必需 | 输出格式可选值json-tailwind、css-tailwind、tailwind、dtcg || 格式 | 输出 | 描述 || ---- | ---- | ---- || json-tailwind | JSON | Tailwind v3 theme.extend 配置对象 || css-tailwind | CSS | Tailwind v4 theme { ... } 块使用 Tailwind v4 的 CSS 变量标记命名空间 || tailwind | JSON | json-tailwind 的别名 || dtcg | JSON | W3C Design Tokens Format Module 规范 |- spec输出 DESIGN.md 格式规范有助于将规范上下文注入代理提示。npx google/design.md specnpx google/design.md spec --rulesnpx google/design.md spec --rules-only --format json| 选项 | 类型 | 默认值 | 描述 || ---- | ---- | ---- | ---- || --rules | 布尔值 | false | 附加活动的 linting 规则表 || --rules-only | 布尔值 | false | 仅输出 linting 规则表 || --format | 选项参数 | markdown | 输出格式可选值markdown、json |8. Linting 规则linter 对解析后的 DESIGN.md 运行九条规则每条规则在固定的严重级别上生成检查结果。| 规则 | 严重级别 | 检查内容 || ---- | ---- | ---- || broken-ref | 错误 | 无法解析到任何已定义标记的标记引用如 {colors.primary} || missing-primary | 警告 | 定义了颜色但没有主色代理将自动生成一个 || contrast-ratio | 警告 | 组件的背景颜色/文本颜色对低于 WCAG AA 最低对比度4.5:1 || orphaned-tokens | 警告 | 定义了颜色标记但从未被任何组件标记引用 || token-summary | 信息 | 每个部分定义的标记数量摘要 || missing-sections | 信息 | 当存在其他标记时可选部分间距、圆角缺失 || missing-typography | 警告 | 定义了颜色但没有排版标记代理将使用默认字体 || section-order | 警告 | 部分的出现顺序不符合规范定义的标准顺序 || unknown-key | 警告 | 顶级 YAML 键看起来像是已知模式键的拼写错误如 colours: → colors:自定义扩展键保持静默 |9. 编程 APIlinter 也可作为库使用import { lint } from google/design.md/linter;const report lint(markdownString);console.log(report.findings); // Finding[]console.log(report.summary); // { errors, warnings, info }console.log(report.designSystem); // Parsed DesignSystemState10. 设计标记互操作性DESIGN.md 标记受 W3C Design Token Format 启发export 命令可将标记转换为其他格式- Tailwind v3 配置JSONnpx google/design.md export --format json-tailwind DESIGN.md为 tailwind.config.js 生成 theme.extend JSON 对象--format tailwind 是向后兼容的别名。- Tailwind v4 主题CSSnpx google/design.md export --format css-tailwind DESIGN.md生成一个使用 Tailwind v4 CSS 变量标记命名空间的 CSS theme { ... } 块。- DTCG tokens.jsonW3C Design Tokens Format Modulenpx google/design.md export --format dtcg DESIGN.md11. 状态DESIGN.md 格式目前处于 alpha 版本规范、标记模式和 CLI 正在积极开发中随着格式的成熟预计会有变化。12. 免责声明此项目不符合 Google 开源软件漏洞奖励计划的条件。