你给 AI 编码助手描述视觉设计就像给外国人指路用手语——明明说的是同一样东西对方理解的总差那么一点。DESIGN.md 就是这份中英对照词典。读完本文你将了解DESIGN.md 是什么 | 如何5分钟上手 | 它的 token 规范如何工作 | 与 Tailwind/DTCG 的互转能力 | 谁该立刻用、谁该再等等 这个项目解决什么问题你遇到过这种情况吗让 Claude Code 写一个按钮你说了三遍「主色调用深色、按钮用暖橙色」它第一次出来的是浅蓝色第二次是灰色圆角第三次才勉强对上——然后换个页面又来一遍。问题出在设计规范无法传递给 AI 工具。传统链条是这样的设计师在 Figma 画好 → 导出设计规范文档 → 前端开发手动翻译成 CSS 变量 → 代码。每步都有信息损耗。指望 AI 通过对话描述就理解设计系统等于让它从残缺的数据里重建完整信息——精度和一致性都不太行。Google 开源的DESIGN.md项目用一份 Markdown 文件解决这个传输问题。它把视觉 identity 拆成两层YAML 前端数据——颜色、字号、间距、圆角全是 AI 直接能读的结构化值Markdown 正文——设计决策背后的 Why「为什么主色用深墨色而不是纯黑」AI 编码助手读到这份文件就能直接按设计系统的规则生成界面不需要一句一句描述。一份文件永久复用。相比现有方案的差异方案问题DESIGN.md 怎么不同口头描述每次重复、容易遗漏、不一致一份文件代码 review 时一并 review 设计变更传统设计规范文档Word/PDFAI 没法解析YAML front matter 机器可读lint 校验完整性只传 Design Token JSON丢失设计意图为什么用这个颜色Markdown prose 保留设计决策上下文 快速上手动手环节5分钟跑起来从零到设计系统可验证。安装工具npminstall-ggoogle/design.md# 或直接用 npxnpx google/design.md lint DESIGN.md编写 DESIGN.md创建一个DESIGN.md文件---name:MyAppcolors:primary:#1A1C1Esecondary:#6C7278accent:#B8422Eneutral:#F7F5F2typography:heading:fontFamily:InterfontSize:2rembody:fontFamily:InterfontSize:1remrounded:sm:4pxmd:8pxspacing:sm:8pxmd:16pxcomponents:button-primary:backgroundColor:{colors.accent}textColor:#ffffffrounded:{rounded.sm}padding:12px---## Overview简洁、专业、聚焦内容。不为形式牺牲可用性。## Colors高对比度中性色为主导单一点缀色用于交互元素。验证npx google/design.md lint DESIGN.md输出 JSON 格式的检查结果包含 WCAG 对比度检查、未使用 token 检测、组件属性完整性校验。一个按钮的文字色和背景色对比度不够lint 直接告诉你。版本对比npx google/design.mddiffDESIGN.md DESIGN-v2.md可以看到两次迭代之间哪些 token 新增、删除、修改。团队 code review 时一并 review 设计系统变更比「发个新 Figma 链接然后口头通知」靠谱得多。导出到其他格式# 导出 Tailwind v3 配置npx google/design.mdexport--formatjson-tailwind DESIGN.mdtailwind.config.extend.json# 导出 Tailwind v4 theme CSSnpx google/design.mdexport--formatcss-tailwind DESIGN.mdtheme.css# 导出 DTCG 标准 tokensnpx google/design.mdexport--formatdtcg DESIGN.mdtokens.json⚠️踩坑提示Windows 上design.md的.md后缀会被 Markdown 编辑器拦截。用npx -p google/design.md designmd lint DESIGN.md替代——别名designmd绕过了后缀冲突。⚙️ 技术原理DESIGN.md 的核心概念不复杂一份 Markdown 文件前有 YAML 定义的机器可读 tokens后有 Markdown 自然语言供人类阅读。但真正值得关注的是几个设计决策。为什么是 YAML front matter Markdown 正文这是个刻意的设计。AI 擅长解析结构化数据但设计决策远比数值复杂。「为什么选低饱和度」写不进 color hex 字段。YAML 给 AI 吃精确值Markdown 给人看决策语境。AI 通过 YAML 知道「这个颜色是 #B8422E」通过 Markdown 知道「这是品牌色 Boston Clay用于所有可交互元素的高亮反馈」。精度和意图都不丢。Token 引用消除魔法数字DESIGN.md 支持内部 token 引用语法接近设计工具中的别名概念components:button-primary:backgroundColor:{colors.accent}rounded:{rounded.sm}lint 工具会检查所有引用是否可解析——{colors.accent}引用了不存在的 token 直接报 error。这听起来基础但它给设计规范和代码产出之间加了一层编译级别的校验纯 Word 设计文档永远做不到这一点。引用链是传递性的。button-primary引用了rounded.smrounded.sm的值是 4px。如果某天设计系统更新、rounded.sm改成 6px所有引用了它的组件自动更新。一处修改、全局生效。Lint 规则详解不止是语法检查DESIGN.md 的 linter 运行九条规则覆盖了设计系统质量检查的方方面面。其中最有价值的几条broken-referrortoken 引用无法解析时直接报错——{colors.accent}如果accent在 YAML 中未定义构建就会失败contrast-ratiowarning检查组件backgroundColor和textColor的 WCAG AA 对比度。这个功能特别实用——设计师随手选的浅灰底白字lint 直接告诉你对比度只有 2.1:1达不到 4.5:1 的 AA 标准orphaned-tokenswarning定义了颜色但在任何组件中都没用到——帮你发现「死 token」section-orderwarning章节顺序必须符合规范——Overview → Colors → Typography → Layout → Elevation → Shapes → Components → Do’s and Don’ts每条规则都有清晰的 severity 等级error 阻塞、warning 提示、info 仅为参考。这种分层设计让项目可以渐进式提升质量要求。消费者行为容错设计DESIGN.md 遇到不认识的 section heading 时保留不报错遇到不认识的组件属性时给 warning 不阻止。团队可以在不完全遵守规范的前提下逐步采纳——先写颜色和 typography后补组件和 spacinglint 只给 info 级别提示不会阻拦你。导出体系不做替代品做桥梁DESIGN.md 不做替代品做翻译层。导入侧接受 DTCG 标准 Design Token可以从 Figma 插件导出的 tokens.json 转换进来导出侧直接生成 Tailwind CSS 配置v3 JSON 和 v4 CSS、DTCG 格式Figma 团队正常用 Figma 维护设计系统通过工具转成 DESIGN.md再导出给前端和 AI 工具使用。不改变任何人的工作流只加一个翻译层。️ 架构分析项目整体结构清晰三层职责分明DESIGN.md 文件YAML tokens Markdown proseCLI 工具Lint 校验token完整性 WCAG对比度Diff 对比设计系统版本差异Export 导出Tailwind / DTCGSpec 输出格式规范参考Programmatic APITypeScript结构化 Findingserrors / warnings / infoToken 变更报告added / removed / modifiedTailwind config或 DTCG tokens.json模块设计亮点零配置原则npx google/design.md lint DESIGN.md即用不需要design.md.config.json。CLI 的哲学是「如果默认值足够好就不该让用户选」。对比之下很多开源工具光初始化配置就要写 30 行 YAMLDESIGN.md 把复杂性降到了零。diff 输出的人性化token diff 输出的是「什么变了」而不是「原始值和目标值」——团队 code review 时一眼能看到设计系统的版本变更。比如 v1 到 v2 的 diff 会告诉你colors.primary从#1A1C1E改成了#2A2C2E而不是输出两个完整的 YAML 块让你肉眼找差异。export 多格式支持同时支持 Tailwind v3 的 JSON 配置和 v4 的 CSS 语法覆盖了当前最主流的前端设计 Token 消费场景。这意味着无论你的项目在用 Tailwind v3 的tailwind.config.js还是 v4 的 CSS 原生变量DESIGN.md 都能无缝对接。Programmatic API除了 CLI项目还暴露了 TypeScript 的import { lint } from google/design.md/linter接口。CI 流程可以引入 lint 作为自动化检查环节GitHub Actions 上跑个lint DESIGN.md就跟跑eslint一样自然。不足当前处于alpha版本API 和格式可能变化。生产项目引入有风险。缺少对 spacing 单位混用的警告——同一个文件里px、rem、em混用时 lint 不会报 warning。导出只支持 Tailwind 和 DTCG不支持 CSS Modules、styled-components style 对象等前端框架原生格式。✅ 优缺点 适用场景优点AI coding agent 获取设计 context 是目前硬伤DESIGN.md 直接补上了从已有项目导入只需写一个文件不改变技术栈项目在 google-labs-code 下发布持续维护有保障缺点alpha 阶段——版本不稳定不建议生产项目强依赖工具链尚浅——目前只有 CLI缺少 IDE 插件、Git hook、CI 集成设计侧缺一环——从 Figma 直接生成 DESIGN.md 的官方插件尚未发布谁该立刻试试使用 AI 编码助手的团队Claude Code、Cursor、Copilot团队有设计规范但苦于「设计师和 AI 之间鸡同鸭讲」有多产品线需要统一视觉语言的团队谁该再等等单人项目写一份 DESIGN.md 的收益小于口头描述的成本项目已用 DTCG 标准 tokens 并自建了工具链前端不使用 Tailwind目前导出能力主要面向 Tailwind 生态