Markdown or JSON for Design Tokens: What the Evidence Says

Direct answer

No rigorous, reproducible comparison shows that agents follow Markdown design systems better than JSON tokens, or the reverse. JSON in the Design Tokens Community Group (DTCG) format is the right source of values for build pipelines. Markdown such as DESIGN.md carries rules and rationale that raw tokens usually lack. Keep values in JSON, put rules in prose, and measure adherence yourself.

Two files, two jobs

A design token file stores design decisions as data for build tools. A DESIGN.md stores the same decisions plus the reasoning, as context for an agent. Treating one as a replacement for the other is where most of the confusion starts.

A design token is a named decision such as color.action.primary with a color value. The Design Tokens Community Group (DTCG), a W3C Community Group, published its first stable Format Module, version 2025.10, on October 28, 2025. Every token has a $value and an optional $type, tokens sit in nested groups, and one token can alias another with {group.token} syntax. Files use the .tokens or .tokens.json extension.

“Stable” has a narrow meaning here. The report is not a W3C Standard; it is published under the W3C Community Final Specification Agreement. Tooling lags too: Style Dictionary’s documentation says it has had first-class DTCG support since version 4, but that 2025.10 is not yet fully supported, with work in progress for version 5. Check both before you depend on them.

DESIGN.md is Google Labs’ open specification for describing a visual identity to coding agents. A file has optional YAML front matter holding tokens (colors, typography, rounded corners, spacing, components), followed by Markdown sections in a fixed order that ends with Do’s and Don’ts. Google open-sourced it on April 21, 2026, and the repository says the format is at version alpha.

Google’s pitch is about intent, and software engineer Cassia Xu put it plainly in the announcement:

The two formats are not exclusive. Inside a DESIGN.md the spec settles which wins, and the command-line tool can export the front matter to Tailwind or to DTCG JSON.

What each format carries cheaply

The useful question is not which format is smarter but which information each one carries at low cost. JSON wins on values, aliases and build output. Markdown wins on scope, intent and prohibitions.

Two points matter for the argument that follows. First, JSON can hold prose: DTCG supports $description on tokens and $extensions for tool-specific data, so rationale does not strictly need Markdown. Most real token files leave both empty.

Second, a DESIGN.md can fail in the other direction, with prose that contradicts its tokens. The spec says the tokens win, but an agent still has to follow that rule. For how real systems store their values in practice, see how ten public design systems keep their token layers; only two of the ten write them as JSON.

Why the Markdown-wins claim does not hold yet

The most direct claim that Markdown wins comes from an Open Design post by the opendesigner.io editors, and it is a fair hypothesis, not a measurement. It describes the same brand brief and the same landing-page hero, with three agent runs against JSON tokens only and three against a DESIGN.md, using Claude Opus 4.7. Its verdict: with JSON only, the agent used tokens correctly “but didn’t seem to understand why.”

Four things on the page keep it from counting as evidence.

1. Format and information are confounded. The DESIGN.md condition contains prose rules the tokens-only condition lacks. A better result may come from the extra rules, and the test cannot separate the two.
2. The outcome is a judgment. “Visibly closer” has no metric, rubric or blind rater.
3. The sample is tiny and unreconciled. Three runs per condition is six runs, yet the page also mentions “8 out of 10 agent runs we audited” without explaining how the numbers relate.
4. The publisher has a stake. The post belongs to a project that promotes DESIGN.md-style design systems. That does not make it wrong; it is a reason to wait for independent replication.

The pattern repeats elsewhere. A WaveSpeed author rebuilt one component library twice and reported that in the tokens-only run, screens 5 to 8 of 8 started to drift, with no counts. A site that sells DESIGN.md files argues the formats complement each other and offers no test.

The JSON side is no better supported. Brent Haskins argues that machine-readable specs reduce hallucination, backs it with one dashboard project, and gives the practical advice that is easy to adopt whichever format wins:

That advice survives either way, since a CI check works on generated code whatever file the agent read.

What the research on neighbouring problems says

No peer-reviewed study and no public reproducible benchmark isolates the format of design tokens for agent adherence. That absence is a finding, with one caveat: it covers the sources checked on October 1, 2026, and a private study could exist. What does exist falls into five tiers.

Prompt-format studies exist, but on other tasks. He et al. gave the same content to OpenAI GPT models as plain text, Markdown, JSON and YAML. GPT-3.5-turbo varied by up to 40% on a code translation task depending on the template, GPT-4 was more robust, and the authors conclude there is no universally optimal format. Kato and Kato varied algorithm specifications across seven styles and three models over 4,020 generated implementations. The best format differed by model, and one model showed no differences once the specification was complete.

Our reading: format effects are real for some models and tasks, shrink as models get stronger or content gets more complete, and do not point to one winner. Neither study used design tokens or an agent that can read files and run linters, so they cannot be projected onto your case.

The two nearest design-system results answer different questions. The Indeed benchmark, about storing component documentation for retrieval through an MCP server (Model Context Protocol, the interface agents use to call external tools), reports its best configuration at 88% token savings and 92% retrieval accuracy against an in-production baseline at 89%. That is about getting the right facts into context cheaply, not about whether an agent then follows a color rule. A secondary article repeats other figures for it that the primary page does not show, so only the primary page is used here.

The CHI 2026 extended abstract is the closest thing to a controlled design-system study. Across six real-world UIs it reports the highest compliance, 95.08%, for the registry-based strategy, where the agent assembles pre-built components. If that holds up, the bigger lever is giving agents components to compose, not choosing how to write down colors. Only the abstract was read.

For a different kind of real data, the DESIGN.md linter study of public files shows how real files fare: 21 of 48 sampled files exited with errors. The linter checks tokens and structure, not whether prose matches tokens, so it cannot answer the adherence question either.

A fair test: four conditions, same rules

Because nobody has published the clean version, the cheapest answer is your own run. This design is a proposal, sized for an afternoon of compute and an hour of review.

1. Fix the information. Write your design rules once: which token for which role, scope, contrast constraints, prohibitions. Every condition must contain exactly these rules.
2. Build four conditions. A: values only, as DTCG JSON. B: the same JSON with the rules in $description fields. C: a DESIGN.md with the same tokens and rules in prose. D: the hybrid described below. Keep token names identical.
3. Pick five to eight real tasks, from easy (restyle a button) to hard (a settings page with error and empty states). Fix and record the model, version and settings.
4. Run each task in each condition at least five times, in random order, from a clean checkout.
5. Score with machines first. Search the output for hex colors, pixel sizes and font names that are not in the token set, and run your linter and, for DESIGN.md, the project’s lint for broken references.
6. Score rules with a checklist, per prose rule, followed or violated, by someone who does not know the condition.
7. Report counts, meaning violations per output per condition plus tokens consumed. With five runs only large differences are trustworthy.

Condition B is the one published comparisons skip. If A loses to C but B matches C, the format was never the problem; the missing rules were. If C beats B, format or structure matters for your model, and you have your own evidence. For the wider question of what an agent keeps from a design at all, see the four design-to-code mechanisms and how to test fidelity.

A hybrid setup (opinion)

This section is opinion, built on documented behaviour and not on adherence data. If you already run a token pipeline, keep the DTCG JSON as the single source of truth for values, since that is what Style Dictionary, Terrazzo and Figma-side tooling consume.

Generate the token block of a DESIGN.md from that source and hand-write only the prose: scope, contrast intent, prohibitions and edge cases. The DESIGN.md tool documents export to DTCG, not the reverse, so the JSON-to-front-matter step is a small script you write. Add a CI check that every front-matter value equals the JSON value. Because DESIGN.md is alpha, isolate it behind that script.

Rules that apply across tasks can also live in an agent skill instead of a design file; what Claude design skills are and how to judge them covers where that fits. For agents that call an MCP server, return component APIs (props, variants, sizes) as structured JSON and keep behavioural rules in Markdown. That matches the Indeed team’s stated conclusion, though its benchmark measured retrieval and not adherence.

Draw the result as a token flow map so reviewers can see which file feeds which; the four design system diagrams worth drawing shows how. And ask whether a registry of real components would remove more mistakes than any file format. An agent that composes Button from your library cannot invent a hex value for it.

Pick by job, then measure the format

Markdown or JSON is a weaker question than it looks. JSON in the DTCG format is the better home for values that tools must validate and compile. Markdown is the better home for the reasons, scopes and prohibitions that raw tokens rarely carry. DESIGN.md puts both in one file and says tokens win when they conflict with prose.

Whether agents follow prose plus tokens more reliably than tokens alone has not been shown in a public, reproducible test. The strongest claim so far rests on six runs, a confound and a judged outcome. Treat it as a hypothesis, run the four-condition test before rewriting your documentation around it, and recheck the sources below, because specs, tooling and models are changing quickly.