A DESIGN.md example, section by sectionDESIGN.md 示例,逐段拆解
The fastest way to understand a DESIGN.md is to walk through one. Below is the anatomy of a complete file, in the order an AI reads it — what each section contains, what it looks like on the page, and why it sits where it sits. Treat it as a template: the structure here is exactly what you would write for your own style.理解 DESIGN.md 最快的方式就是走读一份。下面按 AI 阅读的顺序,拆解一份完整文件的解剖结构——每个章节装什么、在文件里长什么样、为什么放在那个位置。可以直接当模板用:这里的结构,就是你为自己的风格动笔时要写的结构。
The overall shape of the file文件的整体形状
Every well-formed DESIGN.md has the same three layers, in the same order. First a frontmatter block — a few lines of structured metadata the machine reads before anything else. Then the token sections — colors, typography, spacing, shape, shadow, motion — each stated as exact values. Finally the applied layer: component logic and usage notes, the prose rules that turn tokens into screens.每份合格的 DESIGN.md 都有相同的三层,顺序也相同。最前是 frontmatter 块——几行结构化元数据,机器最先读它。然后是 token 章节——配色、字体、间距、形状、阴影、动效——每项都是精确值。最后是应用层:组件逻辑与用法说明,把 token 变成页面的那些文字规则。
The order is the point. An agent reads top to bottom, so the file moves from orientation (what is this?) through vocabulary (what are the values?) to grammar (how do they combine?). A file in this shape is parseable in one pass — no backtracking, no inference.顺序本身就是要点。agent 从上往下读,文件因此从定位(这是什么?)走到词汇(值是多少?),再走到语法(它们怎么组合?)。这个形状的文件一遍就能解析完——不用回头,不用推断。
The frontmatter: name, essence, flagsfrontmatter:名字、精髓、标志位
The file opens with a fenced YAML block of just a few fields: the style's name, a one-sentence essence — say, "geometric clarity with primary-color accents, form follows function" for a Bauhaus-style spec — and boolean flags that change downstream rendering, the most important being whether the style is dark.文件以一段围栏 YAML 块开头,只有几个字段:风格的名字;一句话精髓——比如包豪斯式规范可能写「几何的清晰,三原色点缀,形式追随功能」;以及会改变后续渲染的布尔标志位,其中最重要的是这套风格是否深色。
Small as it is, this block does the most work per line in the file. The essence primes every later interpretation; the dark flag alone flips how an agent handles contrast, elevation, and imagery. If the agent read nothing else, it would already avoid the worst mistakes.这一块虽小,却是全文件里每行干活最多的部分。精髓句给后面所有解读定了调;单是深色标志位,就会翻转 agent 处理对比度、层级和配图的方式。哪怕 agent 只读到这里,它已经能避开最糟的错误。
The token sections: exact values, named by roletoken 章节:精确值,按角色命名
The color section lists a named palette where every entry is a role plus an exact value: background <hex>, ink <hex>, a small set of accents <hex>, hairline <hex>. Roles, not appearances — so the agent knows where each color belongs, not just what it looks like.配色章节列一套命名色板,每一项都是「角色 + 精确值」:背景 <hex>、墨色 <hex>、一小组强调色 <hex>、发丝线 <hex>。按角色而不是按外观命名——agent 因此知道每个颜色属于哪儿,而不只是它长什么样。
The typography section names the font families and weights, then gives a type scale as concrete sizes — display, heading, body, caption, each at <px> with a line height. The spacing section states the rhythm the layout snaps to: a base unit in <px> and the steps built on it.字体章节点名字体家族与字重,然后给出具体尺寸的字阶——展示、标题、正文、注文,各自的 <px> 与行高。间距章节写明版式吸附的节奏:一个 <px> 的基础单位,和在它之上搭出的步长。
Shape, shadow, and motion round out the vocabulary: corner radii in <px>, elevation levels with their shadow values, and easing curves with durations. Every one of these is a number a machine can apply verbatim — that is the test each line has to pass.形状、阴影、动效补全词汇表:以 <px> 计的圆角、带阴影值的层级、带时长的缓动曲线。这里每一条都是机器能照抄执行的数字——每一行都得过这个测试。
One honest note: the values in this walkthrough are placeholders like <hex> and <px>. The structure of a DESIGN.md is open; the precise values for each of Curio's styles are the paid product. What matters for a template is the shape — swap in your own values and the file works.诚实说明一点:本文走读里的值都是 <hex>、<px> 这样的占位符。DESIGN.md 的结构是开放的;Curio 每种风格的精确数值是付费产品。对模板而言,重要的是形状——换上你自己的值,文件就能用。
The applied layer: component logic and bounds应用层:组件逻辑与边界
After the tokens come short declarative rules for the recurring components. A button rule might read: primary buttons are filled with the ink color, text in background color, radius from the shape section, no shadow. A card rule: cards sit inside a hairline border, never on a drop shadow. An emphasis rule: hierarchy is done with size and weight, never with added colors.token 之后,是高频组件的简短陈述式规则。按钮规则可能写:主按钮以墨色填充、文字用背景色、圆角取形状章节的值、不带阴影。卡片规则:卡片坐在发丝线边框里,永远不浮在投影上。强调规则:层级靠字号与字重,绝不靠加颜色。
The file closes with usage notes — a few sentences on where the style excels (editorial pages, marketing sites) and where it should not go (dense data tables, dashboards). These bounds are what keep an agent from applying a beautiful style in the wrong place.文件以用法说明收尾——几句话讲清这套风格擅长哪儿(杂志式页面、营销站),不该去哪儿(高密度数据表、仪表板)。正是这些边界,拦住 agent 把一套漂亮的风格用错地方。
Use this as a template — or get a real one拿它当模板——或者直接拿一份真的
If you are encoding your own brand, this walkthrough is the template: open with frontmatter, state the tokens by role, close with component logic and bounds. Fill in your values and you have a working spec.如果你在编码自己的品牌,这篇走读就是模板:frontmatter 开头,token 按角色写明,组件逻辑与边界收尾。填上你的值,一份能干活的规范就有了。
If you want an established style instead, the file already exists. Every style in Curio's library — from Bauhaus to contemporary brand-grade looks — ships as a complete DESIGN.md in exactly this shape, with the real values filled in, ready for your AI to apply over MCP, a share link, or a download.如果你要的是一种成熟风格,那这个文件已经存在了。Curio 库中的每种风格——从包豪斯到品牌级的当代长相——都以这个形状的完整 DESIGN.md 交付,真实数值已经填好,你的 AI 通过 MCP、分享链接或下载即可套用。
FAQ常见问题
Can I copy this structure as a template?能把这个结构直接抄去当模板吗?
Yes — the structure is open and this article exists to be copied: frontmatter, token sections stated by role, component logic, usage bounds. Google's open DESIGN.md spec follows the same overall shape, so a file in this form is readable by any tool that speaks the format.可以——结构是开放的,这篇文章就是给你抄的:frontmatter、按角色写的 token 章节、组件逻辑、适用边界。Google 的开放 DESIGN.md 规范也是这个整体形状,照此写的文件任何认这个格式的工具都能读。
Why are the values placeholders instead of real numbers?为什么值是占位符而不是真实数字?
Because the values are the product. The structure of a DESIGN.md is public knowledge and this page shows all of it; the researched, exact token values for each of Curio's styles are what a paid plan unlocks. For your own brand's file, the values are simply yours to fill in.因为数值本身就是产品。DESIGN.md 的结构是公开知识,本页全部展示了;而 Curio 每种风格经过调研的精确 token 值,是付费方案解锁的内容。至于你自己品牌的文件,值当然由你自己填。
What is the minimum viable DESIGN.md?最小可用的 DESIGN.md 长什么样?
Frontmatter with a name, an essence line and the dark flag; a color palette and type scale as exact values; one spacing unit; and three component rules (button, card, emphasis). That fits on half a page and already beats any prompt written in adjectives.frontmatter 里有名字、精髓句和深色标志位;精确值的色板与字阶;一个间距单位;外加三条组件规则(按钮、卡片、强调)。半页纸就装下了,而且已经胜过任何用形容词写的 prompt。