AI 设计 | 如何自己编写一套高质量的 .MD 套件文档

这段时间，很多人在讨论 Google 提出的 DESIGN.md。

原因很简单：以前我们给 AI 做页面，大多还是靠一句 prompt，比如“帮我做一个高级一点的 SaaS 页面”。结果通常也很熟悉——第一屏看着还行，第二屏开始跑偏，第三屏风格就散了。颜色不统一，圆角不统一，按钮气质不统一，最后看起来像是三个不同的人做的。

我用design.md中Claude的风格prompt了一个日语学习网站首页

DESIGN.md 出现之后，这件事开始变得不一样了。

它的核心价值，不是“帮你写一个设计文档”，而是把原本只存在于设计师脑子里的审美判断、组件逻辑和版式规律，翻译成 AI 能稳定理解的自然语言约束。Google Stitch 对它的定义很明确：它是一个可以作为“source of truth”的设计系统文件，用来指导后续生成的新界面与既有设计语言保持一致。

今天这篇文章，我不想讲太玄的概念，而是想从最基础的角度，把这件事讲清楚：

你到底该怎么理解 DESIGN.md？

为什么有些 DESIGN.md 生成效果特别好？

如果你不是 Google，也没有完整设计系统团队，能不能自己写？

答案是：完全可以，而且比很多人想象中更实用。

一、先理解：DESIGN.md 到底是什么？

一句话讲，DESIGN.md 就是：一份写给 AI 读的设计系统 Markdown 文件。

它不是 Figma，也不是 token JSON，也不是一堆截图。

它是用自然语言 + 精确参数，把“这个产品应该长什么样”讲清楚。

DESIGN.md 官方和社区对它的共识大概有几层：

第一，它是纯 Markdown 文本；

第二，它会写颜色、字体、间距、组件、层级、规范；

第三，它被放在项目里，AI coding tool 读取之后，就能更稳定地生成一致的 UI；

第四，它既能让 AI 读，也能让设计师和开发一起维护。

这也是为什么最近很多人会觉得它很“对味”。

因为它解决的不是“如何让 AI 生成一个页面”，而是：

如何让 AI 连续生成很多页面时，仍然像同一个产品。

二、为什么 Google 这类 DESIGN.md 效果会特别好？

很多人第一次看 awesome-design-md，会有一个误会：

“是不是因为他们写得很高级、很会形容？”

其实不完全是。

真正让这些文档有效的，不是文采，而是它们把设计信息写成了 AI 最容易消费的结构。VoltAgent 对每份 DESIGN.md 的结构总结非常清楚：常见章节包括视觉氛围、颜色与角色、字体规则、组件样式、布局原则、层级与阴影、Do’s and Don’ts、响应式行为，以及最后给 Agent 的 Prompt Guide。

你会发现，这套结构本质上在做三件事：

1. 先定“气质”

比如某个系统是克制、极简、精准、偏工具型；

另一个系统可能是优雅、轻盈、品牌感更强、适合展示型页面。

这一步不是在写颜色，而是在先回答：

这个产品应该给人什么感觉。

2. 再定“角色”

好的 DESIGN.md 不会只写：

主色：#7C5CFF
背景：#0B0D12

它会进一步写清楚：

这个颜色是用在主按钮、焦点态、激活态，还是辅助高亮；

这个背景是 app shell，还是 surface，还是 overlay。

也就是说，它不是只给色值，而是给语义和职责。Google Stitch 的 skill 文档也强调了这一点：颜色不仅要有 hex 值，还要有描述性名称和功能角色。

3. 最后定“组件行为”

这一步最关键。

因为 AI 真正在生成 UI 时，不是在“画一个审美氛围”，而是在拼：

ButtonInputCardSidebarTableModalEmpty State

如果这些组件没有写清楚，AI 就会开始“自由发挥”。

所以高质量的 DESIGN.md，一定会尽量把高频组件写成一套稳定配方：默认态、Hover、Active、Focus、边框、圆角、阴影、文本风格、交互语气。

说白了，真正有效的 DESIGN.md 不是“形容一个风格”，而是在写：

这个风格遇到按钮会怎么做，遇到表单会怎么做，遇到导航会怎么做。

三、很多人写不好 DESIGN.md，问题到底出在哪？

我看过不少人第一次写的版本，通常会有三个问题。

问题一：写成了审美散文

比如：

整体要有未来感，要有科技感，要高级，要简洁，要像苹果一样。

这类话不能说完全没用，但它对 AI 的帮助有限。

因为 AI 读到这里，还是会问：

“那按钮到底是填充的还是描边的？”

“表单边框要不要显性？”

“圆角是 8 还是 16？”

“这个页面是 panel-based 还是 marketing hero 结构？”

也就是说，只有感觉，没有约束。

问题二：只写 token，不写语义

另一类人会把文档写成这样：

Primary: #7C5CFFSurface: #11141BText: #F5F7FARadius: 12px

这当然比没有强，但还是不够。

因为 AI 知道值，不知道“怎么用”。

问题三：没有 Do / Don’t

这一步经常被忽略，但其实非常重要。

AI 最大的问题不是不会做，而是太会“补全”了。

它很容易在你没说清楚的时候，自己加一点：

渐变发光卡片阴影过大的圆角漂亮但不必要的插画“magic happens here” 这种过度轻浮的文案

所以高质量 DESIGN.md 一定要有“负面约束”：不允许什么。

VoltAgent 的结构里专门把 Do’s and Don’ts 列成独立章节，不是偶然。

四、入门写法：先不要追求“完整系统”，先写出第一份能用的 DESIGN.md

如果你是第一次写，我建议不要一上来就做得太复杂。

先记住一个原则：

第一版不是为了完美，而是为了让 AI 不再乱生成。

最小可用版本，建议只写 5 部分：

Visual Theme & AtmosphereColor Palette & RolesTypography RulesComponent StylingsDo’s and Don’ts

下面我给你一个最基础的 V0 示例。

五、案例：把一份 MD 文档从“能用”逐步升级成“高质量套件”

我们以一个“AI 原生设计工具”为例，来做一个逐步升级。

V0：最基础版，先让 AI 不跑偏

# DESIGN.md## Visual Theme & AtmosphereThis product should feel professional, minimal, calm, and precise.It is a dark-mode productivity tool for designers and builders.Avoid playful consumer-app aesthetics.## Color Palette & Roles- Background: #0B0D12- Surface: #11141B- Text Primary: #F5F7FA- Text Secondary: #B6BFCC- Border: #303745- Accent: #7C5CFF## Typography Rules- Primary font: Inter, system-ui, sans-serif- Body text: 14px- Heading text: 20px to 24px, semibold- Mono font: JetBrains Mono for prompts and tokens## Component Stylings- Buttons: medium radius, restrained accent fill, no glossy gradients- Inputs: dark surface, visible border, clear focus ring- Cards: subtle border, low shadow, clean spacing## Do's and Don'tsDo:- keep layouts structured- use accent color sparingly- prefer clean spacing and bordersDon't:- do not use bright gradients- do not make the UI playful- do not over-round every component

这一版已经能用了。

它的目标不是“特别高级”，而是先让 AI 别乱来。

如果你把这份文档塞进项目里，再让 AI 生成一个 dashboard，通常已经会比没有规范时稳定很多。因为它至少知道：

是 dark mode是专业工具主色是紫色不要过度活泼组件要克制

但这还不够。

因为这时候它仍然很容易在不同页面里做出“类似但不完全相同”的组件。

V1：加上结构和语义，让文档真正开始“像设计系统”

接下来要升级两件事：

第一，把颜色从“色值”升级成“角色”；

第二，把组件从“名词”升级成“行为描述”。

## Color Palette & Roles- App Background (#0B0D12): base shell of the application- Main Surface (#11141B): default panel background- Secondary Surface (#171B23): nested sections and grouped modules- Primary Text (#F5F7FA): main readable content- Secondary Text (#B6BFCC): supporting content and metadata- Border (#303745): panel and control separation- Primary Accent (#7C5CFF): primary action, selected state, focus emphasis- Accent Soft (rgba(124, 92, 255, 0.14)): subtle highlight backgrounds

这时候，AI 不只是知道“这个颜色存在”，而是知道“它该出现在什么地方”。

再比如组件：

## Component Stylings### Primary ButtonUse for generate, apply, save, and confirm actions.Filled with primary accent.Text should be high contrast.Hover should brighten slightly.Active should darken slightly.Focus must include a visible ring.### Secondary ButtonUse for utility actions and lower-priority actions.Use neutral dark surface with visible border.Hover should increase contrast slightly.### InputDark neutral surface with clear border.Readable placeholder.Focus state should use accent border or ring.Avoid soft consumer-app styling.到这一步，文档已经从“审美说明书”变成了“组件约束文档”。

V2：从单文件升级成 MD 套件

这一步是关键转折。

很多人以为，写好一个 DESIGN.md 就够了。

其实当你的产品稍微复杂一点，就会发现一个文件会开始变得太重。

这时候，最好的办法不是继续往里面塞内容，而是拆成一套 MD 套件。

推荐拆成 4 个文件：

1）DESIGN.md

负责整体风格、色彩、字体、布局原则、Do/Don’t

2）PAGE_TEMPLATES.md

负责不同页面的结构模板，比如：

DashboardEditorPreviewExportSettings

3）COMPONENT_RULES.md

负责按钮、输入框、卡片、表格、模态框、标签等组件规范

4）AI_CONSTRAINTS.md

负责 AI 生成优先级、禁止行为、幻觉控制规则

这一点其实和 Google Stitch 的思路是同向的：DESIGN.md 之所以有效，不是因为它是一个神奇文件，而是因为它承担了“source of truth”的角色。你一旦产品更复杂，就应该让这份 source of truth 拆分得更清晰。

六、真正决定质量上限的，不是 DESIGN.md，而是 AI_CONSTRAINTS.md

这一步很多人没意识到。

你写了设计规范，不代表 AI 就一定会乖乖听。

因为 AI 还有一个本能：在你没说清楚时补全。

所以，进阶阶段一定要加一份 AI_CONSTRAINTS.md。

例如：

# AI_CONSTRAINTS.md## GoalGenerate UI that strictly follows the canonical design system.## Hard Constraints- Reuse existing layout logic before proposing a new one- Reuse existing components before creating variants- Do not invent new accent colors- Do not add decorative gradients- Do not turn product pages into marketing-style layouts## Generation DisciplineWhen uncertain:1. choose the simplest valid layout2. reuse the nearest canonical component3. reduce decorative styling4. preserve hierarchy5. preserve usability

这一层加上去之后，AI 才会真正从“有参考地创作”，变成“在规范内执行”。

这也是为什么我现在越来越觉得，未来真正有效的 AI 设计工作流，不只是 prompt engineering，而是：

Design System + Constraint System + Task Prompt

三者一起工作。

七、想进一步做出“更高级风格”的 MD，升级点到底在哪？

很多人问，为什么同样是 DESIGN.md，有些看起来就更“高级”？

答案通常不在色值，而在下面四件事。

1. 气质词更准确

比如你写“高级、简洁、未来感”，这种词太泛了。

更好的写法是：

restrainedpreciseeditorialdense but breathablecalm futurismpremium but not flashy

Google Stitch 的 skill 也明确建议：氛围描述不要太泛，要尽量让读者能“看见”那个感觉。

2. 颜色命名更语义化

不要只写 Primary Purple。

可以写：

Primary AccentFocus AccentSurface ElevatedMuted BorderQuiet TextCritical Action

这一步会显著提升 AI 的理解质量。

3. 几何语言被翻译出来了

Google Stitch 的 skill 有个很重要的点：

它要求把技术值翻译成“可感知的设计语言”。

比如：

rounded-full 不只是圆角值，而是 pill-shapedrounded-lg 不只是某个 class，而是 subtly rounded cornersrounded-none 不只是 0，而是 sharp, squared-off edges

这件事看起来小，但对 AI 很重要。因为它最终生成的是视觉界面，不是只在复述 CSS。

4. 每一页都有“模板意识”

高质量系统不会只写“按钮长什么样”，还会写：

首页该怎么组织编辑页该怎么分区预览页该怎么布局导出页该如何建立信任感

也就是说，它开始从“组件系统”升级成“页面系统”。

八、一个实用方法：不要一次写完，而是按“四轮升级法”做

这是我更推荐给大多数人的方法。

第一轮：先写 V0

只写：

气质色彩字体组件Do / Don’t

目标：先能用。

第二轮：补 V1

补：

色彩角色组件状态布局原则文案语气

目标：减少页面之间的风格漂移。

第三轮：拆 V2 套件

拆成：

DESIGN.mdPAGE_TEMPLATES.mdCOMPONENT_RULES.mdAI_CONSTRAINTS.md

目标：让系统可维护、可扩展。

第四轮：做 V3 高级版

补：

token 映射页面模式组件复用策略输出格式要求技术栈约束

目标：让 AI 不只是“生成界面”，而是“生成能落地的界面”。

九、给初学者的一个判断标准：你的 MD 文档到底写得好不好？

你可以用下面 5 个问题自测。

1. 它是不是只在讲“感觉”，没有讲“规则”？如果是，说明还太虚。2. 它有没有明确写“这个颜色 / 组件是干什么的”？如果没有，AI 还是会猜。3. 它有没有写禁止项？如果没有，AI 很容易自由发挥。4. 它有没有页面模板？如果没有，跨页面一致性会差。5. 它有没有约束 AI 的生成顺序和优先级？如果没有，最终输出还是不够稳定。

如果这五个问题里，你有三个以上答不上来，说明这份 MD 还停留在“灵感文档”，还不是“生成系统”。