DESIGN.md at scale: when tokens aren’t enough (and what to add)

Your DESIGN.md hit 200 lines. The agent generates on-brand interfaces. You think the problem is solved. It’s not. You solved maybe a third of the problem, and frankly, it was the easiest third.

Tokens are the trivial part. Colors, typography, spacing, border-radius: that’s a lookup table. The agent reads primary: #2563EB and applies it. Done. The difficulty starts when it needs to decide which component to use, how that component behaves in different states, and what must never be done with it. That’s where your DESIGN.md goes silent and the agent starts guessing.

The diagnosis: tokens covered, behavior in the dark

Let me be blunt about what happens when your DESIGN.md only contains tokens.

The agent gets the palette. Gets the fonts. Gets the spacing values. And then it needs to build a pricing card. Which variant should it pick? Does the recommended plan get a highlight? Does the “popular” badge sit inside or outside the card? Is the CTA filled or outline? Does the old price use strikethrough and if so, what style?

None of these questions have answers in your tokens. The agent will infer. Sometimes it gets lucky. Usually it produces something generic and forgettable.

The team at Meticulous.com put this precisely:

“DESIGN.md spec is the right portable interchange for AI coding agents. It is not the right canonical source for tokens.”

Translation: DESIGN.md is the correct communication format between human and agent, but if you treat it as nothing more than a token dump, you are brutally underusing the tool.

And the folks at designproject.io add:

“The agent has the palette and fonts, so it produces something that is on brand, but it still guesses at which component to use.”

Exactly. The result is on brand but not on system. There’s a massive difference between “has the right colors” and “uses the right components in the right way.”

The problem scales exponentially

For a simple landing page, tokens are fine. The agent has a small margin of error because there are few components and minimal interaction.

Now think about a SaaS dashboard with 40 screens. Or a design system serving 5 different products. The agent needs to choose between:

Button primary vs secondary vs ghost vs destructive
Card default vs elevated vs outlined vs interactive
Modal vs Drawer vs Dialog vs Sheet
Table with sorting vs without, with selection vs without, paginated vs infinite scroll

Without explicit documentation, every choice becomes a coin flip. Multiply that by 200 components across 40 screens. The “guessing debt” explodes.

Extension 1: Components section in DESIGN.md

The first extension is obvious yet almost nobody does it: list your components with usage context.

I’m not talking about documenting the full API of each component. That’s Storybook’s job. I’m talking about giving the agent enough information to choose correctly.

## Components

### Button
- **Variants:** primary, secondary, ghost, destructive, link
- **Use primary for:** main CTA per page (only ONE per visible viewport)
- **Use ghost for:** secondary actions, toolbar items, cancel actions
- **Use destructive for:** irreversible actions (always with confirmation dialog)
- **Never:** two primary buttons side by side. Never a destructive button without text label.

### Card
- **Variants:** default, elevated, interactive, outlined
- **Use elevated for:** content that needs visual hierarchy boost (pricing highlight, featured item)
- **Use interactive for:** cards that navigate somewhere on click (cursor: pointer, hover state)
- **Use outlined for:** content grids where cards are dense and elevation would be noisy
- **Never:** elevated card inside another elevated card. Never interactive card without hover state.

This resolves 80% of the guesswork. The agent doesn’t need to know every prop. It needs to know when to use what and what to never do.

Extension 2: Behavior Annotations

Tokens describe appearance. Components describe structure. But what about behavior?

When a form has an error, what happens? Does the field turn red? Does an inline message appear? Does the submit button disable? Does focus jump to the first errored field?

Behavior annotations are micro-specs for interaction:

## Behaviors

### Form Validation
- Validate on blur (not on keystroke)
- Show error message below field, not as tooltip
- Error border: use `destructive` color on field border
- On submit with errors: scroll to first error, focus that field
- Submit button: never disable. Show loading state instead.

### Loading States
- Buttons: show spinner inside, maintain button width
- Pages: skeleton loader matching content layout (not generic spinner)
- Tables: skeleton rows (5 rows placeholder)
- Cards: pulse animation on full card shape

### Empty States
- Always include: illustration + title + description + CTA
- Never show blank area or just "No data"
- CTA should be the primary action to create first item

This eliminates an entire category of “works but works wrong.” The agent knows not to slap a generic spinner in the middle of the screen. It uses skeleton loaders that match the actual layout.

Extension 3: Do/Don’t with visual examples

The most powerful section and the most neglected one. Humans learn from examples. So do agents.

## Do / Don't

### Spacing
- ✅ DO: Use consistent 8px grid for all spacing
- ✅ DO: 24px padding inside cards, 16px gap between cards
- ❌ DON'T: Mix 5px and 8px spacing in the same component
- ❌ DON'T: Padding smaller than 16px inside any container

### Typography
- ✅ DO: Page title in h1 (one per page), section titles in h2
- ✅ DO: Body text at 16px minimum for readability
- ❌ DON'T: More than 3 font sizes visible simultaneously
- ❌ DON'T: Center-align body text longer than 2 lines

### Color
- ✅ DO: Primary color only for CTAs and key interactive elements
- ✅ DO: Neutral backgrounds for content areas, color for accents
- ❌ DON'T: Primary color as background for large areas
- ❌ DON'T: More than 2 accent colors in one viewport

Every single “DON’T” is an error the agent would have committed without this instruction. Think of them as guardrails. They don’t limit creativity. They limit stupidity.

The complete structure that works

After experimenting across dozens of projects, we landed on this structure for DESIGN.md at scale:

# DESIGN.md

## Tokens
(colors, typography, spacing, border-radius, shadows — what you already have)

## Components
(list of components with variants, when to use each, anti-patterns)

## Behaviors
(interaction states, loading, error, empty states, animations)

## Patterns
(recurring layouts: form layout, dashboard grid, card grid, hero sections)

## Do / Don't
(explicit examples of what's correct and what's wrong)

## Decisions
(design decisions already made that the agent must respect: "modals never exceed 640px width", "we never use carousels")

This structure keeps DESIGN.md as a single document. No fragmenting into multiple files that the agent might not load. Each section has a clear function.

How much is too much?

Legitimate question. If DESIGN.md grows to 2000 lines, does it blow up the agent’s context window?

Practical answer: a DESIGN.md with all these sections for a medium-sized SaaS (30-50 components) lands between 400-600 lines. That consumes roughly 2000-3000 context tokens. For an agent with 128K-200K context, that’s nothing. Rounding error.

If your design system is huge (100+ components), then yes, consider a selective loading strategy. But that’s a problem for another article.

The golden rule: if the agent keeps guessing wrong, the documentation needs to grow. If it consistently gets things right, the current size is fine.

The simple test: is your DESIGN.md complete?

Try this exercise:

Pick a screen in your product that doesn’t exist yet
Give the agent only the DESIGN.md and a description of the screen
Look at the result
List everything it guessed incorrectly
Each error maps to a missing section in your DESIGN.md

If it used the wrong component, your Components section is lacking. If it botched the loading behavior, your Behaviors section needs work. If it put two competing primary colors on screen, your Do/Don’t is incomplete.

This feedback loop is how DESIGN.md evolves. Don’t try to document everything upfront. Document what the agent gets wrong.

In practice: before and after

Before (tokens only):

Prompt to agent: “Create a settings page with Account, Notifications, and Billing sections”

Result: three sections stacked vertically, each styled differently, inconsistent buttons everywhere, no clear visual separation, forms mixing inline validation with tooltips randomly.

After (tokens + components + behaviors + do/dont):

Same prompt, same agent.

Result: sidebar+content layout, each section in an outlined card, forms with blur validation and inline error messages, primary button only on the main save action, secondary buttons on per-section saves, skeleton loaders on billing data.

The difference isn’t subtle. It’s the difference between “scrap and rebuild” and “tweak a few things.”

DESIGN.md doesn’t replace your design system. It translates it.

A common confusion: “if I have Storybook, why do I need DESIGN.md?”

Storybook is component documentation for humans. It shows props, variants, interactive playgrounds. But agents don’t browse Storybook. They don’t click through URLs. They don’t open iframes. They read text.

DESIGN.md is the translation of your design system into the format agents consume. It’s not duplication. It’s a different communication format for a different consumer.

Think of it this way: you have technical docs for developers and release notes for users. Same product, different formats, different audiences. DESIGN.md is the “agent format” of your design system.

Conclusion: tokens are yesterday, components are today

If your DESIGN.md is still just a list of colors and fonts, you’re stuck in 2024. Agents in 2025 already know how to apply tokens. They need guidance at higher levels of abstraction.

Add components. Add behaviors. Add do/dont rules. Your DESIGN.md goes from “color palette” to “complete design guide,” and agent output goes from “aesthetically correct” to “functionally correct.”

That’s not a small upgrade. That’s the difference between an agent that saves you time and an agent that creates more work than it eliminates. I’ve seen teams go from spending 40% of their time fixing agent output to spending 5% on minor adjustments. The investment is a few hours of documentation. The return compounds every single day.

If you’re building anything beyond a one-page marketing site, your DESIGN.md needs to grow up. Tokens were the starting line. Components, behaviors, and explicit rules are the actual race.

Want to generate a complete DESIGN.md with tokens, components, and behavior annotations? designmd.app generates your spec in minutes from your existing site, including the component and behavior extensions we discussed here. Try it free.