Migrate from Tokens Studio — SXL Studio Docs

Overview

SXL Studio includes a guided Migration TS flow for teams moving from Tokens Studio. It converts token JSON into SXL Studio's native DTCG shape, can translate $themes.json into SXL config.json, and keeps the result reviewable through Git Sync before anything is pushed.

Step	What happens
Preview	Scans the workspace; shows changed files, converted tokens, type-mapping counts, `$themes` collections, and warnings
Apply Migration	Rewrites token JSON in place to SXL DTCG; the workspace becomes dirty (nothing is pushed)
Push	You review the Git diff and commit when the JSON looks correct

Migration is intentionally explicit: preview first, apply only when you are ready, then review the Push diff.

Where to find it

Open Git Sync, activate a connection, and click Migration TS next to New Sync. The button is available in Figma Design mode when a Git connection is active.

The dialog has three main switches:

Switch	What it does
Convert to W3C / DTCG format	Rewrites `value/type/description/extensions` → `$value/$type/$description/$extensions`
Migrate Tokens Studio types to SXL types	Maps TS token types to SXL types; the type list expands below (all selected by default)
Convert $themes.json to SXL config	Converts TS theme/set state into SXL `config.json` collections, modes, and file statuses

Click Preview first. Preview scans the workspace and shows files changed, tokens converted, type mapping counts, $themes collections/modes, warnings, and invalid JSON files that were skipped. Click Apply Migration only after reviewing the preview.

Migration never pushes to Git automatically. After apply, the workspace becomes dirty and you decide when to push.

Safe migration workflow

Create a branch or make sure the current branch is dedicated to migration work.
Run Pull so the plugin has the latest token files.
Open Git Sync → Migration TS.
Keep all mappings selected unless you have a specific reason to exclude a type.
Run Preview and check warnings.
Run Apply Migration.
Open Push, review the diff, and commit when the JSON looks correct.
Before the first Export Variables & Styles in an existing Figma library, review the warning about existing Figma references. Use Bind existing by name or your normal rebind/adoption process if the file already contains matching Variables/Styles.

What it converts

Migration reads managed token JSON files from the active Git Sync workspace. It converts Tokens Studio token files from legacy value/type/description/extensions or partially DTCG-like JSON into SXL DTCG ($value/$type/$description/$extensions).

Already-valid SXL tokens pass through unchanged. Running the same migration again is stable: unchanged files stay unchanged.

Composite values are normalized together with their type:

boxShadow token layers using Tokens Studio keys such as $x, $y, $blur, $spread, $color, $type become SXL shadow layers with offsetX, offsetY, blur, spread, color, type.
typography values using $fontFamily, $fontWeight, $fontSize, $lineHeight, and related prefixed fields become SXL typography fields without the $ prefix.
Tokens Studio composition values become SXL template values. Nested boxShadow style props keep the template/composition shape (x, y, blur, spread, color, DROP_SHADOW / INNER_SHADOW) so template apply works correctly.

SXL Studio does not treat every file in the repository as a token file. It skips SXL config.json, Tokens Studio $metadata.json, Markdown, README files, and other unmanaged files.

Token type mapping

Every supported Tokens Studio type maps to a canonical SXL type. Plural and legacy aliases are normalized.

Tokens Studio	SXL Studio
`color`	`color`
`typography`	`typography`
`fontFamilies` / `fontFamily`	`fontFamily`
`fontWeights` / `fontWeight`	`fontWeight`
`fontStyles` / `fontStyle`	`fontStyle`
`fontSizes` / `fontSize`	`fontSize`
`lineHeights` / `lineHeight`	`lineHeight`
`letterSpacing`	`letterSpacing`
`paragraphSpacing`	`paragraphSpacing`
`paragraphIndent`	`paragraphIndent`
`textCase`	`textCase`
`textDecoration`	`textDecoration`
`dimension`	`dimension`
`number`	`number`
`border`	`border`
`boxShadow`	`shadow`
`borderRadius`	`borderRadius`
`borderWidth`	`borderWidth`
`spacing`	`spacing`
`sizing`	`sizing`
`opacity`	`opacity`
`boolean`	`boolean`
`text` / `string`	`text`
`asset` (URL string)	`img`
`asset` (object/blob)	clean custom `$type: "asset"`
`composition`	`template`
`other`	clean custom `$type: "other"`
`fontFallbacks`	clean custom `$type: "fontFallbacks"`
any unknown `$type`	preserved as a clean custom `$type`

If you clear a type checkbox in the Migration TS dialog, that type is not migrated. Use this only for controlled partial migrations.

Composition → Template

In Tokens Studio, a composition token is a bag of style properties. In SXL Studio this maps to Template, not to SXL's file-level Composition generator.

Migration converts Tokens Studio $type: "composition" tokens to $type: "template", whether the type is set directly on a token or inherited from a parent group.

A file that is already an SXL composition generator (it has a structure and/or styles block at the root) is recognized by shape and left untouched.

Extensions

Tokens Studio metadata is mapped into SXL's figma.* namespace. Both flat and nested Figma extension forms are supported.

$extensions["studio.tokens"].modify → $extensions["figma.modify"]
$extensions["com.figma.scopes"] → $extensions["figma.scopes"]
$extensions["com.figma"].scopes → $extensions["figma.scopes"]
$extensions["com.figma.codeSyntax"] → $extensions["figma.codeSyntax"]
$extensions["com.figma"].codeSyntax → $extensions["figma.codeSyntax"]
$extensions["com.figma.hiddenFromPublishing"] → $extensions["figma.hide"]
$extensions["com.figma"].hiddenFromPublishing → $extensions["figma.hide"]
studio.tokens.id → $id (when no $id is present)

Color modifiers from Tokens Studio are converted to SXL figma.modify when they match supported modifier shapes. Unsupported modifier forms are preserved as inert metadata with a warning instead of being written as invalid SXL modifiers.

If an SXL-native value already exists, it wins and a warning is reported.

Custom tokens

Types that have no SXL/Figma export target (other, fontFallbacks, unknown types, non-URL asset) become Custom tokens.

authored $type: the original type is kept as a clean $type when possible
compatibility: older files that use $type: "custom" plus sxl.studio.declaredType are still read
value: preserved exactly as-is
export: safe $value shapes are inferred and exported through the existing Variable/Style pipeline; non-inferable values remain internal

You can view and edit Custom tokens in the token editor under Other → Custom. Saving from the visual editor writes the clean $type form.

Config and `$themes.json`

When Convert $themes.json to SXL config is enabled, Tokens Studio theme data becomes SXL config collections and modes. Each token set in a theme becomes a file status:

enabled — exported (creates variables/styles) and used to resolve aliases
disabled — ignored
source — resolve-only: participates in alias/type resolution (for primitive sets like base units or palettes that other sets reference) but does not create variables/styles itself

The migration merges generated config data into the existing SXL config instead of pushing immediately. Review the Push diff before committing.

Existing Figma variables and styles

Migration converts JSON. It does not automatically adopt existing Figma Variables/Styles from Tokens Studio references.

If you migrate a project that already has Variables or Styles in Figma, check the warning after Apply Migration and plan the first export carefully:

enable Bind existing by name when names already match;
inspect/rebind manually if your library has legacy naming;
avoid exporting into a production library before reviewing the diff and warnings.

This prevents accidental duplicate Variables or Styles during the first SXL export.

What Migration TS does not do

It does not push to Git.
It does not mutate Figma Variables or Styles.
It does not rewrite unmanaged files such as README or Markdown.
It does not auto-adopt existing Figma IDs from Tokens Studio references.

Troubleshooting

The button is not visible

Check that you are in Figma Design mode, a Git connection is active, and the plugin build is up to date.

Preview shows no changed files

Run Pull first, then check that your Tokens Path points to the folder that contains token JSON files. Already-migrated files may correctly show as unchanged.

Invalid JSON is skipped

Fix the JSON file and run Preview again. Migration skips invalid JSON instead of partially rewriting it.

Variables are duplicated after export

Migration itself does not create Figma Variables. If duplicates appear after export, review diff-id/adoption state and use Bind existing by name or rebind existing Variables/Styles before re-exporting.

Git integration — Pull, Push, and Migration TS location
Export Variables & Styles — first export after migration
Token JSON format — SXL DTCG token shape
All token types — canonical SXL token types

#Overview

#Where to find it

#Safe migration workflow

#What it converts

#Token type mapping

#Composition → Template

#Extensions

#Custom tokens

#Config and $themes.json

#Existing Figma variables and styles

#What Migration TS does not do

#Troubleshooting

#Related sections