Google 开源的 DESIGN.md让 AI 编码助手真正理解你的设计系统摘要AI 编码助手生成的 UI 总是差点意思颜色不对、字体乱配、间距全靠猜Google Labs 近期开源了 DESIGN.md 规范——用一个纯文本文件把你的设计系统完整、精确地传递给 AI Agent。本文深度解析这个在 GitHub 一周斩获 6700 Star 的项目带你从原理到实战全面掌握。关键词DESIGN.md、AI 编码助手、设计系统、Design Token、Google 开源、Claude Code、Cursor、Tailwind一、痛点为什么 AI 生成的 UI 总是不像样如果你用过 Claude Code、Cursor、GitHub Copilot 等 AI 编码助手来生成前端页面大概率会遇到这些问题颜色混乱每次生成的按钮颜色不一样和你的品牌色毫无关系字体随意标题和正文用了 5 种不同字号看起来像拼凑的间距离谱元素之间的间距有时 4px、有时 40px毫无规律风格漂移同一个项目上午生成的页面和下午生成的像两个产品根本原因很简单AI 没有读过你的设计系统。你的品牌规范、配色方案、字体层级、组件样式——这些存在于 Figma 文件里、存在于设计师脑子里、存在于 Confluence 文档里——但 AI 编码助手根本看不到。你当然可以在每次对话时贴一段 CSS 变量或者 Tailwind 配置但这很碎片化而且上下文窗口用几次就丢了。DESIGN.md 就是为了解决这个问题而生的。二、DESIGN.md 是什么DESIGN.md 是 Google Labs 开源的一套设计规范格式。它的核心思路极其简洁用一个纯文本文件Markdown YAML把设计系统的所有视觉规则——颜色、字体、间距、圆角、组件样式——编码成 AI Agent 能直接读取的格式。图1DESIGN.md 架构概览 — YAML Token 层 Markdown 散文层的双层结构它在设计上遵循三个核心原则原则说明人类可读设计师和产品经理能直接阅读、修改不需要学新工具机器可解析AI Agent 和 CLI 工具能精确提取每一个 Token 值生态兼容能导出为 Tailwind 配置、W3C Design Tokens (DTCG)、Figma 变量换句话说DESIGN.md 就是设计系统的**“README.md”**——一个放在代码仓库根目录、版本控制友好、所有人和 AI 都能理解的设计规范文件。三、核心架构YAML Token Markdown 散文DESIGN.md 文件由两层结构组成3.1 第一层YAML Front Matter机器可读的 Token文件顶部用---围栏包裹一段 YAML定义了所有机器可读的设计 Token---version:alphaname:Heritagedescription:Architectural Minimalism meets Journalistic Gravitascolors:primary:#1A1C1E# 深墨色用于标题和核心文字secondary:#6C7278# 石板灰用于边框、说明文字tertiary:#B8422E# Boston Clay唯一的交互强调色neutral:#F7F5F2# 暖石灰页面底色typography:h1:fontFamily:Public SansfontSize:48pxfontWeight:600lineHeight:1.1letterSpacing:-0.02embody-md:fontFamily:Public SansfontSize:16pxfontWeight:400lineHeight:1.6label-caps:fontFamily:Space GroteskfontSize:12pxfontWeight:500letterSpacing:0.1emrounded:sm:4pxmd:8pxlg:12pxspacing:sm:8pxmd:16pxlg:32pxgutter:24px---这些 Token 是规范性的normative——AI Agent 在生成 UI 代码时应该精确使用这些值。3.2 第二层Markdown Body人类可读的设计散文YAML 之后是标准的 Markdown 章节用##标题组织。这些散文提供了上下文和理由——告诉 AI 为什么要这样用、什么场景适用## 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. - **Tertiary (#B8422E):** Boston Clay — the sole driver for interaction, used exclusively for primary actions and CTA buttons. ## Typography The typography strategy leverages two distinct weights of **Public Sans** for narrative and **Space Grotesk** for technical data. Labels are strictly uppercase with generous letter spacing.为什么需要两层Token 告诉你用什么值散文告诉你为什么用这个值以及在什么场景下用。这种组合让 AI Agent 不仅能生成正确的代码还能在面对 Token 未覆盖的场景时做出合理的设计决策。3.3 Token 引用机制Token 之间可以互相引用使用{path.to.token}语法components:button-primary:backgroundColor:{colors.tertiary}textColor:#FFFFFFrounded:{rounded.sm}padding:{spacing.md}这让组件定义可以复用全局 Token保持一致性。四、实战从零创建一个 DESIGN.md让我们为一个真实的 SaaS 项目创建一份 DESIGN.md。4.1 项目初始化# 在项目根目录创建 DESIGN.mdtouchDESIGN.md# 安装 CLI 工具全局或项目级npminstall-Dgoogle/design.md4.2 编写完整的 DESIGN.md--- version: alpha name: CloudDash description: Modern SaaS dashboard with clean aesthetics colors: primary: #0F172A primary-light: #1E293B accent: #3B82F6 accent-hover: #2563EB success: #10B981 warning: #F59E0B error: #EF4444 surface: #FFFFFF background: #F8FAFC text-primary: #0F172A text-secondary: #64748B border: #E2E8F0 typography: display-lg: fontFamily: Inter fontSize: 36px fontWeight: 700 lineHeight: 1.2 letterSpacing: -0.02em heading-md: fontFamily: Inter fontSize: 20px fontWeight: 600 lineHeight: 1.3 body-md: fontFamily: Inter fontSize: 14px fontWeight: 400 lineHeight: 1.6 caption: fontFamily: Inter fontSize: 12px fontWeight: 400 lineHeight: 1.4 letterSpacing: 0.01em rounded: sm: 6px md: 8px lg: 12px xl: 16px full: 9999px spacing: xs: 4px sm: 8px md: 16px lg: 24px xl: 32px 2xl: 48px components: button-primary: backgroundColor: {colors.accent} textColor: #FFFFFF rounded: {rounded.md} padding: 10px 20px button-primary-hover: backgroundColor: {colors.accent-hover} card: backgroundColor: {colors.surface} rounded: {rounded.lg} padding: {spacing.lg} --- ## Overview CloudDash follows a **Clean Corporate** aesthetic — professional without being sterile, modern without being trendy. The design prioritizes data density while maintaining visual breathing room through generous spacing and clear hierarchy. ## Colors The palette uses a **slate-based neutral foundation** with a **vibrant blue accent**. - **Primary (#0F172A):** Deep slate for navigation and headers - **Accent (#3B82F6):** Vibrant blue for interactive elements - **Background (#F8FAFC):** Very light slate, softer than pure white - **Surface (#FFFFFF):** Cards and elevated containers Color usage rule: accent color should appear no more than 3 times per viewport — on the primary CTA, active nav item, and at most one data highlight. ## Typography **Inter** is used throughout for its excellent screen readability and comprehensive weight range. - **Display (36px/700):** Page titles and hero sections only - **Heading (20px/600):** Section headers and card titles - **Body (14px/400):** Default text, optimized for>4.3 验证文件npx google/design.md lint DESIGN.md输出示例{findings:[{severity:info,path:colors,message:12 color tokens defined}],summary:{errors:0,warnings:0,info:1}}五、CLI 工具链lint、diff、export 三板斧DESIGN.md 配套的 CLI 工具google/design.md提供了三个核心命令图2DESIGN.md CLI 工具链 — lint 验证、diff 对比、export 导出三大功能5.1 lint设计规范校验# 基本校验npx google/design.md lint DESIGN.md# JSON 格式输出适合 CI 集成npx google/design.md lint--formatjson DESIGN.md# 从 stdin 读取适合管道catDESIGN.md|npx google/design.md lint -内置 9 条规则规则级别检查内容broken-refErrorToken 引用{colors.xxx}是否指向了不存在的 Tokencontrast-ratioWarning组件的backgroundColor/textColor是否满足 WCAG AA (4.5:1)missing-primaryWarning定义了 colors 但没有 primary 颜色orphaned-tokensWarning定义了颜色 Token 但没有被任何组件引用missing-typographyWarning有颜色但没有字体定义section-orderWarningMarkdown 章节顺序不符合规范unknown-keyWarningYAML 顶层 key 像是拼写错误如colours→colorstoken-summaryInfo各 section 的 Token 统计摘要missing-sectionsInfo某些可选 section 缺失在 GitHub Actions 中集成# .github/workflows/design-check.ymlname:Design System Checkon:[pull_request]jobs:lint:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv4-uses:actions/setup-nodev4-run:npx google/design.md lint DESIGN.md5.2 diff设计变更检测当你的设计系统迭代时需要知道两个版本之间发生了什么变化npx google/design.mddiffDESIGN.md DESIGN-v2.md输出{tokens:{colors:{added:[accent-light],removed:[],modified:[accent]},typography:{added:[],removed:[],modified:[]}},regression:false}这对于PR Review非常有用——设计师修改了 DESIGN.mdCI 自动检测是否引入了回归比如对比度不达标、删除了正在使用的 Token 等。5.3 export多格式导出# 导出为 Tailwind v3 配置JSONnpx google/design.mdexport--formatjson-tailwind DESIGN.mdtailwind.theme.json# 导出为 Tailwind v4 CSS 主题CSS Custom Propertiesnpx google/design.mdexport--formatcss-tailwind DESIGN.mdtheme.css# 导出为 W3C Design Tokens 格式npx google/design.mdexport--formatdtcg DESIGN.mdtokens.jsonTailwind v4 输出示例theme{--color-primary:#0F172A;--color-accent:#3B82F6;--color-surface:#FFFFFF;--color-background:#F8FAFC;--font-display-lg:Inter;--text-display-lg:36px;--font-weight-display-lg:700;--radius-sm:6px;--radius-md:8px;--spacing-sm:8px;--spacing-md:16px;}六、与主流工具的互操作性DESIGN.md 不是要替代现有的设计工具而是作为设计系统和 AI Agent 之间的桥梁。它在设计上就考虑了与主流生态的互操作性。图3DESIGN.md 在设计工具链生态中的位置 — 连接 Figma/设计师与 AI 编码助手6.1 与 Tailwind CSS 的集成这是最常见的使用场景。流程如下在项目根目录维护DESIGN.md运行export生成 Tailwind 配置AI Agent 读取DESIGN.md获得设计规范同时tailwind.config.js自动生效# 生成 tailwind.theme.jsonnpx google/design.mdexport--formatjson-tailwind DESIGN.mdtailwind.theme.json然后在tailwind.config.js中引用// tailwind.config.js (v3)constdesignTokensrequire(./tailwind.theme.json);module.exports{theme:{extend:designTokens,},};或者用 Tailwind v4 的 CSS 方式/* app.css */importtailwindcss;import./theme.css;/* 由 export --format css-tailwind 生成 */6.2 与 Figma 的关系DESIGN.md 的 Token 格式受 W3C Design Token Format 启发这也是 Figma Variables 所采用的标准。虽然目前没有一键同步工具但你可以通过 DTCG 格式作为中间桥梁Figma Variables → 导出 tokens.json (DTCG) → 手动整理为 DESIGN.md YAML DESIGN.md → export --format dtcg → tokens.json → 导入 Figma Variables6.3 在 Java/Spring Boot 项目中使用对于 Java 后端项目DESIGN.md 同样有价值——特别是当你使用 Thymeleaf、Vaadin 或任何模板引擎时/** * DesignSystemConfig.java * 从 DESIGN.md 导出 Tailwind 配置后 * 在构建流程中生成 CSS 变量文件 */ComponentpublicclassDesignSystemConfig{/** * 读取导出的 CSS 变量文件注入到运行时配置中 * 适用于 Vaadin 等需要运行时主题配置的场景 */Value(${design.theme.css-path:classpath:static/theme.css})privateResourcethemeCssPath;publicStringgetThemeVariables()throwsIOException{returnStreamUtils.copyToString(themeCssPath.getInputStream(),StandardCharsets.UTF_8);}}在构建脚本中Maven/Gradle你可以添加一个步骤!-- pom.xml: 构建时自动导出 Tailwind 配置 --plugingroupIdorg.codehaus.mojo/groupIdartifactIdexec-maven-plugin/artifactIdexecutionsexecutionidexport-design-tokens/idphasegenerate-resources/phasegoalsgoalexec/goal/goalsconfigurationexecutablenpx/executableargumentsargumentgoogle/design.md/argumentargumentexport/argumentargument--format/argumentargumentcss-tailwind/argumentargumentDESIGN.md/argument/argumentsoutputFile${project.basedir}/src/main/resources/static/theme.css/outputFile/configuration/execution/executions/plugin七、在 AI Agent 工作流中的集成实践这是 DESIGN.md 最核心的使用场景。让我展示如何在不同的 AI 编码助手中使用它。7.1 在 Claude Code 中使用Claude Code 会自动读取项目根目录的 Markdown 文件。把DESIGN.md放在根目录Claude Code 在生成 UI 代码时就会自动参考其中的 Token# 确保 DESIGN.md 在项目根目录lsDESIGN.md# Claude Code 在对话中会自动参考# 你也可以在 CLAUDE.md 中添加引用echo- Design system: see DESIGN.md for all visual tokens and guidelinesCLAUDE.md7.2 在 Cursor 中使用Cursor 的 Rules 系统可以直接引用 DESIGN.md!-- .cursor/rules/design-system.md -- When generating any UI code (HTML, JSX, Vue, etc.), always follow the design tokens and guidelines defined in DESIGN.md at the project root. Use exact color values, font sizes, spacing, and border-radius from the YAML front matter. Never invent new design values.7.3 在 CI/CD 中作为质量门禁# .github/workflows/design-gate.ymlname:Design System Gateon:[pull_request]jobs:design-check:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv4-uses:actions/setup-nodev4# 1. 校验 DESIGN.md 格式-name:Lint DESIGN.mdrun:npx google/design.md lint DESIGN.md# 2. 检测设计回归-name:Check design regressionsrun:|npx google/design.md diff \ (git show main:DESIGN.md) \ DESIGN.md# 3. 导出 Tailwind 配置-name:Export tokensrun:|npx google/design.md export \ --format css-tailwind DESIGN.md \ src/theme.css7.4 编程接口Library APIDESIGN.md 的 CLI 同时也是可编程的 Node.js 库// design-check.mjsimport{lint}fromgoogle/design.md/linter;import{readFileSync}fromfs;constmdreadFileSync(DESIGN.md,utf-8);constreportlint(md);// 获取所有 findingsconsole.log(report.findings);// Finding[]// 获取解析后的设计系统状态console.log(report.designSystem);// Parsed DesignSystemState// 统计console.log(report.summary);// { errors: 0, warnings: 2, info: 1 }// 如果有 error退出进程if(report.summary.errors0){process.exit(1);}八、DESIGN.md vs 传统方案对比图4DESIGN.md 与传统设计系统传递方案的对比维度Figma 文件Tailwind ConfigStorybookDESIGN.mdAI 可读性❌ 需要截图⚠️ 仅 Token⚠️ 需要爬取✅ 原生支持人类可读性✅ 可视化⚠️ 需要前端知识✅ 可视化✅ 纯文本设计理由❌ 无❌ 无⚠️ 手动维护✅ 内置散文版本控制❌ 二进制✅ 代码⚠️ 混合✅ 纯文本CI/CD 集成❌ 困难✅ 容易⚠️ 一般✅ 原生 CLI多工具导出❌ 封闭⚠️ 单一❌ 无✅ 多格式离线可用❌ 需要 Figma✅⚠️✅ 完全离线九、最佳实践与注意事项✅ 推荐做法放在项目根目录和README.md、package.json同级AI Agent 自动发现纳入代码审查DESIGN.md 的修改必须经过 PR ReviewToken 命名语义化用primary、accent、surface而非blue、red、white配合 CLAUDE.md / .cursorrules 使用在 Agent 配置文件中显式引用 DESIGN.mdCI 中跑 lint防止格式错误和设计回归用 diff 检测变更每次修改后对比新旧版本❌ 避免做法不要在散文中和 YAML Token 矛盾YAML 是规范性值散文是解释不能冲突不要发明 YAML schema 之外的 key未知的顶层 key会触发unknown-key警告不要过度定义组件只定义原子级组件按钮、卡片、输入框不要在 DESIGN.md 中定义整个页面布局颜色值推荐用 Hex虽然支持 oklch、hsl 等格式但 Hex 最通用、AI 最容易理解十、总结与展望DESIGN.md 解决了一个看似简单但实际影响深远的问题如何让 AI Agent 稳定、一致地遵循你的设计系统。它的成功在于极简一个 Markdown 文件不需要任何新基础设施双层Token 保证精确散文提供上下文生态友好能导出为 Tailwind、W3C DTCG 等主流格式工具完善lint、diff、export 覆盖了完整的生命周期目前 DESIGN.md 还处于alpha版本spec 和 CLI 都在积极迭代中。但从 GitHub 上一周 6700 Star 的增长速度来看社区对这个方向的需求是真实且迫切的。随着 AI 编码助手越来越普及设计系统如何被 AI 消费将成为前端工程化的新课题。DESIGN.md 可能是目前最优雅、最务实的答案。版权声明本文内容为原创基于公开资料独立撰写。文中示例代码可自由使用于学习和个人项目。转载或引用请注明出处。参考来源google-labs-code/design.md - GitHub - 项目主仓库及 READMEdesign.md/docs/spec.md - 完整规范文档 - Token Schema 和 Section 规范google/design.md - npm - CLI 工具使用文档W3C Design Tokens Format - Token 格式标准参考作者超人不会飞
