DESIGN.md - 面向智能体描述视觉识别系统的格式规范

DESIGN.md

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

格式

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

---
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 格式呈现。

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 }
}

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

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

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

规范

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

文件结构

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

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

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

令牌模式

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

组件令牌

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

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 参考

安装

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

检查有效仓库：

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 文件的结构正确性。

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 文件并报告令牌级别的变更。

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 令牌导出为其他格式。

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 格式规范（可用于向智能体提示注入规范上下文）。

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 也可作为库使用：

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 正在积极开发中。随着格式成熟，预计会有变更。

DESIGN.md - 面向智能体描述视觉识别系统的格式规范

格式

快速开始

规范

文件结构

令牌模式

令牌类型

章节顺序

组件令牌

未知内容的消费行为

CLI 参考

安装

npm error ENOVERSIONS（“No versions available for @google/design.md”）

lint

diff

export

spec

Lint 规则

程序化 API

设计令牌互操作性

状态

相关文章

Google DESIGN.md 规范与实践指南

Speech To Speech：使用开源模型构建本地语音智能体

Open Knowledge Format (OKF)

ConfigMap和Secret：配置应用程序

`npm error ENOVERSIONS`（“No versions available for @google/design.md”）

`lint`

`diff`

`export`

`spec`