Migrate from 2.0 to 3.0

Design Token Kit 3.0 changes the public reference model and makes property references work consistently in every platform converter. Read this guide before upgrading a Core integration or relying on Figma FLOAT variable export classification.

Upgrade packages

Upgrade the packages together when they are used in the same project:

npm install @design-token-kit/core@3 @design-token-kit/cli@3

The Figma plugin is distributed separately. Install its v3 release from Figma before exporting files that use the updated FLOAT classification rules.

Replace boolean TokenReference flags

TokenReference no longer accepts a boolean second constructor argument. Use an explicit reference kind instead.

// 2.0
const reference = new TokenReference(
  "#/primitive/color/blue/$value/components",
  true,
);

// 3.0
const reference = new TokenReference(
  "#/primitive/color/blue/$value/components",
  "property",
);

Use the exported TokenReferenceKind type when an API accepts a reference kind:

import {
  TokenReference,
  type TokenReferenceKind,
} from "@design-token-kit/core";

const kind: TokenReferenceKind = "property";
const reference = new TokenReference(
  "#/primitive/color/blue/$value/components",
  kind,
);

The kind getter is the discriminant for new code. Existing isAlias, isTokenReference, and isPropertyReference getters remain useful for narrowing an existing reference.

Review JSON Pointer references

DTK now distinguishes a pointer to a whole token value from a pointer to a property inside that value.

{
  "$ref": "#/primitive/color/blue/$value"
}

The pointer above is a token reference. It keeps the target token type and behaves like an alias.

{
  "$ref": "#/primitive/color/blue/$value/components"
}

The pointer above is a property reference. It resolves to the selected property while keeping the surrounding token value intact.

Do not use a property reference where the selected value cannot produce the required composite field type. For example, a color components reference must resolve to an array of color components. Circular and unresolved property references now fail materialization.

Expect concrete platform fields

DTCG serialization preserves property reference objects. Platform converters instead materialize property references before generating output. This applies to color, dimension, duration, cubic-bezier, border, transition, shadow, gradient, stroke-style, and typography fields.

This can change generated CSS, SCSS, Tailwind CSS, SwiftUI, Android, and Figma script output when an existing token uses property references. Re-generate committed platform artifacts after upgrading.

For themed lists, DTK also emits derived theme overrides when a base property reference resolves differently in that theme.

Review untyped property references

When a token has no declared or inherited $type, DTK infers its type from a property reference only when its target resolves unambiguously. Add $type to a token if its property reference cannot establish a supported type.

Review Figma FLOAT variables

The Figma exporter now recognizes more FLOAT variables as DTCG number:

• variables scoped to OPACITY;
• names with an opacity or alpha segment;
• names with a number segment;
• names with a lineHeight segment.

Other FLOAT variables remain dimension values. An alias chain is exported only when every target is resolvable and compatible with the expected DTCG type. Re-export Figma files and review the generated DTCG type changes before replacing a checked-in token source.

Migration checklist

• Upgrade @design-token-kit/core and @design-token-kit/cli to v3.
• Replace boolean TokenReference constructor flags with explicit kinds.
• Review pointers ending in $value and pointers selecting nested properties.
• Run dtokens check --scope lint on every token source.
• Re-generate platform artifacts for every base and theme source.
• Re-export Figma variables and review FLOAT token types and alias warnings.