All posts
Product design

W3C Design Tokens Format (DTCG): What the Stable Spec Means for You

What the DTCG design tokens format is, how a token file is structured in the stable 2025.10 spec, which tools read it, and what your team should change.

By Mehdi Hassan8 min read

The short answer

The DTCG design tokens format is a JSON format for design tokens published by the W3C Design Tokens Community Group. Each token is an object with a $value and an optional $type, grouped by nesting. Version 2025.10, published on 28 October 2025, is described as stable and adds a Color module and a Resolver module for themes.

Key takeaways

  • DTCG is a shared JSON format for tokens, so Figma, plugins and build tools can exchange the same file.
  • Version 2025.10 is a Final Community Group Report that the group calls stable, not a W3C Recommendation.
  • Tokens use $value and $type; groups pass their $type down to the tokens inside them.
  • Colors and dimensions are objects in 2025.10, not strings, which breaks many older token files.
  • The Resolver module describes light, dark and other themes as modifiers instead of duplicate files.

Part of Design Systems for Startups: What You Need, When and How to Build One

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.

  1. 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.

  2. 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.

  3. Fix names

    Remove periods and curly braces from token names and make sure none start with a dollar sign.

  4. Keep aliases as references

    Check that semantic tokens still point at primitives with curly-brace references rather than resolved values.

  5. Move tool data into $extensions

    Put plugin-specific metadata under a namespaced $extensions key so other tools ignore it safely.

  6. 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.

Frequently asked questions

Is the DTCG format an official W3C standard?
Not in the formal sense. Version 2025.10 was published by the W3C Design Tokens Community Group as a Final Community Group Report, and the group describes it as stable. Community Group reports are not W3C Recommendations, which go through a different process. In practice it's the shared format token tools are aligning on, which is what matters for interoperability.
What file extension should design token files use?
The DTCG format specification recommends .tokens or .tokens.json for token files, and the media type application/design-tokens+json when serving them, with tools also expected to accept application/json. Resolver documents, which describe themes and other contexts, should use the .resolver.json extension according to the Resolver module.
Can a DTCG token value be a plain hex string?
Not in version 2025.10. The Color module defines a color value as an object with a colorSpace and a components array, with optional alpha and hex fields. A hex string can still appear as the hex fallback inside that object. Older drafts and many existing token files use plain strings, so expect to convert them when you adopt the stable version.
Does the DTCG format replace Style Dictionary?
No. The DTCG format describes how tokens are stored, and Style Dictionary is a build tool that transforms stored tokens into platform outputs such as CSS variables, iOS and Android files. They work together: you keep tokens in DTCG JSON and use a build tool to generate code from them. Check your build tool's docs for its level of 2025.10 support.
Should a small startup bother with the DTCG format?
If your tokens only live in one CSS file maintained by hand, you don't need a JSON token file yet. Once you export tokens from Figma, use a plugin or generate code for more than one platform, write that JSON in the DTCG format from the start. It costs nothing extra at that point and avoids a conversion later.

· CEO & Design Director

Copywriter, designer and developer, and founder of Designify Studio. Over five years, 60+ projects across 14+ industries, for startups that have raised $300M+.

Want this done for you? Monthly retainer, $6,000.

Your ongoing design and development team, for products that keep shipping. $6,000, per month, flat fee. Book a free 30-minute call to see if it fits.

Schedule Call