TL;DR
用 AI Coding 做产品时最大的问题不是「AI 不会用组件」，而是「AI 不知道什么时候不该用」。
Google 的 DESIGN.md 给出了一个轻量方案——把设计系统写成 Markdown 放进代码仓库，让 AI 每次 Coding 都能读到设计约束。
本文展示如何从 Foundation（DESIGN.md）扩展到 Component（50+ 组件文档）和 Pattern（30+ 交互模式），用一套 Markdown 文档体系让 AI 真正消费你的设计系统。
篇首语
最近这段时间，我一直在用 Claude Code 做一个数据分析系统。
最开始启动的时候，整体的体验还是非常不错的。我只需要写好需求描述文档，准备好各种 API，Claude 很快就能交付一个质量相当不错的结果。
指定好 React + Tailwind + Shadcn 的技术栈，再配合上 Shadcn 提供的 Skill，Claude 在 Coding 上的确非常顶。整个过程中最大的瓶颈其实是自己，写需求的速度赶不上 AI 写代码的速度，最后还是搞得自己非常累 😅
不过这也算不上是问题，真正的问题其实发生在一段时间之后。随着功能不断推进，界面设计的质量开始有些不太可控了。组件错用，样式不统一，交互流程前后不一致——这些问题开始频繁冒出来。
我用的已经是 Shadcn 了，组件库的文档也给了 AI，为什么还是管不住？
问题出在哪：AI Coding 的一致性为什么难以保证
拿下面这张图来举个例子。这是我在同一个项目下、不同阶段开发的两个功能界面。
菜单、Tab、输入框的样式，在两次 Coding 中出现了明显的不一致。照理说，在同一个项目、同一套技术栈下，不应该出现这种问题。但事实上它不仅出现了，而且随着页面越来越多，这类问题开始陷入了反复纠正，依旧出错的"死循环"。
为什么会这样？我总结了三个原因。
第一，跨会话的记忆丢失。
虽然现在 Claude Opus 可以用上 1M 的长上下文来工作，但它终归是有上限的。一个完整的项目则需要很多个 session 来接力，跨 session 势必会造成信息的丢失。
我们可以让 Claude 自己总结当前阶段的记忆并更新到约束文件里，但这种方式并不结构化，也不够确定性。它非常依赖我们对上下文约束的把控能力，同时还会搞得每次新对话要加载的内容不断膨胀。
第二，AI 会自己假设。
Claude 的幻觉控制算是做得不错的了，但它始终还是存在。虽然我们已经指定了使用 Shadcn 的组件库来构建页面，但它有些时候还是会跳过我们的约束，自己去写一些组件或修改一些布局排版等设定。
第三，AI 无法理解设计意图。
组件库的文档告诉了 AI「这个组件是什么」和「怎么用」，但没有告诉它「什么时候该用」和「为什么用这个而不是那个」。
说白了，Shadcn 的文档是写给开发者的 API 参考，不是写给 AI 的设计决策指南。但一到具体的业务场景里，该用哪个组件、不该用哪个、几个组件之间怎么配合，这些问题组件文档里都没有标准的答案，AI 只能自己猜，结果就是整个产品中存在大量的不一致。
在这里第三个问题其实才是根源的。即使 AI 有无限记忆、零幻觉，只要它不理解你的设计意图，做出来的界面就不会是你想要的。
这个问题的本质，其实和我们在 OpenClaw 中遇到的是一样的。如何用结构化的上下文来约束 AI 的行为。想要靠一套组件库文档就让 AI 按照我们的要求来构建产品，显然是不太够的。
按照配置 OpenClaw 的经验，我的第一反应就是自己来补一些文档做约束，把缺失的设计决策写进去，让 AI 按照这些规则来做。
也正是在这个过程中，突然发现 Google 提出了一个叫 DESIGN.md 的方案。用一个 markdown 文档来告诉 AI 在 Coding 界面的时候该遵循哪些设计约束。这正好是我想要的。
Google 的 DESIGN.md：把设计规范变成 AI 的上下文
设计文档规范这件事本身不新鲜，每个设计师多少都在设计系统中做过相关的工作。但 Google 的 DESIGN.md，做的事情稍有不同。它不是给设计师看的设计规范，而是把设计规范写成 markdown，直接放进代码仓库，让 AI 在 Coding 的时候能读到。
说白了，就是把设计约束变成了 AI 的上下文。
来看看官方的基础案例：
# Design System
## Overview
A focused, minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.
## Colors
- **Primary** (#2665fd): CTAs, active states, key interactive elements
- **Secondary** (#475569): Supporting UI, chips, secondary actions
- **Surface** (#0b1326): Page backgrounds
- **On-surface** (#dae2fd): Primary text on dark backgrounds
- **Error** (#ffb4ab): Validation errors, destructive actions
## Typography
- **Headlines**: Inter, semi-bold
- **Body**: Inter, regular, 14–16px
- **Labels**: Inter, medium, 12px, uppercase for section headers
## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill
- **Inputs**: 1px border, subtle surface-variant background
- **Cards**: No elevation, relies on border and background contrast
## Do's and Don'ts
- Do use the primary color sparingly, only for the most important action
- Don't mix rounded and sharp corners in the same view
- Do maintain 4:1 contrast ratio for all text这个案例看上去很简单，但它其实做了几件关键的事情：风格定调、色彩定义、字体排版、组件基础设定，以及 Do’s and Don’ts。
最后这一项对 AI Coding 来说尤为重要，而且 Don’t 比 Do 更为重要。前面我们分析过，AI 最大的问题不是不会用组件，而是不知道什么时候不该用。Don’t 就是在帮 AI 划出边界。
有了 DESIGN.md 之后，我们只需要在项目 CLAUDE.md 中进行强制加载。
启动加载（强制） 在执行任何任务之前，必须先确认已加载以下三个文件。如果当前对话中尚未读取，先读取再行动。
- DOMAIN.md — 项目背景、内容地图、文件路由
- CONSTRAINTS.md — 硬约束清单
- DESIGN.md — Coding 中强制执行约束
这样 AI 每次执行 Coding 工作前，都会先读一遍这份设计规范，按照设定来进行生成工作。
这个思路很快就火了，GitHub 上还有出现了一个开源项目，专门整理了各大知名产品平台的的 DESIGN.md 案例，可以直接复制到自己的项目中来使用。
内容很多很详细，这里我就不复述了，大家可以直接去看看。https://github.com/VoltAgent/awesome-design-md
其实到这一步，DESIGN.md 已经让 AI Coding 进步很多了，至少界面风格上的一致性有了保障。但如果你真的拿它来做一个完整的产品，你会发现它其实还不够。
从 Foundation 到 Component 再到 Pattern：完整设计系统的 Markdown 化
如果按照我们的对设计系统的定义，DESIGN.md 其实只是做了 Foundation 层的工作，关注的是色彩风格、字体排版等基础设置。但一个真正能用的设计系统，Component 层和 Pattern 层的定义是必不可少的。（关于设计系统的三个层级，可以参考 设计系统学习指南 - 国内外 Design System 案例解析 和 如何规划 B端 设计系统？深度解析 AWS CloudScape 这两篇）
开始如果让我自己手动去对每个组件和 Pattern 写一份文档，这事儿我着实不太相干。于是我干脆直接把 Shadcn 的组件文档扔给了 Opus，想让它面向 AI 使用的视角先来帮我整理个基础版本，我再来逐条优化。
结果有点意思，效果比我预想的要好。
Shadcn 的官方文档详细解释了每个组件的参数配置，但缺少「什么时候用」的说明。所以每次调试的时候我都会把文档链接扔给 AI，让它读完再动手。浪费时间也浪费 token。
但由于我在项目的上下文初始化中写了很多的 Do 和 Don’t，Claude 可能识别到了我的这个习惯，于是在扫描生成文档的过程中，也加上了对 Do 和 Don’t 的定义，指定了什么场景该用这个组件，什么场景不该用。这其实正好补上了我们前面说的那个缺口。
摘取一下 Alert 组件的文档内容：
# Alert
页面内静态提示信息，用于引起用户注意。
层级: Component | 来源: shadcn/ui
## 何时使用
- 展示重要的上下文提示（警告、错误、信息）
- 页面内持久显示的通知
## 何时不用
- 临时性通知 → 用 Sonner（Toast）
- 需要用户确认的阻断提示 → 用 Alert Dialog
## 常见组合
- 配合 lucide-react 图标增强视觉提示
- 表单顶部展示全局校验错误我把 Claude 生成的 50 多个组件的文档都大致看了一下，质量都还不错，稍微修改一下基本就可以直接使用了。
有了这个说明文档之后，AI 在 Coding 时对组件的使用明显改善了不少。再配合上 Shadcn 自带的 Skill，基本上组件层面的问题就不大了。
既然组件的文档梳理工作做得还不错，那 Pattern 是不是也可以交给它试试？
这次 Claude 帮我整理了 30 多个 Pattern，分成了三个类别：交互流程（Flows）、功能区块（Blocks）、页面模板（Pages），基本能覆盖大部分常见的产品场景了。
再来摘取一个「删除确认流」的 Pattern 文档内容来看看：
# 删除确认流
触发删除操作后，通过 AlertDialog 二次确认，执行后以 Toast 反馈结果。
## 适用场景
- 删除数据记录（用户、项目、文件等不可撤销的实体删除）
- 注销账户、清空数据等高风险破坏性操作
## 不适用场景
- 可撤销的软删除或归档操作（-> 直接执行 + undo toast）
- 非破坏性的普通确认（-> Dialog 即可）
## 交互规则
- 高危操作须二次输入确认
- 确认按钮文案必须明确为「删除」，不得使用「确认」「是」等模糊表述
- 确认按钮使用 destructive 变体
- 执行中禁用所有按钮并显示 Spinner
- 对话框关闭时重置输入状态质量也还不错，使用/不使用场景以及对应的一些交互原则，文档里都考虑到了。
我们接下来就是按照实际的产品需求去调整。看看哪些 Pattern 要合并，哪些规则要加严，哪些场景要补充。
这里还有个有意思的做法。如果你觉得别人设计系统中的某个 Pattern 特别好，也想引用进来，可以直接发送给 AI 让它来帮你提炼沉淀到自己的体系中。
比如我觉得 CloudScape Design System 中的 Announcing New Features 这个 Pattern 就很不错，把文档链接发给 Claude，它很快就按照我的逻辑完成了转化，同时还自动将 CloudScape 的组件映射到了 Shadcn：
| Cloudscape 组件 | shadcn/ui 映射 |
|---|---|
| Flashbar（全局横幅） | Alert |
| “New” label + Popover（导航） | Badge + Popover（在 Sidebar 中） |
| “-new” 后缀标签（页面内） | Badge |
最终完整的 DESIGN 目录长这样：
DESIGN/ # 设计系统根目录（90 个文件）
├── index.md # 组件系统总索引 + 选型速查
│
├── components/ # 基础组件文档（59 个）
│ ├── accordion.md # 可折叠内容面板组
│ ├── alert.md # 静态提示信息
│ ├── alert-dialog.md # 确认对话框（阻断式）
│ ├── aspect-ratio.md # 固定宽高比容器
│ ├── avatar.md # 用户头像
│ ├── badge.md # 状态标签/徽章
│ ├── breadcrumb.md # 面包屑路径导航
│ ├── button.md # 按钮
│ ├── button-group.md # 按钮组容器
│ ├── calendar.md # 日期选择日历
│ ├── card.md # 容器卡片
│ ├── carousel.md # 轮播
│ ├── chart.md # 图表（Recharts）
│ ├── checkbox.md # 复选框
│ ├── ...
│
└── patterns/ # 组件组合模式（30 个）
├── index.md # Pattern 总索引 + 场景速查
│
├── flows/ # 交互流程（12 个）
│ ├── add-info-full-page.md # 完整页面添加
│ ├── add-info-inline-dialog.md # 浮层简单添加
│ ├── announcing-new-features.md # 新功能公告（3 种变体）
│ ├── bulk-action.md # 批量操作
│ ├── delete-confirm.md # 删除确认流
│ ├── info-expansion-center-overlay.md # 中间浮层扩展
│ ├── info-expansion-side-panel.md # 右侧浮层扩展
│ ├── inline-edit.md # 行内编辑
│ ├── multi-step.md # 多步骤引导
│ ├── notification.md # 站内通知
│ ├── ...
│
├── blocks/ # 功能区块（10 个）
│ ├── command-palette.md # 全局命令面板（⌘K）
│ ├── data-table-block.md # CRUD 数据表格
│ ├── detail-header.md # 详情页头部
│ ├── empty-state.md # 空状态
│ ├── filter-bar.md # 筛选条件栏
│ ├── form-section.md # 表单分区
│ ├── loading-state.md # 加载状态
│ ├── ...
│
└── pages/ # 页面模板（7 个）
├── dashboard-page.md # 数据仪表盘
├── detail-page.md # 详情查看页
├── error-page.md # 错误页（404/500/403）
├── form-page.md # 独立表单页
├── list-page.md # 列表管理页
├── ...到这里，整套体系就搭完了。在 CLAUDE.md 中设定好加载规则之后，AI 每次接到 Coding 任务都会自动读取 DESIGN/ 下的文档，根据需求场景找到对应的 Pattern 和组件定义，再结合 Shadcn 的 Skill 去构建页面。整个过程不需要我再额外解释该用什么组件、该怎么交互了。
从 Foundation 到 Component 再到 Pattern，三个层面补齐之后，我又根据自己数据分析系统的实际需求，补充了一些业务级的组件、Pattern 和页面模板——比如数据源配置流、指标卡片的交互规则、分析报告页的布局模板。这些是 Shadcn 和通用设计系统里不会有的，属于我自己产品的个性化定义。
有了这套东西之后，后续让 AI 帮我构建的新功能，在界面层面基本就没有太多问题了。如果有想调整的地方，也不用改代码，直接去 DESIGN/ 目录下修改对应的文档就能完成全局调整。
写在最后：设计系统 AI 化的轻量方案
之前聊设计系统 AI 化的时候，总觉得让 AI 真正消费设计系统是一件挺重的事情。
可能需要专门的工具链，可能需要复杂的接口对接。但如今再来看这个问题，一套 markdown 上下文文档体系，可能就是一个相当不错的轻量解决方案了。它不一定是最终的答案，但一定是当下一个值得尝试的方向。
而且现在开源的组件库生态已经非常成熟了。像 Shadcn 这类项目，对数字产品常见的基础组件穷举已经相当完善，给了我们一个很好的底子。
我们要做的其实不是从零开始造轮子，而是在这些已有的生态基础上，去做行业化、业务化的具体方案。把通用的组件库变成你自己产品的设计系统。这在以前可能是大团队才干得起来的事，但现在有了 AI 的协助，个人也可以来尝试尝试了。
上期文章聊到 AI 时代设计师的几个可能方向，设计系统是其中之一。
Google 的 DESIGN.md 其实已经给出了一个很好的起点。无论你现在是在用 AI Coding 做产品，还是在探索设计系统的新可能，都可以从一个 DESIGN.md 开始试试。把你的设计经验变成 AI 能读懂的上下文，也许你会发现，这件事值得去尝试尝试。