❇️ W3C - DTCG Specification Alignment

In V2, you will be able to choose a design token format (how tokens are written in their JSON files)

• Current Tokens Studio "legacy" format

• DTCG W3C spec format

What's the difference between the two?

• 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, in addition to those that currently exist

  • { } $

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

• Note:

  • The DTCG also has specifications on additional token types and their accepted values, which we will support in coming releases.

How and where to use this feature

The choice of token format can be made for tokens stored:

• Local (in file only)

• Remote (sync to git providers)

  • Different branches can have different formats

You can select a token format in two locations:

• Plugin settings > sync/storage providers

• Clicking the DTCG icon at the footer of the plugin

  • Only visible when synced to external storage

Sync/Storage Settings

In the settings page of the plugin, 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 "MESSAGE HERE"

On local document token storage:

With external sync provider selected:

• As soon as you select a provider, the token format for that repository will show.

• The token format for other sync providers or local document will be hidden.

  • When synced to external storage, the current token format also appears in bottom of the plugin next to the branch selector.

Once you choose a new token format you will

• See a modal that explains the process + confirm your decision

  • If you have unsaved changes to your tokens you haven't pushed to your sync provider, the button will be disabled, and an error message will appear to remind you to push so you don't lose your work.

• The plugin will convert your tokens to the new format

• You'll be asked to push your changes to your sync provider

  • A pre-filled commit message is there to help your engineers understand what to do with this.

  • A branch is created in the plugin for you to work in until it is merged into main.

    • Branches can have different formats

• You CAN convert back to the Tokens Studio legacy format if needed

👀 Quick video of the user flow

The token format icon in the bottom of the plugin is not just a status indicator.

• Like the other sync actions, you can access the flow to convert from one format to another by selecting the token format indicator.

🐛 Known issues - being fixed

• 2644 - On remote storage if you cancel out of the "push" from the flow, the "push" button is disabled everywhere across the plugin. You must close the plugin and not restore changes to reset.

  • PRO TIP - If this happened to you and have work you need to save, open the stable build of the plugin, restore the changes and push.

How it works under the hood

As per Github

• Introduces support for the DTCG format as in supporting $value, $type and $description in both input and output.

• Introduces a setting that, when changed,

  • writes and reads tokens to the $-prefixed props

  • instead of the legacy ones we supported before.

• We'll still support both, but this will allow the new format to be chosen.

• Restrictions to token names introduced

  • { } $

Github issues

• 2499 / 999 - Support new W3C syntax for $value, $type and $description

• 1747 - Forbid characters in token names, { } $

Related roadmap items

• ❇️⚙️ Settings page enhancements → Jump to post

• 🪄 👩‍💻 JSON Enhancements → Jump to post

• ❇️ DTCG W3C | Token Group Metadata - Description and Type → Jump to post

• ❇️ W3C DTCG Spec boxShadow values JSON schema → Jump to post