如果你要在仓库中添加 DESIGN.md，请遵循 Google 规范。用文字描述你的设计系统固然有用，但不如按照实际规范并包含 frontmatter 来得更有效。https://t.co/JzlrL6pcr1

google-labs-code/design.md

来源：https://github.com/google-labs-code/design.md

DESIGN.md

一种描述视觉身份并供编码代理使用的格式规范。DESIGN.md 为代理提供对设计系统的持久、结构化理解。

格式

DESIGN.md 文件将机器可读的设计令牌（YAML front matter）与人类可读的设计原理（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)：** 暖石灰底色，比纯白色更柔和。

读取此文件的代理将生成具有深墨色 Public Sans 标题、暖石灰背景和波士顿砖红行动号召按钮的 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,
    "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 文件包含两层：

1. YAML front matter — 机器可读的设计令牌，由文件开头的 --- 分隔符界定。
2. Markdown 正文 — 人类可读的设计原理，按 ## 章节组织。

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

令牌模式

version: # 可选，当前版本："alpha"
name:
description: # 可选
colors:
  <token>:
typography:
  <token>:
rounded:
  <token>:
spacing:
  <token>:
components:
  <name>:
    <property>:

令牌类型

章节顺序

章节使用 ## 标题。可以省略，但已出现的章节必须按以下顺序排列：

组件令牌

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

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

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

该 CLI 以 @google/design.md 发布在 npm 上（https://www.npmjs.com/package/@google/design.md）。ENOVERSIONS 几乎总意味着 npm 没有查询公共注册表（.npmrc 中自定义 registry=、未同步此包的企业镜像、或 @google 范围的 @google:registry 配置错误）。请检查你的有效注册表：

npm config get registry

正常通过互联网安装时，应为 https://registry.npmjs.org。修复配置后，如果缓存了过时的 404，请先运行 npm cache clean --force。

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

Windows 提示：当直接从 package.json 脚本调用 CLI（而非通过 npx）时，请使用别名 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 -

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

diff

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

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

如果检测到退化（“之后的“文件中错误或警告更多），退出码为 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

spec

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

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

Lint 规则

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

程序化 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 设计令牌格式（https://www.designtokens.org/）。export 命令可将令牌转换为其他格式：

• Tailwind v3 配置（JSON） — npx @google/design.md export --format json-tailwind DESIGN.md — 输出适用于 tailwind.config.js 的 theme.extend JSON 对象。--format tailwind 是向后兼容的别名。
• Tailwind v4 主题（CSS） — npx @google/design.md export --format css-tailwind DESIGN.md — 输出使用 Tailwind v4 CSS 变量令牌命名空间（--color-*、--font-*、--text-*、--leading-*、--tracking-*、--font-weight-*、--radius-*、--spacing-*）的 CSS @theme { ... } 代码块。
• DTCG tokens.json（W3C 设计令牌格式模块（https://tr.designtokens.org/format/）） — npx @google/design.md export --format dtcg DESIGN.md

状态

DESIGN.md 格式目前为 alpha 版本。规范、令牌模式及 CLI 处于积极开发中。随着格式成熟，预计会有变更。

免责声明

本项目不符合 Google 开源软件漏洞奖励计划（https://bughunters.google.com/open-source-security）的资格。