DESIGN.md is the only common approach that gives an agent structured values, expressible rules, machine readability, and persistence in one versioned file. Here is how it compares to the alternatives.
tokens.json: values, no rules
A tokens.json gives exact values but 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.
Prose in a README: rules, no structured values
A README or CLAUDE.md can express rules, but has no structured, machine-readable values to anchor to. The agent reads intent but has no precise tokens to apply.
A Figma link: unreadable to the agent
Figma is built for humans. An AI coding agent cannot read it directly, so a link gives the agent nothing.
DESIGN.md: all four properties
# tokens.json -> values (no rules, no prose)
# README prose -> rules (no structured values)
# Figma link -> neither (agent can't read it)
# DESIGN.md -> values + rules + machine-readable + versioned
It complements, not replaces
DESIGN.md exports to Tailwind and the W3C DTCG standard, so you keep your existing pipeline and use DESIGN.md as the source of truth:
$ npx @google/design.md export --format dtcg DESIGN.md > tokens.json
$ npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
FAQ
Can DESIGN.md and Figma coexist? Yes - keep Figma as the design source, export to DTCG, fold into a DESIGN.md whose prose adds rationale.
Is it proprietary? No - open, and its tokens are based on the W3C standard.
Bottom line
Each alternative has one or two of the properties an agent needs. DESIGN.md has all of them at once, in a single file.
Free starter: The format, a complete annotated example, and the core idea are on a free cheat sheet: DESIGN.md Quick-Start Cheat Sheet
Go deeper: The full guide covers the entire format — the token schema, the CLI in depth, accessibility, Tailwind and DTCG export, agent integration, and a complete walkthrough: DESIGN.md: The Complete Guide to Design Systems for AI Agents
How are you giving your agent design context today - a tokens file, a README, or nothing yet? Curious to compare approaches below.