DESIGN.md
DESIGN.md 是 Google Stitch 提出的设计系统规范，把 token 化的视觉语言写进项目根目录。
- 痛点：AI 写组件超过 5 个 ，颜色 / 间距 / 圆角就开始漂移
- 解法：把9 大模块（视觉主题 / 色彩 / 字体 / 组件 / 布局 / 深度 / Do's / 响应式 / Agent 指南）写进
DESIGN.md - 格式：YAML Front Matter + Markdown 正文，机器可读 + 人类可读
- 生态：awesome-design-md 70+ 品牌（9.6 万 Star）+ getdesign.md 索引站 + Chrome 扩展 逆向竞品 + webdesignhot 403 个 CLI 模板
- 本质：和
AGENTS.md平行的"视觉约束文件" - 局限：直接套别人的设计只适合原型 / 内部工具，自有品牌仍得手写
AI 写前端为什么总跑偏
让 AI 写前端最憋屈的体验是这个：
第一版按钮用了
#5e6ad2、圆角 8px、padding 12px 16px；让 AI 接着写个卡片——好家伙，颜色变成#3b82f6、圆角变成 6px、padding 变成 10px 14px。
每个组件都"有自己的想法"，整套 UI 像七个设计师各自为政的拼接。截图给同事看，对方会问："这是哪个产品的页面？"
根因其实很清楚——AI 没有持久的设计认知。每次新组件从零生成，prompt 里又没强调，颜色 / 间距 / 字体就只能"凭感觉"猜，每次感觉都不一样。
传统 workaround 全都失效：
| 做法 | 结果 |
|---|---|
| 在 prompt 里反复强调"用 #5e6ad2、圆角 8px" | 太啰嗦，第二屏组件又开始漂 |
| 贴 Figma 链接 | Agent 抓不下完整 token，只能识别像素 |
| 写一堆 CSS variables | 代码层面统一了，但 AI 不会主动用 |
| 截图 + "照着这个写" | 组件一多就视觉漂移，间距对不上 |
缺的不是约束，是 一个 Agent 能持续读取的设计知识源。
DESIGN.md 是什么
Google Labs 提出的 DESIGN.md 就是为了填这个坑。它是 Google Stitch AI 设计工具的输出格式之一——Stitch 生成 UI 的同时会产出 design.md，专门给 AI Coding Agent 读。
文件就放在项目根目录（和 AGENTS.md / CLAUDE.md 同级），结构是双层：
- YAML 部分：机器读的精确 token——颜色十六进制、字号像素、间距 4/8 倍数、圆角数值
- Markdown 部分：人写的 rationale——为什么用这个主色、按钮 padding 在密集场景下要不要收紧、什么时候用 elevated / outlined 而非 filled
Agent 写组件时，两层都拿得到：YAML 给出精确数值，Markdown 给出判断逻辑。两边都不会在 prompt 里丢。
一份 DESIGN.md 长什么样
VoltAgent/awesome-design-md 收录的版本把 DESIGN.md 拆成 9 大模块，结构高度标准：
- Visual Theme & Atmosphere — 视觉主题（极简 / 工业 / 友好 / 严肃）和整体氛围
- Color Palette & Roles — 主色 / 辅助色 / 语义色 / 中性色，每个色都标注使用角色
- Typography Rules — 字体家族、字号阶梯、行高、字重映射
- Component Stylings — 按钮 / 输入框 / 卡片 / 标签等基础组件样式
- Layout Principles — 栅格、间距系统（4 / 8 / 16px 基准）、对齐规则
- Depth & Elevation — 阴影层级、毛玻璃、z-index 规范
- Do's and Don'ts — 明确禁用项（"不要用纯黑"、"按钮高度不要超过 56px"）
- Responsive Behavior — 断点、栅格塌陷规则、字号缩放
- Agent Prompt Guide — 给 AI 的专属使用提示，告诉它何时调用哪个 token
一份 Claude 风格的 DESIGN.md 大概长这样：
---
version: 1
name: Claude
description: Anthropic Claude 官方风格
tokens:
colors:
primary: "#cc785c"
bg: "#faf9f5"
text: "#262624"
fonts:
sans: "Inter, system-ui"
serif: "Tiempos Headline"
spacing: [4, 8, 12, 16, 24, 32, 48]
radius:
button: 8px
card: 12px
---
# Claude Design System
## Visual Theme
温暖米色背景 + 砖橘主色 + Tiempos 衬线大标题，整体偏编辑感、
偏长内容阅读，避免高饱和和冷色调。
## Do's and Don'ts
- DO 用 8px 网格系统，所有间距从 4/8/12/16/24/32/48 取
- DO 按钮主色用 `#cc785c`，hover 时降低 8% 亮度
- DON'T 不要用纯黑文字，统一用 `#262624` 这种偏暖的深灰
- DON'T 不要在卡片上加 box-shadow，Claude 风格用 1px 边框分层
Agent 读到这个，写出来的按钮会自动用 #cc785c 和 8px 圆角；写卡片会自动避开 box-shadow。
一键复刻大厂设计
最爽的不是自己写 DESIGN.md，是直接拿现成的。四个来源：
路径一：awesome-design-md 仓库
目前最成熟的选择。VoltAgent/awesome-design-md 收录了 70+ 知名品牌的 DESIGN.md——Apple、Stripe、Nike、Linear、Notion、Anthropic Claude、GitHub 等都齐了，目前 9.6 万 Star。每个文件严格按 9 大模块组织，配套 preview.html / preview-dark.html 两个预览页。
# 在仓库 sites/<品牌名>/ 下找到 DESIGN.md，下载到项目根目录
# 配套还有 preview.html（亮色）和 preview-dark.html（暗色）两个预览页
# 打开 cursor / claude code，告诉 Agent
"参考 DESIGN.md 设计规则，帮我生成一个 SaaS 落地页"
比如用 Apple 风格生成的 SaaS 落地页，跟"随便生成的"对比，每个维度都拉开差距。适合 做原型、内部工具、demo 项目——不需要设计师，自己就能"伪造"出大厂质感。
路径二：getdesign.md 索引站
getdesign.md 是 web 形式的索引站，75 个品牌（请求后可扩到 300+），按品类（AI 平台 / 开发工具 / 金融 / 电商 / 汽车等）浏览。和 awesome-design-md 的区别：前者是 GitHub 仓库、文件直接下载，后者是 web 索引、每条带 rationale 解读。
路径三：Chrome 扩展逆向竞品
bergside/design-md-chrome（TypeUI 出品）能从任意网站自动提取 typography / colors / spacing / radius / shadows / motion，一键生成 DESIGN.md 或 SKILL.md。
适合逆向竞品——看到一个网站"长得不错"想"抄"它的设计语言，比手动抄 token 快得多。
路径四：webdesignhot CLI
webdesignhot 收录了 403 个 DESIGN.md（比 awesome-design-md 70+ 数量级多），通过 npx 直接安装：
npx @webdesignhot/design-md add linear # 把 Linear 的 token 拉进项目
适合想要更多品牌覆盖的场景——尤其是电商、汽车等小众品类，awesome-design-md 没覆盖到的这里可能有。
我的几点看法
1. DESIGN.md 解决的是"上下文里的设计知识衰减"
很多人低估了它的价值。AI 不是不擅长写代码，是 没法在长上下文里维持一套设计规则——写到第 20 个组件时，前面约定的 颜色 / 间距早就被冲掉了。
DESIGN.md 本质是把"设计知识"从 prompt 里 外化到文件，每次 Agent 启动时自动加载，等同于 给 Agent 装了一块只读的设计 ROM。这跟 book-to-skill 把书拆成 Skill 是同一类思路——把易失的知识变成长存的资产。
2. 和 AGENTS.md 是平行的两类约束
AGENTS.md（CLAUDE.md是其软链接，物理上是同一个文件）管行为 + 流程纪律（怎么写代码 + Karpathy 4 规则）DESIGN.md管长相（UI 长什么样）
两个文件各管一摊，合起来才是一个完整的"项目记忆系统"。
3. 70+ 模板只解决"复用现成品牌"的问题
不要指望套个 Linear 模板就拥有自己的品牌。awesome-design-md 的 70+ 设计本质上是别人家的设计语言，用来做内部工具 / 原型 / 学习参考都很香，但放到正式产品上有两个坑：
- 品牌辨识度低：一看就知道是"用 Linear 模板写的"
- 法律 / 合规风险：直接套用商业品牌的设计语言到商业产品，边界模糊
自有品牌的 DESIGN.md 只能手写。好消息是结构是标准化的——9 个模块照着填一遍，半天搞定；坏消息是 token 数值没法靠 AI 猜，得参考自己的视觉规范或者设计师稿。
4. 不是银弹
DESIGN.md 解决的是**"已定设计 → 持续执行"**的问题。如果项目还在 0-1 设计探索阶段，今天改主色明天调圆角，那 DESIGN.md 反而成了负担——你得不停同步这个文件。
适用边界：设计已经稳定 + Agent 频繁生成新组件 + 需要跨人 / 跨项目统一风格——这三个条件都满足时，DESIGN.md 价值最大。任何一个不满足，就别硬上。
5. 和 UI-UX-Pro-Max、Frontend Design Skill 是一类东西吗
不是同一类，但目标有重叠：
| 工具 | 形态 | 工作方式 | 安装 |
|---|---|---|---|
| awesome-design-md | 静态文件 DESIGN.md | Agent 读 Markdown 描述的设计 token | 下载到项目根目录 |
| ui-ux-pro-max-skill | Agent Skill 插件 | 内置 237+ 设计原则校验规则（对比度、Fitts 定律等），生成 UI 时动态决策 | 装到 Claude Code / Cursor（26k Star） |
| frontend-design | Anthropic 官方 Skill | 设计导向的 Agent 能力扩展 | 通过 plugin marketplace 安装 |
一句话：
- DESIGN.md 是设计说明书——告诉 Agent"我们家的按钮长这样"
- UI-UX-Pro-Max / Frontend Design 是设计师外挂——给 Agent 装一套"通用设计知识库"，让它在没说明书时也能做出还行的 UI
两者可以叠加：用 awesome-design-md 提供项目专属 token + UI-UX-Pro-Max 提供通用设计校验，覆盖面比单用任何一方都全。
怎么开始
四种姿势，按场景选：
姿势 1：原型 / 内部工具 / 学习——直接在 awesome-design-md 仓库挑一个品牌的 DESIGN.md，下载到项目根目录，5 分钟上手。
姿势 2：自有品牌——按 9 大模块照着 awesome-design-md 模板 写一份，提交到项目根目录。
姿势 3：逆向竞品——装 bergside/design-md-chrome 访问目标网站，一键提取 token 并生成 DESIGN.md 当起点，再手动改成自己品牌的色值 / 字体。
姿势 4：补充参考——去 getdesign.md 看别人写的 rationale，理解"为什么 Apple 用这个留白"、"为什么 Stripe 按钮这么高"，反哺自己的设计判断。
无论哪种姿势，文件结构都长一样：
your-project/
├── AGENTS.md # 行为 + 流程约束（CLAUDE.md 是其软链接）
├── DESIGN.md # 视觉约束（UI 长什么样） ← 新增
├── src/
└── ...
一句话：AI 写前端跑偏，不是因为它笨，是因为没人告诉它"我们的 UI 长什么样"。DESIGN.md 把设计规则固化到项目里，Agent 每次写代码都查——风格自然就稳了。
扩展阅读
- Google Stitch 官方介绍 —— DESIGN.md 的母工具
- VoltAgent/awesome-design-md —— 最完整的 DESIGN.md 模板库
- book-to-skill 把书拆成 Skill —— 同一思路：把易失的知识外化成长存资产
References
- google-labs-code/design.md —— DESIGN.md 原版规范（Google Stitch 输出格式），Apache-2.0 许可
- VoltAgent/awesome-design-md —— 最完整的 70+ 品牌模板库，9.6 万 Star，MIT 许可
- getdesign.md —— web 索引站，75 个品牌 + 300+ 待请求
- Design Tokens W3C 规范 —— DESIGN.md 的 token 部分本质是 Design Tokens 的 Markdown 化