Style Dictionary v5.4.0 ships DTCG 2025.10 dimension tokens…

Style Dictionary remains the workhorse that turns token JSON into platform outputs — CSS variables, Tailwind config, iOS Swift constants, Android XML, Compose theme data, Flutter constants. v5.4.0 tightens alignment with the DTCG 2025.10 spec, with the most visible change in how dimension tokens can be authored.

Style Dictionary v5.4.0 ships first-class support for the DTCG 2025.10 dimension object form while preserving compatibility with older string dimensions.

TL;DR

Dimension tokens support the object form { "value": 1, "unit": "px" } per the DTCG 2025.10 spec.
String dimensions ("16px", "1rem") still work — no breaking change for older token files.
Built-in transforms for typography, border, and shadow composites understand the new dimension shape.
Stricter tuple typing for homogeneous token groups improves generated TypeScript types.
Drop-in upgrade from v5.3.x — no API breaks.

Why a "dimension" needs a type

In earlier token formats, a dimension was just a string: "16px", "1rem", "50%". That's easy to author but hard for tooling. To convert from px to pt for iOS, the consumer has to parse the string. To resolve mathematical references ("{spacing.base} * 2") the tool has to parse the unit again. To validate that a token is in fact a dimension and not, say, a CSS auto value, you parse it again.

DTCG 2025.10 makes the unit explicit:

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

Tools read value and unit as separate keys, do their conversions cleanly, and emit the platform-appropriate output without a parser.

Compatibility with string dimensions

Style Dictionary 5.4 handles both forms:

Old projects with "$value": "16px" keep working.
New projects using { "value": 16, "unit": "px" } are the recommended shape going forward.
Mixed projects (legacy + new tokens in the same file) work without configuration.

The compatibility layer means there's no big-bang migration. Add new tokens in the object form, leave existing tokens as strings, run a migration when you have time.

Composite tokens stay coherent

A common bug in earlier Style Dictionary versions: composite tokens like typography, border, and shadow nested dimension values, but the built-in transforms for CSS shorthands didn't always thread the new object form through. v5.4 updates the transforms:

Typography — fontSize, lineHeight, letterSpacing accept dimension objects.
Border — width accepts dimension objects.
Shadow — offset, blur, and spread accept dimension objects.
Gradient stops — positions accept dimension objects (with % unit).

After v5.4, a typography token like:

{
  "heading-1": {
    "$type": "typography",
    "$value": {
      "fontFamily": "{font.family.display}",
      "fontSize": { "value": 32, "unit": "px" },
      "lineHeight": 1.1,
      "letterSpacing": { "value": -0.02, "unit": "em" }
    }
  }
}

… emits a coherent CSS shorthand:

.heading-1 {
  font: 32px/1.1 "Inter Display", ui-sans-serif;
  letter-spacing: -0.02em;
}

… without manual transforms or post-processing.

Stricter tuple typing

If you use Style Dictionary's TypeScript output, v5.4 tightens types for homogeneous token groups. Before, a group like spacing.scale (an array of dimension tokens) typed loosely as a generic array. After, it types as a tuple with the right element type:

// Before
declare const spacingScale: Array<{ value: number; unit: string }>;

// After
declare const spacingScale: readonly [
  { value: number; unit: "px" },
  { value: number; unit: "px" },
  // … exact length, exact unit
];

The benefit: better IDE autocompletion, more precise checks downstream, and mistakes that previously slipped through (referencing an out-of-bounds index, mixing units in a homogeneous group) now fail at compile time.

Migration

v5.4 is drop-in from v5.3.x. To opt into the new dimension format:

Author new tokens in object form going forward.
Use the migration helper (style-dictionary migrate dimensions if your scripts wrap the CLI) to convert older string dimensions to the object form in bulk.
Re-run your build to verify CSS / Swift / Android / Flutter outputs are unchanged after migration.

If you generate platform code in CI, add a smoke test that compares the output of v5.3.x and v5.4 on the same input — there should be no diff for projects that haven't changed their token files.

Context: spec + tooling in lockstep

For the past few years, design tokens were viable but not fully standardized — tools agreed on big strokes but disagreed on edges. The combination of DTCG 2025.10 stable plus Style Dictionary v5.4 is the first time the spec and the most-used codegen tool moved in lockstep on the same release cycle. That's the cue to standardize on DTCG JSON in new repos.

References

Source / further reading: Style Dictionary (GitHub release)

Style Dictionary v5.4.0 ships DTCG 2025.10 dimension tokens + shorthand fixes