design.md vs style guide: what’s the difference?
They look like the same document described twice. They are not. One is written to be read by a person who will then make a judgement. The other is written to be applied by a machine that will not.
A style guide is a human-facing brand document, usually a PDF, a Figma page or a hosted microsite, covering logo usage and clear space, palette, photography direction, tone of voice and print specifications. A design.md is a machine-facing markdown file kept in the code repository, covering named colour tokens for light and dark mode, a numbered type scale, a spacing and radius scale, component variants and states, motion, accessibility minimums and brand voice, all written as exact values. The practical difference is interpretation: a style guide shows a designer what the brand looks like and trusts them to apply it, while a design.md gives an AI coding tool values precise enough that no interpretation is required. They are complements rather than alternatives. A brand that ships software generally wants a style guide for the people around it and a design.md for the code, and the second can be generated from a logo in about a minute.
Side by side. Seven differences.
| Style guide | design.md | |
|---|---|---|
| Audience | Designers, marketers, printers, agencies | AI coding tools and the developers reading the repo |
| Format | PDF, Figma page or a hosted microsite | A markdown file committed next to the code |
| What it covers | Logo usage, clear space, palette, photography, tone, print specs | Tokens, type scale, spacing, component states, motion, accessibility, voice |
| How values are written | Shown visually, often as swatches and examples | Named variables with exact numbers |
| Who maintains it | Whoever owns the brand, usually outside the codebase | Whoever ships the code, in the same pull request |
| How it is consumed | A person opens it and interprets it | A tool parses it and applies it without interpreting |
| Fails when | Nobody opens the PDF | Values drift from the code it describes |
When a style guide is enough. Genuinely.
If nothing you own is built in code, a design.md buys you nothing. A restaurant, a clinic, a builder, a consultancy whose website is a template: the brand lives on signage, packaging, vehicles and print, and every one of those is produced by a person who will read a document and make judgement calls. That is precisely what a style guide is for, and a token file is the wrong artefact.
The same is true early on. Before there is a product to build, a design.md describes an interface that does not exist. Get the identity settled first. Our brand guidelines output covers the human-facing side, and the brand pack is the folder you hand to a printer.
When you need both. The moment it splits.
The split happens the first time someone builds a screen. A developer, or increasingly an AI tool, asks a question the style guide cannot answer: what is the disabled state of a secondary button. What is the focus ring. What is the spacing between a card title and its body. A style guide says the brand is confident and uses a deep berry; it does not say 44px height, 16px horizontal padding, 15px type.
At that point you need both documents, and they must agree. The style guide keeps the brand coherent for everyone outside the codebase. The design.md keeps it coherent inside, and because it lives in the repo it changes in the same pull request as the code, which is the only reliable way to stop the two drifting apart.
Turning one into the other. Both directions.
Going from style guide to design.md is mostly a translation job: take every value the guide shows visually and write it as a named variable with a number, then add the parts a guide never covers, which is component states, motion and accessibility. See a complete design.md example for the shape of the finished file, and how to write a design.md for the order to work in.
Going the other way is easier, because a design.md already contains the hard values. What it lacks is the visual argument: the examples, the photography direction, the do and do-not pages that make a guide persuasive to a human reader.
Logofai produces both from the same logo. The design system generator writes the design.md and a live HTML style guide together, so the two cannot disagree on day one.
Questions. Answered.
Does a design.md replace a style guide?
No, and it is not trying to. A style guide answers questions a design.md cannot: how the logo behaves on a vehicle wrap, which photography is on brand, what the print Pantones are. A design.md answers the one question a style guide is bad at: what exact values should this interface be built with. Most brands that ship software end up wanting both.
What is the difference between design tokens and a design.md?
Design tokens are the raw values, usually as JSON or CSS variables, and nothing else. A design.md contains tokens but also explains what each one is for, how components use them, and what the brand sounds like. Tokens tell a tool that --primary is #4D0D2E. A design.md tells it that --primary is the fill for main actions and that --primary-ink is the text that sits on top.
Which one should I make first?
If you are building a product, make the design.md first: it unblocks the code and can be generated in about a minute. A full style guide is worth commissioning once the brand is settled and other people, printers, agencies, partners, need to use it without asking you.
Skip the translation. Generate both.
Or see how to create a design.md from your logo.