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 的大结构，在谷歌官方的模板中了解到是由两部分组成：

• YAML 格式的 Token：给机器阅读，提供精确、结构化的设计 Token；
• Markdown 格式的描述：给人和 Agent 阅读，提供设计背后的原因和使用指南。

我也在 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 部分，先分析官方的模板：

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 都要写上具体用法。

新东西倒是有一些。比如 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 具体的效果。

其实用起来很简单，在搭建原型 DEMO 的时候，如果没有特殊指定某个风格，AI 就会默认使用集团官方的 B 端设计系统来开始搭建页面。

对我来说，最大的收获是在设计 SKILL 的过程，有些细节是经过设计的，也踩过坑，这里逐一分享。

约束 Agent 行为

这是一份可被用户通过自然语言来调用的 SKILL，这意味着用户发送的内容是不可预测的。如果不加一些设计和约束，SKILL 执行的效果也将由 LLM 自由发挥，具有强烈的随机性。

举个简单例子，用户给出「给当前界面换个风格」这种意图不明确的指令时，LLM 基于本次的推理，可能会采取以下方式中的其中一种：

1. 直接替换为我们设计组维护的设计系统（因为在提示词里我们让 Agent 优先推荐官方的设计系统）；
2. 基于大模型的理解，直接在库里选一个风格并替换；
3. 把所有风格全列出来让用户选；
4. 追问用户明确需求，比如：你喜欢什么色系？要暗色的还是亮色的？
5. 还可能有其他做法...

这种不确定性会影响 SKILL 的功能和质量。其中第一、二种方式，属于无沟通的直接替换，很可能无法一下子满足用户诉求，造成多次返工，浪费时间和 Token。而第三种：全部把名字从 A-Z 列出来，缺乏视觉与风格特征参考，用户无法直观感知差异，决策成本也很高。

我作为 SKILL 的设计师，其实我可以在这里做一些处理。我希望当用户没有指明某个系统时，Agent 能遵循统一的处理方式：询问用户并提供恰当的选项 —— 使用 AskUserQuestion 工具。

所以我在 SKILL 里做了一个逻辑，如果用户未指定设计系统，LLM 执行推理：

1. 理解当前系统业务属性（AI 自行判断，可能会基于页面标题、路由等项目信息 ）；
2. 与当前 SKILL 里的所有设计系统的风格进行匹配；
3. 选出最贴近的 3 个设计系统，各附一句推荐理由。并通过 AskUserQuestion 组件列出选项询问用户意向，其中：
   1. 第 1 个选项固定是我们首推的集团 B 端设计系统；
   2. 其他 2-3 个选项则是基于当前系统特点给出的推荐的选项。

最终效果如下图所示，在用户发出模糊的需求时，会出现表单让用户明确需求。

在做这个优化点的时候，我脑海里突然闪过一丝火花 —— 这看起来很像是以前设计方案时我们做选项/默认值的优化思路。另外其实这种边缘场景还有很多，比如：

1. 当用户指明要换一个不在 SKILL 内的设计系统时；
2. 当用户选择了一个和当前风格一致的设计系统时；
3. 当用户发出一些自相矛盾的需求时；
4. ...

就像在传统设计链路里，如果设计师没有给出某个状态、场景的设计方案，那开发可能就会自由发挥了。

字体适配

部分设计系统可能会用到特殊字体。比如我们集团 B 端规范里面要求数据看板的字体用 DIN Alternate、IBM Carbon 的品牌字体是 IBM Plex Sans，而 Claude 则是 Anthropic Serif。

因为用户大概率本地是没有安装这些特殊字体的，就算替换了 CSS 样式的 font-family 也不会生效。

所以同样，如果不在 SKILL 中向明确执行步骤，AI 就会自主执行，最终目标字体可能不会真正呈现在用户界面上。

对于这个场景，我做了以下处理：

1. 遍历当前所有内置设计系统里的非系统字体，输出一份 md 文件和特殊字体表；
2. 区分哪些字体是能 通过 Google Fonts CDN 加载，哪些字体不能；
   1. 能从 CDN 加载的就在 Markdown 里补一个 @import，表明加载路径；
   2. 不能在线加载的商业字体，我就手动把字体文件扒下来放进 SKILL 库里作为静态资源调用。
3. 在 SKILL 里补充对字体处理逻辑，分两条支线：通过 CDN 加载和调用静态资源。

在明确告知 SKILL 处理方式之后，Agent 遇到特殊字体的情况也会按照 SKILL 描述的步骤去做。最终效果很稳定：

成本优化（踩坑了）

踩坑实例

最初我根据 AI 循序渐进的引导，把切换设计系统的方法写得很详细。我分了两条路径：新建应用和存量应用。以后者为例，我是这样要求 Agent 去替换主题的：

1. 并行读取：`DESIGN.md`（设计规范）和 `re-theme-system.md`（映射规则）；
2. 启动 subAgent 扫描并阅读项目文件，按全局 CSS / 共享组件 / 页面文件进行分类；
3. Phase 1：
    1. `@theme` 块替换：针对全局 CSS 文件，提取新设计规范中的全部 Token，生成新 CSS 变量后整体替换旧 `@theme` 块；
    2. 字体处理：通过 Google Fonts 或静态资源的方式引用字体，并写入样式表；
    3. 追加组件结构基类。如：`.btn`、`.btn-icon`、`.input-base`、`.tag-base` 等。
4. Phase 2：
    1. 语义 class 重映射。去除尺寸 class 并加挂基类、替换内置色板 class 为语义 Token、对齐字体/字号/间距、清除所有任意值写法。
5. 修改完成后校验一致性。全局扫描残留的内置色板 class、缺失的 body 字体兜底声明等，发现遗漏则单独补执行 Phase 2。
6. 操作边界约束。只允许修改 className/class 属性中的 Tailwind class 字符串以及 CSS 文件中的 @theme 块。业务逻辑、DOM 结构及第三方组件库样式一律不得触碰。

我当时没有察觉到问题，毕竟从互联网上我学习到的就是「SKILL 就像是给实习生员工的操作手册」，明确告知 Agent 每一步，似乎很合理。

但是看到测试结果后，我惊呆了。对比前文提到的「直接丢 Markdown 让 AI 自己改」，通过 SKILL 进行设计系统的更换耗时非常久，而且效果也比前者差了很多 —— 只改了颜色、投影等参数，没有理解到 DESIGN.md 里的精髓。

都是引用同一份 DESIGN.md，为什么用 SKILL 转换的效果这么差？

感觉不对劲后，我想让 AI 帮忙做点优化，所以先将 SKILL 替换过程的 Claude Code 运行日志发给 AI 来，让其分析原因和改方案。这是日志原文：

后面基于 AI 给的建议，我修改了一版 SKILL，然后立马测试了一遍，发现根本没效果，甚至还比之前的慢了。

我开始意识到纯靠 AI 是靠不住的，还是得自己想办法。

我的优化方案

一轮分析后，我想到「直接丢 Markdown」的效果好，这说明 Agent 本身就有自主规划更换设计系统的能力。我写这么多只是在强迫 Agent 集中注意力做我写的事情（数据为例：Read 两份指引文件引发了 17,588 个 thinking 字符数）。

所以我重新聚焦最初的目标，决定大幅精简 SKILL 的内容。不再事无巨细地指导 Agent 工作，而是仅保留最核心的三点能力：

1. 主题路由： 提供各个设计系统的简单介绍和文件路径。不用浪费时间查找和阅读完整 Markdown 就能知道各个设计系统的特点；
2. AskUserQuestion 逻辑： 写清楚什么情况下要主动询问用户来明确需求，以及选项的做法（上文有提到）；
3. 字体路由： 通过 Prompt 约束 Agent 换字体的方式，并给出相关资源路径。

用精简后的 SKILL 再跑一遍完整流程，质量一下子提上来了。AI 在任务中的阅读、推理等消耗骤降，注意力得到大幅提升。下图作为对比：

这里附上这几次实验具体的结果：

这次 SKILL 优化效果显著，也体现在代码行数上面。SKILL.md 主文件从 240 行缩减到 50 行，而且也直接删掉了新建/存量路径的操作指引文件（共 383 行）。一共删了 623 行。

根因复盘

其实真正改样式、写代码的时间和内容长度是差不多的。导致时长和费用爆炸的根因是 thinking 过程。

错误一：滥用 sugAgent
第一版的 SKILL 我强制 subAgent 并发去扫描并阅读项目文件，然后 subAgent 花了很多时间去理解文件，输出内容后返回给主 Agent。此时主模型拿到一大堆新信息，同样也要要理解、推理很长时间。

但实际这种项目文件没有必要单独开 sugAgent 去理解，使用场景就不对。子 Agent 应该用在能输出简短结论的场景，起到并行思考的作用。初版 SKILL 只是把内容复述给主 Agent，完全是负作用。

反观优化版是 Agent 自主去发现文件，不需要重复理解内容。两份 SKILL 在同一个任务里，总 thinking 字符数分别是 21,138 和 2,160，优化版少了 90% 的推理过程。

错误二：滥用 Shots
同时在我修改主题指引的文件里写了太多示例（约 100 条），而且写得特别细。

/* Button — structural base. Paint with color utilities */
.btn {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  padding: var(--btn-padding-y) var(--btn-padding-x);
  border-radius: var(--btn-radius);
  font-size: var(--btn-font-size);
  font-weight: var(--btn-font-weight);
  line-height: 1;
  cursor: pointer;
  border: none;
  gap: var(--spacing-xs);
  transition: background-color 0.15s;
}
 
/* Input — structural base. Paint border/background/text colors on element */
.input-base {
  padding: var(--input-padding-y) var(--input-padding-x);
  border-radius: var(--input-radius);
  font-size: var(--input-font-size);
  border: 1px solid;
  outline: none;
  transition: border-color 0.15s;
}

比如：要求 Agent 必须按某种方式命名 Token、必须做几个常用的样式类名等等。这极大地增加了负担，让模型过度去拟合示例中的具体形式忽略掉本质。但实际上 Agent 本身就有能力做到，不需要额外的提示。

以后做 SKILL 时，只在我们有特殊 Schema 要求的情况下才提供 Shots，Agent 自己能做到的就不要额外添油加醋。而且先从 Zero-Shot 或 Few-Shot 方案开始，通过测试来看效果，效果不好再慢慢加，控制数量。

这么多血和泪总结起来一句话：

Agent 本身有自主规划的能力，SKILL 里只给最关键的信息、防止 Agent 绕弯路的信息即可。写得太多、太细反而增加推理成本。

产品化

把 SKILL 做出来并验收通过后，其实我们就具备了让 Agent 给应用赋予特定设计系统规范的能力。通常 SKILL 有两种启动方式：

• 自然语言触发 ：LLM 理解用户发送的文本，并与 SKILL 内的 description 字段进行语义匹配，命中后启动；
• 指令触发 ：用 /skill-name 的形式直接指定 SKILL，Agent 基本不需要判断。

除了以上两种形态，我还想把门槛做得再低一点，将其包装成一个可视化的 GUI 的形态。所以我在集团内部应用搭建平台的对话框里面增加一个按钮作为触发器。

具体使用路径

如果用户在创建新应用，输入框内部会有个「设计系统」的按钮，点击后会出现弹窗给用户选择。选择其中一个后，用户接下来创建的应用就默认会符合该设计系统。

至于存量应用，则是在编辑页面，点击按钮来唤起一个选择设计系统的浮层。点选任意一个并确定后，直接调用技能的更换设计系统能力。

总结

通过这个项目我觉得有一点很新鲜的是：我们设计师以前总是提到「以用户为中心设计」，现在要在 AI 生态下做建设，就要转变为「面向 LLM 设计」。

另外，做 SKILL 时踩的坑，也让我明白了一个道路：AI 给的建议不能全信，得有自己判断力。虽然 AI 可以几秒钟就生成一大篇方案，但如果不加思考地全盘采纳，效果一定很差。

完整地做完这次 AI 探索项目之后，总结起来我有三点比较深刻的感悟：

1. 设计资产格式转换： AI 时代下，设计资产需要对 AI 友好。不仅是设计系统、设计规范，包括我们日常需求的设计产出物，验收文档等等。这应该是一个大趋势——所有沉淀下来的资产，都应该对 AI 可读；
2. 成为 AI-Native： 想要在 Agent 生态下做一些建设，就要学习 Agent 是怎么运作的。不然对着一个黑盒来优化效率很低；
3. 多做测试： AI 相关的工作不像平常的设计任务，在没有太多实践经验时，心里对预期结果是没底的。需要根据测试结果再一点一点调。多花点时间在实验上面，比一直在捣鼓方案、纸上谈兵要有效得多。

接下来

项目结束后，我能明显感觉到 DESIGN.md 的短板。这不是一份万能的提示词，但我觉得我们或许可以通过 Harness 来逐渐补足、调优。

我目前想到以下三个优化方向，在这里也记录下来吧。

组件库场景

前文提到 DESIGN.md 是无法影响到组件库样式的，但恰好我们公司内部的组件库支持进行「主题配置」。

我们内部有一个主题编辑器，支持对系统的全局样式和组件维度进行样式定义。因为是内网工具无法公开公开访问，但可以想像为类似 Ant Design 的主题编辑器。

我觉得结合 DESIGN.md 做一些编排，可以解决掉组件库的场景。

初步想法是这样：

1. 我们需要一个转换能力：给一个DESIGN.md，能根据特征转化为主题编辑器的配置参数；
2. 将其编排进换主题的流程里：SKILL 里进行风格更换时，在 Agent 基于 DESIGN.md 进行修改样式的同时，也把主题编辑器的配置引入系统。

最终可以做到全页面覆盖：组件相关的风格读取主题编辑器，组件以外的部份则按照 DESIGN.md 来还原。

效率和性能

使用 DESIGN.md 来生成页面是有成本的。这是一份数百行，甚至上千行的提示词，加载 DESIGN.md 之后，AI 生页面的速度会被明显拖慢。

尤其是每次加载就必须是全量加载，很容易把上下文撑爆。所以是不是也能做到按需加载，这是可以探讨的方向。

功能扩充

目前我的 SKILL 只能在我提供的若干份 DESIGN.md 里选择主题风格，但其实社区上有很多开源免费的资源。

如果 SKILL 支持从几个公开资源库里检索主题，能让主题的丰富程度大幅提升，还能更好地满足不同用户的喜好，也是一个可以扩展的方向。