google-labs-code/design.md

# DESIGN.md 一种用于向编程智能体描述视觉标识的格式规范。DESIGN.md 为智能体提供了对设计系统持久且结构化的理解。 ## 格式说明 DESIGN.md 文件将机器可读的设计 token（YAML front matter）与人类可读的设计原理（Markdown 文本）结合在一起。Token 为智能体提供准确的值。而文本则告诉它们存在这些值的*原因*以及如何应用它们。 ``` --- name: Heritage colors: primary: "#1A1C1E" secondary: "#6C7278" tertiary: "#B8422E" neutral: "#F7F5F2" typography: h1: fontFamily: Public Sans fontSize: 3rem body-md: fontFamily: Public Sans fontSize: 1rem label-caps: fontFamily: Space Grotesk fontSize: 0.75rem rounded: sm: 4px md: 8px spacing: sm: 8px md: 16px --- ## 概览 Architectural Minimalism meets Journalistic Gravitas. The UI evokes a premium matte finish — a high-end broadsheet or contemporary gallery. ## 颜色 The palette is rooted in high-contrast neutrals and a single accent color. - **Primary (#1A1C1E):** Deep ink for headlines and core text. - **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata. - **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction. - **Neutral (#F7F5F2):** Warm limestone foundation, softer than pure white. ``` 读取此文件的智能体将生成一个 UI，其中包含使用 Public Sans 的深色墨水标题、温暖的石灰岩背景，以及 Boston Clay 行为呼吁（call-to-action）按钮。 ## 快速入门 根据规范验证 DESIGN.md，捕获损坏的 token 引用，检查 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 } } ``` 比较设计系统的两个版本，以检测 token 级别和文本的退化： ``` npx @google/design.md diff DESIGN.md DESIGN-v2.md ``` ``` { "tokens": { "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] }, "typography": { "added": [], "removed": [], "modified": [] } }, "regression": false } ``` ## 规范 完整的 DESIGN.md 规范位于 [`docs/spec.md`](docs/spec.md)。以下为简明参考。 ### 文件结构 DESIGN.md 文件包含两层： 1. **YAML front matter** —— 机器可读的设计 token，由文件顶部的 `---` 围栏分隔。 2. **Markdown 正文** —— 人类可读的设计原理，组织成 `##` 章节。 Token 是规范的值。文本为如何应用它们提供了上下文。 ### Token Schema ``` version: # optional, current: "alpha" name: description: # optional colors: : typography: : rounded: : spacing: : components: : : ``` ### Token 类型 | 类型 | 格式 | 示例 | |:-----|:-------|:--------| | Color | 任何 CSS 颜色（hex、`rgb()`、`oklch()`、命名颜色等） | `"#1A1C1E"`, `"oklch(62% 0.18 250)"` | | Dimension | 数字 + 单位（`px`, `em`, `rem`） | `48px`, `-0.02em` | | Token Reference | `{path.to.token}` | `{colors.primary}` | | Typography | 包含 `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation` 的对象 | 见上文示例 | ### 章节顺序 章节使用 `##` 标题。它们可以省略，但存在的章节必须按以下顺序出现： | # | 章节 | 别名 | |:--|:--------|:--------| | 1 | Overview | Brand & Style | | 2 | Colors | | | 3 | Typography | | | 4 | Layout | Layout & Spacing | | 5 | Elevation & Depth | Elevation | | 6 | Shapes | | | 7 | Components | | | 8 | Do's and Don'ts | | ### 组件 Token 组件将一个名称映射到一组子 token 属性： ``` components: button-primary: backgroundColor: "{colors.tertiary}" textColor: "{colors.on-tertiary}" rounded: "{rounded.sm}" padding: 12px button-primary-hover: backgroundColor: "{colors.tertiary-container}" ``` 有效的组件属性：`backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`。 变体（hover、active、pressed）以具有相关键名的单独组件条目表示。 ### 对未知内容的消费端行为 | 场景 | 行为 | |:---------|:---------| | 未知的章节标题 | 保留；不报错 | | 未知的颜色 token 名称 | 如果值有效则接受 | | 未知的排版 token 名称 | 作为有效的排版接受 | | 未知的组件属性 | 接受但发出警告 | | 重复的章节标题 | 报错；拒绝该文件 | ## CLI 参考 ### 安装 ``` npm install @google/design.md ``` 在 **Windows** 上，如果你的 shell 对 `@` 有特殊处理（PowerShell，某些终端），请给包名加上引号： ``` npm install "@google/design.md" ``` 或者直接运行（始终从公共 npm registry 解析）： ``` npx @google/design.md lint DESIGN.md ``` 在 **Windows/PowerShell** 上，这种直接形式可能不会产生输出（或者在你的 Markdown 编辑器中打开 `DESIGN.md`），因为 `design.md` bin 名称中的 `.md` 后缀在命令解析期间会与 Windows 的 Markdown 文件关联发生冲突。请改用不带点的 `designmd` 别名——使用 `-p` 将 `npx` 指向该包，然后调用 `designmd`： ``` npx -p @google/design.md designmd lint DESIGN.md ``` `designmd` shim 会解析到相同的入口点，并在所有平台上以相同方式工作。 #### `npm error ENOVERSIONS`（“No versions available for @google/design.md”） CLI 以 [`@google/design.md` on npm](https://www.npmjs.com/package/@google/design.md) 的形式发布。出现 `ENOVERSIONS` 几乎总是意味着 npm 没有在查询公共 registry（`.npmrc` 中有自定义的 `registry=`，尚未同步此包的企业镜像，或者 `@google` scope 的 `@google:registry` 配置错误）。 检查你生效的 registry： ``` npm config get registry ``` 对于从互联网进行的正常安装，它应该是 `https://registry.npmjs.org/`。修复配置后，如果缓存了过期的 404，请使用 `npm cache clean --force` 重试。 所有命令都接受文件路径或表示 stdin 的 `-`。默认输出为 JSON。 ### `lint` 验证 DESIGN.md 文件的结构正确性。 ``` npx @google/design.md lint DESIGN.md npx @google/design.md lint --format json DESIGN.md cat DESIGN.md | npx @google/design.md lint - ``` | 选项 | 类型 | 默认值 | 描述 | |:-------|:-----|:--------|:------------| | `file` | positional | required | DESIGN.md 的路径（或表示 stdin 的 `-`） | | `--format` | `json` | `json` | 输出格式 | 如果发现错误，退出代码为 `1`；否则为 `0`。 ### `diff` 比较两个 DESIGN.md 文件并报告 token 级别的更改。 ``` npx @google/design.md diff DESIGN.md DESIGN-v2.md ``` | 选项 | 类型 | 默认值 | 描述 | |:-------|:-----|:--------|:------------| | `before` | positional | required | “之前”的 DESIGN.md 路径 | | `after` | positional | required | “之后”的 DESIGN.md 路径 | | `--format` | `json` | `json` | 输出格式 | 如果检测到退化（在“之后”的文件中出现更多的错误或警告），退出代码为 `1`。 ### `export` 将 DESIGN.md token 导出为其他格式。 ``` npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json npx @google/design.md export --format css-tailwind DESIGN.md > theme.css npx @google/design.md export --format dtcg DESIGN.md > tokens.json ``` | 选项 | 类型 | 默认值 | 描述 | |:-------|:-----|:--------|:------------| | `file` | positional | required | DESIGN.md 的路径（或表示 stdin 的 `-`） | | `--format` | `json-tailwind` \| `css-tailwind` \| `tailwind` \| `dtcg` | required | 输出格式 | | 格式 | 输出 | 描述 | |:-------|:-------|:------------| | `json-tailwind` | JSON | Tailwind v3 `theme.extend` 配置对象 | | `css-tailwind` | CSS | 包含 CSS 自定义属性的 Tailwind v4 `@theme { ... }` 块 | | `tailwind` | JSON | `json-tailwind` 的别名 | | `dtcg` | JSON | W3C Design Tokens Format Module | ### `spec` 输出 DESIGN.md 格式规范（对于将规范上下文注入智能体 prompt 很有用）。 ``` 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` | 输出格式 | ## Linting 规则 linter 对解析后的 DESIGN.md 运行九条规则。每条规则都会在固定的严重性级别下生成发现结果。 | 规则 | 严重性 | 检查内容 | |:-----|:---------|:---------------| | `broken-ref` | error | 无法解析到任何已定义 token 的 token 引用（`{colors.primary}`） | | `missing-primary` | warning | 定义了颜色但不存在 `primary` 颜色——智能体将自动生成一个 | | `contrast-ratio` | warning | 低于 WCAG AA 最低标准（4.5:1）的组件 `backgroundColor`/`textColor` 组合 | | `orphaned-tokens` | warning | 定义了但从未被任何组件引用的颜色 token | | `token-summary` | info | 关于每个部分中定义了多少个 token 的摘要 | | `missing-sections` | info | 当存在其他 token 时缺失的可选部分（spacing、rounded） | | `missing-typography` | warning | 定义了颜色但不存在排版 token——智能体将使用默认字体 | | `section-order` | warning | 章节出现的顺序与规范定义的标准顺序不一致 | | `unknown-key` | warning | 顶层 YAML 键看起来像是已知 schema 键的拼写错误（例如 `colours:` → `colors:`）；自定义扩展键保持静默 | ### 编程 API linter 也可以作为库使用： ``` 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 DesignSystemState ``` ## 设计 token 互操作性 DESIGN.md token 的灵感来源于 [W3C Design Token Format](https://www.designtokens.org/)。`export` 命令可将 token 转换为其他格式： - **Tailwind v3 config (JSON)** —— `npx @google/design.md export --format json-tailwind DESIGN.md` —— 生成用于 `tailwind.config.js` 的 `theme.extend` JSON 对象。`--format tailwind` 是向后兼容的别名。 - **Tailwind v4 theme (CSS)** —— `npx @google/design.md export --format css-tailwind DESIGN.md` —— 使用 Tailwind v4 的 CSS 变量 token 命名空间（`--color-*`, `--font-*`, `--text-*`, `--leading-*`, `--tracking-*`, `--font-weight-*`, `--radius-*`, `--spacing-*`）生成 CSS `@theme { ... }` 块。 - **DTCG tokens.json** ([W3C Design Tokens Format Module](https://tr.designtokens.org/format/)) —— `npx @google/design.md export --format dtcg DESIGN.md` ## 状态 DESIGN.md 格式目前处于 `alpha` 版本。该规范、token schema 和 CLI 正在积极开发中。随着其逐渐成熟，预计该格式会发生变化。 ## 免责声明 本项目不符合参与 [Google Open Source Software Vulnerability Rewards Program](https://bughunters.google.com/open-source-security) 的条件。

标签：AI编程助手, MITM代理, 无障碍测试, 暗色界面, 自动化攻击, 设计系统, 设计规范, 防御加固