Google 开源项目 · Alpha

面向编码智能体的
视觉识别格式

DESIGN.md 将机器可读的设计令牌与人类可读的设计原理相结合，为智能体提供持久化、结构化的设计系统理解。

$ npx @google/design.md lint DESIGN.md

DESIGN.md

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
---

01 — 概述

为什么需要
DESIGN.md

建筑极简主义与新闻庄重感相结合。DESIGN.md 文件将机器可读的设计令牌（YAML 前置事项）与人类可读的设计原理（Markdown 正文）相结合。令牌提供精确值，正文解释这些值存在的原因以及如何应用它们。

双层

YAML 令牌层 + Markdown 原理层，结构化设计系统。

精确

颜色、排版、间距、圆角——所有设计决策均可量化。

互操作

导出为 Tailwind 主题或 W3C DTCG 令牌格式。

快速开始

即刻验证你的
设计系统

验证规范合规性、捕获损坏引用、检查 WCAG 对比度——所有操作均可通过 CLI 完成。

验证 DESIGN.md

检查结构正确性、对比度比率和令牌引用。

npx @google/design.md lint DESIGN.md

比较版本差异

检测令牌级别和正文回归。

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

导出令牌

输出为 Tailwind 主题或 W3C DTCG 格式。

npx @google/design.md export --format tailwind DESIGN.md

02 — 规范

文件结构

DESIGN.md 由两层构成：YAML 前置事项承载机器可读令牌，Markdown 正文承载人类可读原理。

1 概述品牌与风格

2 颜色

3 排版

4 布局布局与间距

5 高度与深度高度

6 形状

7 组件

8 注意事项

令牌模式

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>

组件令牌示例

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"

03 — 令牌类型

设计令牌一览

颜色

sRGB 十六进制格式

#1A1C1E

尺寸

数字 + 单位

48px · -0.02em · 3rem

令牌引用

引用其他令牌

{colors.primary}

排版

字体族、大小、字重

fontFamily · fontSize …

Heritage 调色板

主色

#1A1C1E · 深墨色

次色

#6C7278 · 石板灰

第三色

#B8422E · 波士顿陶土

中性色

#F7F5F2 · 温暖石灰岩

04 — CLI 参考

命令行工具

lint 验证文件结构正确性

$ 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

位置参数 · 必需 · 文件路径或 -

--format

json · 默认: json

退出代码

有错误返回 1，否则 0

diff 比较两个版本的令牌变更

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

before

位置参数 · 必需 · "之前" 路径

after

位置参数 · 必需 · "之后" 路径

退出代码

检测到回归返回 1

export 导出为 Tailwind 或 DTCG 格式

$ npx @google/design.md export --format tailwind DESIGN.md
$ npx @google/design.md export --format dtcg DESIGN.md

spec 输出格式规范（可注入智能体提示）

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

05 — Linting 规则

八条内置规则

规则	严重级别	检查内容
`broken-ref`	错误	令牌引用无法解析为任何已定义令牌
`missing-primary`	警告	颜色已定义但不存在 primary 颜色
`contrast-ratio`	警告	组件对比度低于 WCAG AA 最低标准 (4.5:1)
`orphaned-tokens`	警告	颜色令牌已定义但未被任何组件引用
`token-summary`	信息	每个章节中定义的令牌数量摘要
`missing-sections`	信息	可选章节（间距、圆角）缺失
`missing-typography`	警告	颜色已定义但不存在排版令牌
`section-order`	警告	章节出现在规范定义的规范顺序之外

程序化 API

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

06 — 消费者行为

未知内容
处理策略

DESIGN.md 消费者遇到未知内容时的标准行为定义，确保向前兼容性。

未知章节标题保留；不报错

未知颜色令牌名称如果值有效则接受

未知排版令牌名称作为有效排版接受

未知组件属性接受并警告

重复章节标题错误；拒绝文件

07 — 互操作性

设计令牌生态

受 W3C 设计令牌格式启发，DESIGN.md 令牌可无缝转换为主流格式。

Tailwind 主题

导出为 Tailwind CSS 主题配置，直接在项目中使用设计令牌。

export --format tailwind

DTCG 令牌

W3C 设计令牌格式模块标准，实现跨平台设计令牌互操作。

export --format dtcg

面向编码智能体的 视觉识别格式

为什么需要DESIGN.md

即刻验证你的设计系统