AI 에이전트를 위한 DESIGN.md vs tokens.json vs Figma

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

Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

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.