Token Format - W3C DTCG vs Legacy | Tokens Studio for Figma

PreviousBase Font Size Setting NextLocal Document - Figma File Token Storage

Last updated 4 months ago

Was this helpful?

Token formats W3C DTCG vs Legacy

In support of moving towards the , as managed by the Design Tokens Community Group (DTCG), you can choose a Design Token Format (how tokens are written in their JSON files) from within the Tokens Studio Plugin.

Current Tokens Studio "legacy" format
W3C DTCG spec format

What's the difference?

The DTCG format prefixes the properties of a design token in the JSON file with the dollar sign ($)

$value
$type
$description

Restrictions of special characters in token names are introduced to support this:

When creating Token names with these characters, an error message appears, and the action is blocked.

In the plugin

The choice of Token Format can be defined for Tokens stored in the local file or remote via a sync provider. For Git sync providers, different branches can have different Token Formats.

You can select a token format in two locations:

Plugin settings > sync/storage providers.
Sync actions at the bottom of the plugin when a remote storage provider is active.

You can change between the W3C DTCG and Legacy token formats at any time by following the steps below.

1. Settings page

On the plugin's settings page, you can see the Token Format being used in your file next to your token storage provider.

The default is legacy format
When you make the switch, you'll see W3C DTCG format

Tokens stored on the local document

If your tokens are stored locally in the Figma file (no external storage or sync providers), the Token format action is to the right of the local document option.

Tokens stored externally

When your tokens are stored externally via Sync providers the token format for the active sync provider will show.

The token format for other sync providers will be hidden.

2. Sync actions

When synced to external storage, the current token format also appears at the bottom of the plugin alongside the other Sync provider actions.

It's possible for different branches of a sync provider to have different token formats, so you can select the Token format icon button to switch formats if needed.

Convert between Token Formats

Select the Token format indicator to start the process of changing formats (from the settings page or sync actions):

A Token format modal appears to explain the process.
Confirm your decision to switch formats.
The plugin will convert your token JSON files to the format of your choice.

The plugin will convert your token JSON files to the format of your choice without any further action from you.

Push changes to remote storage

If you have unsaved changes that need to be synced to a remote storage provider that requires it, the plugin will prompt you to push changes so you don't lose your work.

A new branch is automatically created for you with updated JSON files.
The push changes modal will open.
A pre-filled commit message is added to help your engineers know what to do when they receive your changes.
Follow the prompts in the plugin to push changes to your sync provider.

Once you've synced your changes, the plugin will automatically have you working in the newly created branch. You'll see the W3C DTCG Token Format indicators next to the branch name at the bottom of the plugin.

Transforming Tokens

When your design token format is set to W3C DTCG Format using the steps above, you'll need to configure Style Dictionary to support this.

For each Token Type the SD-Transforms package will automatically convert the Tokens Studio specific Token Type to align with the DTCG Format Token Type where necessary.