Understanding the W3C Design Token Community Group Format

Before the W3C Design Token Community Group (DTCG) published its specification, every tool that consumed design tokens invented its own file format. Style Dictionary used one JSON shape, Theo used another, Specify used a third. Tokens defined in one tool couldn't be imported into another without a custom transform. The DTCG spec exists to end that fragmentation.

What the spec defines

The DTCG specification is a JSON format for describing design tokens in a way that any compliant tool can read, write, and transform. It defines:

• —The structure of a token (what fields it must and may have)
• —The set of built-in token types (color, dimension, fontFamily, fontWeight, duration, cubicBezier, number, shadow, typography, fontStyle, strokeStyle, border, transition, gradient)
• —How tokens can reference other tokens
• —How tokens can be grouped into a hierarchy

The specification does not define what tools must do with tokens — only how tokens must be represented at rest.

Token anatomy

Every DTCG token is a JSON object with at least a $value field. The leading $ is the delimiter that separates token metadata from group structure — any key without $ is treated as a nested group, not a token property.

{
  "color": {
    "brand": {
      "primary": {
        "$value": "#2563eb",
        "$type": "color",
        "$description": "Primary brand color used for interactive elements."
      }
    }
  }
}

$value (required) — the token's value. Its format depends on the type. For color it is a hex string or rgba(). For dimension it is a string with a unit (16px, 1rem). For shadow it is an object.

$type (recommended) — declares what kind of value this is. When omitted, tools may infer it from context or the parent group's $type. Specifying it explicitly at the token level is the safest approach.

$description (optional) — a human-readable explanation. Picked up by documentation generators and surfaced in Figma's variable description field when using Tokens Studio.

$extensions (optional) — a namespace for tool-specific metadata that isn't part of the core spec. Tokens Studio uses $extensions["studio.tokens"] to store extra configuration. Style Dictionary uses it for transform hints.

Groups and inheritance

Tokens are organized into a hierarchy by nesting objects. Any object that doesn't contain a $value is a group. Groups can carry a $type that their children inherit:

{
  "spacing": {
    "$type": "dimension",
    "xs": { "$value": "4px" },
    "sm": { "$value": "8px" },
    "md": { "$value": "16px" },
    "lg": { "$value": "24px" }
  }
}

Every token inside spacing inherits $type: "dimension" without declaring it explicitly. This keeps the file concise while remaining unambiguous to compliant parsers.

References

References are the most powerful feature of the DTCG format. A $value can point to another token by its dot-separated path, wrapped in curly braces:

{
  "semantic": {
    "background": {
      "page": {
        "$value": "{color.neutral.50}",
        "$type": "color"
      }
    }
  }
}

The reference {color.neutral.50} tells any compliant tool: "resolve this token's value by looking up color.neutral.50 in the same file." This is how semantic tokens stay decoupled from raw values. Change the primitive, and everything that references it updates automatically.

Circular references are invalid. A token may reference a token that itself references another token (chained references), but the chain must terminate at a concrete value.

Composite types

Some types have structured $value fields — objects rather than scalars. The spec defines several:

typography — bundles font properties into a single token:

{
  "body": {
    "$type": "typography",
    "$value": {
      "fontFamily": "Inter",
      "fontSize": "16px",
      "fontWeight": "400",
      "lineHeight": "1.5"
    }
  }
}

shadow — describes a CSS box shadow:

{
  "md": {
    "$type": "shadow",
    "$value": {
      "offsetX": "0px",
      "offsetY": "4px",
      "blur": "16px",
      "spread": "0px",
      "color": "rgba(0,0,0,0.24)",
      "inset": false
    }
  }
}

Each property inside a composite value can itself be a reference, so a shadow token can reference a color token for its color field.

Why tooling converged on DTCG

Style Dictionary v4 adopted DTCG as its primary format. Tokens Studio uses it as its wire format when syncing with code repositories. Figma's own variables API is designed to map onto the DTCG type system. Amazon, Adobe, and Google have all contributed to or publicly aligned with the spec.

The reason is practical: the alternative is a permanent layer of per-tool adapters. Every new integration requires a custom transform in both directions. With a shared format, a token defined in BaseFrame can be consumed by Style Dictionary, imported into Figma via Tokens Studio, and validated against a JSON schema — all without any transformation.

How BaseFrame uses the spec

BaseFrame generates a fully compliant DTCG token tree. The structure follows the two-layer pattern the spec is designed for:

• —token.primitive.* holds concrete values — colors, sizes, typography scales — with explicit $type declarations on every token
• —token.semantic.* holds reference-only tokens — every $value is a {token.primitive.*} reference, never a raw value

The $description field is populated for semantic tokens to explain their intended role. The output passes DTCG schema validation and is accepted by Style Dictionary v4 without any custom transforms.