我要投稿

怎么写一份 Claude 真正能看懂的 DESIGN.md 文件？

发布日期：2026-06-17 07:55:29 浏览次数： 1613

作者：番阅

微信搜一搜，关注“番阅”

核心心法：你的 DESIGN.md 应该讲好一个产品故事，而不是干巴巴地列账单。

原作者：Lisa Demchenko ｜原标题：How to write a DESIGN.md file Claude can actually use | 翻译：蕃茄酱

最近你们的社交媒体信息流，是不是也天天被 DESIGN.md 这玩意儿刷屏？

前阵子我一不小心掉进了这个技术大坑。我一口气扒了几十份公开的 DESIGN.md 文件，还亲自动手给一个真实项目从零写了一份，最后——可能嫌自己还不够——我干脆写了一个专用的“Claude Skill（指令技能）”把整套流程给固化了下来。

本来只是出于好奇，结果一通折腾下来，我顺手摸清了一个极为管用的门道：为什么有些 DESIGN.md 能让 AI 写的代码极其惊艳，而有些文件却只能让 AI 默默写出一堆垃圾代码？

如果你还没听过这玩意儿，简单科普一下：DESIGN.md 就是一个纯文本文件，用来给 Claude Code、Cursor 这种 AI 编程工具“投喂”你的设计系统规范，好让 AI 还原界面时别太放飞自我。理论上，它能让 AI 完美复刻你的产品视觉；但现实是，市面上绝大多数文件，都把最核心的灵魂给写漏了。

第一阶段：拆解市面上的“大路货”

我干的第一件事，就是把市面上能找到的各种文件翻了个遍——既有大牛精心雕琢的，也有 GitHub 上大搜罗来滥竽充数的。说实话，有些确实走心，但绝大多数……不看也罢。

这里面有个非常明显的翻车规律：几乎所有不及格的文件，一上来第一行绝对是色板（Color Palette）。

这简直莫名其妙。在第一行十六进制色号（Hex Code）出现之前，没有任何业务背景，也没有设计意图。不解释这个产品是干嘛的、给谁用的、在这个特定业务场景下什么才叫“正确的设计决策”。

这些不及格的文件做的是“描述”： 告诉 AI 系统“长什么样”。

而 AI 真正需要的是“限制”： 告诉 AI 系统“允许干嘛”、“绝对禁止干嘛”，以及“遇到极端边界情况时该怎么兜底”。

这是两种完全不同的写作逻辑。把描述当成了限制，正是导致 AI 写出来的 UI 充满廉价感、忽左忽右的罪魁祸首。

Surface (表面/底色)Pure White ({colors.canvas} — #ffffff): 主画布底色。用于承载内容、功能卡片、店铺平铺块、配置器网格。Parchment ({colors.canvas-parchment} — #f5f5f7): 经典的苹果风暖白/浅灰。用于交替出现的浅色平铺块、页脚区域，以及店铺工具部分的默认页面画布。它与纯白有着微妙的差距，刚好足以营造出视觉节奏感。Pearl Button ({colors.surface-pearl} — #fafafc): 一种接近白色的浅色，用作次级“幽灵按钮（Ghost Button）”的填充色 —— 它比 parchment 画布更浅一些，因此当按钮放在 {colors.canvas-parchment} 背景上时，依然能被清晰地识别为一个按钮。Near-Black Tile 1 ({colors.surface-tile-1} — #272729): 首页产品网格上的主要深色平铺块表面。Near-Black Tile 2 ({colors.surface-tile-2} — #2a2a2c): 颜色浅了极其微小的一阶 —— 用于深色平铺块直接叠在 Tile 1 上方或下方时，通过极微弱的色彩差异来实现视觉分割。Near-Black Tile 3 ({colors.surface-tile-3} — #252527): 颜色深了极其微小的一阶 —— 用于堆叠底端以及内嵌视频/播放器的框架。Pure Black ({colors.surface-black} — #000000): 专为“纯黑留白”预留 —— 用于视频播放器背景、通栏（无边框）图片遮罩层、全局导航栏背景。Translucent Chip Gray ({colors.surface-chip-translucent} — #d2d2d7): 半透明灰色 Chip 的基础十六进制色号，用于悬浮在图片上方的圆形控制按钮。在生产环境中，实际应用时需开启 64% 的不透明度，表现为 rgba(210, 210, 215, 0.64)。

公共库里的DESIGN.md 的例子

而那些最顶级的标杆文件，都有一个共同的杀手锏：把设计推导逻辑直接缝进 Token（设计变量）的定义里。

❌ 错误示范：
```
primary: #1B4DFF
```
✅ 正确姿势：

primary: #1B4DFF —— 仅用于主按钮（CTA）和激活状态。严禁做背景色，严禁做纯装饰。一个屏幕原则上只允许出现一个主操作。如果你想放两个，重新考虑排版布局。

这就是核心公式：先给数值，再给意图，最后给边界。 而“边界”这层防线，大部分人压根就没设。

第二阶段：硬核手写一份 `DESIGN.md`

纸上谈兵没意思，我决定给自己的一个真实项目——Oooff（一个我自制的旅游规划 Web 移动端应用原型）——从零手写一份 DESIGN.md。在这个过程中，我学到的东西比单纯看别人案例多得多。

想写好，第一件要死磕的事就是前后顺序：

一上来先放“产品简介”（Product Brief）： 在列任何设计 Token 之前，先用两三句大白话把调子定死：

这个产品是帮用户干嘛的？
谁会用它？
界面必须要帮用户搞定什么核心任务？

在模型读到任何颜色数值之前，这段大白话就已经在潜移默化地规范它后面所有的生成逻辑了。

接着列 Token： 记住，字字句句都要奔着“立规矩/做限制”去，别写废话。

然后是字体排版（Typography）： 别光丢个字号大小，说明白每一级字号在什么时候用，以及绝对禁止在什么时候用。

再然后是组件逻辑（Component Logic）： 这也是很多看似完整的 DESIGN.md 最常翻车的地方。别光说一个卡片长什么样，你得告诉 AI “什么时候该用卡片，什么时候该用单行列表”。缺少了这一层决策逻辑，AI 还原出来的界面绝对一天一个样。

压轴大戏：“避坑指南/绝对禁止”章节（The Don’ts Section）：

这部分的分量比大部分人想象的沉得多。也就是明确列出这个系统绝对不会干的事。比如：全站严禁使用渐变色；状态色具有排他性，严禁乱套；报错状态必须“文字+颜色”双重提示，严禁只改颜色。八条一针见血的铁律，效果直接秒杀你把 Token 列表的体积扩大一倍。

不过说实话，写这个“绝对禁止”章节挺熬人的。

你必须对自己的设计系统了如指掌，才能精准说出它“绝对不干什么”——绝大多数设计师以前在搬砖时，还真没被逼着把这些黑白分明地敲成文字过。

第三阶段：把方法论做成 Claude 专属技能

在踩完一轮坑之后，我意识到：写好这玩意的正确姿势确实反直觉，但它的底层套路是可以复制的。于是，我直接写了一个 Claude Skill。

## 步骤 1：动手撰写前的“强制访谈”
在开始自动生成任何内容之前，必须先盯着用户回答 3-4 个核心问题。这些答案将直接决定后续文档里的每一项设计决策。这一步绝对不能偷懒跳过 —— 缺少了产品业务背景写出来的 `DESIGN.md`，只会让 AI 吐出一堆毫无特色的大路货代码。
提问模板：
1. **产品是干嘛的？** 用一两句话概括：它是解决什么痛点的、给谁用的、在什么特定场景下用（例如：移动端、桌面端、用户处于时间紧迫的压力状态下等）。2. **目前有现成的设计变量吗？** 比如色板、字阶、间距规范 —— 还是说咱们这次得从零开始抓起？3. **界面必须死守的核心原则是什么？** 也就是该用户界面要扛下的那件最核心的任务（例如：“必须让用户一眼就能看清当前状态”、“绝对不能让非技术用户产生认知过载”）。4. **这个系统绝对不会干什么？** 明确那些不可触碰的铁律 —— 比如绝不用渐变色、状态色具有排他性、一个屏幕只允许放一个主按钮。如果用户一时半会儿想不清楚，你要引导他们把这些规则盘出来。
如果用户已经扔给你一份现成的 `DESIGN.md` 让你优化，先把它通读一遍，然后只针对漏掉的核心关键点进行追问。
---
## 步骤 2：优秀 DESIGN.md 的骨架结构
严格按照以下先后顺序来构建文件。每一个章节都有它不可替代的卡位价值。
### 1. 产品简介（雷打不动放第一位）在列任何设计变量之前，先用两三句话定下大调。说明白产品是干嘛的、给谁用的、界面得帮他们解决什么核心卡点。这段简介会直接规范模型接下来的所有下层代码决策 —— 绝对不要让 AI 看着一堆色号去瞎猫碰死耗子般地自己脑补业务背景。

这个技能只要一启动，在生成任何文档之前，会强行卡住 AI 走一个“强制访谈流程”。AI 必须先回答四个问题，以此锁死产品背景、现有 Token、UI 的核心使命和限制条件。

接下来，它会死死按住 AI，逼它按照最完美的顺序去吐文件：产品简介 ➡️ 带有意图和边界的 Token ➡️ 带有决策逻辑的字阶 ➡️ 组件说明 ➡️ 绝对禁止章节。

为什么要写这个 Skill？因为哪怕 AI 智商再高，只要你放任不管，Claude 绝对会选最省力的偷懒路径——直接从 Figma 里把色号 Token 扒出来往文件里一丢，然后打卡下班。 必须用规矩把它的底线卡死。

第四阶段：让 AI 自己写一份 `DESIGN.md`

为了测试，我把 Oooff 这个项目的 Figma 设计稿（包括 UI 界面和 Token 资产库）全喂给了 Claude Code，让它用我写好的那个 Skill 自动生成一份 DESIGN.md。

Oooff的设计参考

不得不说，AI 的“数据提取能力”强到令人发指。

它把我所有的底裤都看穿了：全套色板（精确到 Hex 值和不透明度变体）、完整的 Inter 字体字阶（连字距 Tracking 值都没漏）、间距 Token、圆角、阴影，甚至连我设计的一个微型内凹按钮的视觉小花招都被它扒了出来。所有组件的解剖结构一览无遗，每个像素都精准无误。

## 产品简介
Oooff 是一款旅游规划 Web 应用，它能结合用户所在国家的年假和公共假期来帮助他们规划假期。用户可以一眼看清自己剩余的假期天数，在周视图/月视图日历中轻松查看已规划的休假时间与公共假期的重叠情况，并可以申请请假或浏览 AI 自动生成的近期行程。该产品设计支持按国家进行本地化适配。用户界面（UI）必须做到在几秒钟内让假期余额和请假状态清晰易读 —— 它的使用特征是单次停留时间短、使用频率高，且需要达到“零学习成本”。
---
## 设计原则
**状态大于装饰。** 绿色的品牌色带有明确的业务含义 —— 它代表“属于你的”（你的日历、你的时间、你的假期）。色板中的其他所有颜色要么是中性色，要么代表特定的分类。如果某个颜色不能传递任何明确的信息，它就不应该出现在界面上。
**卡片作为聚焦单元。** 布局通过边界清晰的卡片面板来划分用户的注意力。每张卡片只承载一项核心任务。严禁为了节省空间而把不相关的信息强行组合在一张卡片里。
**克制的密度。** 这是一个日历工具，因此屏幕上会有海量的信息。间距系统需要极力保持界面的呼吸感，同时又不浪费空间。如果拿不准，卡片内部应该留白多一点，而不是少一点（多用 padding，少用内缩）。
**导航始终保持一致。** 顶部导航栏是固定的、带有毛玻璃效果，并且在所有视图中的结构完全一致。严禁在导航栏区域强行塞入页面主体内容。

然后，我给它发了一句：“老实交代，你刚才到底用没用我给你的那个 Skill 流程？”

Claude 的回答挺让人玩味的：

“说实话，只用了一部分。我把它当成了格式排版指南，但我偷懒把最核心、能让这份文件真正出彩的部分给跳过了。”

这就是整件事最关键的转折点。

它跳过的是什么？恰恰是第一步的“访谈”。 那些关于产品是干嘛的、用户是谁、界面该坚持什么、摒弃什么的高层思维。相反，Claude 采取了“盲猜”。它根据现有的 Figma 界面，自己脑补了产品的业务目的，自作聪明地现编了一套设计原则，并根据看图说话看到的视觉规律，自己发明了一堆限制条件。

数据全对，但逻辑全是编的。这就露馅了。

Claude确实极度擅长“看图抠数字”，给它个设计稿，它连多少像素都能一毫不差地给你扒下来。但背后的核心逻辑（Why）——比如产品简介、设计原则、防线边界、绝不妥协的底线——依然得靠设计师脑子里的底层思考。如果你把这一层思考留白，AI 就会自作聪明地用它那套“听起来挺像那么回事的瞎编推理”把坑填满。但那根本不是真正的业务逻辑，那只是统计学概率的文字游戏。

如果你也想用 Claude 亲手盘一份自己的 DESIGN.md，可以去试试我公开的这个 Design-md.skill 专属技能。

https://github.com/llsbet-digital/Claude-design-md-skill

最后，我还做了一个极限测试：只用这一份 DESIGN.md 加上两张产品截图，配合一段非常具体的长 Prompt，看 Claude 能不能直接把一个 Web 应用的底层代码架构给秒出来。虽然结果谈不上天衣无缝，但单看里面抠出来的各种细节，对于只用了一段提示词和一个清晰点子就能跑出来的效果来说，已经惊艳得超出预期了。