Token Values in Tokens Studio

The value of a Design Token defines what the design decision is and, in some cases, where the decision came from.

You might recall from our Intro to Design Tokens Guide that the Token Type determines what values are acceptable.

For example, a hard-coded Value of #22c55e is possible when the Token Type is color, but not when it is fontFamily.

In this infographic, the Token examples on the right side highlight the Value. The top code block shows a hard-coded value. The bottom code block has a value that references another Token.

Each of the 24 unique Token Types supported Tokens Studio has its own specifications on what values are allowed.

Before you jump into Token Types, here's an overview of the terms and capabilities of Token Values you'll see across our guides.

Once you understand whats possible you'll be able to craft Token Values that will help you work smarter, scale faster, and manage less components.

---

Common terms

These terms are not the only way to describe Token Values; they are the labels the Tokens Studio team uses for simplicity across our documentation.

If your team uses different descriptive terms, that's totally okay!

Hard-coded value

When you write a Token with an exact value that doesn't require any work from a tool to interpret it, we call that a hard-coded value.

For example, #22c55e is a hard-coded hex-code value for a Color Token.

Each Token Type has different specifications about what kind of hard-coded value is allowed based on its properties which are defined in the W3C specifications for Design Tokens, managed by the Design Tokens Community Group (DTCG).

For example, the hard-coded string value accepted for a Color Token is different from a Font Family Token.

An infographic example of documenting a Token applied to the text layer of a button label requiring different values depending on the defined Token Type.

Here are some additional terms related to hard-coded values that might be helpful:

Numeric Value

A numeric value includes numbers.

For example, the Opacity Token accepts0.33 as a numeric value.

Alphanumeric Value

An alphanumeric value includes numbers and letters that are not defined.

For example, the Text Token accepts Welcome back {name}as an alphanumeric value.

String Value

A string value includes letters and/or numbers that are defined in a particular way.

For example, the Text Decoration Token accepts underline as a string value.

Syntax

Syntax is the way you write the value of the Token. The requirements for syntax change depending on the type of value and Token Type.

For example, spaces are to be avoided when writing the value of a Dimension Token which requires a unit 16px, but required between operators of a math equation 8 * 4

Unit

Unit is short for unit of measurement. Some numeric values require a unit, but not all.

For example 4px

Most popular units when working with Tokens are:

• pixels px

• rem rem

• percentage %

References or Alias Tokens

When you write a Token with a value including the name of another Token wrapped in curly brackets, we call that a reference, some folks call it an alias.

For example, {colors.green.dark.1200}

Working with References is one of the main advantages of working with Design Tokens!

→ Jump to the Token Values with References Guide for more details.

An infographic example of documenting a Color Token applied to the text layer of a button label. The Value of the Token directly applied is referencing another Token. Following the pathway of referenced Tokens as Values shows where the Color comes from in the system.

Math

You can write the value of your Token to include a math equation.

For example, to calculate a border radius of a focus ring the value of your Token could be

{button.border-radis} + {focus.offset}

Working with Math to calculate Token Values is a powerful feature supported by Tokens Studio.

→ Jump to the Using Math in Token Values guide for more details.

Raw Value

The exact value as it is written, which could show referenced tokens, math equations, etc. is called the Raw Value.

For example

• {green-500} is the raw value of a Token with a reference to another Token.

• #22c55e is the raw value of a Token with a hard-coded value.

Resolved Value

The final value of the Token which may be a result of inheriting its value from another Token, or calculating its value from a math equation is called the Resolved Value.

For example

• A Token with a math equation as its raw value of 16 + 4 would have a resolved value of 20

• A Token named green-500 with a raw value that is hard-coded as #22c55e would have the same resolved value #22c55e

• A Token named success-default with a raw value referencing the {green-500} would have a resolved value of #22c55e

Test your Token Value knowledge

Take a look at the image below showing the color Tokens applied to a button label and see if you can identify:

1. Which Tokens have a hard-coded value?

2. Which Tokens are referencing another in its value?

3. What is the raw value of each token?

4. What is the resolved value of each token?

Hints if you need them

In the image below, the text color of the button changes when the value of the middle Token is changed to reference a greycolor instead of green .

• The name of the Token is on the top line.

• The raw value is below the name.

• The resolved value is inside the color swatch.

An infographic example of documenting a Color Token applied to the text layer of a button label. The difference between the two buttons is the color of the label text which is controlled by the value of the middle Token. On the left side, it is referencing a Token from a greenscale. On the right right, it is referencing a Token from a greyscale.

---

Working with Token Values

From the Tokens Page of the Tokens Studio Plugin for Figma, there are three places to see the value of a Token.

1. Token data on hover

2. Token form

3. JSON file

1. Token Data on Hover

Hover on an existing Token to view its data. The value appears as the second piece of data in the list under the Token Name.

Each Token will have different data to view on Hover depending on its type and value, however the position the data remains the same.

If the value of the Token is hard-coded, it will appear as entered.

From the Tokens Page of the Plugin, hovering on a Color Token displays its data. In this example, the hard-coded value of a hex code is shown under the Token Name.

If the Value references another Token, the raw value appears on the left, the resolved value on the right.

From the Tokens Page of the Plugin, hovering on a Color Token displays its data. In this example, the raw value of a reference to a Token is shown under the Token Name. The resolved value it inherits from the Token being referenced appears on the right side.

2. Token Form

Right click on a Token Name and select Edit to view its properties as a form. The second input displays the raw value.

The Token Form for each Token Type is unique, but value always appears as the second input.

Right-click on a Color Token to open its Form. The example on the right shows the raw value of the Color Token as a hard-coded hex code.

If the Token has a value with a math equation or references another Token, the resolved value appears below the input.

A Color Token form on the left shows a raw value with references to another Token. A Dimension Token form on the right shows a raw value with a math equation. Both forms show the resolved values below the Value input.

If you have edit permissions, you can make changes to the Value using the input. Be sure to save your changes using the bottom button when you are finished.

3. JSON File

Use the Token View Toggle see your Tokens written in JSON code files.

The raw value will appear in the code file. The resolved values are not shown in the JSON view.

Select the JSON view toggle from the Tokens Page to see the current Token Set as an editable code file. The raw value of the Token is shown in the JSON files.

If you are comfortable working in code (and have edit permissions), you can edit Token Values in the JSON view.

The JSON view functions similar to Visual Studio Code thanks to an amazing open-source contribution from a Tokens Studio community member. 🫶

Jump to the guide on JSON view for more details by selecting the card below.

JSON View

---

Resolved value inheritance

Recall that Token Names within each Token Set must be unique. Token Names in different Token Sets can be identical, which provides the basis of Theming.

If you have more than one enabled Token Set with the same Token Names, how does the plugin know which resolved Value it should inherit?

1. The status of Token Sets

2. The position of Token Sets

The plugin considers all Token Sets when inheriting the value from a Token being referenced.

• Token Sets with an enabled status are preferred, then sourcethen disabledis last.

• If there is more than one Token Set with the same status, the Token Set in the lowest position will `win`.

In the example below, the Color Tokens are inheriting their value from the theme-colorTokens being referenced as their raw value. The resolved values change based on the position of the themeToken Sets. Whichever Token Set is lowest in the list on the left passes it's value.

Component-specific Tokens with values that reference Tokens from the Theme Token Sets are shown. The resolved values change based on the position of the Theme Token Sets.

Jump to the guide on Token Values with References for more details by selecting the card below.

Token Values with References

---

In Figma

When you apply a Token to a design element in Figma, the resolved value is applied to your chosen design property and displayed in Figma's UI. Each Token Type has different options that map to corresponding properties in Figma.

When you export your Tokens as Styles or Variables, the resolved value is reflected in the matching Style or Variable.

If you are using values that aren't suppored by Figma, the plugin does all the work under the hood to convert them to something Figma can use. These nuances are described in detail in the guides for each Token Type.

Token Types

---

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.

Each Token Type has specific Transforms to be aware of that ensure accurate resolved values that are usable in code.

Token Types

---

Resources

Mentioned in this doc:

• SD-Transforms - Read Me

• Style Dictionary - Read Me

• Design Tokens Community Group - W3C Draft

• Design Tokens Community Group - 3.8 Reference Alias

Community resources:

• None yet!

💡 Something to share? Submit it here!

Known issues and bugs

Tokens Studio Plugin GitHub - Open issues for Token Values

Tokens Studio Plugin GitHub - Open issues for String Values

🐞 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.