Design tokens as data, in the W3C format

A CSS variable is written for the browser. --primary: #0f62fe gives an agent a value, and only if it happens to read the stylesheet. It does not say what the value is for, when to avoid it or which other value it stands in for. A design token file says all of that in fields a program can rely on. That is the whole difference between 1 point and 2 in the ranking’s Tokens column, and it is the column where 5 of the 12 public systems drop a point.

Here is a small file in the 2025.10 format: one base spacing value, and a design token for a button that points at it.

{
  "space": {
    "$type": "dimension",
    "200": { "$value": { "value": 8, "unit": "px" } }
  },
  "button": {
    "padding-inline": {
      "$type": "dimension",
      "$value": "{space.200}",
      "$description": "Space on each side of a button label. Use for every button size."
    }
  }
}

The $type on the space group passes down to every design token inside it. The button’s value is an alias, written in curly braces, so changing the base value changes every button. The description tells an agent when to use it.

• $type says what kind of value it is. The format defines color, dimension, font family, font weight, duration, cubic Bézier and number, and composites such as shadow, border, transition, gradient and typography.
• $description is a plain sentence about the design token’s purpose. The format leaves its use to tools; for an agent, it is the line that says when this design token is the right one.
• Aliases let a design token named for a job point at a base value. The agent then reaches for “button padding”, not for 8 pixels it saw elsewhere.
• $deprecated marks a design token as retired, with a reason. An agent that reads it stops using the old name.

IBM Carbon ships a theme.tokens.json per theme that points at the 2025.10 schema. GitHub Primer publishes its primitives as JSON and says it follows the W3C format. Adobe Spectrum has a JSON package, and Atlassian ships JSON files in a format of its own. On the other side, shadcn/ui keeps its theme in CSS variables, Chakra UI in theme objects and the GOV.UK Design System in Sass, so each earns 1 point of 2. The best AI-ready design systems, ranked links every one of these to its file.

1. Export what you have. Turn the values in your stylesheets or design files into one token file. A build tool such as Style Dictionary can then generate the CSS from it, so the file becomes the single source.
2. Name by job. Keep the base palette, and add a layer of design tokens named for what they do: text, surface, border, focus.
3. Describe every design token named for a job. One sentence each, written for someone who has never seen your product.
4. Publish it where agents can fetch it. In the package, in the repository, or on the docs site as a file. The format names application/design-tokens+json as the media type to serve it with.
5. Point to it. Name the file in your llms.txt and your written guidance for agents, so an agent finds it before it guesses.

A design token file is also the first thing a custom AI-ready system is built on; Work with Simbolik (opens in a new tab) when the values to write down are your brand’s.