A tokens.json file that only your team understands is a private dialect. A tokens.json file that conforms to the W3C Design Tokens Community Group format is a public language - one that Style Dictionary, Tokens Studio, the Figma Variables import path, every DTCG validator, and the AI agents now reading your system all speak natively. The difference between the two is not cosmetic. It is the difference between a file that the broader tooling ecosystem and an MCP-enabled agent can consume without breaking, and a file that quietly produces wrong values the first time something other than your own scripts tries to read it. This lesson takes the file you built last time and makes it governable: you read the DTCG Format Module spec for the parts that matter, validate the file against it, fix three real non-compliant tokens by hand, and design the governance - naming rules, deprecation flags, CI validation - that keeps it conformant as it changes. The artifact is a DTCG-validated tokens.json plus a one-page governance doc that survives the file outliving you.

Why a Shared Spec Matters Now, Specifically

For most of design-systems history, every team's token format was bespoke. One team used "value", another used "$value", a third nested colors one way and spacing another, and it did not much matter because each team wrote its own build script to read its own file. The format was private and the consumer was singular, so private was fine. That world is over. In 2026 your token file is read by tools you did not write and agents you did not configure, and they can only read it if it speaks a format they already know. The W3C Design Tokens Community Group format is that shared format - the convergence point the ecosystem standardized on so that a file from one team is legible to tooling from another.

Concretely, conformance buys you things that a bespoke format cannot. A DTCG-conformant file imports into Figma Variables through the standard path instead of a custom translator. It feeds Style Dictionary to generate platform outputs without a bespoke parser. It validates against off-the-shelf validators that catch errors before they ship. And it is consumable by an MCP-enabled agent or a Storybook MCP server that expects DTCG shape, so the agent resolves your aliases to real values instead of guessing. The moment your brand is read by more than your own scripts - which in 2026 it always is - the spec stops being pedantry and becomes the thing that makes the file actually work outside your laptop.

The Four Parts of the Spec That Actually Matter

The DTCG Format Module is a careful document, but for a practicing designer four parts carry almost all the weight. Read these closely; skim the rest. Get these four right and your file is conformant in every way that affects whether tools and agents can consume it.

The $type Field

Every token must declare what kind of value it holds, via the $type field. The spec defines a set of types - color, dimension, fontFamily, fontWeight, duration, number, and composite types like typography, shadow, and border. The type is what tells a consumer how to interpret the value: a color value is parsed as a color, a dimension value carries a unit. A crucial convenience the spec allows is that $type can be set on a group and inherited by every token inside it, so you declare $type: "color" once on the color group rather than on every color token. The failure mode is a token with no resolvable type, which leaves the consumer guessing how to parse the value - and guessing is exactly what conformance exists to eliminate.

The $value Structure

The $value key holds the token's value, and its structure depends on the type. A color token's value is a string (a hex, or in newer revisions a structured color object); a dimension value carries a number and a unit; a composite type like typography holds an object with sub-properties (fontFamily, fontSize, fontWeight, lineHeight). The rule that trips teams up is that the value structure must match the declared type. A token typed dimension whose value is a bare number with no unit, or a token typed typography whose value is a single string, is non-conformant: the structure and the type disagree, and a strict consumer rejects it.

Alias Resolution

References between tokens use the curly-brace alias - a token's $value set to "{color.blue.500}" means "use whatever that token holds." The spec defines how these resolve: the reference points at a token's path, the consumer follows it, and chains are allowed (a component token aliasing a semantic aliasing a primitive). Two rules matter. First, an alias must point at a token that exists; a reference to a non-existent path is a broken alias and a hard failure. Second, aliases must not form a cycle - A referencing B referencing A is unresolvable and the spec forbids it. Alias correctness is the single most common real-world conformance problem, because aliases break silently when a token is renamed or removed and nothing re-checks the references.

Group Nesting and Reserved Keys

Tokens are organized into groups by object nesting, and the spec reserves the $ prefix for its own keys ($value, $type, $description, and group-level $type). This means a group can contain both tokens and nested sub-groups, and the parser distinguishes a token (an object with $value) from a group (an object without one). The governance-relevant consequence is that your own metadata cannot collide with reserved keys: if you want to attach custom data, the spec provides the $extensions field, namespaced to your organization, precisely so your custom properties do not get mistaken for spec keys. Putting raw custom keys at the token level without using $extensions is the kind of thing that validates today and breaks the day a stricter consumer reads it.

Running the Validator: The CLI Step

Reading the spec tells you what conformance is; a validator tells you whether you have it. The practical move is to run a DTCG validator over your file - there are CLI validators in the ecosystem that parse the file, check every token for a resolvable $type, verify each $value matches its type, resolve every alias and report broken or circular references, and flag reserved-key misuse. You run it once to find out where you stand, and then you wire it into CI so it runs on every change forever.

The output of a first validation run on a real file is humbling and useful. It is a list of specific, located failures: this token has no type, that one's value is a unitless dimension, this alias points at a path you renamed last month, that group uses a reserved key for custom data. None of these are visible by reading the file with your eyes, which is exactly why the validator exists - conformance is a machine property and machines should check it. The validator turns "I think this file is fine" into "these eleven tokens are not, here are their paths," which is the only basis on which you can actually fix it.

A Worked Example: Fixing Three Non-Compliant Tokens

Abstractions do not teach this; specific fixes do. Here are three real non-compliances a validator commonly surfaces, and exactly how each gets fixed.

Non-compliance one: a dimension token with no unit. The validator flags space.4 whose $value is the bare number 16 with $type: "dimension". The DTCG dimension type expects a value carrying a number and a unit, not a bare integer. The fix is to express the value in the conformant structure - { "value": 16, "unit": "px" } as the spec's revision defines it (or the equivalent string form your target revision specifies) - so a consumer knows the 16 is sixteen pixels, not sixteen of some unstated unit. The behavior on screen does not change; the file's legibility to strict consumers does.

Non-compliance two: a broken alias. The validator reports that color.action.primary aliases "{color.brand.blue}", but no token at that path exists - the primitive was renamed to color.blue.500 in a refactor and the semantic's reference was never updated. This is the classic silent break: the file still parses as JSON, but the alias resolves to nothing, and a consumer either errors or falls back to a default. The fix is to re-point the alias to the real path, "{color.blue.500}". The deeper fix - which is why this lesson is about governance, not just one file - is the CI check that would have caught this the moment the rename happened instead of months later in production.

Non-compliance three: a custom key colliding with the reserved namespace. The validator flags that color.action.primary carries a top-level "deprecated": true key that is not a spec key and sits where the parser expects only reserved $ keys and the value. The fix is to move custom metadata into $extensions under your organization's namespace - for example "$extensions": { "com.acme.lifecycle": { "deprecated": true } } - so your deprecation flag is preserved but lives where the spec says custom data goes, and no consumer mistakes it for a malformed token. This one matters directly for the deprecation lifecycle you will design two lessons from now, which depends on exactly this $extensions mechanism.

Conformance is not pedantry once your brand is read by more than your own scripts. A bespoke file works until the first tool or agent you did not write tries to read it; a DTCG-conformant file works for the whole ecosystem, including the agents that now do real production. The spec is the difference between a private dialect and a public language.

Designing the Governance: Naming, Deprecation, CI

A conformant file today is not a governed file. Governance is the set of rules and gates that keep it conformant and legible as it changes over years, through many hands, under deadline. Three pieces carry the load.

Naming Rules

A naming convention is governance because it is what lets a human and an agent both predict where a token lives and what it does. The rule is to name by role and structure, not appearance: a consistent category.role.variant shape (color.action.primary, color.text.secondary, space.inset.md) so that the name is a stable address. Consistency matters more than the specific scheme; what breaks systems is a file where half the colors are color.text.primary and half are textColorMain, because neither a contributor nor an agent can guess which convention a given token follows. Write the convention down, enforce it in review, and ideally lint it, so new tokens join the system in its language rather than inventing their own.

Deprecation Flags

Tokens do not get deleted; they get deprecated, because something somewhere still consumes them and a hard delete breaks that consumer silently. The governance pattern is a deprecation flag in $extensions that marks a token as on its way out, ideally with a pointer to its replacement and a target removal date. This is what lets a consumer - human or agent - be warned ("this token is deprecated, use X instead") before the token disappears, rather than discovering it vanished when their build breaks. The full lifecycle is a later lesson; the governance point here is that the deprecation mechanism must be designed into the file's metadata convention from the start, using the $extensions namespace so it is both preserved and spec-legal.

CI Validation

The gate that makes governance real rather than aspirational is CI validation: the DTCG validator runs automatically on every pull request to the token file, and a non-conformant change cannot merge. This is the difference between governance as a document people are supposed to follow and governance as a property the system enforces. The broken alias from our worked example never reaches production because the rename that broke it fails CI; the unitless dimension never ships because the validator rejects it at the gate. CI validation converts every governance rule that can be machine-checked - type presence, value structure, alias resolution, reserved-key hygiene, and naming-convention linting - from a hope into a guarantee. The rules a machine cannot check (is this the right semantic role? is this deprecation justified?) remain human review, which is exactly where human judgment should sit.

Why Governance Is Exactly What AI Agents Need

It is worth being explicit about the connection to AI, because it is the reason this lesson sits where it does in 2026 rather than being a back-office concern. An AI agent reading your design system - through the Storybook MCP server, through a Figma integration, through a direct read of the file - is the most demanding consumer your tokens have ever had. A human contributor can muddle through a slightly malformed file by guessing what you meant. An agent cannot; it does exactly what the file says, and if the file says something malformed or ambiguous, the agent produces something malformed or wrong, fast, and at scale.

So the governance you design here is not bureaucracy layered on top of the design system. It is the precondition for the design system being usable by agents at all. A conformant file with resolvable types, valid aliases, consistent names, and clean extension metadata is a file an agent can read and build on correctly. A non-conformant file is one the agent reads wrong, and because agents do not flinch, no one notices until the wrong output has propagated. Governance is how you make your brand safe to hand to a machine that will take everything in the file literally. The one-page governance doc you write - the naming convention, the deprecation mechanism, the CI gate, and who owns the file - is the contract that keeps that handoff safe as the file lives on past any single contributor, including you.

Key Takeaways

• A bespoke token format works only while your own scripts are the sole consumer. In 2026 your file is read by Style Dictionary, Figma Variables, validators, and AI agents you did not write, and they can only read it if it conforms to the shared W3C DTCG format. Conformance is the difference between a private dialect and a public language.
• Four parts of the DTCG Format Module carry the weight: the $type field (declared per token or inherited from the group), the $value structure (which must match the declared type), alias resolution (references must point at existing tokens and form no cycles), and group nesting with reserved $ keys (custom metadata goes in $extensions, namespaced).
• A DTCG validator turns "I think this file is fine" into a located list of specific failures - no type, unitless dimension, broken alias, reserved-key misuse - none of which are visible to the eye. Run it once to find your standing, then wire it into CI to run on every change forever.
• The three most common real fixes: give a unitless dimension its number-and-unit structure; re-point a broken alias to the renamed token's real path; and move a custom key like a deprecation flag into $extensions under your org's namespace so it is preserved and spec-legal.
• Governance is three pieces that keep the file conformant over years: naming rules (consistent category.role.variant so names are stable addresses), deprecation flags in $extensions (tokens get deprecated, never silently deleted), and CI validation (the gate that makes a non-conformant change unmergeable).
• Governance is exactly what AI agents need, not bureaucracy. An agent is your most demanding consumer - it takes the file literally and does not flinch at malformation - so a conformant, governed file is the precondition for the design system being safely usable by agents at all.