DESIGN.md：Google开源的AI编码智能体设计规范

一、什么是 DESIGN.md

DESIGN.md 是 Google Labs 推出、面向AI编码智能体（Coding Agent）的标准化设计系统描述文件格式，配套开源工具包 @google/design.md 实现全流程自动化处理，仓库开源协议为Apache-2.0，项目语言以TypeScript为主（占95.7%）。

该格式核心解决行业痛点：传统设计Token仅存储数值，缺少设计意图描述，AI生成界面时无法理解规范背后的使用逻辑，频繁出现视觉风格错乱、色彩对比度不达标、组件样式混乱等问题。

单个DESIGN.md文件分为双层结构，兼顾机器解析与人类阅读：

1. YAML前置元数据：文件顶部---包裹，存储标准化设计Token（色彩、字体、圆角、间距、组件样式），供程序、AI自动读取；

2. Markdown正文：二级标题分段撰写设计理念、使用约束、使用场景，人工可快速读懂设计规范，同时为AI提供决策上下文。

二、功能特色

1. 人机双可读单文件载体
   一份文件同时承载机器可解析数值与人类设计思路，无需拆分设计文档、Token配置两份文件，仓库、AI工具、前端项目可统一托管。

2. 原生适配AI编码智能体
   专门为Gemini、Claude Code、Cursor等代码AI设计，AI读取文件后可自动遵循品牌规范生成界面，统一视觉输出标准。

3. 完整CLI自动化工具链
   内置lint、diff、export、spec四大核心命令，覆盖校验、版本对比、格式导出、规范查询全流程，支持CI流水线集成。

4. WCAG无障碍自动校验
   内置对比度检测规则，自动识别文字与背景色对比度是否满足WCAG AA 4.5:1标准，输出结构化警告。

5. 多格式Token导出能力
   一键将设计令牌转换为Tailwind v3配置、Tailwind v4 CSS主题变量、W3C DTCG标准JSON，无缝对接前端工程。

6. 标准化Token引用体系
   支持{分组.令牌名}跨引用语法，组件可复用基础色彩、字体、间距令牌，统一维护、一处修改全局生效。

7. 跨平台兼容处理
   提供designmd无后缀命令别名，解决Windows PowerShell因.md文件关联导致的命令失效问题，全操作系统统一调用。

8. 宽松容错+严格校验双机制
   未知章节、自定义Token仅抛出警告；重复章节、失效令牌引用直接判定错误，兼顾拓展性与规范严谨性。

三、技术细节

1. 文件底层结构规范

• 固定章节顺序：Overview → Colors → Typography → Layout → Elevation & Depth → Shapes → Components → Do's and Don'ts，章节顺序错乱会触发lint警告；

• 组件支持状态变体：hover、active、pressed等交互状态单独定义组件节点，区分基础样式与交互样式；

• 支持全部CSS色彩格式：hex、rgb、oklch、命名色；尺寸单位支持px、rem、em，支持负数间距/字重调整。

2. 仓库工程架构

仓库采用Turbo多包管理，核心代码存放于packages/cli；配套CI脚本（.github/workflows）、规范文档docs/spec.md、使用示例examples、贡献指南CONTRIBUTING.md；依赖使用Bun管理，锁定文件bun.lock保障环境一致性。

3. 程序API与运行机制

• 提供Node.js程序化导入API，可在项目代码中直接调用lint方法解析DESIGN.md，获取结构化校验报告、解析后的设计系统对象；

• CLI输出统一JSON结构化数据，可接入自动化流水线、监控平台、AI提示词注入；

• 9项内置校验规则，分级输出error、warning、info三类结果，命令行通过退出码区分是否存在严重错误。

4. 标准兼容

底层Token模型遵循W3C DTCG设计令牌标准，export命令可直接输出合规DTCG JSON，打通设计工具、前端框架、AI智能体数据链路。

四、应用场景

1. AI代码生成统一视觉管控
   给Cursor、Gemini、Claude Code等AI提供DESIGN.md文件，AI生成页面、组件时自动遵循品牌色彩、字体、间距规范，避免AI输出混乱UI。

2. 前端项目设计系统轻量化托管
   中小型项目无需搭建复杂设计系统工程，单文件存放全部视觉规范，配合CLI自动导出Tailwind样式变量，减少配置文件数量。

3. 设计规范版本迭代对比
   使用diff命令对比新旧版本DESIGN.md，快速识别色彩、字体、组件令牌增删改，监控设计规范变更风险。

4. CI流水线自动化合规检测
   在代码提交、构建流程集成lint命令，自动拦截对比度不达标、失效令牌引用、规范格式错误的设计文件。

5. 团队设计规范文档统一维护
   设计师、前端共用一份DESIGN.md，YAML负责数值，Markdown负责设计说明，减少文档与代码两套维护成本。

6. 多端样式一键转换
   一套Token导出Tailwind配置，同时适配Web页面、后台管理系统、移动端H5，统一多端视觉基准。

五、使用方法

1. 安装工具包

npm全局/本地安装

npm install @google/design.md
# Windows PowerShell需加引号规避@符号冲突
npm install "@google/design.md"

直接npx运行（无需安装）

# Windows通用兼容写法（推荐）
npx -p @google/design.md designmd lint DESIGN.md
# 普通系统简写
npx @google/design.md lint DESIGN.md

2. 四大核心CLI命令使用

（1）lint 校验规范文件

校验格式、令牌引用、无障碍对比度、章节顺序，输出JSON报告

# 校验本地文件
npx designmd lint DESIGN.md
# 标准输入读取文件
cat DESIGN.md | npx designmd lint -

（2）diff 对比两个版本文件

识别令牌新增、删除、修改，检测规范退化

npx designmd diff DESIGN.md DESIGN-v2.md

（3）export 导出令牌至前端格式

# 导出Tailwind v3 JSON配置
npx designmd export --format json-tailwind DESIGN.md > tailwind.theme.json
# 导出Tailwind v4 CSS变量
npx designmd export --format css-tailwind DESIGN.md > theme.css
# 导出W3C DTCG标准令牌
npx designmd export --format dtcg DESIGN.md > tokens.json

（4）spec 输出完整规范文档

用于给AI注入格式上下文，可单独输出校验规则

npx designmd spec --rules-only --format json

3. 项目脚本配置（package.json）

Windows环境统一使用designmd别名，避免.md后缀冲突

{
 "scripts": {
  "design:lint": "designmd lint DESIGN.md",
  "design:diff": "designmd diff DESIGN.md DESIGN-v2.md",
  "design:export-tailwind": "designmd export --format css-tailwind DESIGN.md > src/theme.css"
 }
}

4. 程序化代码调用

import { lint } from '@google/design.md/linter';
const markdownText = `---
name: Demo
colors:
 primary: "#1A1C1E"
---
## Overview
测试设计规范`;
const report = lint(markdownText);
console.log(report.findings, report.summary);

六、竞品对比

选取行业主流设计令牌工具：Style Dictionary、Figma Tokens Studio、Google design.md横向对比

七、常见问题解答（FAQ）

Q：Windows执行npx @google/design.md lint没有输出怎么办？

A：Windows系统会将design.md识别为Markdown文件，触发本地文件关联，改用无后缀别名designmd执行，完整命令：npx -p @google/design.md designmd lint DESIGN.md，package.json脚本中也统一使用designmd命令。

Q：执行npm安装提示ENOVERSIONS无可用版本？

A：该报错源于npm镜像源未同步官方包，执行npm config get registry确认源地址为https://registry.npmjs.org/，清理缓存npm cache clean --force后重新安装；企业内网镜像未同步该包需联系运维同步。

Q：lint检测提示broken-ref失效令牌引用是什么意思？

A：文件中使用{xxx.xxx}令牌引用，但未在YAML中定义对应令牌，属于错误级问题，会直接导致校验失败，需要补充对应令牌定义或修正引用路径。

Q：DESIGN.md章节顺序错乱会直接报错吗？

A：不会抛出error终止流程，仅生成warning警告，工具会保留全部内容不丢弃，但规范要求章节按固定顺序排列，建议按文档标准调整。

Q：导出css-tailwind格式适配哪个Tailwind版本？

A：专门适配Tailwind v4，输出@theme {}标准CSS变量块；json-tailwind格式适配Tailwind v3，输出theme.extend配置对象。

Q：可以自定义YAML顶层字段扩展功能吗？

A：支持自定义顶层键，仅名称拼写接近标准字段（如colours代替colors）会抛出未知键警告，完全自定义拓展字段不会触发任何提示。

Q：项目处于alpha阶段，是否适合生产环境使用？

A：规范、CLI工具仍持续迭代，接口与文件格式存在变更风险，生产环境使用建议锁定固定版本号，避免自动更新引发兼容性问题。

八、官方链接

• GitHub仓库：https://github.com/google-labs-code/design.md

九、总结

Google design.md是Google Labs针对AI代码生成场景打造的轻量化设计系统标准与配套工具，通过DESIGN.md融合机器可读设计令牌与人工设计说明，填补了传统Token工具缺少设计语义、无法给AI提供规范上下文的短板，配套完整跨平台CLI实现规范校验、版本比对、多格式样式导出，兼容W3C DTCG国际标准与Tailwind主流前端框架，既能满足设计师与前端统一维护视觉规范的需求，也可解决AI生成界面视觉混乱的行业痛点，是适配AI开发工作流的轻量化设计系统管理方案。