> ## 文章索引
> 在这里获取全部文章的索引：https://lrd.im/blog/llms.txt
> 这是 lrd.im 的个人博客，记录设计、技术与思考。
# DESIGN.md 企业内落地实践与踩坑复盘分享
## 项目背景
我当前所处的团队属于设计中台，负责制定和维护集团内部 B 端业务的组件库、规范等，同时也为一些业务线做设计。我们有一套 B 端设计系统（包含颜色板、字体梯度等风格规范）。
这是在 AI 时代之前产出并推广的，我们确实也成功推广到绝大部分的 B 端业务线里。但是 AI Coding 成为主流后，集团内涌现了新的产品开发模式。比如：
1. 开发在用 Code Agent 来做前端界面；
2. 产品在用自然语言生成网页的工具来做原型设计或甚至直接投入使用。
在这样的背景下，我们发现了三个痛点：
1. **AI 产出同质化：** 直接用 AI 做出来的页面风格大多千篇一律（蓝紫色主题、大圆角大投影等）。用户觉得不好看，但他们不知道怎么优化；
2. **设计系统成为黑盒：** 大模型无法高效地从 Figma 源文件或图文文档中提取信息。曾经广泛应用在公司内部系统的设计系统，在 AI 工作流里隐身了；
3. **设计的影响力在减弱：** 在一些场景，AI 和自然语言建站工具已经能绕过设计师了。如果集团内所有 AI 生成的项目里都没有设计师的影子，我们团队的影响力会持续减弱。最坏的情况是：连存在的必要性都会受到质疑。
## 改造规划
针对以上痛点，我们希望在 AI Coding 的流程中也有设计的介入，所以我们认为需要将设计资产转为可被 AI 消费的形态 —— DESIGN.md。
光有一份提示词文件是不够的，其他部门、其他角色怎么用起来呢？总不能给一个下载链接让别人每次 AI 写页面都引用着来吧。所以要用一个 SKILL 把整个搭建设计系统、更换设计系统的过程包装起来。
最终这次项目的产出会是以下内容：
#### 1. 集团 B 端设计系统 DESIGN.md
- **形态：** 一份 Markdown 提示词文件，承载的结构化设计系统设计资产；
- **定位：** 作为原始资产，让设计系统变为对 LLM 友好的格式，在 AI Coding 链路上可被消费。
#### 2. 设计系统 SKILL
- **形态：** 一份 SKILL 压缩包。分发到集团内各种渠道，如 SKILL 市场、AI 原型搭建平台和 AI 应用搭建平台等；
- **定位：** 通过内置设计系统文件，让 DEMO 页面和轻量应用等能快速输出符合集团设计规范的界面。
接下来会详细介绍在做这两件事情时我的思考过程，设计亮点以及具体的实现效果。值得一提的是，下半段还有踩坑记录 + 复盘反思，充满了血与泪。
## DESIGN.md
### 调研
在开始之前我先了解了下 DESIGN.md 的大结构，在[谷歌官方的模板](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md)中了解到是由两部分组成：
- YAML 格式的 Token：给机器阅读，提供精确、结构化的设计 Token；
- Markdown 格式的描述：给人和 Agent 阅读，提供设计背后的原因和使用指南。
我也在 [Awesome DESIGN.md](https://github.com/voltagent/awesome-design-md) 里找了几份样例。看看其他人是怎么写这份文档的，主要是去尝试寻找共同点，同时思考我们的设计规范如果转成 DESIGN.md 时，有哪些注意事项。
#### YAML 部分
前半部分的 YAML 还算简单，其实就是把我们的颜色、文字、圆角、间距梯度列出来，但有一点需要注意的是：**Token 名称尽量语义化**，让 AI 在读取 Token 名时就已经知道用在何处，直指意图。
比如主题色叫 `primary`、背景色叫 `canvas`、正文色叫 `ink`。避免使用无意义的序号，如 `brand-6`、`text-1` 等。
另外，我还我发现所有 DESIGN.md 都至少会包含这三个组件：`Button`、`Input` 和 `Card`。
我理解这三个是最能影响整体风格的组件，所以要写得详细些。尽量把各种状态的样式都写出来（悬停、按下、聚焦、错误等）。同时样式参数要尽量引用上方写到的 Token 名，避免用绝对值如 `8px` 这种。
#### Markdown 部分
在 Markdown 部分，先分析官方的模板：
``` json
1. Overview
2. Colors
3. Typography
4. Layout
5. Elevation
6. Shapes
7. Components
8. Do's and Don'ts
```
虽然模块不少，但拉远来看，其实都是以前的东西。开始会先有一段 Overview，用氛围词来做主观描述，定调。比如：
- 描述品牌气质，如：_Claude.com is **the warmest, most editorial interface** in the AI-product category_
- 类比其他参照物，如：_Claude reads **like a long-form magazine column** rather than a marketing template._
- ...
这和古早时期作品集里流行的「情绪板」有点像，只是这里会用一段话来描述，包含核心理念，层级体系等。个人理解是本身 LLM 阅读到这些词语之后具体会做什么也是充满不确定性的，所以细究用词没意义。设计师给些关键词，让 AI 润色生成即可。
除此之外，还有一些内容其实和以前写的设计规范大同小异。比如：不同档位的文字色分别要在什么场景时使用、各档位的间距怎么区分等等。每个 Token 都要写上具体用法。
| Token | Value | Usage |
|---|---|---|
| `{spacing.xs}` | 4px | Icon-to-text gap, metric card inner element spacing |
| `{spacing.sm}` | 8px | Component internal spacing, compact form item horizontal gap, tag spacing |
| `{spacing.md}` | 12px | Form item spacing, grid gutters |
| `{spacing.lg}` | 16px | Universal spacing — card padding, inter-card gap, inter-module gap, sub-container padding. When in doubt, use 16px |
| `{spacing.xl}` | 24px | Modal padding |
新东西倒是有一些。比如 _Do's and Don'ts_ 和 _Known Gaps_，但这些都不难，把设计系统里的一些大原则写进去即可。
### 制作过程
分析过几份 DESIGN.md 之后，我想到如果真要自己手工从零到一写一份，那工作量得多大呀！于是我用了一个取巧的方式。
> 我在社区上找了一份与我们公司设计风格相似的 DESIGN.md，以此为骨架，再逐步调整、补充属于自己的内容。
毕竟是拿的社区公开资源来改，细节丰富程度是达不到预期的。我要做的就是把我们设计系统的要求、细节补充上去，让颗粒度尽可能地接近我们设计组最开始定下来的那套设计规范。
氛围词的部分没有想象中难，因为 B 端后台长相都是大同小异。加上我内心也觉得 LLM 怎么理解氛围词本身就带有一点**随机性**，所以这里我没有花很多时间来写 MD 部分，反而是在不断的测试中看效果、调整。
重点是确保各种梯度和组件写得够全，稍微使用频率高一点的组件，都写进去了。
### 验收效果
在不断调整和补充后，属于我们设计组的 DESIGN.md 出炉了！验收阶段，我当时是直接把这份 DESIGN.md 发给 AI，然后给一句指令：「换成这个风格」。AI 很快就能完成，而且效果也不错，乍一看是和我们设计系统整体风格差不多了。
下面简单展示下使用效果，点击图片可查看用 DESIGN.md 优化过后的页面效果：
### 局限
对于 Vibe Coding 出来的页面——比如产品演示 DEMO 这种一次性静态网页——DESIGN.md 的表现是令人满意的。转换的质量确实很好。
但我在测试阶段体验的过程中，也发现了 DESIGN.md 有明显的短板。
#### 组件库场景场景
对于已经引用了组件库的项目，DESIGN.md 对此束手无策。通过 NPM 包引用了外部组件库之后，在页面里其实不会包含这些组件的样式，Agent 想改也无从下手——总不能每个组件的细节都以覆盖样式来修改。
#### 效果随机
使用 DESIGN.md 进行新页面的设计或原有页面重构时，出来的结果仍然会带有一定随机性。比如有时会会给卡片容器加上描边，有时却不会；两次生成的容器内部间距不同等。
不过这也在预料之内，DESING.md 本质上也是一份提示词文件，AI 工作本身就有一定随机性。
#### AI 会偷懒
一份 DESIGN.md 文件动辄 500 行、800 行，AI 还要对整个项目页面进行探索发现，注意力一定会降低。
如果对一个小型用 DESIGN.md 重新设计，在没有额外提示词的情况下，AI 不会做很详细功能梳理和重新规划布局，只会按照 Markdown 里的描述改一下间距、圆角、颜色。
### 新的定位
结合对 DESIGN.md 的测试结果和对其局限性的认知。这次任务的目标发生了轻微的改变。
本来我们希望这次的产出能覆盖「开发用 AI 写页面代码」和「产品用 AI 做原型」两个方向。但 DESIGN.md 对第一点的短板很明显。为了保证最终效果，我们的这套 DESIGN.md 改为面向做原型设计、DEMO 页面的场景。
## SKILL
我们面向的场景是中小型的静态页面，这些站点很轻量，不像业务系统那样有复杂业务逻辑。所以对于我们要做的 SKILL，需要满足以下功能即可：
1. 在全新的页面/站点初次搭建时就植入设计系统；
2. 在存量项目中套用设计系统规范，类似给页面「换肤」的效果；
3. 除了官方的设计系统.md，也要采集一些外部设计系统的供用户自主选择。适配更多场景和用户喜好。
这里先给大家看看这个 SKILL 具体的效果。