如何编写有效的 DESIGN.md

梯形图转SCL | 博途AI辅助编程文档 | AI模型价格对比 | AI工具导航 | ONNX模型库 | Vibe Coding教程 | PLC在线仿真器 | Tripo 3D | Meshy AI | ElevenLabs | KlingAI | ArtSpace | Phot.AI | InVideo

DESIGN.md 文件不是风格指南导出，如何让 DESIGN.md 讲述你的产品故事？

1、分析现有文件

我做的第一件事是拆解一系列现有文件——既有精心编写的，也有在 GitHub 上流传的抓取合集。有些确实很有深度，有些则……不太有说服力。

规律很快显现出来。几乎每个表现不佳的文件都以相同的方式开头：先是调色板。在第一个十六进制值之前没有上下文，没有关于产品是什么、服务谁，或在该产品环境中什么才算好决策的信息。

这些文件提供的是描述：系统看起来是什么样的。

模型真正需要的是约束：系统允许什么、禁止什么，以及遇到边缘情况时该怎么办。

这两者不是同一个写作任务。把它们当作同一回事，正是为什么这么多 DESIGN.md 文件只能产出平庸结果的原因。

最强的范例都有一个共同点：将设计原理直接嵌入 token 定义中。

不是这样：

primary: #1B4DFF

而是这样：

primary: #1B4DFF — 仅用于 CTA 和激活状态。绝不作为背景色，绝不用于装饰。每个屏幕只有一个主要操作。如果需要两个，请重新考虑布局。

先给出值，再说明意图，最后划定边界。

大多数文件完全跳过了边界。

2、从零开始构建

我决定为一个真实产品——Oooff，一个旅行规划 Web 应用（我自己的 POC）——从零开始构建一个 DESIGN.md 文件。这个过程教会我的比分析更多。

第一个重要的决定是顺序。

从产品简介开始——在出现任何 token 之前，只写两三句话。

• 产品做什么？
• 谁使用它？
• UI 必须帮助用户完成什么？
• 这个简介在模型读取任何颜色值之前，就塑造了所有后续决策。

然后是 token，为约束而非描述而编写。

接着是 排版——不仅是比例，还包括每个级别何时使用、绝不用于什么。

然后是 组件逻辑——不是卡片长什么样，而是何时使用卡片而非列表行。这个决策层在那些技术上看起来完整但仍然产出不一致界面的文件中始终缺失。

最后是 注意事项 部分。

这部分比人们预期的更重要。系统绝不做的事情。不使用渐变。状态颜色是保留的。错误状态必须始终使用文字加颜色，绝不单独使用颜色。八条精心挑选的规则，在防止不良输出方面，比将 token 部分的大小翻倍更有效。

令人惊讶的是？写注意事项很难。

你必须足够了解你的系统，才能命名它绝不会做什么——而大多数设计师以前从未需要明确表达这一点。

3、将流程编码为技能

自己创建 DESIGN.md 并分析现有文件让我意识到，构建一个好的 DESIGN.md 的正确流程并不明显。但这个模式可以复用。

所以我为它构建了一个 Claude 技能。

该技能从生成前的强制访谈开始。四个问题建立产品上下文、现有 token、UI 的核心任务和约束。然后按照正确的顺序处理文件：先是简介，然后是带有意图和边界的 token，接着是带有决策逻辑的排版，然后是组件，最后是注意事项部分。

最后，它建议一个诊断循环：生成三个屏幕，找出输出偏离的地方，添加缺失的约束，然后重复。

换句话说，该技能使流程变得明确。

它的存在是因为即使有可用的技能，Claude 也会默认最快路径——从 Figma 提取 token 然后就算完成——除非内置了正确的顺序。

4、让 Claude 生成 DESIGN.md

我分享了 Oooff 的 Figma 文件——UI 和 token 库——并让 Claude 编写文件。

它提取了所有内容。

完整的调色板，包含精确的十六进制值和不透明度变体。完整的 Inter 字体比例和字间距值。间距 token、圆角半径、阴影，甚至一个小的内嵌按钮技巧。标签列表、日历网格、事件卡片和侧边栏面板的组件剖析。每个 token。每个测量值。

然后我问它是否使用了该技能。

它回答：

老实说，部分使用了。我把它当作格式指南，但跳过了让文件真正有用的部分。

这才是重要的部分。

它跳过的是访谈（技能的第一部分）：建立产品做什么、服务谁、UI 必须做什么、绝不能做什么的问题。相反，Claude 从 Figma 文件推断了所有这些。它假设了产品的目的，在没有被告知的情况下编写了设计原则，并根据观察到的视觉模式发明了约束。

token 是准确的，但推理层是捏造的。这才是真正的差距。

Claude 能够以惊人的精确度从设计文件中提取"是什么"。但"为什么"——产品简介、原则、边界、不可协商的部分——仍然需要设计师的思考。如果你留空这一层，模型会为你填充。而它填充的不是产品知识，是听起来合理的推断。

5、我的收获

DESIGN.md 文件不是风格指南导出。不是 token 转储。绝对不是你应该让模型从 Figma 文件中不受监督地生成的东西。

它是你的设计系统与模型之间的通信层。

token 是容易的部分——对你和 Claude 都是。

简介、意图、约束和注意事项：这才是真正的工作。

有趣的是，这项工作在 AI 工具之外也非常有用。它只是好的设计文档。模型受益于此，但在你之后接触产品的每个设计师或开发者也同样受益。

原文链接：How to write a DESIGN.md file Claude can actually use

汇智网翻译整理，转载请标明出处