DESIGN.md vs a Style Guide

Most teams already have a design system. It lives in a Figma library, a brand PDF, or a Notion page full of color swatches and font specimens. It's thorough, it's well-designed, and it's completely useless to an AI agent. The moment you ask Claude Code to build a screen, none of that carefully documented intent reaches the model — it builds from a guess. The artifact you spent weeks producing serves exactly one audience, and that audience is no longer the only one building your UI.

This is the gap a DESIGN.md closes. Both a style guide and a DESIGN.md document the same underlying design system — the same colors, type, and spacing. The difference is who can read them. A style guide is a human document: a PDF, a Figma file, a slide deck meant for people to interpret. A DESIGN.md is human-readable and agent-parseable: a token block an agent applies directly, plus markdown rationale a person can review. Same intent, two very different consumers.

This piece interprets the publicly indexed DESIGN.md pattern and common brand-documentation practices; it is not affiliated with or endorsed by any company named.

Key Takeaways

• A style guide targets humans; a DESIGN.md targets humans and agents. That single difference drives everything else.
• The DESIGN.md token block is machine-applied. An agent reads primary: "#635BFF" and uses it exactly — no interpretation, unlike a PDF swatch.
• Both document the same system. A DESIGN.md doesn't replace design thinking; it encodes it in a form agents consume.
• A DESIGN.md lives in your repo — versioned, reviewed in pull requests, and diffable, where a Figma file or PDF sits outside your codebase.
• You can derive a DESIGN.md from an existing style guide by translating its decisions into structured tokens plus rationale.

What a traditional style guide does well

Style guides aren't wrong — they're optimized for the wrong reader in the agent era. A good brand style guide excels at communicating feel to a human. It shows the logo in context, demonstrates correct and incorrect usage with annotated examples, and tells a story about the brand's personality through layout and imagery. A designer reading it absorbs not just the values but the taste behind them.

That richness is real, and it's worth keeping. The problem is purely mechanical: a human reads a swatch labeled "Primary Blue" and knows to sample the exact pixel; an agent handed a PDF extracts, at best, the word "blue." The format that makes a style guide expressive for humans makes it opaque to machines.

What a DESIGN.md does differently

A DESIGN.md takes the same decisions and makes them executable. The colors become a token block with exact hex values. The type system becomes a typography object with fontFamily, baseSize, weights, and lineHeight. The spacing becomes a named scale. An agent doesn't interpret any of it — it reads the values and applies them.

Then the markdown half does the job the style guide did for humans: it carries intent. "Reserve the accent color for a single primary action per screen" is a sentence an agent can both parse and respect. So a DESIGN.md isn't less than a style guide — it's a style guide whose values have been made machine-readable and whose prose has been written for a reader that takes instructions literally. The Stitch-style pattern formalizes this two-half structure.

DESIGN.md vs style guide: the head-to-head

Do you need both?

In practice, many teams keep both, and that's fine. The style guide remains the place where designers explore and present the brand to stakeholders. The DESIGN.md is the operational artifact — the thing your agents actually read when they build. Think of the style guide as the brand's portfolio and the DESIGN.md as its API.

If you have to choose where to invest first, and agents are building your UI, the DESIGN.md wins. A style guide that no agent can read produces the same generic, AI-looking output as having no design system at all. A DESIGN.md, even a minimal one, changes what the agent produces immediately. You can always make it beautiful later; you can't make a PDF executable.

How to convert a style guide into a DESIGN.md

The translation is mostly mechanical. Pull the exact hex values out of your color section and write them as a colors token block. Capture the type system as a typography object. Convert the spacing rules into a named scale and the corner treatments into a rounded block. Then write the prose: a one-line Overview, usage notes per color, and a Do's and Don'ts section that names the mistakes — the off-brand gradient, the wrong radius — you want agents to avoid.

If you'd rather learn by example, the Designs category indexes 135 working DESIGN.md files. Study a few — the Discord design system for "always-on" readability, or the MongoDB design system for a developer-tool aesthetic — and the conversion pattern becomes obvious. For the underlying token mechanics, see design tokens explained for agents.

Frequently Asked Questions

Does a DESIGN.md replace my Figma design system?

No. Figma stays your design-and-collaboration tool. The DESIGN.md is the agent-readable export of the decisions Figma holds — the two complement each other.

Can an AI read my existing PDF style guide?

Only loosely. It can extract some text and described intent, but not exact, applicable values. That's precisely why the token block in a DESIGN.md exists — to give the agent values it can use deterministically.

Is a DESIGN.md harder to maintain than a style guide?

Usually easier. It's one plain-text file in your repo, edited and reviewed like code, so updates propagate without a manual re-export step.

Which should a solo builder create first?

The DESIGN.md, by a wide margin. If you're shipping with an agent, an agent-readable spec changes your output today, whereas a polished style guide is a nice-to-have that no agent can consume.

How is a DESIGN.md different from a Stitch-style spec?

They're the same thing described two ways. "Stitch-style" names the structure; DESIGN.md names the file. See Stitch-style design systems explained.

Browse 135+ agent-ready design systems in the Designs category, or explore the full skill catalog at aiskill.market.