Tokens Studio for Figma
  • Getting Started
    • Tokens Studio Plugin for Figma
    • Install the Figma Plugin
    • Pro Licence for the Figma Plugin
    • Join the Slack Community
    • Feature Requests - Featurebase
    • Changelog - Featurebase
  • Design Token Fundamentals
    • Intro to Design Tokens
      • Token Anatomy - Type
      • Token Anatomy - Value
      • Token Anatomy - Description
      • Token Anatomy - Name
  • Token Management
    • Token Types
      • Asset
      • Boolean
      • Border - Composite
      • Box Shadow - Composite
      • Color
        • Modified Colors (pro)
        • Gradient Colors
      • Dimension
        • Border Radius
        • Border Width
        • Sizing
        • Spacing
      • Number
      • Opacity
      • Other
      • Text (string)
      • Typography - Composite
        • Font Family
        • Font Weight
        • Font Fallbacks
        • Font Size
        • Line Height
        • Letter Spacing
        • Paragraph Indent
        • Paragraph Spacing
        • Text Case
        • Text Decoration
      • Composition (legacy)
    • Token Values
      • Token Values with References
      • Using Math in Token Values
    • Token Names
      • Token Name Technical Specs
      • Token Groups
      • Edit Token Names
    • Token Description
    • Token Sets
      • JSON View
  • Themes management
    • Themes (pro)
    • Themes that switch
  • Working in Figma
    • Variables and Tokens Studio
    • Styles and Tokens Studio
    • Export to Figma Guide
      • Export Options
      • Export Using Themes (pro)
      • Export Using Token Sets
      • Variables Skipped on Export
      • Styles with Variable References
    • Import from Figma Guide
      • Import Styles from Figma
      • Import Variables from Figma
        • Connect Themes to Imported Variables
        • Imported Variable Types and Token Types
    • Non-local Variables and Styles (pro)
    • Remove Tokens from Figma elements
    • Dev Mode in Figma
  • Settings Management
    • Plugin Settings
    • Base Font Size Setting
    • Token Format - W3C DTCG vs Legacy
  • Token Storage and Sync Integrations
    • Local Document - Figma File Token Storage
      • Figma Data Limits
    • Remote Token Storage Integrations
      • GitHub - Git Sync Provider
      • GitLab - Git Sync Provider
      • Bitbucket - Git Sync Provider
      • Azure DevOps - Git Sync Provider
      • JSONBin - Cloud Sync Provider
      • Supernova - Cloud Sync Provider
      • Tokens Studio Platform - Cloud Sync Provider
      • URL - Server Sync Provider
      • Generic Versioned Storage - Server Sync Provider
    • Multi-file Sync to Remote Storage (pro)
    • Manage Sync Providers
      • Edit Sync Provider
      • Change Active Sync Provider
      • Remove Sync Provider
    • Sync Changes to Remote Storage - Push and Pull
    • Branch Switching (pro) - Version Control
  • Inspect and Debug Tokens
    • Inspect Tokens
    • Remap Tokens
  • Transform Tokens for Development
    • Style Dictionary + SD Transforms
    • Official docs for Style Dictionary
  • Style Dictionary Playground
  • Troubleshooting
    • Reset Tokens from Dev Console
    • Tokens Studio Status
  • Open Source
    • Contribute
    • Shared Plugin Data
Powered by GitBook
On this page
  • Using Math in Token Values
  • Token Types compatible with math
  • Possible Values
  • Known limitations
  • Equations to try
  • W3C DTCG Token Format
  • Transforming Tokens
  • Resources

Was this helpful?

Edit on GitHub
Export as PDF
PreviousToken Values with ReferencesNextToken Names

Last updated 4 months ago

Was this helpful?

Using Math in Token Values

Tokens Studio supports math equations to calculate the Value of a Token.

This is a popular approach to a create scales for typography, spacing, size, or dynamically calculate the radius of a focus ring (pictured above).

Combining math equations with referenced to another Token can create a flexible and powerful design system.

Token Types compatible with math

All Token Types that accept numeric values can use math equations to calculate their value in Tokens Studio.

When you apply a Token with a math equation as its value, the Plugin applies the resolved value to the corresponding property in Figma.

Select a card to jump to its technical docs.

Number variables in Figma doesn't support Math equations

This means when you export a Token with math in its value as a Variable in Figma:

  • You won't see the references or equations.

  • The plugin sends the resolved value of the equation to Figma as a Number Variable.


Possible Values

Token Values written as equations can include hard-coded number values and references to other Tokens.

For example, if you want spacing.lg to be twice as large as spacing.md you can write an equation to calculate its value:

{spacing.md} * 2

Or, you can replace the multipler with a reference to another Token named scale.multiplier

{spacing.md} * {spacing.multipler}

Syntax

The syntax for writing a math equation varies based on the kind of equation you are writing.

Simple math equations can be written with or without brackets.

For example, 8 * 8 and (8 * 8) will both resolve to 64

Complex formulas require spaces between operators to ensure the Tokens can be transformed correctly using Style Dictionary.

For example: 8 * 8 will transform as expected 8*8 will not.

Looking for more complex formulas supported in the Plugin?


Known limitations

Working with math in the plugin can be a powerful workflow enhancement, but there are some limitations to be aware of.

Multi-value Tokens won't resolve

The plugin supports Tokens with more than one value. When these Tokens are referenced in a math equation, the plugin can not resolve the equation because it doesn't know how to interpret the value.

Units in equations

Referencing Tokens in our math equations that have values that contain units can lead to unexpected results.

This is because the math package we use can resolve equations with units, as long as the units aren't mixed.

For example:

  • A Token named size-2 with a value of 1.5rem

  • A Token named density-default with a value of 2px

When both Tokens are included in a math equation written as:

{size-2} + {density-default}

The equation can't be resolved because the Tokens referenced contain a mix of rem and pixel units. If both Tokens have the same units, or are unitless, the equation would resolve as expected.

Workarounds

  • lineHeights = {lineHeights-calc-body-default}%

  • fontSize = {scale-rem-md}rem


Equations to try

Here are some math equations used by our team.

Round to the nearest whole number

When using multipliers that aren't a whole number, you can use a rounding function to calculate values that don't include decimals, because a spacing value of 12.11px might not be ideal.

To round to the nearest whole number, you can put our equation inside the roundTo function.

For example, if sizing.sm has a value of 2

roundTo({sizing.sm} * 1.33, 0)

2 * 1.33 = 2.66

Will calculate a resolved value of 3

Create a percentage from a unitless number

For example, the Number Token called lineHeights-unitless.heading.relaxed with a value of 1.5 would be written in a Line Height Token as:

{lineHeights-unitless.heading.relaxed} * 100%

Which calculates a resolved value of 150%

Convert unitless numbers to rem

This equation requires having a Token which defines the value of 1 rem, and adjusting the Tokens Studio plugin settings to reference this Token as the value for "base font size".

In this example, there is a

  • Number Token called unitless-Token with a value of 48

  • Number Token called rem-base with a value of 16

A new Dimension Token is created with the value as an equation:

{unitless-Token} / {rem-base} * 1rem

Which calculates a resolved value of 3rem


W3C DTCG Token Format

Tokens Studio has included this feature in the plugin to help design system maintainers work more efficiently.


Transforming Tokens

When transforming Tokens with Math in their Values, there are specific configurations to be aware of.

Token Values entered with math equations need to be checked and resolved.

Token Values entered as a number without a unit converted to a number with pixels as a unit.


Resources

Tokens Studio uses the JavaScript Expression Evaluator for the implementation of math in token values.

Mentioned in this doc:

Community resources:

  • Sam I am Designs has a written guide and Figma community file featuring many of the math equations mentioned above.

Known issues and bugs

  • None yet

Requests, roadmap and changelog

Here's the docs for under the hood.

For example, a with 2,4 as its value represents spacing on top/bottom and right/left.

One method is to create your math equations using the or Types which don't require a unit, and add them in later.

For example, you could create a sizing scale using then add the required unit when it is referenced in a .

In Figma, the only option for a , but your engineers might prefer the Token defined as a unitless number.

In this case, you can create a unitless Number Token with the preferred value, and write an equation in the to convert it to a percentage so it works well with Figma.

At the time of writing this doc, Math as a Token value is not mentioned in for Design Tokens.

→

→

Having trouble with Math equations not resolving properly? Check your syntax!

nmp -

SD-Transforms -

Style Dictionary -

Design Tokens Community Group -

Tokens Studio Plugin GitHub -

Math in token value enhancements -

the math package used
Other
Number Token
Typography Token
responsive line-height value is in percentage
→ Jump to the guide on Base Font Size Settings
the most recent Design Tokens Community Group W3C specifications
SD-Transforms Read-Me Doc, ts/resolveMath
SD-Transforms Read-Me Doc, ts/size/px
JavaScript Expression Evaluator
Read Me
Read Me
W3C Draft
Sam's Fancy Math Equations in Tokens Studio
Open issues for Token Values Math
Feature Request
↑ Spaces are required between operators as described above.
Spacing Token
Typography Composite Token
Page cover image
Cover

Dimension

Cover

Number

Cover

Spacing

Cover

Sizing

Cover

Border Width

Cover

Border Radius

Cover

Font Size

Cover

Line Height

Cover

Letter Spacing

💡 Something to share?

💡 Something to share?

Submit it here!
Submit it here!

🐞 If you are experiencing an issue not listed here, please reach out to us on the Troubleshooting channel of our , , or send us an email support@tokens.studio

community Slack
submit it on our feedback tool

Engineers typically transform Tokens used in code with , which is tool-agnostic. Tokens coming from Tokens Studio require an additional step: , an npm package that prepares Tokens for Style Dictionary.

Style Dictionary
@Tokens-studio/sd-transforms

💌 Visit to contribute or subscribe to updates.

https://feedback.tokens.studio/