A DESIGN.md example, section by section
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.
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.
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.
The frontmatter: name, essence, flags
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.
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.
The token sections: exact values, named by role
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
What is the minimum viable 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.