W3C Design Tokens (DTCG) Format: A Deep Dive for Color

The DTCG format (formally the W3C Design Tokens Community Group draft) is the closest thing the industry has to a shared file format for design tokens. Figma Variables, Tokens Studio, Style Dictionary, Specify, Supernova and the new Adobe Spectrum tooling all read or write it. Authoring your color tokens in DTCG today is the fastest way to keep options open tomorrow.

The minimum viable token

{
  "color": {
    "brand": {
      "$type": "color",
      "$value": "#7c5cff"
    }
  }
}

The $ prefix is the spec's way of distinguishing metadata from nested tokens. Anything starting with $ describes the token itself; anything else is a nested group.

Aliases (referencing other tokens)

{
  "color": {
    "brand": { "$type": "color", "$value": "#7c5cff" },
    "action": {
      "primary": { "$type": "color", "$value": "{color.brand}" }
    }
  }
}

The curly-brace syntax dereferences the path. Aliases let you author the two-tier system from our naming article: a reference layer (color.brand) and a semantic layer (color.action.primary) that points at it.

Color values: more than HEX

The 2024 update to the DTCG color type accepts richer values:

{
  "color": {
    "brand": {
      "$type": "color",
      "$value": {
        "colorSpace": "oklch",
        "components": [0.65, 0.18, 290],
        "alpha": 1
      }
    }
  }
}

Authoring in OKLCH inside the token file is the new best practice. Exporters convert down to sRGB HEX where needed; tools that support wide-gamut emit color(display-p3 ...) automatically.

Themes and modes

The spec does not yet officially define multi-mode tokens, but Tokens Studio's "themes" extension - widely supported - uses a sibling-file pattern:

// tokens/light.json
{ "color": { "surface": { "$type": "color", "$value": "#ffffff" } } }
// tokens/dark.json
{ "color": { "surface": { "$type": "color", "$value": "#0b0b10" } } }
// tokens/$themes.json
[ { "name": "light", "selectedTokenSets": { "global": "enabled", "light": "enabled" } } ]

Resolvers (Style Dictionary, Tokens Studio CLI) generate one CSS file per theme by merging shared + theme-specific sets.

Token type tips for color

• Always set $type. Auto-detection is fragile across tools.
• Group by role, not by color. color.text.primary, not color.gray.900.
• Use $description generously. A short note ("primary action surface, hover and active variants exist") makes the token self-documenting.
• Author OKLCH first. HEX exports are derivative. Authoring HEX is a one-way street.

Practical pipeline (2026)

1. Author tokens in Figma Variables or your repo as DTCG JSON.
2. Run Style Dictionary (or Tokens Studio Sync) to emit:
   • CSS custom properties (web)
   • Tailwind config (web)
   • iOS / Android resources
   • SCSS map (legacy)
3. Commit the generated artifacts. Components consume the generated outputs, never the JSON directly.
4. On change, regenerate. Diffs are visible in PRs.

What is still messy

The spec is a "candidate recommendation" - not yet a W3C Recommendation. Two tools may interpret edge cases differently. Stick to the well-trodden path (color, dimension, shadow, font) and you will dodge 95% of incompatibility bugs.

Export your palette as DTCG JSON in our Design Tokens tool - the output validates against the latest draft and imports cleanly into Style Dictionary.