DESIGN.md: the AI-era brand guide

Your brand guide is a 60-page PDF in Google Drive. Your Figma library has 200 components, most of them themed wrong. Your tokens live in a tokens.json file nobody outside engineering has ever opened.

None of that is what Claude Design asks for when it generates a dashboard for you at 11pm.

What it asks for, implicitly, by how it was built, is a single Markdown file that describes your brand in language an AI can actually use. We call that file DESIGN.md. It's the thing the old brand guide was trying to be, before PDFs and AI design tools existed in the same sentence.

This post lays out what DESIGN.md is, why it works, what goes inside one, and how to start building yours today.

Brand context keeps dying in the handoff

Every team hits the same wall. The brand lives somewhere: Notion, a PDF, a style guide deck, a Figma page titled "Brand v2 FINAL". The people who need it most (developers, AI tools, new hires on day one) don't read any of those.

It's not a discipline problem. It's a format problem.

PDFs are for reading, not for parsing. A designer opens one when they're stuck, finds the hex code, moves on. A large language model can't open one during a prompt.
Figma libraries are for designers, not engineers. They encode what a button looks like, not why your brand picks blue over amber.
tokens.json has values but no reasoning. --accent: #2563EB tells a tool what to use. It doesn't tell the tool when to use it.

So when an AI tool (Claude Design, Cursor, Lovable, v0) goes to generate UI for you, there's nothing to read. It falls back to the statistical mean of everything it was trained on, which is a million shadcn dashboards. Your tool produces a generic result not because it's bad at design, but because you haven't given it anything specific to work from.

DESIGN.md is what you give it.

What DESIGN.md is

DESIGN.md is a single Markdown file, usually 200 to 500 lines, that encodes everything an AI tool (or a new hire) needs to produce on-brand work. It lives in your repo, typically at design-system/DESIGN.md. It sits next to tokens.json and SKILL.md, and together they form a design system that's legible to both humans and machines.

A well-written DESIGN.md has six parts:

Essence. The one-paragraph answer to what is this brand, fundamentally? Not a tagline. The emotional substrate the brand is built on.
Personality. If the brand were a person, who would they be? Archetype, age, how they dress, how they talk at a party.
Principles. Five to seven decision-making rules. "Warmth over neutrality." "Density over decoration." "Earn every animation." The things that tell you what to do in a situation the brand guide never anticipated.
Nevers. What this brand actively rejects. "No cold clinical blue." "No gamification." "No marketing-speak headlines." Constraints make AI output dramatically better.
References. A small reference gallery with commentary. Not "we like Linear", but why we like Linear. What specifically, in one sentence each.
Tokens. A pointer to tokens.json (or inline for simple cases) plus the reasoning behind the key choices. Colors, type, spacing, shape, elevation, with a line each explaining the intent.

That's it. A hundred pages of brand guide compresses down to one readable file that any AI tool can ingest in a single prompt.

Why Markdown specifically

This part isn't arbitrary. The format is doing load-bearing work.

Every frontier AI model was trained on Markdown. Documentation, GitHub READMEs, blog posts. It's the native dialect of the modern web. AI tools parse it without effort or error.
It's human-readable without rendering. Your designer can open the file in a plain editor and understand it. So can your marketing lead. So can Claude.
It's version-controllable. Every edit lives in git. When the brand evolves, you have a history. CHANGELOG.md in the same folder tracks the why.
It round-trips. Any tool can produce it, any tool can consume it. Claude Design reads it via Skills. Cursor picks it up from your project root. You can copy-paste the whole thing into ChatGPT.

There's no magic here. You're using the format that happens to sit at the intersection of readable by anyone with a text editor and parseable by every language model that exists.

Where it lives and how AI tools find it

DESIGN.md belongs in your repo. The conventional location is design-system/DESIGN.md, next to tokens.json, tokens.css, and SKILL.md.

From there:

Claude Design reads it via a Skill. You publish a SKILL.md (a small wrapper file that points Claude Design at your DESIGN.md and tokens.json) and load it into your Claude Team workspace. Every future session uses it as context.
Cursor and Claude Code read it automatically. Both agents scan the project root for Markdown files and use them as context when generating code. No setup beyond checking the file in.
ChatGPT, Lovable, v0 (tools without a formal project-context concept) still work. You copy the contents into the prompt once per session, or use their context-pinning features where available.

The point isn't that one tool is better than another. It's that DESIGN.md is the common language between them. Write it once, use it everywhere.

What happens when you actually use it

Here's the difference in practice.

Without a DESIGN.md, a prompt like "generate a settings page for a B2B fintech dashboard" produces a page. It has a sidebar, some form fields, probably a blue button labeled Save. It looks like every other B2B settings page on the internet, because the model had nothing else to work from.

With a DESIGN.md that includes the essence "confident but not cold. Finance that respects your intelligence," the principles "warmth over neutrality" and "editorial confidence", and tokens pointing to a warm accent and serif headlines, the same prompt produces a settings page that feels like it belongs to your product. The form labels are in your serif. The Save button is warmer. The layout breathes where your brand breathes.

You didn't micro-manage the prompt. You gave the tool the brand, and the brand did the work.

This is why DESIGN.md matters more than any individual principle or token choice inside it. It's the handoff mechanism. Without something in that role, AI generates generic. With it, AI generates yours.

DESIGN.md vs everything else

If you already have design assets, a natural question is do I still need a Figma library? A brand guide? tokens.json?

Yes. They do different jobs.

Figma library: for designers working in Figma. Encodes shape, spacing, component APIs.
Brand guide (PDF or otherwise): for humans at a high level. Story, positioning, logo usage rules.
tokens.json: for engineers and build tooling. Machine-readable values.
DESIGN.md: for AI tools and anyone who needs the reasoning, not just the values.

They aren't replacements for each other. DESIGN.md fills the gap where AI tools and new team members used to fall through.

If I had to rank them by value per hour spent creating, though, DESIGN.md wins. A Figma library takes weeks to build and serves one audience. A well-written DESIGN.md takes two days and serves every audience, every tool, every future team member.

How to start building yours

You can write a first draft in an afternoon. Here's the shape:

Start with Essence. Not your marketing copy. The real thing. What does this brand feel like? One paragraph. Rewrite it three times before you settle.
Draft Personality. Age, archetype, how they talk, what they wear. Make it specific enough that two readers would picture the same person.
Write five Principles. These are the hardest. Each one should be the thing you'd tell a new designer on day one. "Use color to create hierarchy, not decoration" is a principle. "Use blue" is a value.
Write five Nevers. What the brand rejects. Constraints are force multipliers for AI.
Curate References. Five to eight visual references, with one sentence each explaining what specifically you're drawing from them. "Linear: the quiet confidence of their spacing."
Pull in Tokens. Either inline the key values with reasoning, or point to tokens.json. If you point out, add a short explanation of each token family's intent.

Save it as DESIGN.md in your repo. Commit it. Open a fresh Claude Design session and paste it into the first message. Ask for a screen. Watch how different the output is.

Either way: the bar for AI-era brand work is a file like this one, and teams who have one will ship on-brand output from the first prompt. Teams who don't will keep fighting their tools.

This is the hub post for our series on design systems for AI tools. See also: DESIGN.md is now an open standard (Google Labs just published the spec), and What is Claude Design, and how do you give it your brand?.