Design Tokens JSON: The DTCG Format Explained

It's a vendor-neutral JSON format for design tokens, so a design tool, a token manager and a code generator can all read the same file. It's written by the Design Tokens Community Group (DTCG), a W3C Community Group.

The group announced the first stable version, 2025.10, on 28 October 2025. The release has three modules: Format (the file structure and token types), Color (how colours are written) and Resolver. The Format module says "This specification is considered stable."

One thing to be precise about: it's published as a Final Community Group Report, not a W3C Recommendation (the kind of document a web standard such as CSS becomes). Tools adopt it because it's useful and shared, not because the W3C has standardised it.

• Files: the spec recommends the .tokens and .tokens.json extensions.
• Media type: application/design-tokens+json, though files may also be served as application/json.
• A living draft is also kept on designtokens.org, alongside the stable 2025.10 release.

A token is a JSON object with a $value. In the spec's words: "An object with a $value property is a token." The other properties starting with $ are optional:

• $type: the kind of value (color, dimension, duration and so on). It's case-sensitive.
• $description: "A plain text description explaining the token's purpose".
• $deprecated: marks a token as deprecated, optionally with the reason.
• $extensions: an object where tools may store their own data.

{
  "spacing-md": {
    "$type": "dimension",
    "$value": { "value": 16, "unit": "px" },
    "$description": "Default gap between related items."
  }
}

Names are case-sensitive, must not begin with $, and must not contain {, } or a full stop (the characters references use). Note that in 2025.10 a dimension is an object with a numeric value and a unit, not a string like "16px".

Any object without a $value is a group: it organises tokens and can nest. A $type set on a group applies to every token inside it, and a token can point to another token with a reference in curly braces.

The spec says a token's type "is inherited from the closest parent group with a $type property", and that tools "MUST NOT attempt to guess the type of a token by inspecting the contents of its value." So either set $type on the token or on a group above it.

References (aliases) use the token's path with full stops between names: "{color.teal.600}". They can only point at complete tokens, objects with a $value, not at a group or a part of a value. The spec also supports JSON Pointer with $ref, where "$ref": "#/colors/blue/$value" is equivalent to "{colors.blue}".

Aliases are how you build semantic tokens on top of a raw palette: color.accent points at color.teal.600, so a rebrand changes one value and every accent follows.

The Format module defines seven basic types and six composite types. Composite values are objects (or arrays) built from basic values, and each part can be a reference to another token.

The Color module lists the colour spaces you can use, from srgb and hsl to oklch, display-p3 and rec2020. The hex field is only a fallback and must be written in 6-digit form, so transparency always lives in alpha.

Here's a small but complete file: a raw palette, semantic colours that alias it, spacing, a radius, font tokens, motion, a shadow and a typography token that references the font tokens.

{
  "color": {
    "$type": "color",
    "teal": {
      "600": { "$value": { "colorSpace": "srgb", "components": [0.051, 0.447, 0.408], "hex": "#0d7268" } }
    },
    "neutral": {
      "0": { "$value": { "colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff" } },
      "900": { "$value": { "colorSpace": "srgb", "components": [0.082, 0.082, 0.075], "hex": "#151513" } }
    },
    "background": { "$value": "{color.neutral.0}" },
    "text": { "$value": "{color.neutral.900}" },
    "accent": { "$value": "{color.teal.600}", "$description": "The one action you want taken on a screen. Use it once per view." }
  },
  "space": {
    "$type": "dimension",
    "sm": { "$value": { "value": 8, "unit": "px" } },
    "md": { "$value": { "value": 16, "unit": "px" } },
    "lg": { "$value": { "value": 2, "unit": "rem" } }
  },
  "radius": {
    "card": { "$type": "dimension", "$value": { "value": 12, "unit": "px" } }
  },
  "font": {
    "body": { "$type": "fontFamily", "$value": ["Inter", "system-ui", "sans-serif"] },
    "semibold": { "$type": "fontWeight", "$value": 600 }
  },
  "motion": {
    "fast": { "$type": "duration", "$value": { "value": 150, "unit": "ms" } },
    "ease-out": { "$type": "cubicBezier", "$value": [0.2, 0, 0, 1] }
  },
  "shadow": {
    "card": {
      "$type": "shadow",
      "$value": {
        "color": { "colorSpace": "srgb", "components": [0, 0, 0], "alpha": 0.08 },
        "offsetX": { "value": 0, "unit": "px" },
        "offsetY": { "value": 1, "unit": "px" },
        "blur": { "value": 3, "unit": "px" },
        "spread": { "value": 0, "unit": "px" }
      }
    }
  },
  "typography": {
    "heading": {
      "$type": "typography",
      "$value": {
        "fontFamily": "{font.body}",
        "fontSize": { "value": 32, "unit": "px" },
        "fontWeight": "{font.semibold}",
        "letterSpacing": { "value": -0.5, "unit": "px" },
        "lineHeight": 1.2
      }
    }
  }
}

Two details are easy to miss. The color and space groups set $type once, so their tokens inherit it. And the typography token's fontFamily and fontWeight are references, so changing font.body updates every text style built on it.

Use a token transformer. Style Dictionary is an open-source one: its site describes it as a way to "Export your Design Tokens to any platform", including CSS, JavaScript, iOS and Android.

Check the version before you rely on it. Style Dictionary's docs say "As of version 4, Style Dictionary has first-class support for the DTCG format", but also that "the latest format 2025.10 does not have full support yet" and that this is "a work in progress in v5."

1. 1Keep tokens in one or more .tokens.json files in your repository.
2. 2Configure the transformer with the platforms you need (CSS variables, a JS module, Android resources).
3. 3Generate the outputs in your build and never edit them by hand.
4. 4Point components, and your AI coding agent, at the generated variables rather than literal values.

No. Livery's tokens.json uses its own shape, built for an AI coding agent to read, and doesn't use $value or $type. It is plain JSON you can convert to DTCG with a short script.

Each Livery kit's tokens.json records where it was measured from, then colour roles for each theme the site has (background, surface, surface-alt, text, text-muted, border, accent, on-accent) as hex values, plus the swatches that carry real weight with their share of the page. Typography lists the font families and a scale of steps with size in px, weight, line height and letter spacing in em. Spacing has a base and a scale in px; radii come with how often each is used, and shadows note whether they are tinted; motion has durations in ms, easing curves and measured animation patterns.

Mapping it to DTCG is mechanical: each hex colour becomes a color token in the srgb space with the hex as fallback, each px number becomes a dimension object, each ms number becomes a duration, and each type-scale step becomes a typography token. The reasons and rules live in the kit's rules.md, which a token file has no place for and an agent needs most.