---
title: "Migrating legacy tokens"
description: "Convert deprecated community-plugin exports to the current DTCG token format and regenerate project artifacts."
requested_language: nl
language: en
translation_notice: "This page isn't translated yet"
url: https://docs.systhema.app/nl/next/design/legacy-tokens
version: unreleased (main)
docs_index: https://docs.systhema.app/nl/next/llms.txt
---
> This page isn't translated yet. Showing English.


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 tokens

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](https://docs.systhema.app/nl/next/cli/doctor.md).

## Convert with migrate-tokens

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

```bash
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.

> [!WARNING]
> Conversion writes the manifest and every listed collection and style file in place. Save or commit your current export first, then inspect the diff and conversion messages. Missing files are warned about and individual file errors are logged while the command continues.

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 runs

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 converting

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](https://docs.systhema.app/nl/next/design/figma.md) for later exports. Configuration changes belong in [custom tokens](https://docs.systhema.app/nl/next/design/custom-tokens.md).

Use the generated [colors](https://docs.systhema.app/nl/next/reference/tokens/colors.md), [typography](https://docs.systhema.app/nl/next/reference/tokens/typography.md), [spacing](https://docs.systhema.app/nl/next/reference/tokens/spacing.md) and [effects](https://docs.systhema.app/nl/next/reference/tokens/effects.md) tables to compare your migrated design with the shipped defaults. These tables are not a record of your project's custom export.