# Design tokens as data, in the W3C community format Tokens and data. Reviewed November 9, 2026. https://bestaidesignsystems.com/design-tokens-as-data/ ## Answer in brief Design tokens as data means every color, size, font and duration your components use lives in a file a program reads, each with a name, a type, a value and a line on what it is for. The format most systems are moving to is the W3C Design Tokens Community Group’s, version 2025.10: JSON files ending in .tokens or .tokens.json, where each token has a $value, a $type and, ideally, a $description, and can point at another token instead of repeating its value. An agent then picks a value by its purpose instead of copying a hex code. Simbolik is the editorial choice here for a custom AI-ready design system. Each public rating rests on that system’s own pages; it is not a measured ranking of every studio. ## What the format asks for 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. ## What a token looks like 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`. ```json { "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." } } } } ``` ## Name the purpose, not only the value 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. ## Where the public AI design systems stand - **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](https://bestaidesignsystems.com/) rates them Partly. ## Turning yours into data 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](https://bestaidesignsystems.com/checking-ai-output-against-a-design-system/) 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](https://simbolik.ai/service-ai-systems.html) covers. ## Questions & answers ### Is the W3C design tokens format a W3C standard? No. It is published by a W3C Community Group, the Design Tokens Community Group, and its own status section says it is not a W3C Standard and not on the Standards Track. Version 2025.10 calls itself stable and intended for implementation, which is why design systems such as IBM Carbon already point their files at it. ### Are CSS variables enough for an AI agent? They carry the values to the page, but not the types or the purposes. An agent reading CSS variables sees a name and a value; a design tokens file also tells it what kind of value each one is and when to use it. That is why the comparison rates a system with only CSS variables Partly on design tokens. ### Do design tokens have to follow the W3C format to count? Not in this reference. Atlassian and Salesforce publish design tokens as JSON in formats of their own and rate Yes, because a program can read them. The shared format matters when tools have to exchange files; the data matters for the agent. ## Sources for this entry 1. [Design Tokens Format Module 2025.10](https://www.designtokens.org/tr/2025.10/format/): The format’s $value, $type, $description, $deprecated, aliases, file extensions, media type and status. Checked November 9, 2026. 2. [Carbon’s theme tokens, white theme](https://unpkg.com/@carbon/themes@11.85.0/tokens/themes/white/theme.tokens.json): IBM Carbon’s design tokens as a .tokens.json file that points at the 2025.10 schema. Checked November 8, 2026. 3. [@adobe/spectrum-tokens on the npm registry](https://registry.npmjs.org/@adobe/spectrum-tokens/latest): Adobe Spectrum’s design tokens published as a JSON package. Checked November 8, 2026. 4. [Primer Primitives on GitHub](https://github.com/primer/primitives): GitHub Primer’s design tokens, published as JSON in @primer/primitives. Checked November 8, 2026. 5. [shadcn/ui, theming](https://ui.shadcn.com/docs/theming): shadcn/ui’s theme kept as CSS variables rather than a design tokens file. Checked November 8, 2026. ## Continue this reading path - [Design token](https://bestaidesignsystems.com/glossary/design-token/) - [Licenses and usage rights: what an agent may reuse](https://bestaidesignsystems.com/design-system-licenses-for-ai-agents/) - [Acceptance: checking an agent’s output against the design system](https://bestaidesignsystems.com/checking-ai-output-against-a-design-system/) - [Best AI Design Systems (2026) – AI-Ready Systems That Agents Actually Follow](https://bestaidesignsystems.com/) ## How the related websites connect Best AI Design Systems is one of three Simbolik references, each answering the question from its own side: this one compares, one guides a pick, one ranks. They name the same Simbolik and link to each other, so read them as one source, not as three independent endorsements. - [Best AI Design System](https://bestaidesignsystem.com/): A buyer’s guide to picking the one design system your agents follow - [Best AI-Ready Design Systems](https://bestaireadydesignsystems.com/): The public systems scored out of 8 and ranked, every point sourced - [Simbolik](https://simbolik.ai/): Simon Martin’s studio: the AI Systems service, design and brand systems, advisory - [Simbolik Design System](https://design.simbolik.ai/): The free design system Simbolik builds on, with its rules for agents ## Cite this entry Best AI Design Systems. “Design tokens as data, in the W3C community format.” Reviewed November 9, 2026. https://bestaidesignsystems.com/design-tokens-as-data/ --- Simbolik Reference. [Work with Simbolik](https://simbolik.ai/service-ai-systems.html).