How to Write a design.md (Structure and Examples)

A design.md is a plain markdown file that describes a whole design system in terms an AI coding tool can apply without interpreting it: named tokens, exact numbers, component states and brand voice. If the format is new to you, start with what a design.md is. This is the practical version: which sections to write, in what order, and what makes each one work or quietly fail.

Write the sections in dependency order

Order matters more than it looks. Each section should only depend on the ones above it, so a model reading top to bottom never meets a reference it cannot resolve. Components refer to tokens, so tokens come first. Voice depends on nothing, so it can sit late.

• 1. Brand essence. Three or four lines on the attitude, plus the tagline. Short. This is orientation, not strategy.
• 2. Colour tokens. Light mode and dark mode, as CSS custom properties, with a usage note per token.
• 3. Typography. The font pairing and a full scale with sizes, line heights, weights and the use case for each level.
• 4. Spacing and layout. A numeric spacing scale, container width, gutters, grid behaviour, a radius scale and elevation levels.
• 5. Buttons. Variants, sizes and every state.
• 6. Cards. The patterns you actually use, described structurally.
• 7. Forms. Field sizing, focus and error states.
• 8. Voice and copy. Rules plus worked examples.
• 9. Motion. Easing curves, durations, and a reduced-motion rule.
• 10. Accessibility. Contrast minimums, target sizes, focus-visible behaviour.
• 11. Logo usage. Minimum sizes and clear space.
• 12. Do and do not. The whole thing compressed into decisions.

You can drop sections you genuinely do not need. Do not drop states, motion or accessibility, because those are the three an AI tool is least likely to get right unprompted.

Name tokens so a model can reason about them

This is the single highest-leverage decision in the file. Name by role, never by appearance.

/* Fights you later */
--berry: #4D0D2E;
--dark-berry: #660A3A;

/* Survives a rebrand */
--primary: #4D0D2E;
--primary-ink: #FDFDFD;
--accent: #660A3A;

Three rules make the difference:

• Pair every fill with its ink. If --primary exists, --primary-ink must too. Otherwise a tool guesses the text colour on a filled button, and it guesses white every time, including on your pale yellow.
• Write a usage note per token. One clause is enough: helper copy, timestamps, placeholders. A hex list alone makes the model invent placements, and brand purple ends up as body text.
• Define dark mode even if you do not ship it. Asked for a dark screen with no dark tokens, a tool inverts your light palette. Contrast breaks and the brand colours turn to mud.

How much voice guidance is useful

More than most people write, and of a different kind. Adjectives are close to worthless: modern, clean and premium describe nearly every brand and constrain nothing. What works is rules plus finished examples.

A rule sounds like: keep confidence earned, describe fit and fabric without hype. An example sounds like a real headline you would ship. Two or three worked examples teach a model more about register than a paragraph of description, because it can pattern-match on rhythm and length rather than infer them.

Answering three or four FAQs in the brand voice is the most efficient thing you can add. It gives the model a demonstration of how the brand handles a plain question, which is most of the copy in any product.

Test it, do not assume it

A design.md that has never been tested is a guess. The test takes five minutes.

• Paste the file into Cursor, Claude Code, v0 or Lovable as project context.
• Ask for something with many states: a pricing card with a featured variant, or a form with an error.
• Compare the output against the file, token by token. Did it use your radius, or 8px because that is the default? Is the disabled state your 45 percent opacity? Is the focus ring yours?

Every mismatch points at an ambiguity in the file, not a failure of the tool. Fix the sentence that allowed the wrong reading and run it again. Two rounds of this usually gets a file from roughly right to reliable.

Then repeat once in a different tool. Tools weight context differently, and a file that only works in one of them is under-specified.

Keep it alive

The failure mode for a design.md is not being wrong on day one. It is being right on day one and stale by month three, because tools follow it confidently either way.

Keep the file in the repository next to the code, not in a drive folder. That way a change to the palette and the change to the file land in the same pull request, and code review catches drift. Treat it as a source file with an owner, and add a short changelog at the bottom if more than two people touch it.

By hand, or generated

Written by hand, budget an afternoon. Tokens and typography take twenty minutes. Component states and the voice section take the rest, and they are also the parts that decide whether the file is any good.

The alternative is to generate it. The Logofai design.md generator reads your logo, extracts the palette, pairs typography and writes all twelve sections along with a live HTML style guide and exports as CSS variables, a Tailwind config and W3C design tokens JSON. It costs 9 credits and takes about a minute. Either way, edit it afterwards: it is markdown, and the generated file is a starting point, not a verdict.

If you want to see the finished shape before you commit, there is a complete design.md example you can copy, and if you are still deciding whether you need this at all rather than a traditional brand document, design.md versus a style guide covers the difference.

A worked example: the button spec

Buttons are the fastest way to see the difference between a file that works and one that reads well. Here is the version most people write first:

Buttons are rounded and use the brand colour.
Primary buttons are filled, secondary are outlined.
Hover states should feel responsive.

Every sentence is true and none of it is usable. Rounded by how much. Which brand colour, and what colour is the label on top of it. What does responsive mean in milliseconds. A model handed this invents all three and invents them differently on each screen. Now the same spec written to be applied:

Radius: 10px. Type: Space Grotesk 700, 15px / 1, 0.01em.
Icon gap: 8px.

Variants
- Primary: fill --primary, text --primary-ink, border --primary.
- Outline: transparent fill, text --primary, border --primary.
- Ghost: transparent fill, text --text, no border.

Sizes
- Small: 36px height, 12px horizontal padding, 14px type.
- Medium: 44px height, 16px horizontal padding, 15px type.
- Large: 52px height, 22px horizontal padding, 15px type.

States
- Hover: translateY(-1px), fill deepens to --accent.
- Active: translateY(0), tighter shadow.
- Disabled: 45% opacity, no transform, cursor not-allowed.
- Loading: keep button width, show monochrome spinner.

It is longer, but nothing in it requires a decision. Write every component this way and the file stops being documentation and starts being a specification.

Spacing: pick a scale and refuse to leave it

An 8-based scale with one or two tight exceptions covers almost everything: 4, 8, 12, 16, 24, 32, 48, 64, 96. The exact numbers matter far less than the fact that there is a fixed set. Without one, generated components each choose their own padding and a page reads as a collection of unrelated blocks rather than one product.

Add container width, page gutters at each breakpoint, and a radius scale in the same section. Those three plus the spacing scale are what make the fifth screen a tool builds still look like the first.

What to leave out

A design.md is not a brand book, and padding it out makes it worse rather than more thorough. Leave out brand history and positioning narrative, mood boards and photography direction, print specifications and Pantone references, and anything expressed only as an image. None of it survives contact with a text model, and all of it dilutes the parts that do.

Those things are worth having. They belong in a human-facing document instead, which is what design.md versus a style guide is about.