design.md

为什么 AI 写代码最大的痛点不在「不会写」

我每天用 Claude Code 做评测文章的 HTML 生成。同一个项目，同一个 Hermes Cyber Terminal 主题，第一页和第十页的按钮圆角不一样，配色偏移到离谱，字体字号每次都在猜。我不是没试过——我在 prompt 里反复写「主色 #7ed3a4，字号 15px，圆角 8px」，但 AI 的上下文窗口一滑动，这些细节就蒸发了。

这不是模型能力的问题。模型完全知道怎么写 CSS。问题是我们从来没给它一个持久的设计规矩文件，让它每次生成都有参照，而不是从头猜。

这就跟团队里没有设计规范一样——十个工程师各写各的 CSS，出来的产品当然是十个样子。AGENTS.md 解决了代码层的规矩，DESIGN.md 解决的是设计层的规矩。

我的判断：design.md 不只是一个 Markdown 格式规范，它是 AI 编码时代的设计基础设施层。它把「给 AI 立视觉规矩」这件事从临时 prompt 变成了持久规范文件。这不是工具升级，是方法论升级。

双层结构：YAML 给机器值，Prose 给机器意图

DESIGN.md 的核心创新不在格式本身——YAML front matter 加 Markdown body，这个结构很朴素。创新在于它同时传递两种信息：Token 层告诉 Agent 精确数值（颜色 #1A1C1E，字号 3rem），Prose 层告诉 Agent 这些数值为什么存在、什么时候用、什么时候不该用。

传统 design token 只传值：`--primary: #4285F4`。Agent 拿到一个蓝色值，但它不知道这个蓝色是做按钮的，还是做标题的，还是做警告色的。结果就是 Agent 随机选择，一页一个风格。

DESIGN.md 传的是意图：`--color-brand-primary: 用于主要按钮和链接，传达品牌核心色调`。Agent 拿到的不是十六进制值，是「这个颜色是做什么的」。这从「猜」变成了「查」。

这段 Prose 里最关键的一句不是颜色值，是 "Boston Clay — the sole driver for interaction"。这句话告诉 Agent：这个红色只用在交互元素上，不是随便哪个地方都能用。Agent 以后就不会把品牌色刷在标题上。

designmd.ai — 社区驱动的 DESIGN.md 设计系统库，数百个免费品牌规范可直接下载使用

CLI 工具链：lint、diff、export、spec 四个命令

光有格式还不够，design.md 附带了一套完整的 CLI 工具链：lint 验证结构 + diff 检测回归 + export 转换格式 + spec 输出规范。这四个命令把 DESIGN.md 从「写完就扔」变成了「可验证、可追踪、可转换」的工程资产。

lint 是我最看重的命令。九条 linting 规则，覆盖从最基本的 broken-ref（token 引用不存在）到 contrast-ratio（WCAG 对比度检查）。这意味着你写完 DESIGN.md 之后，不需要人肉检查配色对比度，一条命令就能告诉 Agent 哪些地方不合规。

diff 命令对比两个版本的 DESIGN.md，检测 token 级别和 prose 级别的回归。如果 v2 比 v1 多了 error 或 warning，diff 返回 exit code 1——你可以直接把这个放在 CI 里。

export 支持四种输出格式：Tailwind v3 config (JSON)、Tailwind v4 theme (CSS)、DTCG tokens (W3C 标准)、以及 Tailwind 别名。这意味着 DESIGN.md 写一次，可以同时喂给 Tailwind 项目、W3C 标准工具链和任何接受 DTCG 的设计系统平台。

spec 命令输出完整的规范文本——你可以直接把这个丢进 Agent 的上下文里，让它理解 DESIGN.md 的全部规则表。

设计哲学：Prose 才是灵魂，不是 Token

PHILOSOPHY.md 是这个项目最被低估的文件。它不只解释了 DESIGN.md 怎么用，它解释了为什么这么用。三条核心哲学，每一条都值得独立拿出来说。

第一条：Prose 是灵魂，Token 是配角。PHILOSOPHY.md 开篇就说："The quality of a generated design is determined less by the precision of its values than by how clearly the intent is described."翻译过来：生成质量不取决于数值多精确，取决于意图多清晰。这句话直接否定了传统 design token 的核心假设——精确值就是一切。

第二条：具体引用胜过形容词堆砌。"A 1970s graduate lecture handout in the tradition of an old and established university" 比 "Modern, clean, trustworthy, premium" 信息量大十倍。前者让模型知道：单色墨水、大留白、阅读字号、无装饰。后者让模型在四个形容词的中心区域取值，输出必然是通用的。

第三条：负面约束定义性格。Do's and Don'ts 不是可有可无的装饰——它是性格的定义。"Don't add a hero moment"、"Don't use Bold anywhere"、"Don't introduce dark mode"——这些 Don't 比 Do 更有力量，因为它们框住了 AI 最容易犯的错。

看到 "not a magazine cover" 和 "the Substack register" 这两个否定类比了吗？这比写一百条 CSS 规则更有效。因为模型知道「杂志封面」长什么样，知道「Substack 风格」长什么样，它自然就不会往那个方向走。

// 架构：DESIGN.md 如何让 AI 从猜变成查

// 竞品对比：谁在做 AI 设计规矩这件事

关键对比维度：是否传意图（不只是传值）| 是否可验证 | 是否跨工具链流通 | 是否有社区生态

// 社区生态：designmd.ai 和 54 家品牌规范

// 数据指标

// verdict

// links