What is DESIGN.md and Why You Need It in 2026

The shortest possible definition

A DESIGN.md is a single Markdown file at the root of your project that tells every AI coding agent — Cursor, Claude Code, v0, Bolt, Lovable, Kiro, Stitch — what tokens to use when it generates UI. Colors. Type. Radius. Shadow. Spacing. Motion. Each token has a name and a value, written in fenced blocks the agent can parse without a markdown library. The file is small enough to review in a PR and large enough to render an opinionated brand.

That's it. Everything else in this post is texture on those two sentences.

Why a file, not a config service

You could imagine a world where each agent fetches your design tokens from a remote service. We considered it. The wager doesn't pay off:

• A network call adds latency to every prompt and a failure mode to every offline session.
• Auth complicates the developer-day-one experience. npx designdrop add stripe works without a login because the file is right there, in your repo, ready to commit.
• Every existing agent already reads files in the project root. The integration cost is zero.

So the file wins. The format is a strict subset of Markdown — agents can read it as prose, parsers can extract the tokens, and humans can edit it in whatever editor they already have open.

Anatomy of a DESIGN.md

Every DESIGN.md begins with a metadata comment so tooling can detect it:

<!-- @designdrop name=stripe version=1.0.0 -->

Then a heading, an optional description blockquote, and a series of ## Section blocks. Each section contains a fenced code block with one --token: value pair per line. A typical Stripe-inspired file looks like this:

# DESIGN.md — stripe

<!-- @designdrop name=stripe version=1.0.0 -->

> Developer-first SaaS. Vibrant gradients, minimal chrome.

## Colors / Light

\`\`\`
--primary: #635BFF
--ink: #0A2540
--accent: #00D4FF
--bg: #F6F9FC
--muted: #425466
\`\`\`

## Colors / Dark

\`\`\`
--primary: #8B85FF
--ink: #F4F2ED
--accent: #00D4FF
--bg: #0A1628
--muted: #94A3B8
\`\`\`

## Typography / Family

\`\`\`
--sans: "Inter", system-ui, sans-serif
--mono: "JetBrains Mono", ui-monospace, monospace
\`\`\`

## Typography / Size

\`\`\`
--sm: 14px
--base: 16px
--lg: 20px
--xl: 32px
\`\`\`

## Radius

\`\`\`
--sm: 4px
--md: 8px
--lg: 12px
--pill: 999px
\`\`\`

That's the whole format. Sections you don't need (Shadow, Spacing, Motion) are simply omitted. Sections you want to extend (custom semantic colors like --success, --warning) are added with the same --name: value shape.

What's required vs optional

The minimum viable DESIGN.md has four required pieces:

1. The metadata comment.
2. ## Colors / Light with at least --primary, --ink, and --bg.
3. ## Typography / Family with at least --sans.
4. ## Typography / Size with at least --base.

Everything else is optional but recommended. The DesignDrop validator (npx designdrop validate DESIGN.md) flags missing required tokens as errors with line numbers and tells you exactly what to add. It also warns when your dark theme is missing roles your light theme defines, because a dark theme that's missing --accent will produce inconsistent UI in dark mode.

What it intentionally is not

A DESIGN.md is not:

• A component library. There are no React/Vue/Svelte components in the file. The agent uses your tokens to render whatever component it's generating. Components are an output, not an input.
• A style guide. There's no prose explaining "use primary for primary actions". The token names already say that. Style guides are for human onboarding; DESIGN.md is for agent runtime.
• A complete brand book. Logo usage, voice and tone, photography direction — all out of scope. DESIGN.md is the visual decisions an agent needs to make a button. Anything an agent doesn't need to render UI doesn't belong here.
• A lockfile. You'll edit DESIGN.md often. Treat it like tsconfig.json — committed, reviewed, intentional, but not sacred.

How agents actually use it

When an agent encounters a project with a DESIGN.md at the root, the integration looks like this in pseudocode:

on prompt(p):
  spec = read("DESIGN.md")
  tokens = parseTokens(spec)
  augmentedPrompt = p + ", using these tokens: " + serialize(tokens)
  generate(augmentedPrompt)

The agent's training data already understands CSS Custom Properties and Tailwind theme blocks, so the augmented prompt produces UI that respects your tokens without any further prompting. You don't need to tell the agent to use --primary for the button background. It just does, because it knows what --primary means.

The behavior changes the moment DESIGN.md exists. There's no setup beyond the file. Drop it in, prompt as usual, get on-brand UI.

Conversion to every downstream format

DesignDrop's exporters round-trip DESIGN.md to every other token format:

• CSS Custom Properties — :root { --color-primary: #635BFF; ... } for any web project.
• Tailwind v4 @theme — CSS-first @theme { --color-primary: #635BFF; } so utility classes like bg-primary and text-ink work without a config file.
• W3C DTCG JSON — the standard format Style Dictionary, Tokens Studio, and Figma Variables understand. Each leaf is { $value, $type }.
• Plain JSON — flat token tree for any tool that doesn't speak DTCG.

The exporters are deterministic. The same DESIGN.md always produces the same output for every format. The DTCG export round-trips back to DESIGN.md without drift, which means you never get stuck in any of these formats.

Why naming the roles matters

Notice the colors are --primary, --ink, --accent — not --blue-500 or --purple-700. The role names matter more than the values. A six-line color section that names roles produces more consistent UI than a fifty-line color section that names hex values. Here's why:

When an agent generates a button, it asks "what color is the primary action?" Not "what color is blue 500?". When it generates a danger toast, it asks "what's the error color?" not "what's red 600?". Naming by role lets the agent reason about intent, which is the only thing that survives across components, themes, and brand changes.

You can change --primary from indigo to forest green tomorrow and every component the agent generates after that change picks up the new color, because the role didn't change. If you'd named your tokens --blue-500, you'd be stuck — the name lies, but the agent will use it anyway.

Editing live

You'll edit DESIGN.md three ways:

1. Directly in your editor. It's a markdown file. Open in VS Code, Vim, anything. Save. Re-prompt. New tokens take effect immediately because there's no build step.
2. Visually in DesignDrop. The editor at designdrop.app/editor gives you a real-time preview, color picker, contrast warnings (so you can't accidentally break WCAG AA), and one-click export. Useful when you don't want to think in hex.
3. Programmatically via the CLI. npx designdrop validate for linting. Future commands will scaffold sections from URL extractions and from popular brand starting points.

The three ways produce the same artifact. There's no "DesignDrop format" that's different from the file you can hand-edit. WYSIWYG without lock-in.

Common questions

Do I need DesignDrop to use DESIGN.md? No. The file is plain markdown with conventional fenced blocks. Hand-author one if you want; agents will read it. DesignDrop is the platform that makes browsing, generating, editing, and exporting easier — but the file format is open.

What if my agent doesn't read DESIGN.md yet? Most modern agents already crawl your project root. If yours doesn't, prefix your prompt with "use the tokens from ./DESIGN.md" and it'll pick them up. We're working with agent vendors to make this automatic.

Can I have more than one DESIGN.md? Yes. Apps in monorepos often have one per app (apps/web/DESIGN.md, apps/admin/DESIGN.md). Agents resolve relative to the file they're editing.

What about themes beyond light and dark? The format supports any number of theme sections — ## Colors / Halloween, ## Colors / Holiday. Most projects only need light and dark, but the spec doesn't restrict you.

How do I version the file? The metadata comment carries a version=... field. Bump it when you make a change you want to flag for downstream tools. Treat it like semver — patch for token-value changes, minor for new tokens, major for renamed roles.

The shortest possible recap

If you take one thing from this post: drop a DESIGN.md at the root of your project, and every prompt to your AI coding agent gets a free upgrade. No build. No config. No service. One file.