文章目录
- [一、主题与背景：为什么是 DESIGN.md？](#一、主题与背景：为什么是 DESIGN.md？)
- 二、仓库概览：一个"可执行"的设计系统合集
-
- [2.1 仓库基本信息与结构](#2.1 仓库基本信息与结构)
- [2.2 收录范围：从 AI 平台到车企官网](#2.2 收录范围：从 AI 平台到车企官网)
- [2.3 每个站点包含哪些文件？](#2.3 每个站点包含哪些文件？)
- [三、什么是 DESIGN.md：一份"可读可执行"的设计规范](#三、什么是 DESIGN.md：一份“可读可执行”的设计规范)
- [四、DESIGN.md 的标准结构：九大板块详解](#四、DESIGN.md 的标准结构：九大板块详解)
-
- [4.1 章节总览](#4.1 章节总览)
- [4.2 Visual Theme & Atmosphere：定义"气质"的章节](#4.2 Visual Theme & Atmosphere：定义“气质”的章节)
- [4.3 Color Palette & Roles：颜色不仅是值，更是语义](#4.3 Color Palette & Roles：颜色不仅是值，更是语义)
- [4.4 Typography Rules：严格定义文字层级](#4.4 Typography Rules：严格定义文字层级)
- [4.5 Component Stylings：把 UI 组件拆解到状态级别](#4.5 Component Stylings：把 UI 组件拆解到状态级别)
- [4.6 Layout Principles：用文字描述网格与留白](#4.6 Layout Principles：用文字描述网格与留白)
- [4.7 Depth & Elevation：阴影与层级的统一语言](#4.7 Depth & Elevation：阴影与层级的统一语言)
- [4.8 Do's and Don'ts：把反面案例写给 AI 看](#4.8 Do's and Don'ts：把反面案例写给 AI 看)
- [4.9 Responsive Behavior & Agent Prompt Guide：为 AI 量身订做的操作手册](#4.9 Responsive Behavior & Agent Prompt Guide：为 AI 量身订做的操作手册)
- [五、实践：如何在自己的项目中使用 DESIGN.md？](#五、实践：如何在自己的项目中使用 DESIGN.md？)
-
- [5.1 最小接入路径：两步走](#5.1 最小接入路径：两步走)
- [5.2 场景示例一：快速搭出"像某产品"的 Landing Page](#5.2 场景示例一：快速搭出“像某产品”的 Landing Page)
- [5.3 场景示例二：设计系统升级中的"过渡期"](#5.3 场景示例二：设计系统升级中的“过渡期”)
- [5.4 场景示例三：多品牌、多产品线的统一治理](#5.4 场景示例三：多品牌、多产品线的统一治理)
- [六、如何编写属于你自己的 DESIGN.md？](#六、如何编写属于你自己的 DESIGN.md？)
-
- [6.1 从 clone 开始：先复制再裁剪](#6.1 从 clone 开始：先复制再裁剪)
- [6.2 避免"CSS 导出型设计文档"](#6.2 避免“CSS 导出型设计文档”)
- [6.3 专门为 AI 写的 Do/Don't](#6.3 专门为 AI 写的 Do/Don’t)
- [七、展望：文本化设计系统与 AI 辅助开发的未来](#七、展望：文本化设计系统与 AI 辅助开发的未来)
- [八、结语：从 awesome-design-md 出发，重构你与 AI 的 UI 协作方式](#八、结语：从 awesome-design-md 出发，重构你与 AI 的 UI 协作方式)
读者定位：本篇面向前端开发者、全栈工程师、AI 应用开发者、设计系统建设者，以及对「AI + UI 生成」感兴趣的技术爱好者。
近年来，越来越多团队尝试用大模型自动生成页面和组件，但落地时常遇到一个核心问题：如何让模型真正"理解"你的设计系统，并稳定地生成风格一致的 UI？ Google Stitch 提出的 DESIGN.md 概念，加上 VoltAgent 维护的 awesome-design-md 仓库，正在给出一个非常工程化的答案------用纯 Markdown，把设计系统表达成 AI 读得懂、开发者改得动的"对话式规范"。
本文将围绕这个仓库，系统拆解 DESIGN.md 的理念、结构与实践方式，并结合典型场景，讨论如何在你自己的项目中落地这一套"文本化设计系统 + AI 代理"的工作流。
一、主题与背景：为什么是 DESIGN.md？
1.1 设计系统遇上大模型的落地困境
在传统前端和设计协作流程中，一个完整的设计系统通常分布在多个载体中：Figma 文件、设计文档、组件库源码、token 配置等。 这些载体对人类设计师和工程师很友好，却对大模型非常不友好：需要解析二进制文件、懂得各种导出格式、理解 CSS 与组件代码背后的意图。
结果就是，当你对 AI 代理说"按我们现有的设计系统做一个新页面"时，它往往要么视而不见，要么照猫画虎生成一个"似是而非"的 UI，离真正的品牌一致性和像素级对齐差距很大。
1.2 Google Stitch 的回答：纯文本 DESIGN.md
Google Stitch 提出 DESIGN.md 的核心思想非常直接：把设计系统写成一份结构化的纯文本 Markdown 文档，让 AI 代理像读说明书一样读取它。
- 文件名固定为
DESIGN.md，放在项目根目录； - 内容是严格组织的设计规范，而不是随意的说明文档；
- 不依赖 Figma 导出、JSON schema 或专有工具，只依赖 Markdown。
对大模型来说，Markdown 是最"母语级"的格式，没有解析负担，你给它什么内容，它就按什么内容去生成页面和组件。
1.3 awesome-design-md：把知名网站的设计系统"翻译"成 DESIGN.md
VoltAgent 的 awesome-design-md 仓库，做的事情可以理解为：替你把一批知名产品的设计系统，手工翻译成高质量的 DESIGN.md 文件，并按类别整齐整理。
这个仓库目前包含了诸如 Claude、Mistral、Vercel、Stripe、Notion、Airbnb、Tesla 等大量网站的 DESIGN.md，以及对应的预览 HTML，方便你直接复制到自己的项目里使用。
仓库本质上是一个精心策划的"设计系统语料库"，既是 AI 代理的训练/提示素材，也是开发者理解 DESIGN.md 写法的活体范本。
二、仓库概览：一个"可执行"的设计系统合集
2.1 仓库基本信息与结构
awesome-design-md 仓库是一个公开的 GitHub 仓库，采用 MIT 许可协议，截至目前已有约 3.7 万 Star、4.7k Fork，足见社区关注度。
在根目录下，主要文件和目录包括：
design-md/：存放各个网站的 DESIGN.md 以及预览 HTML，是核心内容目录；README.md：项目介绍、使用说明和收录网站列表；CONTRIBUTING.md：贡献指南，包括如何改进现有文件和提交流程；LICENSE：MIT 开源协议说明。
开发者只需进入 design-md 目录，就可以找到按站点分好的 DESIGN.md 集合，每个站点通常会包含一个 DESIGN.md 和两个预览 HTML 文件。
2.2 收录范围：从 AI 平台到车企官网
仓库按照产品类型，将 DESIGN.md 分为多个板块，便于浏览和选择：AI & Machine Learning、Developer Tools & Platforms、Infrastructure & Cloud、Design & Productivity、Fintech & Crypto、Enterprise & Consumer、Car Brands 等。
例如，在「AI & Machine Learning」分类下，你可以找到：Claude（温暖陶红、编辑排版）、Cohere（企业级渐变与数据化风格）、Mistral AI（紫调极简）、Ollama（终端风黑白）、RunwayML（视频感暗色 UI）、xAI（未来感黑白极简）等。
在「Developer Tools & Platforms」下则有 Cursor、Linear、Raycast、Supabase、Vercel、Warp 等，每个都精准概括了对应产品的设计气质和关键视觉元素。
甚至连「Car Brands」也有专门一节：BMW、Ferrari、Lamborghini、Renault、Tesla 等，每一个 DESIGN.md 都试图捕捉品牌官网的独特气质------比如 Tesla 的"极致留白 + 全屏摄影"。
这个分类体系本身就是一个"设计风格地图"，适合你根据项目定位选择相近的视觉语言作为基础模板。
2.3 每个站点包含哪些文件？
根据 README 中的说明，每个站点的条目通常包含以下三个文件：
| 文件名 | 作用 |
|---|---|
DESIGN.md |
主体设计系统文档，供 AI 代理读取和遵循 |
preview.html |
以浅色/默认背景展示颜色、排版、按钮、卡片等的视觉目录 |
preview-dark.html |
在深色背景下展示同一设计系统的暗色表现，用于检查暗色适配性 |
preview.html 和 preview-dark.html 对人类开发者和设计师很友好，可以快速对照 DESIGN.md 与实际视觉效果是否一致，同时也是校准 AI 输出的一把尺子。
三、什么是 DESIGN.md：一份"可读可执行"的设计规范
3.1 官方定义：Google Stitch 的 DESIGN.md
README 对 DESIGN.md 的定义引用了 Google Stitch 的文档：它是一份用于 AI 代理读取的纯文本设计系统文档，目的是让代理能生成风格一致的 UI。
在这个理念下，项目根目录下往往有两个特殊的文档角色：
| 文件名 | 主要读者 | 定义内容 |
|---|---|---|
AGENTS.md |
Coding agents | 项目如何构建、运行与部署 |
DESIGN.md |
Design agents | 项目整体视觉与交互应呈现的样子 |
也就是说，AGENTS.md 管"怎么做"，DESIGN.md 管"长什么样"，两者共同构成一个对 AI 友好的项目说明入口。
3.2 DESIGN.md 的核心特点
从仓库描述和格式说明来看，一个高质量的 DESIGN.md 至少要具备以下几个关键特性：
- 纯文本、无二进制依赖：完全用 Markdown 写成，避免工具锁定；
- 结构化、分章节：遵循统一的章节布局，便于 AI 定位信息；
- 语义化命名：颜色、组件、排版都以"语义 + 角色"形式描述，而不是仅仅列出 CSS；
- 有"哲学"，不仅有"规则"：不仅说明怎么排版，还解释"为什么这样排版"；
- 专门为 AI 书写：章节中往往包含"Do/Don't"和"提示用语"，帮助模型在生成时做正确的选择。
这使得 DESIGN.md 在本质上更接近"为 AI 写的 Style Guide"，而不是给人看的设计说明书。
四、DESIGN.md 的标准结构：九大板块详解
README 中给出了 DESIGN.md 推荐遵循的标准结构，一共九个部分，每一部分都明确说明"捕获什么信息"。
4.1 章节总览
- Visual Theme & Atmosphere：整体视觉主题与氛围；
- Color Palette & Roles：颜色调色板及语义角色；
- Typography Rules：排版与字体层级规则；
- Component Stylings：UI 组件的样式与状态；
- Layout Principles：布局原则与间距体系；
- Depth & Elevation：层级与阴影系统；
- Do's and Don'ts：应该遵守与避免的设计模式；
- Responsive Behavior：响应式行为与断点策略；
- Agent Prompt Guide：为 AI 准备的提示指引与速查。
这九个部分构成了一套相对完整的"设计系统描述 DSL"，任何一个 Agent 只要按照这些章节来解析，就能相对稳定地遵循设计规范生成 UI。
4.2 Visual Theme & Atmosphere：定义"气质"的章节
这一部分关注的是宏观的设计气质和哲学，包括界面密度（dense / spacious）、品牌调性（warm / cold / playful / corporate）、整体对比度、线条与圆角倾向等。
举例来说，一个逼近 Linear 的 DESIGN.md 可能会强调"极简、精确、冷静"的气质，而一个逼近 Lovable 的则会强调"友好、活泼、渐变丰富"，这样的描述能帮助模型在生成时做出正确的取舍，比如选择多大字号、多少留白、用不用插画。
4.3 Color Palette & Roles：颜色不仅是值，更是语义
在颜色章节中，不仅要列出颜色的十六进制值，更重要的是给每个颜色一个语义角色和使用范围，例如：primary/brand, accent, danger, surface, border/subtle 等。
一个好的 DESIGN.md 会采用"语义名 + Hex + 功能描述"的格式，让 Agent 可以根据用途选择颜色，而不是只按 RGB 值硬套。
4.4 Typography Rules：严格定义文字层级
排版规则章节会确立：基础字体家族、字号/行高/字重层级、标题与正文的搭配、代码字体、数字展示用字型等。
通常会通过结构化表格列出，如：Heading 1、Heading 2、Body, Caption, Button label 等，配以示例说明和适用场景，使 AI 在生成页面时能知道"某个标题应该用哪个层级"。
4.5 Component Stylings：把 UI 组件拆解到状态级别
组件样式是 DESIGN.md 中对开发者和模型都非常重要的一部分，它需要详细描述常用组件的外观与状态，例如按钮、输入框、卡片、导航栏、标签、Badge 等。
一个典型的组件描述会包括：
- 默认、悬停、按下、禁用等状态；
- 轮廓/填充风格（ghost, outline, solid）；
- 圆角大小、内边距、阴影、边框；
- 图标和文字的排布与间距。
这种级别的细致描述，能够显著减少 AI 生成 UI 时"样式走偏"的概率。
4.6 Layout Principles：用文字描述网格与留白
布局原则章节会定义：整体栅格系统、容器宽度、断点策略、整体水平/垂直节奏、模块间距，甚至"什么时候选择两栏、什么时候三栏"。
例如，你可以规定首页 Hero 区域通常为"左文右图"，或者列表页面通常以特定的卡片宽度排列，这些都可以用自然语言精准描述出来。
4.7 Depth & Elevation：阴影与层级的统一语言
层级部分主要处理的是：哪些元素可以浮起、阴影层级有哪些档位、何时使用毛玻璃/模糊、模态与弹出层的层级关系等。
对于 AI 来说，这部分能防止它在每个卡片上胡乱添加阴影，或在不该浮起的元素上使用强对比光影效果，从而保持整体层次感一致。
4.8 Do's and Don'ts：把反面案例写给 AI 看
Do/Don't 章节非常关键，它把很多"设计师心中的潜规则"写成显式的文字：应避免的颜色组合、应禁止的按钮排列、表单布局的雷区等。
例如："不要在同一页面使用超过两种主按钮颜色"，"不要在大面积图片上叠加密集文字"等，这些提示能直接抑制模型常见的"设计味不对"的错误。
4.9 Responsive Behavior & Agent Prompt Guide：为 AI 量身订做的操作手册
响应式行为中，通常会列出断点（如 mobile, tablet, desktop 的宽度区间）、导航折叠策略、表格在小屏上的展示方式、触控目标大小等。
而 Agent Prompt Guide 则更像是为 AI 事先准备好的"提示片段"和"颜色速查表"，让你在对话中可以直接引用，比如："用 primary surface 颜色构建一个 3 卡片布局，每个卡片使用 subtle elevation level 1"。
五、实践：如何在自己的项目中使用 DESIGN.md？
5.1 最小接入路径：两步走
README 给出的"使用方法"非常简洁，只有两步：
- 复制某个站点的
DESIGN.md到你项目的根目录； - 告诉你的 AI 代理（比如某个 coding agent 或 Stitch）使用该 DESIGN.md 作为设计规范。
从工程实践角度，可以做得稍微更系统一点：
然后，在每次让 AI 生成页面或组件时，把 DESIGN.md 的 URL 或路径连同任务一同发给代理。
5.2 场景示例一：快速搭出"像某产品"的 Landing Page
假设你正在构建一个新的 AI 工具，希望它的官网视觉风格接近 Vercel 或 Linear，可以按以下步骤操作：
- 在 awesome-design-md 中找到「Developer Tools & Platforms」分类下的
Vercel或Linear条目，打开对应的 DESIGN.md； - 复制该文件到你的项目根目录，并根据实际品牌名做少量改动（如名称、Logo 使用规则）；
- 在与 AI 代理对话时，给出指令："根据项目根目录的 DESIGN.md，生成一个用于展示 X 产品的 Landing Page，包括 Hero、Features、Pricing 和 CTA 段落。"
因为 DESIGN.md 已经详细描述了整体气质、排版层级和按钮样式，AI 在生成 HTML/CSS 或 React 组件时，就能在相当程度上模仿这种风格。
5.3 场景示例二：设计系统升级中的"过渡期"
如果你的团队正在重建设计系统，但旧页面还大量存在，在过渡期内可以使用 DESIGN.md 来逐步统一风格：
- 先根据"目标设计系统"手工撰写或整理一份 DESIGN.md；
- 逐页迁移时，用 AI 根据 DESIGN.md 重写旧页面的 UI 结构与样式；
- 通过 preview.html 的机制检查新旧视觉差异，逐步修正 DESIGN.md 直至稳定。
这样可以借助 AI 替你做大量"重复劳动"，把人力集中在规范制订和质量审查上。
5.4 场景示例三：多品牌、多产品线的统一治理
当你维护的是一个多品牌矩阵（比如同时有 B2B、B2C、开发者品牌），可以为每个品牌维护一份独立的 DESIGN.md，再在高一层级上维护一个"元 DESIGN.md"，描述跨品牌的共性（如网格系统、响应式哲学）。
AI 在生成具体页面时，则根据当前上下文选择对应品牌的 DESIGN.md，实现"同一套内容，在不同品牌视觉层面的自动适配"。
六、如何编写属于你自己的 DESIGN.md？
6.1 从 clone 开始：先复制再裁剪
awesome-design-md 最直接的价值之一，是为你提供了大量"生产级" DESIGN.md 示例，你可以选择一个与你的产品定位接近的站点作为起点。
建议流程：
- 挑选 1~2 个与目标产品气质接近的 DESIGN.md（比如开发者工具选 Linear/Vercel，消费者产品选 Airbnb/Spotify）；
- 对比它们的章节结构、用词习惯和量级，作为你编写自有 DESIGN.md 的参考；
- 在此基础上：保留结构，替换品牌、颜色和 Tone of Voice，逐步改写内容，让它真正描述的是你的产品，而不是原网站。
6.2 避免"CSS 导出型设计文档"
一个常见误区是：直接把现有 CSS 的 color/font/spacing 列表复制进 DESIGN.md，这会使文档缺少语义与哲学，只剩下一堆 token。
更理想的做法是：
- 对 token 进行语义命名；
- 明确描述每个 token 在界面中的典型使用场景；
- 写出"为什么"这么用，而不仅是"怎么"用。
AI 更擅长理解"带解释的规则"，而不是"纯配置项"。
6.3 专门为 AI 写的 Do/Don't
在 Do/Don't 部分，可以考虑针对模型常犯的错误，专门写一些反面条款，例如：
- 不要在同一组件上混用超过两种不同圆角半径；
- 不要在一个页面里混用超过三种字体大小；
- 不要让主按钮和次按钮的颜色对比过弱。
这些条目看起来像是在和人类设计师沟通，但实质上是在给模型划定"行为边界"。
七、展望：文本化设计系统与 AI 辅助开发的未来
7.1 DESIGN.md 会成为设计系统的新"接口"吗？
在 Figma、Design Token、组件库、Storybook 等多种载体之外，DESIGN.md 提供了一个非常"模型友好"的接口：简单、可版本控制、可审阅、可被 AI 直接消费。
从趋势上看，它可能会逐步成为：
- 设计系统对 AI 代理开放的"首选接口"；
- 设计团队与开发团队在讨论"AI 能做什么"时的共同语境；
- 多端、多品牌、多主题系统的统一元描述层。
7.2 从"生成页面"到"对话式设计系统迭代"
一旦你把设计系统写成 DESIGN.md，就可以想象下一步的工作流：
- 设计师与 AI 一起迭代 DESIGN.md 文本，探索新的视觉方向；
- 前端工程师根据 DESIGN.md 自动生成组件库骨架；
- 产品经理通过高层级的"设计哲学"描述，引导 AI 产出符合产品定位的界面草图。
换句话说，DESIGN.md 让"设计系统本身"也变成了一个可对话、可协作、可渐进演化的对象，而不仅仅是一堆静态文档或配置文件。
八、结语：从 awesome-design-md 出发，重构你与 AI 的 UI 协作方式
awesome-design-md 并不仅仅是一个"好玩的 GitHub 仓库"，它更像是一个面向 AI 的设计系统"语料库 + 标准示例集"，向我们展示了：如何用纯文本、结构化的方式，把复杂的视觉语言转化为 AI 可理解、可执行的设计规范。
如果你正在：
- 探索如何让大模型稳定生成"看起来就像你产品"的 UI；
- 搭建下一代"AI 驱动"的前端开发和设计协作流程；
- 或者只是想系统学习优秀产品的设计系统写法------
那么，从克隆 awesome-design-md、认真阅读几份 DESIGN.md 开始，可能是一个很好的切入点。
在不远的将来，当我们对 AI 说"做一个页面，风格就按项目里的 DESIGN.md 来"，它真正能明白你说的是"我们的设计哲学"，而不仅仅是一串颜色值和组件样式，这或许才是"AI 原生 UI 开发"的真正起点。
