DESIGN.md vs tokens.json vs Figma: Which Gives Agents Design Context?

DESIGN.md is the only common approach that gives an AI agent structured values, expressible rules, machine readability, and persistence in one versioned file. A tokens.json has values but no rules; prose in a README has rules but no structured values; a Figma link the agent cannot read at all.

Why is a tokens.json not enough?

A tokens.json gives an agent exact values, but it cannot express rules. There is no way to say "use the accent only for the primary action" in JSON. The agent knows your colors but not how to apply them, so it uses them generically. DESIGN.md keeps the structured values and adds the prose that carries intent.

Why is prose in a README not enough?

Prose in a CLAUDE.md or README can express rules, but it has no structured, machine-readable values for the agent to anchor to. The agent reads the intent but has no precise tokens to apply. DESIGN.md pairs the prose with typed tokens, so intent and values live together.

Why can't the agent just use Figma?

A Figma file is built for humans. An AI coding agent cannot read it directly, so a Figma link gives the agent nothing. DESIGN.md is plain text the agent reads natively — and it can be generated from or exported to design tooling, so it complements Figma rather than replacing it.

Does DESIGN.md replace my existing tokens?

No — it complements them. DESIGN.md exports to Tailwind and the W3C DTCG standard, so you keep your existing pipeline and use DESIGN.md as the human-and-agent-readable source of truth. It is a layer you add, not a system you swap in.

FAQ

Can DESIGN.md and Figma coexist? Yes. You can keep Figma as the design source, export tokens to DTCG, and fold them into a DESIGN.md whose prose adds the rationale Figma cannot capture.

Is DESIGN.md a proprietary format? No. It is open, and its tokens are based on the W3C standard, so they convert cleanly to other formats.