Design Tokens Format Module becomes the contract between your design system and AI

The problem this draft tackles is old and tedious: every design system team writes glue code. You export tokens from Figma in one format, need to convert them to Style Dictionary in another, and still maintain a fragile script in between to keep design and code in sync. Switch tools and redo everything. The Design Tokens Format Module, published as a Draft Community Group Report by the W3C's Design Tokens Community Group, proposes ending this rework by defining a single file format for exchanging tokens between tools.

The version under discussion is 2025.10, and the document itself warns in bold letters: it's a preview, don't implement it yet, don't cite it as authoritative. In other words, it's not a W3C standard and isn't on the standards track. But the design is already mature enough to be worth reading for anyone working with design systems, and the reason it matters now goes beyond interoperability between design tools.

What a token is in this format

The specification starts from a lean definition: a token is, at minimum, a name/value pair with meaning. The file is plain JSON, chosen because it has native support in nearly every language, is editable in any text editor, and is already familiar. A minimal color token looks like this:

{
  "token name": {
    "$type": "color",
    "$value": {
      "colorSpace": "srgb",
      "components": [1, 0, 0]
    }
  }
}

Two things are mandatory: name and value. The presence of $value is what unambiguously defines that object as a token, not a group. All reserved properties in the format start with a dollar sign ($type, $value, $description), so token names cannot start with $ nor contain {, }, or a period, precisely because of the reference syntax.

The $type is the heart of reliability. The spec is emphatic: tools must not try to guess a token's type by inspecting its value. Either the type is declared, or it's inherited from the closest parent group that has $type, or the token is invalid. This refusal of heuristics is a design decision, not a detail: it's what allows an automated consumer (a translator, an IDE, or an agent) to handle the data deterministically.

Aliases, composite tokens, and groups

A token's value can be a reference to another token, the well-known alias. It's the mechanism that separates the raw palette from semantic decisions: color-text-primary points to color-palette-black, and changing the palette propagates to all the semantic tokens that reference it. When the value is a reference, the type is the resolved type of the referenced token.

For styles that always travel together, there are composite tokens. A shadow, for example, carries color, offsets, blur, and spread in a single structured value:

{
  "shadow-token": {
    "$type": "shadow",
    "$value": {
      "color": { "$type": "color", "$value": { "colorSpace": "srgb", "components": [0,0,0], "alpha": 0.5 } },
      "offsetX": { "value": 0.5, "unit": "rem" },
      "offsetY": { "value": 0.5, "unit": "rem" },
      "blur": { "value": 1.5, "unit": "rem" },
      "spread": { "value": 0, "unit": "rem" }
    }
  }
}

Groups organize tokens into hierarchical collections, but the spec insists that groups are arbitrary and that tools must not infer type or purpose from them. An interesting new detail is the root token: using the reserved name $root, a group can have a base value coexisting with variants (light, dark) without the ambiguity of referencing the group as if it were a token.

Metadata that becomes part of the definition of done

Here's what, in my reading, turns the format from mere plumbing into a contract. $description is plain text explaining the token's purpose, and the spec lists where it can appear: an autocomplete tooltip in the IDE, a comment in the code generated by the translator, a caption next to the preview in the style guide. In other words, the intent behind each decision travels along with the value.

There's also $deprecated, which accepts true or a string with the reason ("Please use the border style for active buttons instead."), allowing tools to resolve the cited alias and link to the replacement token. And $extensions, an object where each vendor stores proprietary data using a key in reverse-domain notation (org.example.tool-a), with a golden rule: tools must preserve extension data they don't understand. If Tool B opens a file saved by Tool A, Tool B has to give back Tool A's extension intact when saving.

Why this decides whether AI respects your system

The practical angle for those already living with agents editing components: a design system is only trustworthy for automation when every value has a declared type, explicit semantics, and a single, machine-readable source of truth. That's exactly what this format delivers. An agent editing a button in Figma or generating CSS doesn't need to guess whether #dd0000 is a brand color or an error color, nor invent a spacing value outside the scale: it reads the token by name, respects the $type, follows the alias down to the palette, and still has the $description as an instruction of what that means.

Without a contract like this, the agent operates by heuristics, exactly what the spec forbids for tools. The AI that "guesses" a pretty color outside the palette is every design system's nightmare, and standardization is the barrier that swaps guessing for lookup. The determinism of $type is the same guarantee you want in the pipeline: if the value doesn't match any token, it's an error, not an improvisation.

It's worth noting the accessibility trade-off here, which isn't optional. The format models color with colorSpace and components instead of just a hex value, which opens room to programmatically check contrast before a value enters the system. A well-described, well-typed token is the basis for automating WCAG contrast checks in CI, turning accessibility into part of the token's own definition of done, rather than a late audit.

What's still open

The document is honest about its gaps. An editorial note records that the group is still studying whether to add a JSON Schema to validate the files, something currently missing and exactly what would provide automatic conformance validation. Another note raises a concern, brought up by a vendor, about JSON file size limits in large token systems. And there's the definition of file extensions (.tokens or .tokens.json) and the MIME type application/design-tokens+json, with the caveat that, while adoption hasn't matured, .tokens.json helps files open in the user's preferred JSON editor.

The source's own recommendation is clear: don't implement this version. For teams, the move now is to follow the design-tokens/community-group repository on GitHub, where discussion happens via issues, and to watch which tools (Style Dictionary, Terrazzo, Figma, Penpot) already signal support. What nobody should do is bet the entire pipeline on a draft marked as preview. The value, for now, is understanding the shape this contract is taking, because that shape is what will determine whether the next agent that touches your component respects the system or corrupts it.