--- title: 把设计系统变成 Markdown：让 AI Coding 真正读懂你的设计约束 date: 2026-04-19 tags: [设计系统, 设计 AI, AI Coding, Markdown] description: Google 提出的 DESIGN.md 让设计系统第一次以 AI 能读懂的形式进入代码仓库。本文从 Claude Code 做产品时的一致性失控问题出发，讲解如何把设计系统拆解为 Foundation / Component / Pattern 三层 Markdown 文档体系，让 AI 每次 Coding 都遵循你的设计约束。 author: 5key source: https://www.thefivekey.com/design-system-as-markdown/ --- # 把设计系统变成 Markdown：让 AI Coding 真正读懂你的设计约束 > Google 提出的 DESIGN.md 让设计系统第一次以 AI 能读懂的形式进入代码仓库。本文从 Claude Code 做产品时的一致性失控问题出发，讲解如何把设计系统拆解为 Foundation / Component / Pattern 三层 Markdown 文档体系，让 AI 每次 Coding 都遵循你的设计约束。 **作者**：5key　·　**发布于**：2026-04-19　·　**原文链接**：https://www.thefivekey.com/design-system-as-markdown/ --- ![OFF DESIGN 45 封面：把设计系统变成 Markdown，让 AI Coding 读懂设计约束](design-system-as-markdown-cover.webp) > **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 的一致性为什么难以保证 拿下面这张图来举个例子。这是我在同一个项目下、不同阶段开发的两个功能界面。 ![Claude Code 在同一项目不同阶段产出的两个界面，菜单、Tab、输入框样式出现明显不一致](ai-coding-ui-inconsistency.png) 菜单、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 的上下文。 来看看官方的基础案例： ```markdown # 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](https://github.com/VoltAgent/awesome-design-md) 其实到这一步，DESIGN.md 已经让 AI Coding 进步很多了，至少界面风格上的一致性有了保障。但如果你真的拿它来做一个完整的产品，你会发现它其实还不够。 ## 从 Foundation 到 Component 再到 Pattern：完整设计系统的 Markdown 化 如果按照我们的对设计系统的定义，DESIGN.md 其实只是做了 Foundation 层的工作，关注的是色彩风格、字体排版等基础设置。但一个真正能用的设计系统，Component 层和 Pattern 层的定义是必不可少的。（关于设计系统的三个层级，可以参考 [设计系统学习指南 - 国内外 Design System 案例解析](/how-to-learn-from-other-design-systems/) 和 [如何规划 B端 设计系统？深度解析 AWS CloudScape](/b-end-design-system-deep-dive-aws-cloudscape/) 这两篇） 开始如果让我自己手动去对每个组件和 Pattern 写一份文档，这事儿我着实不太相干。于是我干脆直接把 Shadcn 的组件文档扔给了 Opus，想让它面向 AI 使用的视角先来帮我整理个基础版本，我再来逐条优化。 结果有点意思，效果比我预想的要好。 Shadcn 的官方文档详细解释了每个组件的参数配置，但缺少「什么时候用」的说明。所以每次调试的时候我都会把文档链接扔给 AI，让它读完再动手。浪费时间也浪费 token。 但由于我在项目的上下文初始化中写了很多的 Do 和 Don't，Claude 可能识别到了我的这个习惯，于是在扫描生成文档的过程中，也加上了对 Do 和 Don't 的定义，指定了什么场景该用这个组件，什么场景不该用。这其实正好补上了我们前面说的那个缺口。 摘取一下 Alert 组件的文档内容： ```markdown # Alert 页面内静态提示信息，用于引起用户注意。 层级: Component | 来源: shadcn/ui ## 何时使用 - 展示重要的上下文提示（警告、错误、信息） - 页面内持久显示的通知 ## 何时不用 - 临时性通知 → 用 Sonner（Toast） - 需要用户确认的阻断提示 → 用 Alert Dialog ## 常见组合 - 配合 lucide-react 图标增强视觉提示 - 表单顶部展示全局校验错误 ``` 我把 Claude 生成的 50 多个组件的文档都大致看了一下，质量都还不错，稍微修改一下基本就可以直接使用了。 有了这个说明文档之后，AI 在 Coding 时对组件的使用明显改善了不少。再配合上 Shadcn 自带的 Skill，基本上组件层面的问题就不大了。 既然组件的文档梳理工作做得还不错，那 Pattern 是不是也可以交给它试试？ 这次 Claude 帮我整理了 30 多个 Pattern，分成了三个类别：交互流程（Flows）、功能区块（Blocks）、页面模板（Pages），基本能覆盖大部分常见的产品场景了。 再来摘取一个「删除确认流」的 Pattern 文档内容来看看： ```markdown # 删除确认流 触发删除操作后，通过 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 能读懂的上下文，也许你会发现，这件事值得去尝试尝试。 {{< callout type="cta" title="关于这篇文章" >}} 本文是我付费专栏 [OFF DESIGN](https://xiaobot.net/p/offdesign) 第 45 篇的节选。原文还涵盖：DESIGN.md 在 CLAUDE.md 中的组织方式、完整的 Project Template，以及常见踩坑排查。 如果你对设计系统 Markdown 化的实践感兴趣，可以看我在 [OFF DESIGN](https://xiaobot.net/p/offdesign) 的最近一篇——以一个具体的 Pattern 为案例，聊了聊具体怎么做。 {{< /callout >}} --- ## 💡 延伸阅读 - [半年过去了，AI 设计的进展如何?](/progress-of-ai-design-in-ui-interface/) - [一年过去了，AI design 的进展如何？](/current-trends-ai-design-in-interface-design/) - [产品界面的 AI 生成式设计，为什么没人关注了？](/why-generated-ai-ui-design-is-losing-interest/) - [Salesforce 的生成式画布，证明了 AI 在产品界面设计中的可行性？](/salesforce-generative-canvas-proves-ai-ui-design-feasibility/) - [从概念到落地，产品界面的 AI 生成究竟卡在哪儿了？](/ai-generated-ui-not-work/) - [设计系统中的决策树：让设计决策更简单](/design-system-decision-tree/) - [设计系统 · 我们为什么要做 Design System](/why-we-need-design-system/) - [如何规划 B端 设计系统？深度解析 AWS CloudScape](/b-end-design-system-deep-dive-aws-cloudscape/) - [设计师的下一站，成为架构师，还是走向业务？](/designer-architect-or-business/) --- _本文由 [5key](https://www.thefivekey.com/) 创作，原文发布于 [https://www.thefivekey.com/design-system-as-markdown/](https://www.thefivekey.com/design-system-as-markdown/)。欢迎引用，请注明出处。_ _订阅付费专栏「OFF DESIGN」：https://www.thefivekey.com/premium-design-subscription/_