核心心法：你的 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 应用的底层代码架构给秒出来。虽然结果谈不上天衣无缝，但单看里面抠出来的各种细节，对于只用了一段提示词和一个清晰点子就能跑出来的效果来说，已经惊艳得超出预期了。
最后一波总结干货
记住：DESIGN.md 绝对不是从 Figma 导出的样式指南（Style Guide），也不是单纯的数据倾倒，更不是能丢给 AI 搞无人驾驶的自动化工具。
它是你的“设计系统”与“AI 程序员”之间，唯一能真正听懂彼此的沟通桥梁。
Token 数据的提取是最简单的部分——对你如此，对 Claude 亦然。
而讲清产品简介、设计意图、设好限制和禁区：才是你真正显能耐、也最值钱的硬活。
最妙的是，当你为了调教 AI 把这些脏活累活干完之后，你会发现：这玩意儿的价值早就超越了 AI 工具本身。这本身就是一份顶级的设计系统文档。AI 看了能开挂，后续接手你项目的任何设计师或开发，看了也得跪谢你留下的造福后人的祖传代码。
