Migrating legacy tokens

Migrate token exports from the old community Figma plugin before relying on current Systhema token metadata. Core still has a deprecated compatibility adapter, but its warning says support will be removed in a future major release.

Find legacy tokensLink to this section

The manifest's generator.name selects the extraction path. @systhemaui/figma and @systhemaui/design use the current format. Other generator names use the legacy adapter, even if individual leaves already have $type and $value.

The legacy adapter removes asterisks from runtime keys and references, unwraps $type/$value leaves, and unwraps style arrays to their first item. It does not rewrite the source files. A process logs the deprecation warning only once. Do not remove asterisks by hand from an export.

systhema doctor detects legacy exports with the legacy-tokens check; systhema doctor --fix invokes conversion. See systhema doctor.

Convert with migrate-tokensLink to this section

Run this from the consumer project root, with systhema.config.ts, .js or .json pointing to a manifest:

pnpm systhema-core migrate-tokens
pnpm systhema-core sync

The global CLI also proxies systhema migrate-tokens to the project-local command. The converter resolves the manifest from configuration; it does not assume tokens live in src/tokens/. There are no command-specific flags or dry-run mode.

The conversion:

• Changes literal hex colors to sRGB objects with normalized components, alpha and hex.
• Converts legacy dimension leaves to number leaves and parses numeric string values.
• Keeps reference strings and reconstructs cross-collection com.figma.aliasData.
• Reconstructs typography and grid com.figma.boundVariables; converts grid colors and shadow colors and dimensions.
• Changes the manifest generator to @systhemaui/figma, with a version ending in -migrated, and retains collection modes and style filenames.

Metadata and repeated runsLink to this section

If a sibling <token-directory>-new/ or tokens-new/ directory contains a new-format manifest and matching filenames, the converter uses it to match scopes and Figma variable IDs. It also copies complete style values and extensions when matched. Without a reference export, it reconstructs aliases and style bindings from references, but cannot recover scopes or variable IDs; re-export from Figma to restore those.

A first-party manifest without the -migrated suffix makes the command report that nothing needs migration. A migrated manifest remains eligible for another pass, so you can rerun with a reference export available. Do not treat that rerun as a guaranteed byte-for-byte no-op.

After convertingLink to this section

Run pnpm systhema-core sync to refresh generated artifacts, types and references. Review the generated CSS, especially opacity variables whose scope metadata was missing, and use the Figma plugin for later exports. Configuration changes belong in custom tokens.

Use the generated colors, typography, spacing and effects tables to compare your migrated design with the shipped defaults. These tables are not a record of your project's custom export.