Design tokens as data, in the W3C community format

The Design Tokens Format Module describes one JSON file format that design tools, code tools and docs tools can all read. The parts an agent benefits from most:

• $value is the only thing a token must have.
• $type says what kind of value it is (color, dimension, fontFamily, duration and others). A group can set it once for every token inside. A token whose type cannot be found is invalid, and tools must not guess it from the value.
• $description is plain text saying what the token is for. Tools may show it as a tooltip or turn it into a code comment, and it is the line an agent reads when it chooses.
• Aliases in curly braces, such as {color.red.700}, point at another token, so one decision changes everywhere it is used.
• $deprecated marks a token on its way out, with an optional line saying what to use instead.
• Files end in .tokens or .tokens.json and are served as application/design-tokens+json.

The format comes from a W3C Community Group, not from the W3C itself; its status section says it is not a W3C Standard. It does call itself stable, and meant to be implemented.

An excerpt: the palette the alias points at lives elsewhere in the same file. A dimension’s value is an object with a number and a unit, px or rem.

{
  "space": {
    "$type": "dimension",
    "inset": {
      "card": {
        "$value": { "value": 1.5, "unit": "rem" },
        "$description": "Padding inside a card, on every side."
      }
    }
  },
  "color": {
    "$type": "color",
    "text": {
      "danger": {
        "$value": "{color.red.700}",
        "$description": "Text that reports an error. Never for decoration."
      }
    }
  }
}

An agent that sees #B42318 can only copy it. An agent that sees color.text.danger, described as text that reports an error, can pick it for a new error message and leave it off a decorative heading. That second layer, design tokens named for what they do and pointing at the palette, is the one that helps an agent most. A system with only a palette has done half the job.

• IBM Carbon ships a .tokens.json file per theme that points at the 2025.10 schema.
• Adobe Spectrum publishes its design tokens as a JSON package, @adobe/spectrum-tokens.
• GitHub Primer publishes JSON in @primer/primitives.
• Atlassian and Salesforce publish design tokens as JSON in formats of their own.
• shadcn/ui, Chakra UI and the GOV.UK Design System keep theirs as CSS variables, theme objects or Sass, so the comparison of the best AI design systems rates them Partly.

1. Collect every value your components use, from the code and from Figma variables.
2. Name the palette by value, then add the purposes on top as aliases.
3. Write a $description for every purpose; skip it and the agent is back to guessing.
4. Build CSS variables and platform files from the JSON, never the other way round, so the data stays the source.
5. Fail any value written outside a design token, so a hex code an agent slips in never ships. Acceptance checks covers how.

Steps 1 and 2 are counting and naming. Steps 3 and 5 take judgment about what each value is for and what counts as drift, and they are part of what Work with Simbolik (opens in a new tab) covers.