Design Tokens Are an ABI: Why a Stable Format Is Not a Stable Design System

A token file is an interface, not a design system

The first stable Design Tokens Format from the Design Tokens Community Group solves a real problem: tools can exchange design decisions without every team maintaining a custom adapter. It does not solve the harder problem of agreeing what those decisions mean.

That distinction matters because design tokens are increasingly consumed by more than CSS compilers. They feed native mobile code, design tools, documentation, accessibility checks, theme generators, and AI coding agents. Once several consumers depend on the same token set, the token file behaves less like a palette and more like an application binary interface (ABI): a compatibility boundary between a source of decisions and many generated implementations.

An ABI does not tell a program whether an API is well-designed. It tells independently compiled pieces how to connect without guessing. Design tokens need the same discipline. A stable interchange format gives you syntax and types; a durable design system still needs semantic contracts, ownership, compatibility rules, and tests for the outputs.

The recommendation is simple: adopt the DTCG format as transport, but govern tokens as a versioned interface. Do not declare victory when an export validates. Ask whether every consumer can interpret the same token with the same intent.

What the DTCG format fixes—and what it deliberately leaves open

The 2025.10 DTCG report standardizes JSON files, token types, groups, aliases, and composite values. Its own introduction describes the problem as tool-specific formats that force design-system teams to write and maintain bespoke glue code. The proposed format lowers that integration burden by giving tools a common vocabulary for exchanging token data (the DTCG Format Module).

That is an interoperability win, not a governance policy. The specification explicitly says groups are arbitrary and that tools should not infer a token’s type or purpose from group names. In other words, a folder called brand, semantic, or components is not a universal contract. Your organization must define how those layers behave.

The same is true of names. A token has a human-readable name, a value, a type, and optional metadata. The format can carry color, dimension, typography, aliases, and composites. It cannot decide whether blue-500 is safe for body text, whether surface-brand may be used for a destructive action, or whether changing a primitive is a breaking change for a native app.

That boundary is healthy. A standard that tried to encode every team’s naming and architecture choices would not be interoperable; it would be another opinionated tool. The mistake is treating the boundary as if it were a complete operating model.

Layer	What the standard provides	What your team must provide
Syntax	JSON structure, $value, $type, groups, aliases	File layout, naming conventions, repository ownership
Meaning	Standard token types and composite shapes	Semantic roles, allowed contexts, accessibility intent
Translation	A shared input for platform-specific generators	CSS, Android, iOS, and web mapping rules
Compatibility	A common representation tools can parse	Deprecation policy, versioning, migration notes
Quality	A machine-readable object model	Contrast, usage, drift, and generated-output tests

This is why “we now export DTCG” is not the same statement as “we have a source of truth.” The first describes serialization. The second describes a system of consequences.

Treat tokens like an ABI: separate primitives from semantic contracts

The most important design decision is to stop exposing raw values as the primary API. A consumer should rarely ask for blue-500; it should ask for the role that the interface needs, such as text-link, surface-action, or focus-ring. Primitive tokens can remain useful, but they should be implementation details behind semantic aliases.

A useful three-layer model looks like this:

1. Primitives describe measurable values: a color space value, a spacing dimension, a font family, or a duration.
2. Semantics describe intent: text, surface, border, action, status, focus, or elevation.
3. Components bind intent to a particular state: button background, input border, dialog scrim, or card padding.

The DTCG specification supports aliases, so the contract can be represented directly rather than duplicated in every platform output:

{
  "color": {
    "blue": {
      "500": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [0.12, 0.32, 0.88]
        }
      }
    },
    "text": {
      "link": {
        "$type": "color",
        "$value": "{color.blue.500}"
      }
    }
  }
}

The example is intentionally small. In production, text.link should carry metadata or adjacent documentation that answers questions the value alone cannot answer: which backgrounds are allowed, whether visited and hover states are required, and which accessibility test owns the rule.

This also makes rebranding safer. A primitive may change while the semantic role remains stable. A product can change its blue without forcing every consumer to search for raw values. Conversely, a semantic role can be removed only after consumers have a migration path. That is ABI thinking: the internal implementation may move, but the public contract changes deliberately.

The approach extends the argument in our earlier analysis of design tokens and manual hex-code adoption, but the operational question has changed. The challenge is no longer merely getting values into variables. It is preventing each downstream tool from inventing its own meaning for those variables.

The strongest evidence is not the format; it is the generated contract

A token pipeline is successful only when the generated artifacts are more reliable than the files they replace. The DTCG community lists format, color, and resolver modules among its stable 2025.10 reports, and describes the ecosystem as a way to share stylistic pieces across tools at scale (the Design Tokens Community Group). That ecosystem still needs a reproducible build boundary.

Define one source directory and make every output disposable:

 tokens/
   primitives.tokens.json
   semantic.tokens.json
   components.tokens.json
   themes/
     dark.tokens.json
     high-contrast.tokens.json
 generated/
   css/tokens.css
   ios/DesignTokens.swift
   android/DesignTokens.kt
   docs/token-index.json

Then make the pipeline explicit:

DTCG source → resolve aliases → validate policy → generate targets → test outputs

The resolver step deserves special attention. An alias is not merely a string replacement when tokens can be composite, themed, or platform-specific. Resolution must be deterministic, cycles must fail the build, and a missing reference must not silently fall back to a guessed value. The source specification gives implementers a shared representation; your resolver policy determines whether a broken reference becomes a visible failure or a production inconsistency.

Use contract tests at the boundary. A minimum suite should check:

• every referenced token resolves;
• every semantic role has an allowed type;
• every theme provides the roles required by each supported component;
• every component state maps to a valid semantic token;
• generated CSS, Swift, Kotlin, and documentation outputs contain the expected public names;
• contrast-sensitive foreground/background pairs meet the team’s accessibility threshold.

Google’s open DESIGN.md project demonstrates the value of this output-oriented approach. Its CLI can lint broken references, flag orphaned tokens, check contrast ratios, compare token-level changes, and export to Tailwind or the DTCG format (the DESIGN.md repository). The important pattern is not the specific file format. It is that a machine-readable design description is paired with linting and diff behavior, so “valid” means more than “the parser accepted the file.”

NVIDIA takes a similar portable-contract approach with its official Elements DESIGN.md: exact tokens sit beside guidance for component selection, accessibility, layout, and operational UI patterns, with links to maintained components and tools (NVIDIA Elements DESIGN.md). Tokens provide precision; prose and component rules provide intent. A token-only pipeline cannot replace that second layer.

Why token coverage is a product metric, not a bragging right

A declared token that no production component consumes is documentation inventory, not adoption. OverlayQA’s audit of 375 production websites found average token coverage of 40.4%; only 7.5% of sites reached 90% or higher, and the study reported 17,731 hardcoded values across the sample (OverlayQA’s original research). The study is one dataset, not a universal benchmark, but its shape illustrates the failure mode: most teams have tokens, yet most rendered values still bypass them.

That means the useful dashboard is not “number of tokens.” Track the path from declaration to rendered behavior:

Signal	What it tells you	Bad interpretation
Reference coverage	How much authored code uses approved roles	“Our tokens are complete”
Rendered coverage	How much production CSS resolves to approved values	“No hardcoded values exist”
Orphan rate	Which tokens have no consumer	“More tokens means more maturity”
Override rate	Where consumers bypass a component contract	“Teams are ignoring governance”
Migration age	How long deprecated roles remain in use	“The deprecation is done”

Measure coverage by semantic role and component state, not just by string matches. A stylesheet containing var(--color-blue-500) may technically use a token while bypassing the intended semantic layer. A token inventory should distinguish primitive consumption from approved role consumption.

This is also where AI-assisted development raises the stakes. Atlassian reported that giving agents structured design-system content produced 34% faster task completion on average, 4.9% more accurate code, 11% fewer errors, 16% lower token use, and 26% fewer tool calls in its internal evaluation (Atlassian’s structured-content case study). Those are Atlassian’s results, not a promise for every team. The broader lesson is portable: agents make better decisions when the system exposes explicit roles, examples, constraints, and failure conditions.

If your token names are technically valid but semantically ambiguous, an agent will choose a plausible value. So will a new engineer. A design system should make the safe path the easiest path for both.

Version the meaning, not only the file

Semantic token changes need a compatibility policy. A renamed token is an obvious breaking change; a changed value can be just as disruptive when it affects contrast, layout density, motion, or native-platform rendering.

Use a change classification that reflects consumer risk:

PATCH   metadata, descriptions, generated formatting
MINOR   new token, new theme, new optional component role
MAJOR   rename/remove, type change, alias meaning change, state contract change
REVIEW  value change that can alter contrast, layout, motion, or interaction

The REVIEW category is deliberately separate. Semantic versioning is useful, but a numerical version cannot tell you whether a new brand color fails a high-contrast theme. Require a visual and accessibility diff for changes to roles consumed by interactive states.

Publish deprecation metadata with a replacement and deadline. A consumer should see something like:

{
  "surface": {
    "brand": {
      "$value": "{color.blue.500}",
      "$description": "Primary action surface. Replace with surface.action by 2026-12-01.",
      "deprecated": true,
      "replacement": "surface.action"
    }
  }
}

Whether your chosen tooling supports those exact extension properties is less important than establishing a policy and making the generator preserve it. If the source can express a deprecation but the CSS or native output drops it, the migration system is incomplete. Add a machine-readable deprecation report and fail CI when the deadline passes.

This is the difference between a token library and a token ABI. A library tells you what is available today. An ABI tells you how change is managed across consumers that do not upgrade together.

The counterargument: a single source of truth can become a single bottleneck

Centralizing tokens can concentrate authority in a team that does not understand every product. A mobile app may need a platform-specific density scale. A marketing site may need a fluid type ramp. A regulated product may require a slower approval process than an internal tool. One giant semantic vocabulary can become as restrictive as the vendor-specific formats it replaced.

The answer is not to abandon a shared source. It is to define the boundary of what must be shared. Centralize core primitives, semantic accessibility roles, interaction states, and naming rules. Allow product-level extensions in a namespaced area, with an owner and a documented path to promotion. Keep experimental tokens out of the stable public contract until real usage proves their value.

The DTCG report’s neutrality makes this possible: it standardizes exchange without requiring one organization to own every design decision. Your architecture can have a shared core plus product namespaces, as long as resolution, collision rules, and compatibility behavior are explicit.

For a small product with one codebase and one brand, this may be more machinery than you need. A local CSS variable file and a few accessibility tests can be the right answer. The ABI model pays off when several tools, platforms, brands, or autonomous teams consume the same decisions and upgrade on different schedules.

A practical migration plan for this quarter

Do not begin by converting every hex value. Start with the interface boundary.

1. Inventory consumers. List every place tokens are read or generated: design tools, CSS, native platforms, docs, CMS themes, and agent context files.
2. Choose ten semantic roles. Prefer high-frequency roles such as page surface, default text, action surface, focus ring, and danger text. Map primitives behind them.
3. Write forbidden ambiguity down. State which roles can be used for text, borders, backgrounds, interaction, and status. Make invalid combinations lintable.
4. Convert one component family. Generate CSS and one native target, then compare rendered output and accessibility results against the existing implementation.
5. Add resolver and output tests. Broken aliases, missing theme roles, orphaned public tokens, and expired deprecations should fail CI.
6. Measure rendered adoption. Report semantic-role coverage and hardcoded-value drift by route or product, not only by repository.
7. Publish the contract. Put the token schema, naming rules, version policy, and migration examples beside the generated artifacts. If agents consume the system, provide the same material in structured form.

The DTCG format is worth adopting because interoperability is valuable. But the format is the beginning of the architecture, not its conclusion. Design tokens become durable when they behave like a carefully versioned ABI: precise enough for tools, meaningful enough for people, explicit enough for agents, and tested enough that a change cannot quietly mean five different things.

A valid JSON file can still describe a broken design system. A governed interface can survive a tool migration, a new brand, and a new consumer without asking every team to rediscover the design language from screenshots.