Token Descriptions in Tokens Studio
The description
is the anatomic part of a Design Token that can be used to define additional details, like why or how we made this decision.
You might recall from our Intro to Design Tokens Guide that the description
is optional but very helpful to provide additional context about the Token.

You can think of a Token's description as a place to add a note or reminder about this design decision for your engineers, designers, or future self.
For example, a Font Family Token may have a description with a link to download the files.

Working with Token Descriptions
From the Tokens Page of the Tokens Studio Plugin for Figma, there are three places to see the Description of a Token.
Token data on hover
Token form
JSON file
1. Token Data on Hover
Hover on an existing Token to view its data. If a Description was added to the Token, it appears as the last piece of data you can view about a Token on hover.

2. Token Form
Right click on a Token Name and select Edit to view its properties as a form.
The Description input will be empty if no Description was entered.
If you have edit permissions, you can make changes to the Description by typing in the input. Be sure to save your changes using the bottom button when you are finished.

If you reference a Token with a Description as the Value in another Token, the Description does not get passed along. This allows you to write a unique description for each Token.

3. JSON File
Use the Token View Toggle see your Tokens written in JSON code files. If a Token has a Description it will appear as the last part of the code for that Token. If no Descriptions was entered, the code files will not include a description for that Token.

If you are comfortable working in code (and have edit permissions), you can edit Token Descriptions in the JSON view.
There are some nuances about editing Tokens in the JSON view to be aware of, documented in its guide.
JSON ViewIn Figma
Using the Plugin, when you Export a Token with a Description to Figma as a Style, the Description will be available for Designers to see in the Figma UI.
If you Import a Style from Figma into Tokens Studio, its Description will be automatically added to the Token that is created by the plugin.
The plugin does not yet support Descriptions for Variables.
→ Read Figma's guide on Descriptions for Styles for more details.
Transforming Tokens
Engineers typically transform Tokens used in code with Style Dictionary, which is tool-agnostic. Tokens coming from Tokens Studio require an additional step: @Tokens-studio/sd-transforms, an npm package that prepares Tokens for Style Dictionary.
While the description
of a Token is included in the DTCG Design Tokens Specifications as a plain text addition to a Design Token, we've included a specific transform in the generic sd-transforms package to convert the description
to a code comment
based on popular workflows of engineers in the community.
The SD-Transforms package's preprocessor will transform the TS Token Type to the Style Dictionary Type, as described in the table below.
→ SD-Transforms Read Me - ts/descriptionToComment
Resources
Mentioned in this doc:
SD-Transforms - Read Me
Style Dictionary - https://styledictionary.com/
Design Tokens Community Group - W3C Draft
Design Tokens Community Group - 5.2.1 Description
Figma Resources
Figma Learn - Add descriptions to styles, components, and variables
Community resources:
None yet!
💡 Something to share? Submit it here!
Known issues and bugs
Tokens Studio Plugin GitHub - Open issues for Token Descriptions
🐞 If you are experiencing an issue not listed here, please reach out to us on the Troubleshooting channel of our community Slack, submit it on our feedback tool, or send us an email [email protected]
Requests, roadmap and changelog
None Yet!
💌 Visit https://feedback.tokens.studio/ to contribute or subscribe to updates.

Last updated
Was this helpful?