The Design Tokens JSON Format (tokens.json), Explained

Published August 17, 2026 · 10 min read · by the CSS DNA team

Quick answer: The design tokens format is a vendor-neutral JSON standard from the W3C Design Tokens Community Group. Every token is an object with a required $value and an optional $type. It reached its first stable version, 2025.10, on October 28, 2025. Files use the .tokens or .tokens.json extension.

What the design tokens format is

A design token is one indivisible design decision — a color, a spacing step, a font size — stored as data rather than as code. The problem the format solves is that every tool used to invent its own JSON shape, so a token file from Figma could not be read by Style Dictionary without a translation layer.

The Design Tokens Community Group (DTCG) exists to end that. It is a W3C Community Group whose output is a single interchange format that design tools export and build tools consume.

The anatomy of a token

A token is any JSON object that has a $value. That single rule is what separates a token from a group.

{
  "brand": {
    "$type": "color",
    "primary": {
      "$value": {
        "colorSpace": "srgb",
        "components": [0.486, 0.361, 1],
        "hex": "#7c5cff"
      },
      "$description": "Primary action color"
    }
  }
}

Two naming rules bite people immediately. Token and group names cannot begin with $, and they cannot contain {, } or a period. The dollar sign is reserved for spec properties; the braces and dot are reserved for the alias syntax below.

The types

There are seven core types and six composite types. Composite types take an object as their $value rather than a primitive.

Colors are objects now, not hex strings

This is the single biggest change for anyone who wrote a token file two years ago. A color's $value is an object carrying an explicit colorSpace, an array of components, and an optional hex fallback.

"accent": {
  "$type": "color",
  "$value": {
    "colorSpace": "oklch",
    "components": [0.63, 0.23, 285],
    "hex": "#7c5cff"
  }
}

The reason is wide-gamut color. A hex string cannot express a Display P3 or OKLCH color at all, so any format built on hex strings quietly caps your design system at sRGB. Naming the color space makes the value unambiguous, and hex remains as the fallback for targets that cannot do better.

Dimensions carry their unit separately

"spacing": {
  "md": { "$type": "dimension", "$value": { "value": 16, "unit": "px" } }
}

"16px" as a string forces every consumer to parse it. Splitting the number from the unit means an iOS build can convert to points without a regex.

Groups, and how $type is inherited

A group is any object without a $value. Groups nest freely and can carry $type, $description, $extends, $deprecated and $extensions.

Setting $type once on a group is the main thing that keeps real token files readable — every child inherits it:

{
  "color": {
    "$type": "color",
    "bg":   { "$value": { "colorSpace": "srgb", "hex": "#0a0b10", "components": [0.039, 0.043, 0.063] } },
    "text": { "$value": { "colorSpace": "srgb", "hex": "#f2f2f7", "components": [0.949, 0.949, 0.969] } }
  }
}

The stable version also reserves the token name $root, which lets a group hold a base value alongside its variants — useful when color.brand itself needs a value and color.brand.hover exists beside it.

Aliases: the part that makes it a system

A token can point at another token instead of holding a literal. This is what turns a flat list of values into a system with semantic layers.

{
  "palette": {
    "$type": "color",
    "violet-500": { "$value": { "colorSpace": "srgb", "hex": "#7c5cff", "components": [0.486, 0.361, 1] } }
  },
  "action": {
    "primary": { "$value": "{palette.violet-500}" }
  }
}

Two syntaxes are defined:

• Curly braces — {group.token} resolves to that token's $value. This is the one you will write by hand.
• JSON Pointer — { "$ref": "#/path/to/target" }, following RFC 6901, for addressing an arbitrary location in the document.

Both support chained references, and both require implementations to detect circular references. Note that action.primary above needs no $type — it inherits color through the reference it resolves to.

A complete, valid file

{
  "$description": "Example token file",
  "palette": {
    "$type": "color",
    "violet-500": {
      "$value": { "colorSpace": "oklch", "components": [0.63, 0.23, 285], "hex": "#7c5cff" }
    },
    "ink-50": {
      "$value": { "colorSpace": "srgb", "components": [0.949, 0.949, 0.969], "hex": "#f2f2f7" }
    }
  },
  "semantic": {
    "action":  { "$value": "{palette.violet-500}" },
    "on-dark": { "$value": "{palette.ink-50}" }
  },
  "space": {
    "$type": "dimension",
    "sm": { "$value": { "value": 8,  "unit": "px" } },
    "md": { "$value": { "value": 16, "unit": "px" } }
  },
  "text": {
    "body": {
      "$type": "typography",
      "$value": {
        "fontFamily": "Space Grotesk",
        "fontSize":   { "value": 16, "unit": "px" },
        "fontWeight": 400,
        "lineHeight": 1.7
      }
    }
  }
}

Save that as design.tokens.json. The spec prefers the media type application/design-tokens+json, falling back to application/json.

What actually reads these files

The announcement cites reference implementations in Style Dictionary, Tokens Studio and Terrazzo, with more than ten design tools supporting or implementing the standard.

Getting a starting file out of a site you already have

Writing a token file from nothing is the slow part — you are transcribing values that already exist in a running product. The faster route is to read them off the rendered page.

CSS DNA scans any live site's computed styles and returns the colors ranked by usage, the type scale, spacing, radii and shadows, then exports them as W3C / Figma design tokens, a Tailwind theme, CSS custom properties, SCSS or JSON. Point it at your own product and you get a first draft of the file above in a few seconds, with the near-duplicate shades flagged so you do not enshrine four greys that should have been one.

That is a starting point, not a finished system — the naming and the semantic layer are judgement calls no scanner makes for you. But it removes the transcription.