---
type: article
title:  "DESIGN.md - 面向智能体描述视觉识别系统的格式规范"
date:   2026-06-28 16:59:00 +0800
tags: [translation, design.md, design, agent, google-labs, cli]
---

- [DESIGN.md](https://github.com/google-labs-code/design.md)

一种用于向编码智能体描述视觉识别系统的格式规范。DESIGN.md 让智能体对设计系统拥有持久、结构化的理解。

## 格式

DESIGN.md 文件将**机器可读的设计令牌**（YAML 前置元数据）与**人类可读的设计原理**（Markdown 正文）相结合。令牌为智能体提供精确值，正文则解释这些值为何存在以及如何使用。

```yaml
---
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
---

## 概述

建筑极简主义与新闻庄重感相遇。UI 唤起一种高级哑光质感——如同高端大报或当代画廊。

## 颜色

调色板植根于高对比度中性色与单一强调色。

- **主色 (#1A1C1E)：** 深墨色，用于标题和核心文本。
- **次色 (#6C7278)：** 精致石板灰，用于边框、说明文字、元数据。
- **强调色 (#B8422E)：** "波士顿陶土"——交互的唯一驱动色。
- **中性色 (#F7F5F2)：** 温暖石灰石底色，比纯白更柔和。
```

读取此文件的智能体将生成一个 UI：Public Sans 字体的深墨标题、温暖石灰石背景，以及波士顿陶土色的行动号召按钮。

## 快速开始

对照规范验证 DESIGN.md，捕获损坏的令牌引用、检查 WCAG 对比度比率，并输出结构化发现——所有结果均以智能体可处理的 JSON 格式呈现。

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

```json
{
  "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 }
}
```

比较设计系统的两个版本，以检测令牌级别和正文层面的回归：

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

```json
{
  "tokens": {
    "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
    "typography": { "added": [], "removed": [], "modified": [] }
  },
  "regression": false
}
```

## 规范

完整规范位于 `docs/spec.md`。以下为精简参考。

### 文件结构

DESIGN.md 文件包含两个层级：

1. **YAML 前置元数据** —— 机器可读的设计令牌，以文件顶部的 `---` 分隔符界定。
2. **Markdown 正文** —— 人类可读的设计原理，以 `##` 章节组织。

令牌是规范值。正文提供如何应用它们的上下文。

### 令牌模式

```yaml
version: <string>          # 可选，当前值："alpha"
name: <string>
description: <string>      # 可选
colors:
  <token-name>: <Color>
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>
```

### 令牌类型

| 类型 | 格式 | 示例 |
|------|------|------|
| 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 | |

### 组件令牌

组件将名称映射到一组子令牌属性：

```yaml
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）表示为具有相关键名的独立组件条目。

### 未知内容的消费行为

| 场景 | 行为 |
|------|------|
| 未知章节标题 | 保留；不报错 |
| 未知颜色令牌名 | 若值有效则接受 |
| 未知排版令牌名 | 作为有效排版接受 |
| 未知组件属性 | 接受并发出警告 |
| 重复章节标题 | 报错；拒绝该文件 |

## CLI 参考

### 安装

```bash
npm install @google/design.md
```

在 **Windows** 上，若 shell 对 `@` 特殊处理（PowerShell、某些终端），请给包名加引号：

```bash
npm install "@google/design.md"
```

或直接运行（始终从公共 npm 仓库解析）：

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

在 **Windows/PowerShell** 上，直接运行此命令可能无输出（或在 Markdown 编辑器中打开 `DESIGN.md`），因为 `design.md` 中的 `.md` 后缀与 Windows 的 Markdown 文件关联在命令解析时冲突。请改用无点的 `designmd` 别名——用 `-p` 指向包，然后调用 `designmd`：

```bash
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` 发布在 npm 上。`ENOVERSIONS` 几乎总是意味着 npm 未查询公共仓库（`.npmrc` 中自定义了 `registry=`、企业镜像未同步此包，或 `@google` 作用域的 `@google:registry` 配置错误）。

检查有效仓库：

```bash
npm config get registry
```

正常从互联网安装时应为 `https://registry.npmjs.org/`。修复配置后，若缓存了过期的 404，请用 `npm cache clean --force` 重试。

所有命令接受文件路径或 `-` 表示标准输入。输出默认为 JSON。

> **Windows 提示**：从 `package.json` 脚本（而非通过 `npx`）直接调用 CLI 时，请使用 `designmd` 别名而非 `design.md`。原始 bin 名称中的 `.md` 后缀会混淆 Windows 命令解析与 Markdown 文件关联。`designmd` shim 解析到相同的入口点，在所有平台上工作方式一致。

### `lint`

验证 DESIGN.md 文件的结构正确性。

```bash
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 | 必填 | DESIGN.md 路径（或 `-` 表示标准输入） |
| `--format` | `json` | `json` | 输出格式 |

发现错误时退出码为 `1`，否则为 `0`。

### `diff`

比较两个 DESIGN.md 文件并报告令牌级别的变更。

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

| 选项 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `before` | positional | 必填 | "之前" 的 DESIGN.md 路径 |
| `after` | positional | 必填 | "之后" 的 DESIGN.md 路径 |
| `--format` | `json` | `json` | 输出格式 |

检测到回归（"之后" 文件中更多错误或警告）时退出码为 `1`。

### `export`

将 DESIGN.md 令牌导出为其他格式。

```bash
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 | 必填 | DESIGN.md 路径（或 `-` 表示标准输入） |
| `--format` | `json-tailwind` \| `css-tailwind` \| `tailwind` \| `dtcg` | 必填 | 输出格式 |

| 格式 | 输出 | 描述 |
|------|------|------|
| `json-tailwind` | JSON | Tailwind v3 `theme.extend` 配置对象 |
| `css-tailwind` | CSS | Tailwind v4 `@theme { ... }` 块，使用 CSS 变量令牌命名空间（`--color-*`、`--font-*`、`--text-*`、`--leading-*`、`--tracking-*`、`--font-weight-*`、`--radius-*`、`--spacing-*`） |
| `tailwind` | JSON | `json-tailwind` 的向后兼容别名 |
| `dtcg` | JSON | W3C Design Tokens Format Module |

### `spec`

输出 DESIGN.md 格式规范（可用于向智能体提示注入规范上下文）。

```bash
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` | 输出格式 |

## Lint 规则

linter 对解析后的 DESIGN.md 运行九条规则。每条规则产生固定严重级别的发现。

| 规则 | 严重级别 | 检查内容 |
|------|----------|----------|
| `broken-ref` | error | 无法解析到任何已定义令牌的令牌引用（`{colors.primary}`） |
| `missing-primary` | warning | 已定义颜色但不存在 `primary` 颜色——智能体将自动生成一个 |
| `contrast-ratio` | warning | 组件 `backgroundColor`/`textColor` 对低于 WCAG AA 最低标准（4.5:1） |
| `orphaned-tokens` | warning | 已定义但未被任何组件引用的颜色令牌 |
| `token-summary` | info | 每个章节中定义的令牌数量摘要 |
| `missing-sections` | info | 当其他令牌存在时，可选章节（spacing、rounded）缺失 |
| `missing-typography` | warning | 已定义颜色但不存在排版令牌——智能体将使用默认字体 |
| `section-order` | warning | 章节出现顺序与规范定义的标准顺序不符 |
| `unknown-key` | warning | 顶层 YAML 键看起来像已知模式键的拼写错误（如 `colours:` → `colors:`）；自定义扩展键保持静默 |

### 程序化 API

linter 也可作为库使用：

```javascript
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
```

## 设计令牌互操作性

DESIGN.md 令牌受 W3C Design Token Format 启发。`export` 命令可将令牌转换为其他格式：

- **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` — 输出 CSS `@theme { ... }` 块，使用 Tailwind v4 的 CSS 变量令牌命名空间（`--color-*`、`--font-*`、`--text-*`、`--leading-*`、`--tracking-*`、`--font-weight-*`、`--radius-*`、`--spacing-*`）。
- **DTCG tokens.json**（W3C Design Tokens Format Module）— `npx @google/design.md export --format dtcg DESIGN.md`

## 状态

DESIGN.md 格式当前版本为 `alpha`。规范、令牌模式和 CLI 正在积极开发中。随着格式成熟，预计会有变更。