Migrate from 1.x to 3.0

Use this guide when upgrading directly from Design Token Kit 1.x to 3.0. It combines the public API changes introduced in 2.0 with the reference model and Figma export changes introduced in 3.0.

For a staged upgrade, use the 1.x to 2.0 and 2.0 to 3.0 guides instead.

Upgrade packages

Update Core and CLI together:

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

Design Token Kit requires Node.js 20.19.0 or newer.

Replace the validation API

DtcgChecker.validate() was replaced by TokenChecker.check().

// 1.x
import { DtcgChecker } from "@design-token-kit/core";

const issues = await new DtcgChecker().validate(sources);

// 3.0
import { TokenChecker } from "@design-token-kit/core";

const issues = await new TokenChecker().check(sources);

TokenChecker accepts DTCG JSON, HRDT YAML, and DESIGN.md. Use CheckScope.SCHEMA for schema-only checks and CheckScope.LINT to run architecture checks.

Update readers and results

Readers and writers use format-specific names.

1.x	3.0
DtcgJsonReader	DtcgReader
HrdtTokenReader	HrdtReader
DtcgJsonWriter	DtcgWriter
HrdtTokenWriter	HrdtWriter

Readers load their schema during asynchronous setup and read() returns a result object:

const reader = await DtcgReader.create();
const result = reader.read(json);

if (!result.ok) {
  console.error(result.issues);
} else {
  const document = result.documents[0];
}

DtcgReader.noSchema() is available when content is already schema-validated or the runtime cannot read schema files.

Removed validator classes include TokenValidator, DtcgSchemaValidator, HrdtTokenValidator, and DesignMdTokenValidator. Use TokenChecker for source validation or a format reader for in-memory content.

Split input and output format enums

Replace the old Format enum with TokenFormat or PlatformFormat:

import {
  PlatformFormat,
  TokenFormat,
} from "@design-token-kit/core";

const inputFormat = TokenFormat.DTCG;
const outputFormat = PlatformFormat.CSS;

The same enums are exported from @design-token-kit/core/browser.

Handle loader results

DtcgListLoader.read() returns a LoadResult instead of throwing a TokenSyntaxError:

const result = await new DtcgListLoader().read(sources);

if (!result.ok) {
  console.error(result.issues);
  return;
}

const list = result.list;

DtcgListLoader.load() remains available when a failed load should throw.

Use current converter names

Use these names in new code:

1.x name	3.0 name
DtcgTokenCssConverter	CssTokenConverter
DtcgTokenScssConverter	ScssTokenConverter
DtcgTailwindCssConverter	TailwindTokenConverter
ColorCssSerializer	CssColorValueConverter
TokenScssOutput	ScssTokenOutput
createTokenCssConverter()	createCssTokenConverter()
createTokenScssConverter()	createScssTokenConverter()
createTailwindCssConverter()	createTailwindTokenConverter()

Older Dtcg* converter aliases remain available, but applications should use the primary v3 names.

Replace boolean TokenReference flags

TokenReference no longer accepts a boolean second constructor argument. Pass an explicit kind instead:

// 1.x and 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 for APIs that accept a reference kind. Use the kind getter to discriminate a reference in new code.

Review JSON Pointer references

A pointer ending in $value references a whole token value. A pointer below $value is a property reference:

{
  "components": {
    "$ref": "#/primitive/color/blue/$value/components"
  },
  "alpha": {
    "$ref": "#/primitive/opacity/disabled/$value"
  }
}

DTCG output preserves these objects. Platform converters resolve property references to concrete fields before they generate CSS, SCSS, Tailwind CSS, SwiftUI, Android, or Figma output.

Re-generate platform artifacts after upgrading. An unresolved, circular, or type-incompatible property reference now prevents conversion. Theme output includes derived overrides when a base property reference resolves differently for a theme.

Update browser integrations

Use the browser facade with split format enums:

import {
  BrowserTokenToolkit,
  CheckScope,
  PlatformFormat,
  TokenFormat,
} from "@design-token-kit/core/browser";

const toolkit = new BrowserTokenToolkit();
const issues = toolkit.check(input, { scope: CheckScope.LINT });
const [output] = toolkit.convert(input, PlatformFormat.CSS);

convert() and stats() validate the input before producing output. They throw BrowserTokenValidationError with structured issues when validation fails.

Review Figma FLOAT variables

The Figma exporter maps a FLOAT variable to DTCG number when its scope is OPACITY or a slash-separated name segment is opacity, alpha, number, or lineHeight. Other FLOAT variables map to dimension.

The exporter follows aliases only when every local target is resolvable and compatible with the expected type. Re-export Figma files and review generated DTCG type changes and warnings.

Migration checklist

• Upgrade @design-token-kit/core and @design-token-kit/cli to v3.
• Replace DtcgChecker.validate() with TokenChecker.check().
• Replace old reader, writer, validator, enum, and converter names.
• Handle ReadResult and LoadResult before accessing documents or lists.
• Replace boolean TokenReference flags with explicit kinds.
• Review JSON Pointers that select nested $value properties.
• Update browser integrations to use TokenFormat and PlatformFormat.
• Run dtokens check --scope lint for all token sources.
• Re-generate every platform artifact and theme output.
• Re-export Figma sources and review FLOAT types and alias warnings.