What is the DTCG design tokens format?
The DTCG design tokens format is a vendor-neutral JSON specification for storing design tokens, written by the W3C's Design Tokens Community Group. It defines how a token, a group, a type and a reference are written, so a file exported from one tool can be read by another without a custom converter.
The group published version 2025.10 on 28 October 2025 as a Final Community Group Report and states that the specification is considered stable. It's worth being precise about that label: a Community Group report is not a W3C Recommendation or official W3C standard, but it is the shared format the major token tools have been converging on.
This article covers the format itself. For what tokens are and how to layer them, read design tokens explained, and for how tokens fit a startup's wider system, see our guide to design systems for startups. Spec details below come from the published 2025.10 documents; check the group's site for later drafts.
- First version the DTCG describes as stable
- 2025.10
- Modules in 2025.10: Format, Color and Resolver
- 3
- Color spaces defined in the DTCG Color module
- 14
What does a DTCG token file look like?
A DTCG token file is a JSON object of nested groups, where any object with a $value property is a token and any object without one is a group. The token's name is its key, and its path is the chain of group names above it, such as color, then action, then default.
Properties that start with a dollar sign are reserved by the spec. Everything else is a group or token name. The spec recommends the .tokens or .tokens.json file extension and the media type application/design-tokens+json.
Property | Where | What it does |
|---|---|---|
$value | Token | Required. The token's value, or a reference to another token |
$type | Token or group | The value's type; tokens inherit it from the nearest parent group |
$description | Token or group | Plain-text explanation for people and documentation |
$deprecated | Token or group | true, false, or a string explaining what to use instead |
$extensions | Token or group | Vendor-specific data that tools must preserve |
$extends | Group | Inherits another group's tokens and overrides some of them |
$root | Group | Reserved name for a group's base token, such as color.accent itself |
Names have three rules: they can't start with a dollar sign, and they can't contain curly braces or periods, because those characters are used for references. Names are case-sensitive.
Which token types does the W3C design tokens spec define?
The W3C design tokens spec defines seven single-value types and six composite types. Composite types combine several values, so one typography token holds family, size, weight and line height together.
Kind | Types |
|---|---|
Single value | color, dimension, fontFamily, fontWeight, duration, cubicBezier, number |
Composite | strokeStyle, border, transition, shadow, gradient, typography |
Two details catch teams migrating older files. First, a dimension value is an object with a numeric value and a unit, and the only units allowed are px and rem; durations allow only ms and s. Second, a color value is an object too, defined by the separate Color module: a required colorSpace such as srgb, display-p3 or oklch, a components array, an optional alpha from 0 to 1 and an optional hex fallback.
That color model matters if you work in wide-gamut or OKLCH colors, as Tailwind v4's default palette does. A string like #2563eb is no longer the canonical value; it becomes an optional fallback. Our guide to brand colors and typography as tokens covers how to decide which brand values become tokens in the first place.
Example: one color token and one alias, described field by field
For example, suppose a file has a group named color with $type set to color. Inside it, a group named blue holds a token named 600 whose $value is an object: colorSpace srgb, components 0.15, 0.39 and 0.92, and hex #2563eb as a fallback. Because the parent group sets $type, the token doesn't repeat it.
A second group, action, holds a token named default whose $value is the string {color.blue.600} in curly braces. That's an alias: tools resolve it to the referenced token's value, and if blue 600 changes, action default follows. A $description on the alias might say: use for primary buttons and links only.
How do aliases and references work in the design tokens JSON format?
Aliases in the design tokens JSON format point one token at another, so semantic tokens can reference primitives instead of repeating raw values. The spec defines two syntaxes for this.
- Curly braces, such as {color.blue.600}, reference a whole token and always resolve to its $value. This is the familiar syntax most tools already use.
- JSON Pointer, through a $ref property, can target any location in the file, including part of a value, such as one component of a color. The spec says tools must support it.
- Circular references must be reported as errors, so a token can't point at itself through a chain of aliases.
Keep aliases intact through every export. A pipeline bug we see often is an export that resolves aliases into raw values, so the semantic layer silently disappears. Our walkthrough of syncing Figma variables to code shows where that happens and how to keep references.
How does the Resolver module handle themes and modes?
The Resolver module describes how one set of tokens takes different values in different contexts, such as light and dark themes, without duplicating every token per theme. It's the DTCG's answer to what Figma calls modes.
It works with three ideas. Sets are collections of DTCG token files merged in order. Modifiers are named dimensions, such as theme, each with contexts such as light, dark and high contrast that load different source files. A resolution order decides which sets and modifiers apply first, with later ones overriding earlier ones. A tool is given an input such as theme set to dark and produces the resolved tokens for that combination. The spec recommends naming resolver documents with the .resolver.json extension and keeping modifiers independent of each other where possible.
If you already model themes as Figma modes, this maps cleanly: each mode becomes a context. The setup on the Figma side is in our guide to Figma variables.
Which tools support the DTCG format?
Support for the DTCG format is broad but uneven, because many tools adopted earlier drafts before 2025.10 settled details like object-based colors. Treat DTCG support as a starting point and test your own file.
Tool | DTCG support we can confirm | What to check |
|---|---|---|
Figma variables | Its help center describes importing modes from DTCG JSON and exporting modes to JSON | Supported types are limited, such as px-only dimensions |
Tokens Studio | A plugin setting switches between W3C DTCG and its legacy format | Composite types and theme files on export |
Style Dictionary | Reads DTCG-style $value and $type tokens since version 4 | Handling of 2025.10 color and dimension objects in your version |
Figma's documentation notes, for example, that dimension imports must use px and that string tokens are accepted even though DTCG doesn't define a string type. Small mismatches like these are why a round-trip test belongs in your setup. If you're choosing between editors, our comparison of Tokens Studio and Figma Variables goes deeper.
What should your team change now?
Most teams should move their token files to the DTCG format now, because it's stable and it removes lock-in to any one plugin. The change is mostly mechanical, but it touches every token, so do it in a branch and test before switching.
Rename value and type keys
Replace value and type with $value and $type, and move notes into $description. Older plugin formats often used the unprefixed keys.
Convert colors and dimensions to objects
Rewrite colors as colorSpace plus components, keeping hex as a fallback, and dimensions as a value with a px or rem unit.
Fix names
Remove periods and curly braces from token names and make sure none start with a dollar sign.
Keep aliases as references
Check that semantic tokens still point at primitives with curly-brace references rather than resolved values.
Move tool data into $extensions
Put plugin-specific metadata under a namespaced $extensions key so other tools ignore it safely.
Round-trip test
Export from your design tool, run your build, and compare the generated CSS with production before switching over.
Document the conventions you choose, such as naming and which tokens are allowed in components, in your design system documentation. If you want the conversion and pipeline done for you, our design system service covers tokens through to code, and our design retainer keeps them current.
