designtoken.md vs design.md

What's the difference?

Both are markdown files that describe a design system for coding agents. The difference is depth and structure. One captures intent, the other provides deterministic, production-ready token definitions.

The concept

What is a design.md file?

A design.md file captures design intent in natural language — color names, font choices, and layout descriptions. It gives AI agents basic design context in a format that's easy to write. A typical design.md is 20–30 lines of high-level guidance: primary colors, font families, and brief component descriptions.

~20–30 lines
The extension

What is a designtoken.md file?

A designtoken.md extends this concept with structured, production-ready token definitions. Instead of “Primary: Blue” you get a full 50–900 color scale. Instead of “Font: Inter” you get a 9-level type hierarchy with sizes, weights, line heights, and letter spacing. 150–200 lines of deterministic, parseable tokens.

~150–200 lines
Side by side

See the difference

A design.md gives you the broad strokes. A designtoken.md gives your agent everything it needs to build consistent UI without guessing.

design.md

~25 lines
# Design System ## Colors Primary: #3B82F6 (Blue) Secondary: #8B5CF6 (Purple) Background: #FFFFFF Text: #111827 Error: #EF4444 ## Typography Headings: Inter, bold Body: Inter, regular, 16px Small: 14px ## Layout Max width: 1200px Spacing: 8px base grid Border radius: 8px for cards ## Components Buttons: Primary blue, white text, rounded corners, hover darkens Cards: White bg, subtle shadow, rounded corners, 24px padding Inputs: Border, rounded, focus ring with primary color

designtoken.md

~170 lines
# Design Tokens ## Color – Primary (Blue) | Stop | Hex | Usage | |------|---------|--------------------| | 50 | #EFF6FF | Hover backgrounds | | 100 | #DBEAFE | Selected states | | 200 | #BFDBFE | Light accents | | 300 | #93C5FD | Borders | | 400 | #60A5FA | Icons | | 500 | #3B82F6 | Default buttons | | 600 | #2563EB | Hovered buttons | | 700 | #1D4ED8 | Pressed states | | 800 | #1E40AF | Focus rings | | 900 | #1E3A8A | High-contrast text | ## Typography Scale | Level | Size | Weight | LH | LS | |---------|------|--------|-----|---------| | display | 36px | 700 | 1.1 | -0.02em | | h1 | 30px | 700 | 1.2 | -0.02em | | h2 | 24px | 600 | 1.3 | -0.01em | | h3 | 20px | 600 | 1.3 | -0.01em | | h4 | 16px | 600 | 1.4 | 0 | | body | 16px | 400 | 1.5 | 0 | | body-sm | 14px | 400 | 1.5 | 0 | | caption | 12px | 500 | 1.4 | 0.01em | | overline| 11px | 600 | 1.4 | 0.06em | ## Spacing Scale | Token | px | Use | |-------|-----|-----------------| | xs | 4 | Inline gaps | | sm | 8 | Icon gaps | | md | 16 | Card padding | | lg | 24 | Section gaps | | xl | 32 | Page margins | | 2xl | 48 | Section padding | | 3xl | 96 | Hero padding | ## Component – Button | Prop | Default | Hover | |------------|-------------|-------------| | bg | primary-500 | primary-600 | | text | #FFFFFF | #FFFFFF | | radius | md (8px) | | | padding | 10px 20px | | | font-weight| 600 | | …
Feature breakdown

Token by token

A detailed comparison of what each file format covers.

Dimension design.md designtoken.md
Color depth 4–6 named color roles Full 50–900 scales for 4 color roles + semantic aliases
Typography 2–3 font/size entries 9-level type scale with weights, line heights, letter spacing
Components Natural language descriptions Structured component token sets with states
Elevation Not typically addressed Shadow scale from sm to xl
Spacing Mentioned in layout text Named scale (4px–96px) with use annotations
Border radius Inline in component text Radius scale with semantic names
Visual preview None Visual reference card
Agent parsing Requires NLP interpretation Deterministic markdown — headings + tables
Typical size ~30 lines ~150–200 lines
Guidance

When to use each

Both formats have a place. Here's how to choose.

design.md

  • Quick prototyping and throwaway projects
  • Simple landing pages where a few colors and fonts are enough
  • When you just need basic color and font guidance for an agent
  • Early exploration before your design system is finalized

designtoken.md

  • Production projects that need consistent component styling
  • When multiple agents or developers share the same token reference
  • When you need full color scales, not just a single hex per role
  • When components need defined states: default, hover, active, disabled
FAQ

Common questions

Can I use both design.md and designtoken.md?
Yes — a designtoken.md is a superset. You can use it alongside or instead of a design.md. If you already have a design.md, adding a designtoken.md gives your agent the structured depth it needs without losing any existing context.
Does designtoken.md replace design.md?
Not necessarily. A design.md is a solid concept for capturing quick design intent. A designtoken.md provides the structured depth agents need for consistent production UI. Think of it as going from a sketch to a blueprint — both are useful at different stages.
Which coding agents read designtoken.md?
Any agent that reads project context files: Claude Code, Cursor, Copilot, Codex, and Gemini CLI. The file uses standard markdown with headings and tables, so any agent that can parse markdown will understand it without special integration.

Try the generator

Generate your own designtoken.md file — free, no signup.

Start generating →