# design.md Is The New Design System Primitive
**作者**: rico
**日期**: 2026-04-29T16:39:02.000Z
**来源**: [https://x.com/_heyrico/status/2049528899898610085](https://x.com/_heyrico/status/2049528899898610085)
---
Here's the thing
The most important design file in your project in 2026 is not the Figma library.
It is a markdown file at the root of your repo called design.md
If your team has not written one yet, every AI agent you point at your codebase is generating off-brand UI by default. Cursor, Claude Code, Codex, Lovable, v0, Windsurf, Figma Make. All of them are reading the closest set of rules they can find. If you have not given them a design.md, they pick the closest substitute. The closest substitute is "generic Tailwind dashboard."
Here is why this file exists, what to put in it, and how to write one tonight.
## Why every agent suddenly reads markdown files
The pattern started with claude.md. Anthropic's Claude Code reads it before every prompt. Then Cursor added .cursorrules. Then Windsurf added .windsurfrules. Then OpenAI standardized on AGENTS.md for Codex. Then the open-source community pulled them all into one shared convention.
The bet underneath all of them is the same. The agent does not need a JSON schema or a compiled config. It needs a document a human can read and a model can parse. Markdown is the cheapest, most durable medium that does both.
Once you accept that, the question is not "should I write one." It is "how many do I need."
The answer is at least two:
1. CLAUDE.md or AGENTS.md for the project-wide brain. Voice, tone, business rules, what the codebase is, what it is not.
2. design.md for the visual brain. Tokens, components, layout rules, accessibility constraints, what the brand looks like.
Some teams collapse them into one. Bigger teams keep them split. Either is fine. Splitting them lets a designer own the second file without touching the first.
## What goes in design.md, and what does not
design.md is for visual rules
Color tokens, semantic color names, typography scale, spacing scale, layout grids, component anatomy, interaction states, accessibility constraints, what the icons look like, when shadows are allowed, when they are not, what radius means.
CLAUDE.md is for project-wide brain.
Voice and tone, the audience, the business model, the file structure, what frameworks are used, what conventions matter, what the agent should refuse to do.
When the two overlap, design.md wins on anything visual and CLAUDE.md wins on anything structural. If you are not sure which file a rule belongs in, ask: "Is this rule about how something looks, or about how something works?" Looks goes in design.md. Works goes in CLAUDE.md.
## The five sections every design.md needs
You can copy this skeleton tonight. It works for almost every product.
Section 1, the brand line.
```
Brand
Name: Acme Studio
Voice: calm, generous, practical
Avoid: gradients, glassmorphism, generic SaaS purple, neon, drop shadows
```
Three lines. The "avoid" line saves you more than the other two combined.
Section 2, the color tokens.
```
Color
Semantic
- bg: #FAFAF7 (warm off-white, default page background)
- surface: #FFFFFF (cards, modals)
- text: #111111
- text-muted: #555555
- border: #E5E1DA
- accent: #C45A3D (terracotta, used sparingly)
- success: #2E7D5A
- error: #B43E3E
Rules
- Never use pure black. Use #111111.
- Never use pure white as a page background. Use bg.
- Accent is for one element per screen, max two.
- Dark mode reverses bg and text only. Accent stays the same.
```
Tokens with a "rules" subsection beat tokens without one. The rules carry the taste.
Section 3, the typography scale.
```
Type
- Display: Inter 600, 48px, line-height 1.1, tracking -0.02em
- H1: Inter 600, 32px, line-height 1.2
- H2: Inter 600, 24px, line-height 1.3
- H3: Inter 600, 18px, line-height 1.4
- Body: Inter 400, 16px, line-height 1.6
- Caption: Inter 400, 14px, line-height 1.5
- Mono: Berkeley Mono 400, used only for code, schemas, and data
Rules
- Never use more than three type sizes on a single screen.
- Never use italic. Use weight or color for emphasis.
```
Section 4, the components.
```
Components
Button
- Radius: 8px
- Vertical padding: 14px
- Horizontal padding: 20px
- States: default, hover (darken 8%), focus (2px accent ring), disabled (50% opacity)
- Variants: primary (accent bg, white text), secondary (border only), ghost (text only)
Card
- Radius: 12px
- Padding: 24px
- Border: 1px solid border token
- No shadow by default. Add shadow only on hover for clickable cards.
input
- Same border and radius as cards
- Focus ring: 2px accent, no shadow
- Error state: border becomes error token, helper text below
```
The pattern. Name. Anatomy. States. Variants. Anything not in this list does not get built.
Section 5, accessibility and dark mode.
```
Accessibility
- All interactive elements have visible focus rings
- Color contrast: WCAG 2.1 AA minimum, AAA on body text
- Touch targets: 44px minimum on mobile
- Color is never the only signal. Use icon, text, or shape too.
Dark mode
- Reverse bg and text tokens.
- Surface token shifts from #FFFFFF to #1A1A1A.
- Border token shifts from #E5E1DA to #2A2A2A.
- All other tokens stay the same.
```
That is the entire file. Five sections. Roughly one page. You will spend more time fighting the agent without it than writing it.
## The pitfalls people hit when they write their first one
A clean numbered list:
1. Overstuffing it. A design.md longer than two pages is a liability. The agent loses focus. Cut anything that is not load-bearing.
2. Mixing brand voice into design.md. Voice belongs in CLAUDE.md. design.md is visual. Keep them separate or you will end up duplicating updates.
3. Documenting Figma styles instead of intent. "Use the H1 style from Figma" is useless to an agent that cannot open Figma. Write the actual values.
4. Skipping the "avoid" lines. Tell the agent what not to do. Negative constraints are sharper than positive ones. "Never use a gradient" is more powerful than "use solid colors."
5. Not versioning it. Commit it to git. Review changes in pull requests. A design.md that nobody reviews drifts the same way an unreviewed component library drifts.
6. One file for everything. When the brand evolves, one file becomes a merge nightmare. Split into design.md, brand.md, and components.md if you grow past two pages.
7. Forgetting to refresh it. Every six months, audit. The agent's output is a mirror of the file. If the output looks wrong, the file is wrong.
## The exercise that proves the point
Try this tonight, even if you have no project ready.
1. Create an empty folder.
2. Write a design.md using the skeleton above. Fill in your own taste. Spend forty minutes.
3. Open Claude Code or Cursor in that folder.
4. Type: "Build me a settings page using the rules in design.md."
5. Look at what you get back.
The output will be ninety percent of the way to your brand the first time. That is not because the agent suddenly got better. It is because you finally articulated your taste in writing.
The exercise is not about the page. It is about the file.
## The bigger shift this is part of
Design systems used to live in Figma and get translated to code by engineers. The translation was always lossy.
In 2026 the design system lives in code. The Figma file is a viewer. design.md is the source of truth. Every agent reads it. Every component respects it. Every screen ships with the right tokens because the tokens are the input, not the output.
This is the quietest, biggest change to design ops in a decade. Most teams have not noticed yet. The teams that have are shipping faster, more consistent product than the rest. The gap is going to compound.
The work is small. Open your project. Create design.md. Write five sections. Commit it.
Tomorrow, every agent that touches your code will know what your brand looks like.
That is the whole game.
Go check my newsletter here for more awesome practical stuff
## 相关链接
- [rico](https://x.com/_heyrico)
- [@_heyrico](https://x.com/_heyrico)
- [27K](https://x.com/_heyrico/status/2049528899898610085/analytics)
- [design.md](http://design.md/)
- [design.md](http://design.md/)
- [design.md](http://design.md/)
- [brand.md](http://brand.md/)
- [components.md](http://components.md/)
- [design.md](http://design.md/)
- [design.md](http://design.md/)
- [design.md](http://design.md/)
- [design.md](http://design.md/)
- [newsletter here](https://designaccelerator.substack.com/)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [12:39 AM · Apr 30, 2026](https://x.com/_heyrico/status/2049528899898610085)
- [27.6K Views](https://x.com/_heyrico/status/2049528899898610085/analytics)
---
*导出时间: 2026/4/30 16:46:30*
---
## 中文翻译
# design.md 是新的设计系统基石
**作者**: rico
**日期**: 2026-04-29T16:39:02.000Z
**来源**: [https://x.com/_heyrico/status/2049528899898610085](https://x.com/_heyrico/status/2049528899898610085)
---
听好了
2026年，你项目中最重要的设计文件不是 Figma 库。
它是你代码仓库根目录下的一个 Markdown 文件，名为 design.md。
如果你的团队还没写这个文件，那么每一个指向你代码库的 AI 代理默认生成的都是不符合品牌调性的 UI。Cursor、Claude Code、Codex、Lovable、v0、Windsurf、Figma Make。它们都在读取能找到的最接近的规则集。如果你没有提供 design.md，它们就会找最接近的替代品。这个替代品就是“通用的 Tailwind 仪表盘”。
以下是这个文件存在的原因、里面该写什么，以及今晚该如何写出一个。
## 为什么每个代理突然都开始读取 Markdown 文件
这种模式始于 claude.md。Anthropic 的 Claude Code 会在每次提示前读取它。然后 Cursor 添加了 .cursorrules。接着 Windsurf 添加了 .windsurfrules。后来 OpenAI 为 Codex 将标准统一为 AGENTS.md。最后开源社区将它们整合成了一个通用惯例。
它们背后的赌注是一样的：代理不需要 JSON 模式或编译后的配置。它需要一份人类可读且模型可解析的文档。Markdown 是同时满足这两点的成本最低、最持久的媒介。
一旦你接受了这一点，问题就不再是“我要不要写一个”，而是“我需要写几个”。
答案至少是两个：
1. CLAUDE.md 或 AGENTS.md 用于项目层面的全局大脑。包括语气、语调、业务规则、代码库是什么、不是什么。
2. design.md 用于视觉大脑。包括设计变量、组件、布局规则、无障碍约束、品牌长什么样。
有些团队把它们合并为一个。大团队则保持分开。两种都可以。分开的好处是，设计师可以拥有第二个文件的所有权，而无需触碰第一个文件。
## design.md 里该写什么，不该写什么
design.md 用于视觉规则。
颜色变量、语义化颜色名称、排版层级、间距层级、布局网格、组件解剖结构、交互状态、无障碍约束、图标长什么样、何时允许阴影、何时不允许、圆角意味着什么。
CLAUDE.md 用于项目层面的全局大脑。
语气和语调、受众、商业模式、文件结构、使用了什么框架、哪些约定很重要、代理应该拒绝做什么。
当两者重叠时，design.md 在任何视觉层面获胜，CLAUDE.md 在任何结构层面获胜。如果你不确定一条规则属于哪个文件，请问自己：“这条规则是关于外观的，还是关于运作方式的？”外观写进 design.md。运作写进 CLAUDE.md。
## 每个 design.md 都需要的五个部分
你今晚就可以复制这个骨架。它几乎适用于所有产品。
第一部分，品牌简介。
```
Brand
Name: Acme Studio
Voice: calm, generous, practical（冷静、宽厚、务实）
Avoid: gradients, glassmorphism, generic SaaS purple, neon, drop shadows（渐变、玻璃拟态、通用的 SaaS 紫色、霓虹色、投影）
```
三行。其中的“避免（Avoid）”这一行比其他两行加起来还能节省你的精力。
第二部分，颜色变量。
```
Color
Semantic
- bg: #FAFAF7 (暖米白色，默认页面背景)
- surface: #FFFFFF (卡片、模态框)
- text: #111111
- text-muted: #555555
- border: #E5E1DA
- accent: #C45A3D (赤陶色，少量使用)
- success: #2E7D5A
- error: #B43E3E
Rules
- 永远不要使用纯黑。使用 #111111。
- 永远不要将纯白用作页面背景。使用 bg。
- 每个屏幕上的强调色最多用于一个元素，最多两个。
- 暗黑模式仅反转 bg 和 text。Accent 保持不变。
```
带有“规则（Rules）”子部分的变量比没有的更有用。规则决定了品味。
第三部分，排版层级。
```
Type
- Display: Inter 600, 48px, line-height 1.1, tracking -0.02em
- H1: Inter 600, 32px, line-height 1.2
- H2: Inter 600, 24px, line-height 1.3
- H3: Inter 600, 18px, line-height 1.4
- Body: Inter 400, 16px, line-height 1.6
- Caption: Inter 400, 14px, line-height 1.5
- Mono: Berkeley Mono 400, 仅用于代码、架构和数据
Rules
- 单个屏幕上绝不要使用超过三种字号。
- 绝不要使用斜体。使用字重或颜色来表示强调。
```
第四部分，组件。
```
Components
Button
- Radius: 8px
- Vertical padding: 14px
- Horizontal padding: 20px
- States: default, hover (darken 8%), focus (2px accent ring), disabled (50% opacity)
- Variants: primary (accent bg, white text), secondary (border only), ghost (text only)
Card
- Radius: 12px
- Padding: 24px
- Border: 1px solid border token
- 默认无阴影。仅对可点击的卡片在 hover 时添加阴影。
input
- 边框和圆角同 Card
- Focus ring: 2px accent, 无阴影
- Error state: 边框变为 error token, 下方显示辅助文本
```
这个模式。名称。解剖结构。状态。变体。任何不在此列表中的东西都不会被构建。
第五部分，无障碍和暗黑模式。
```
Accessibility
- 所有交互元素都有可见的 focus ring
- 颜色对比度：WCAG 2.1 AA 最低标准，正文达到 AAA
- 触摸目标：移动端最小 44px
- 颜色绝不作为唯一的信号。同时使用图标、文本或形状。
Dark mode
- 反转 bg 和 text 变量。
- Surface token 从 #FFFFFF 变为 #1A1A1A。
- Border token 从 #E5E1DA 变为 #2A2A2A。
- 所有其他变量保持不变。
```
这就是整个文件。五个部分。大约一页。如果没有它，你花在跟代理扯皮上的时间会比写它的时间还多。
## 人们写第一个文件时常遇到的坑
这里有一个清晰的编号列表：
1. 塞得太满。超过两页的 design.md 是一种负债。代理会失去焦点。删掉任何非承重的内容。
2. 将品牌语调混入 design.md。语调属于 CLAUDE.md。design.md 是视觉层面的。保持它们分离，否则你最终会不得不重复更新工作。
3. 记录 Figma 样式而非意图。对于无法打开 Figma 的代理来说，“使用 Figma 中的 H1 样式”毫无用处。写出具体的数值。
4. 跳过“避免（Avoid）”行。告诉代理不要做什么。负面约束比正面约束更有效。“绝不要使用渐变”比“使用纯色”更有力。
5. 不进行版本控制。把它提交到 git。在 pull request 中审查变更。如果没有人审查，design.md 会像未经审查的组件库一样逐渐走样。
6. 万物归一文件。当品牌演变时，单个文件会成为合并噩梦。如果你增长到超过两页，拆分为 design.md、brand.md 和 components.md。
7. 忘记刷新它。每六个月审计一次。代理的输出是文件的镜像。如果输出看起来不对，那就是文件不对。
## 一个能证明观点的练习
今晚试试这个，即使你还没有准备好项目。
1. 创建一个空文件夹。
2. 使用上面的骨架写一个 design.md。填入你自己的品味。花四十分钟。
3. 在该文件夹中打开 Claude Code 或 Cursor。
4. 输入：“使用 design.md 中的规则为我构建一个设置页面。”
5. 看看你会得到什么。
第一次，输出就会达到你品牌预期的 90%。这并不是因为代理突然变强了。而是因为你终于用文字清晰地表达了你的品味。
这个练习不在于页面。而在于文件。
## 这属于更大的转变的一部分
设计系统过去存在于 Figma 中，并由工程师翻译成代码。这种翻译总是有损耗的。
在 2026 年，设计系统存在于代码中。Figma 文件只是一个查看器。design.md 是唯一真实来源。每个代理都读取它。每个组件都遵守它。每个屏幕都搭载正确的变量，因为这些变量是输入，而不是输出。
这是十年来设计运营中发生的最安静、最大的变化。大多数团队还没有注意到。已经注意到的团队比其他团队交付更快、更一致的产品。这种差距将会扩大。
工作量很小。打开你的项目。创建 design.md。写出五个部分。提交它。
明天，每一个接触你代码的代理都会知道你的品牌长什么样。
这就是全部的游戏规则。
来这查看我的通讯以获取更多精彩的实用内容
## 相关链接
- [rico](https://x.com/_heyrico)
- [@_heyrico](https://x.com/_heyrico)
- [27K](https://x.com/_heyrico/status/2049528899898610085/analytics)
- [design.md](http://design.md/)
- [design.md](http://design.md/)
- [design.md](http://design.md/)
- [brand.md](http://brand.md/)
- [components.md](http://components.md/)
- [design.md](http://design.md/)
- [design.md](http://design.md/)
- [design.md](http://design.md/)
- [design.md](http://design.md/)
- [newsletter here](https://designaccelerator.substack.com/)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [12:39 AM · Apr 30, 2026](https://x.com/_heyrico/status/2049528899898610085)
- [27.6K Views](https://x.com/_heyrico/status/2049528899898610085/analytics)
---
*导出时间: 2026/4/30 16:46:30*