Design Tokens vs DESIGN.md — Complementary or Competing?

You already have a tokens.json. Figma Variables are set up. The W3C Design Tokens spec finally stabilized. Your build pipeline transforms tokens into CSS custom properties, Tailwind config, and platform-specific files. Everything works.

Then someone mentions DESIGN.md and the first question is always: “Don’t I already have this covered?”

Short answer: no. Design tokens and DESIGN.md solve fundamentally different problems. One talks to machines that compile code. The other talks to machines that write code. That distinction matters more in 2026 than it did even a year ago.

What Design Tokens Actually Are

The W3C Design Tokens Community Group spent years defining a standard interchange format. The result: a JSON structure that describes atomic design decisions — colors, spacing, typography, shadows, borders. Raw values with names.

{
  "color": {
    "primary": {
      "$value": "#2563eb",
      "$type": "color"
    },
    "surface": {
      "$value": "#ffffff",
      "$type": "color"
    }
  },
  "spacing": {
    "md": {
      "$value": "16px",
      "$type": "dimension"
    }
  }
}

Figma Variables implement this concept natively. You define tokens in Figma, export them via plugin or API, and tools like Style Dictionary, Tokens Studio, or the Figma REST API push them through a build pipeline into platform-specific formats.

This is infrastructure. Tokens are the what — the raw values your system uses. They don’t explain why those values exist, when to use each one, or how they combine.

What DESIGN.md Adds

DESIGN.md is a Markdown file with YAML frontmatter that sits in your repository root. It describes your design system in a format optimized for LLM context windows. Not just values — rules, semantics, constraints, component patterns, and explicit do’s and don’ts.

Here’s what tokens can’t express:

• “Cards never use drop shadow, only 1px border”
• “Never combine more than 2 font weights on one page”
• “Primary buttons are reserved for the single most important action per screen”
• “Use surface for card backgrounds, never background”
• “Spacing follows 8px grid — no exceptions, no 12px hacks”

These are the rules that make a design system feel coherent. A human designer keeps them in their head. An AI agent needs them explicitly written down, every single time, because it has no memory between prompts.

DESIGN.md packs both the token values and the semantic rules into one file that fits inside a context window alongside your code. It’s the difference between giving someone a box of LEGO bricks versus giving them the bricks plus the instruction manual.

Check What is DESIGN.md for the full spec breakdown.

The Comparison That Actually Matters

Aspect	Design Tokens (W3C/Figma)	DESIGN.md
Format	JSON (W3C spec)	Markdown + YAML frontmatter
Primary consumer	Build tools (Style Dictionary, compilers)	AI agents (Claude, Cursor, Kiro)
Contains values	✅ All atomic values	✅ Key values (subset)
Contains rules	❌ No semantic rules	✅ Do’s, don’ts, component patterns
Build pipeline	✅ Transforms to CSS/Swift/Kotlin	❌ Not compiled — read at prompt time
LLM-readable	⚠️ Parseable but lacks context	✅ Designed for context windows
Versionable	✅ Git-tracked JSON	✅ Git-tracked Markdown
Multi-platform output	✅ (that’s the whole point)	❌ (not its job)
Explains intent	❌ Just values	✅ Why, when, how
Component patterns	❌ Token-level only	✅ Full component specs
Fits context window	⚠️ Large token files overflow	✅ Designed to be compact

Here’s what actually matters: design tokens feed your build system. DESIGN.md feeds your AI collaborator. One runs at compile time. The other runs at generation time.

When to Use Each (and When to Use Both)

Tokens alone work when:

• You have a mature component library already built
• Developers copy-paste existing components, no AI generation
• Your build pipeline needs multi-platform output (web + iOS + Android)
• The team is large enough that Figma is the single source of truth

DESIGN.md alone works when:

• You’re building fast with AI agents as primary implementers
• The project is small enough that you don’t need Style Dictionary pipelines
• You want one file that gives an agent everything it needs
• You’re prototyping or building an MVP

Both together work when (this is most teams in 2026):

• Tokens handle the build pipeline — CSS variables, Tailwind config, platform exports
• DESIGN.md handles the AI communication — rules, semantics, component patterns
• DESIGN.md references the token values but adds the context tokens can’t carry
• The system stays in sync because DESIGN.md can be generated from tokens + manual rules

Nobody tells you this: most teams that only use tokens still get inconsistent AI output. The agent reads your tokens.json, sees 47 color values, and has no idea which one to use for a card background versus a page background. DESIGN.md eliminates that ambiguity.

The Real Pipeline: tokens.json + DESIGN.md

Here’s how this works in practice with the official tooling:

# 1. Export tokens from Figma (via plugin or API)
figma-export tokens --output ./tokens/tokens.json

# 2. Transform tokens for your platforms
npx style-dictionary build --config sd.config.js

# 3. Generate or update DESIGN.md from tokens + your rules
npx @designmd/cli init --from-tokens ./tokens/tokens.json

# 4. Add semantic rules manually (the part tokens can't express)
# Edit DESIGN.md — add component patterns, do's/don'ts, constraints

# 5. Validate DESIGN.md structure
npx @designmd/cli lint ./DESIGN.md

# 6. Export to other formats if needed
npx @designmd/cli export --format yaml

The workflow splits cleanly:

• Figma → tokens.json → Style Dictionary → CSS/platform code (build pipeline)
• tokens.json → DESIGN.md → AI agent context (generation pipeline)

Both pipelines can live in the same CI. Tokens change in Figma, the build pipeline updates your CSS, and a separate step regenerates the token values section of your DESIGN.md. The semantic rules you wrote manually stay untouched.

Want pre-built DESIGN.md files to start from? The designmd.app library has 454+ options covering every visual style.

Pipeline Integration Example

In a real project, your package.json might look like:

{
  "scripts": {
    "tokens:build": "style-dictionary build",
    "tokens:sync-designmd": "npx @designmd/cli sync --from-tokens ./tokens/tokens.json",
    "designmd:lint": "npx @designmd/cli lint ./DESIGN.md",
    "prebuild": "npm run tokens:build && npm run tokens:sync-designmd"
  }
}

Every build ensures your DESIGN.md token values match the latest Figma export. The rules section — the part that makes AI output actually consistent — stays manually curated because no tool can infer “never use shadow on cards” from a JSON value.

Not Competing. Complementing.

Design tokens are infrastructure. They’ve been solving the multi-platform consistency problem since Salesforce invented the concept a decade ago. They’re not going anywhere.

DESIGN.md is communication. It solves the AI-agent consistency problem that didn’t exist until 2024. As more code gets written by agents, the need for a human-readable, LLM-optimized design system file only grows.

Use tokens for your build pipeline. Use DESIGN.md for your AI pipeline. They share the same source of truth (Figma, usually), but serve completely different consumers.

The teams shipping consistent AI-generated UI in 2026 aren’t choosing between them. They’re running both — tokens compiled into their CSS, DESIGN.md loaded into their agent’s context window. Different tools, same design system, zero conflict.

If your AI output still looks inconsistent despite having tokens, the problem isn’t the values. It’s the missing rules. That’s exactly what DESIGN.md adds.