设计协议

一种向编码代理描述视觉标识的格式规范。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
---

## Overview

Architectural Minimalism meets Journalistic Gravitas. The UI evokes a
premium matte finish — a high-end broadsheet or contemporary gallery.

## Colors

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.

读取此文件的代理将生成一个使用 Public Sans 深墨色标题、温暖石灰石背景和 Boston Clay 行动号召按钮的 UI。

入门

根据规范验证 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, "infos": 1 }
}

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

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

{
  "tokens": {
    "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
    "typography": { "added": [], "removed": [], "modified": [] },
    "rounded": { "added": [], "removed": [], "modified": [] },
    "spacing": { "added": [], "removed": [], "modified": [] },
    "components": { "added": [], "removed": [], "modified": [] }
  },
  "findings": {
    "before": { "errors": 0, "warnings": 1, "infos": 1 },
    "after": { "errors": 0, "warnings": 1, "infos": 1 },
    "delta": { "errors": 0, "warnings": 0 }
  },
  "regression": false
}

规范

完整的 DESIGN.md 规范位于 docs/spec.md。以下是一个精简参考。

文件结构

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

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

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

令牌模式

version: <string>          # optional, current: "alpha"
name: <string>
description: <string>      # optional
omitted: <string[] | OmittedSection[]> # optional, list of sections to intentionally omit
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 颜色（十六进制、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 别名——将 npx 指向包并使用 -p，然后调用 designmd：

npx -p @google/design.md designmd lint DESIGN.md

designmd 垫片解析到相同的入口点，并在所有平台上工作一致。

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

CLI 发布为 @google/design.md on 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 后缀会与 Markdown 文件的文件关联产生混淆，导致 Windows 命令解析出错。designmd 垫片解析到同一入口点，在所有平台上工作方式一致。

// package.json
{
  "scripts": {
    "design:lint": "designmd lint DESIGN.md"
  }
}

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

如果发现错误，则退出码为 1，否则为 0。

diff

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

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

选项	类型	默认值	描述
before	位置参数	必填	”之前”版本的 DESIGN.md 路径
after	位置参数	必填	”之后”版本的 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	位置参数	必填	DESIGN.md 的路径（或 - 表示标准输入）
--format	json-tailwind | css-tailwind | tailwind | dtcg	必填	输出格式

格式	输出	描述
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

成功导出时退出码为 0（无论源文件中 lint 结果如何——如需以此作为检查条件，请先运行 lint）；--format 无效或发射器错误时退出码为 1；输入文件无法读取时退出码为 2。

spec

输出 DESIGN.md 格式规范（用于将规范上下文注入代理提示中）。

npx @google/design.md spec
npx @google/design.md spec --rules
npx @google/design.md spec --rules-only --format json

选项	类型	默认值	描述
--rules	布尔值	false	追加当前 lint 规则表
--rules-only	布尔值	false	仅输出 lint 规则表
--format	markdown | json	markdown	输出格式

Linting 规则

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

规则	严重级别	检查内容
broken-ref	错误	令牌引用（{colors.primary}）未解析到任何已定义的令牌
missing-primary	警告	定义了颜色，但不存在 primary 颜色——代理将自动生成一个
contrast-ratio	警告	组件的 backgroundColor/textColor 对低于 WCAG AA 最低要求（4.5:1）
orphaned-tokens	警告	定义了颜色令牌，但未被任何组件引用
token-summary	信息	每个部分定义了多少个令牌的摘要
missing-sections	信息	存在其他令牌时，缺少可选部分（spacing, rounded）
missing-typography	警告	定义了颜色，但不存在排版令牌——代理将使用默认字体
section-order	警告	部分出现的顺序不符合规范定义的规范顺序
unknown-key	警告	顶级 YAML 键看起来像是已知 schema 键的拼写错误（例如 colours: → colors:）；自定义扩展键保持静默
token-like-ignored	警告	未知顶级键具有类似令牌的值（例如十六进制颜色、字体族、尺寸），表明它被丢弃或拼写错误
omitted-rules	信息	验证 omitted 配置映射中是否存在未知或冗余的部分

程序化 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);   // 解析后的 DesignSystemState

设计令牌互操作性

DESIGN.md 令牌的灵感来源于 W3C Design Token Format 。export 命令可将令牌转换为其他格式：

• Tailwind v3 配置 (JSON) — npx @google/design.md export --format json-tailwind DESIGN.md — 输出一个 theme.extend JSON 对象，用于 tailwind.config.js。--format tailwind 是向后兼容的别名。
• Tailwind v4 主题 (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 版本。规范、令牌 schema 和 CLI 正在积极开发中。随着格式的成熟，预计会有变更。

免责声明

本项目不参与 Google Open Source Software Vulnerability Rewards Program。