We've upgraded the tokens manager to use Style Dictionary v5 and the 2025.10 version of the Design Tokens Community Group (DTCG) spec. This specification is maintained by a W3C Community Group to standardise how design tokens are described. If you've set up token automation or you're using the Style Dictionary URL export or zeroheight API to fetch tokens, the JSON your pipeline consumes will look a little different. This guide walks through what's changed and what you'll need to update.

What's changed

• The default export format is now DTCG JSON. It replaces the older DTCG JSON (legacy) and Style Dictionary formats.
• Platform exports (CSS, SCSS, iOS, iOS Swift, Android, Compose, Flutter, LESS, JS, Web) are now generated by Style Dictionary v5.
• The legacy DTCG JSON (legacy) and Style Dictionary formats are no longer available when you create a new token set output or download a new URL export. Existing outputs on those formats continue to work.
• DTCG JSON files now use the extension .tokens.json instead of .json.

Why we made the change

DTCG published a stable 2025.10 revision of the spec earlier this year, and Style Dictionary v5 adopted it as its base format. Figma, Tokens Studio, the Style Dictionary CLI, and most other design-token tools now read 2025.10 directly. If your tokens pipeline was previously converting zeroheight output into one of those tools, the intermediate transformation step is no longer needed. The same code that reads your zeroheight export will also work against token files from other tools that follow the spec, so you can share tooling across projects.

Who's affected

You'll want to read on if any of the following is true:

• You have a token automation set up against a Git repository.
• You consume the Style Dictionary URL export in a downstream pipeline.
• You click Export → Download JSON on a token set and feed that file into a downstream tool.
• You download via the zeroheight API (/token_management/token_set/export_json) or call the Style Dictionary URL export programmatically.
• You have code that parses zeroheight token files and reads value, type, or description keys.

If you've never set up an export or automation, there's nothing to do.

What the new DTCG JSON looks like

The keys that describe a token are now prefixed with $. This matches the 2025.10 spec.

Aliases still use curly braces around the full path of the referenced token:

{
  "color": {
    "brand": {
      "primary": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [
            0.8980392156862745,
            0.0,
            0.0
          ],
          "alpha": 1.0,
          "hex": "#e50000"
        },
      },
      "primary-alias": {
        "$type": "color",
        "$value": "{color.brand.primary}"
      }
    }
  }
}

The 2025.10 spec also introduces richer value types. In the updated export, you'll also see:

• dimension and duration values are structured objects with a value and unit (e.g. { "value": 16, "unit": "px" }) instead of a single string like "16px".
• color values carry a colorSpace, a components array, alpha and a hex fallback.
• strokeStyle values use the structured dimension form inside dashArray.
• Every token, group, and set also includes a $extensions object carrying zeroheight-specific IDs under the com.zeroheight namespace.

More information about these types, along with spec features like $deprecated, $root, references, and resolver files, can be viewed in the spec.

Platform exports (CSS, SCSS, iOS, Android, etc.)

Platform outputs are now built by Style Dictionary v5 from the DTCG 2025.10 JSON. The file format stays the same (a CSS file is still a CSS file), but variable names and generated structure can shift in places. Before you switch a production pipeline over, download a copy of the new export, run it side-by-side with your current output, and diff the files. This is especially worth doing if:

• Your token set has modes (dark / light, density, brand).
• You rely on aliases that cross token groups.
• You've hard-coded variable names in downstream apps.

Most projects will see no meaningful differences. A small number of tokens that used mode inheritance or alias chains may resolve slightly differently under v5.

What you need to do

1. Find your token set outputs that are on the legacy format. Open the automations panel on any token set: legacy outputs show a warning icon on the Format column, with a row explaining the change and linking to this page.

   

2. Decide which downstream consumers need to move:
   • Pipelines that read the DTCG JSON directly: Update your parser to read $value / $type / $description instead of the unprefixed keys. If your build script hard-codes the .json extension, change it to .tokens.json or make it extension-agnostic.
   • Pipelines that consume a platform export (CSS, iOS, Android, etc.): Download the new version, diff it against what's in your repo today, and update any references to renamed variables.
3. When you're ready, open the token set output and change the format from the legacy option to the new one. For automations, repeat for each configured output.
4. Re-run your build and confirm everything still works.

Reverting to v3

Once you've switched a token set output to DTCG 2025.10, there's no in-product way to move it back to the legacy DTCG JSON or Style Dictionary format.

If you need to revert for any reason (an unresolved issue with your pipeline or a blocker you've hit during migration), email us at support@zeroheight.com with the token set URL and we'll help sort it out.

See also

• Convert design token sets to use zeroheight tokens manager
• Style Dictionary v5 release notes
• DTCG 2025.10 specification