跳到主要内容

DESIGN.md：让 AI Agent 真正读懂你的 UI 风格

· 阅读需 8 分钟
一介布衣
一介布衣
全栈开发者

AI 写前端，最常见的问题往往不是功能跑不起来，而是页面“看起来不像你想要的东西”：颜色不对、字体随意、间距没有节奏、组件圆角到处变化。你在一次对话里解释过设计规范，下一次对话却还要从头解释；截图、Figma 链接和口头描述也很难成为稳定的项目上下文。

Google Labs 的 DESIGN.md 试图解决的就是这个问题：用一个放在代码仓库里的纯文本文件，把设计系统和设计意图交给 AI coding agent 反复读取。

一句话理解 DESIGN.md​

DESIGN.md 不是 Figma 的替代品，也不是另一套 CSS 框架。它更像是写给 Agent 的设计系统说明书：

  • YAML front matter 保存颜色、字体、圆角、间距等精确 token，便于工具解析。
  • Markdown body 用自然语言解释视觉调性、使用场景和取舍，便于人和 Agent 理解。
  • CLI 负责检查、比较和导出，让这份文件可以进入实际工程流程。

这个拆分很重要。#1A1C1E 只能告诉 Agent 颜色是什么，不能告诉它这个颜色应该用于标题、正文还是交互状态；而“深色墨水，用于标题和核心文本”才是设计决策。token 提供可执行的数值，prose 提供数值背后的语境，两者缺一不可。

文件结构：先定调，再给数值​

仓库建议的标准 section 有 8 个，顺序如下：

  1. Overview：品牌气质和产品定位
  2. Colors：颜色及其使用语义
  3. Typography：字体、字号、字重和行高
  4. Layout：页面结构、密度和对齐方式
  5. Elevation & Depth：阴影、层级和深度关系
  6. Shapes：圆角、边框和形状语言
  7. Components：按钮、卡片等组件的基础属性
  8. Do's and Don'ts：应该做什么，以及明确避免什么

不需要第一次就写满 8 个 section。最小版本可以从项目名称、主色、底色、正文字体和一段 Overview 开始：

---
name: 我的项目
colors:
  primary: "#2563EB"
  neutral: "#F8FAFC"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
---
## Overview

一个面向开发者的 B2B SaaS 后台。信息密度优先，强调长时间使用的舒适度。
参考 Linear 和 Vercel Dashboard 的克制感，不使用营销落地页式的视觉装饰。

这里有一个容易被低估的写法：少写“现代、简洁、高级”这类无法执行的形容词，多写具体参照。比如“像一份排版考究的论文预印本”，同时传达了信息密度、排版克制和阅读场景，也自然排除了大面积渐变、发光装饰和营销式构图。

token 解决什么，prose 解决什么​

YAML token 适合表达确定的事实：

colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
typography:
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px

Markdown prose 则应该解释这些事实如何被使用：

## Colors

- **Primary (#1A1C1E)：** 深色墨水，用于标题和核心文本。
- **Tertiary (#B8422E)：** 只用于交互和需要被注意的状态。

颜色支持 hex、rgb()、oklch() 和命名色，组件中也可以通过 {colors.primary} 这样的引用复用 token。但不要以为写了 token，Agent 就会自动理解设计含义。命名没有强制规范时，更应该在 prose 里解释每个自定义名字的职责。

CLI：把设计文件放进工程闭环​

项目提供了三个关键命令，入口通过 npm 使用，不需要全局安装：

lint：检查设计系统本身​

npx @google/design.md lint DESIGN.md

lint 输出 JSON，除了检查格式，也会发现设计逻辑问题。比如：

  • broken-ref：token 引用了不存在的路径。
  • contrast-ratio：背景色和文字色的对比度可能达不到 WCAG AA。
  • missing-primary：定义了颜色，但缺少主色。

这意味着 DESIGN.md 不只是给 Agent 看的提示文件，也可以成为一份有基本质量门槛的设计配置。

diff：审查设计变更​

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

diff 会按 token 输出新增、删除和修改项。如果新版本比旧版本多出 error 或 warning，命令会返回非零退出码。这适合放进 CI，避免一次看似普通的主题修改悄悄改变整个产品的对比度或视觉层级。

export：同步到实际工具链​

# Tailwind v3
npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json

# Tailwind v4
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css

# W3C Design Token 格式
npx @google/design.md export --format dtcg DESIGN.md > tokens.json

比较实用的定位是：DESIGN.md 作为单一信源，Tailwind 或 DTCG 文件由 export 生成。这样设计 token 不需要在多份配置里手工同步。

接入 AI coding agent 的两种方式​

第一种是直接放进 Agent 能读取的项目上下文：

  • Claude Code：放到 CLAUDE.md 或 .claude/ 目录中。
  • Cursor：放到 .cursorrules 或项目根目录。
  • Windsurf、Copilot 等工具：放到对应的项目上下文文件中。

实际使用时，先写一份十几行的最小版本通常就够了。先把主色、底色、正文字体、布局密度和明确的视觉参照写清楚，再随着项目迭代补充组件和反例。设计系统的价值在于持续被使用，不在于第一天就写成一份几十页的规范。

第二种是接入 CI：

- name: Lint design system
  run: npx @google/design.md lint DESIGN.md

- name: Check design regressions
  run: npx @google/design.md diff DESIGN-base.md DESIGN.md

这样可以把“设计有没有被破坏”从一次人工目测，变成每次提交都能重复执行的检查。

三个例子说明了什么​

仓库里的示例覆盖了完全不同的产品气质：

  • Paws & Paths 是暖橙主色、超大圆角和 Plus Jakarta Sans，重点是友好、可靠。
  • Totality Festival 是深色背景、琥珀高亮和玻璃态层级，关键词是 Cosmic Premium。
  • Atmospheric Glass 使用深蓝渐变和多层玻璃卡片，强调空灵但仍然可用。

它们的意义不在于照抄颜色，而在于展示了 prose 和 token 如何共同约束 Agent：prose 先规定“这个产品应该给人什么感觉”，token 再把颜色、字体、圆角和组件属性落成具体值。

目前的限制​

这个项目仍处于 Alpha 阶段，格式可能继续变化，不能假设未来版本完全向后兼容。用于生产环境时，应该锁定 CLI 版本，并把 DESIGN.md 的 lint 和 diff 当成普通工程依赖来管理。

组件规范也还比较早期，目前主要描述 backgroundColor、textColor、typography、rounded、padding、size、height 和 width 等基础属性。复杂的 hover、focus、disabled 状态，还需要通过类似 button-primary-hover 的命名约定表达，而不是依赖一套成熟的状态语法。

另外，Windows PowerShell 对带 .md 后缀的 npm 包名可能存在解析冲突，可以使用项目提供的别名：

npx -p @google/design.md designmd lint DESIGN.md

我的判断：它最适合解决“风格漂移”​

DESIGN.md 解决的不是“AI 不会写 CSS”，而是 AI 每次生成界面时缺少稳定的设计上下文。它尤其适合以下场景：

  • 多轮迭代中经常重新生成页面或组件。
  • 多个 Agent、多个开发者共同维护一个前端项目。
  • 已经有设计偏好，但不想维护一套很重的设计系统平台。
  • 想让设计 token 同时服务 Agent、Tailwind 和其他工具链。

它不应该被理解成“写完 DESIGN.md，Agent 就一定一次写对”。真正有效的工作流仍然是：先写少量明确约束，生成页面，检查偏差，再把重复出现的偏差补回 DESIGN.md。设计文件不是一次性提示词，而是随着项目演化的长期上下文。

如果你的痛点正是 AI 生成的页面功能可用、视觉却总在漂移，那么用一个轻量的 DESIGN.md 作为项目入口，可能比继续堆更长的 prompt 更值得尝试。它足够简单，可以马上开始；它又有 lint、diff 和 export，能够逐步进入正常的工程流程。

参考资料​