Page cover image

Number - Token Type

Number Tokens define the numeric value of several design properties that don't require a unit of measurement.

The primary difference between a Number Token and a Dimension Token is a unit of measurement.

  • Number tokens are intended to be unitless.

    • For example: 4

  • Dimension Tokens are required to have a unit of pixels or rem.

    • For example: 4px

Creating a new Number Token in the Tokens Studio Plugin for Figma.

Design decisions

The Number Token is used for design decisions with a numeric value that doesn't benefit from a unit of measurement. For example:

  • Math equations to create scales

  • A -90 degree rotation of an image filling the background of a hero section of a website.

Number Tokens can define these design properties in Figma; however, many of these properties benefit from a unit of measurement, and a Dimension Token is preferred:

  • rotation

  • background blur

  • absolute position location

  • size (Dimension Token preferred)

  • space (Dimension Token preferred)

  • border-radius and width (Dimension Token preferred)

Jump to the Dimension Token technical docs by selecting the card below.

Dimension


Possible values

According to the W3C DTCG specification, the value of a Number Token must be a unitless number.

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

Jump to the guide on Tokens with Math Values by selecting the card below to learn more.

Using Math in Token Values

Hard-coded values

The syntax used to write numeric values for Number Tokens is important.

Values that reference another Token

When trying to reference another Token as the Value for a Number Token, you will see Tokens in the dropdown list that are:

  • Living in Token Sets that are currently active.

    • In the left menu on the plugin's Tokens page, a checkmark is visible next to the Token Set name.

  • Token Type is compatible:

    • The same = number

However, like all Token Types, you can "force" a reference by manually entering the Token Name between curly brackets.

For example {token.name.here}

The value will show a broken reference until the originating Token Set is marked as enabled.

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

Token Values with References

Compatible Token Types

After you've created Number Tokens, they can be referenced in another Number Token and several compatible Token Types.

See all Token Types compatible with Number Tokens

Typography - Composite

Font Size

Paragraph Spacing

Border - Composite

Color Tokens with Reduced opacity (transparency)

You can also reference a Number Token in these additional Token Types; however, they are not recognized in the W3C DTCG specifications as official Token Types, more details below .

Spacing

Sizing

Border Radius

Border Width


Apply Number Tokens

A Number Token can define the numeric value of several design properties when applied to frames, groups or graphic elements in Figma.

With one or more elements selected in Figma, right-click on the Number Token Name in the Plugin to see the design property options.

Select your desired design property by clicking on it to apply the Tokens value instantly.

If you click to apply this Token to an element without accessing the right-click Token menu, the value will be applied as a spacing-gap property.

The right-click menu and sub-menus of a Number Token are opened to reveal the design properties it can be applied to in Figma.

1. Spacing

The spacing property defines the distance between layers of an auto-layout frame in Figma when the Number Token is applied.

1

Gap

Apply the Token value to the space between child elements within an auto-layout frame.

2

All

Apply the Token value to padding on all sides of the parent container, and the space between child elements within an auto-layout frame.

3

Horizontal padding

Apply the Token value to the space between the border and child elements on the left and right sides an auto-layout frame.

4

Vertical padding

Apply the Token value to the space between the border and child elements on the top and bottom sides an auto-layout frame.

5

Row Gap

Apply the Token value to the space between rows of child elements in auto-layout frames set to wrap.

6

Top

Apply the Token value to padding on the highest side of an auto-layout frame on the X-axis only.

7

Apply the Token value to padding on the right side of an auto-layout frame on the y-axis only.

8

Bottom

Apply the Token value to padding on the lowest side of an auto-layout frame on the X-axis only.

9

Left

Apply the Token value to padding on the left side of an auto-layout frame on the y-axis only.

For independent styling per side, you can repeat the steps above and apply different Number Tokens to each position of the same design element.

If you apply the Token to a frame before auto-layout is applied in Figma, you may have to remove and re-apply the Token after auto-layout has been enabled for the Token Value to apply as expected.

Read Figma's doc on Autolayout here

2. Sizing

The Sizing property defines the width or height of polygonal shape, frames, groups or graphic elements in Figma when the Number Token is applied.

1

All

Apply the Token value to the horizontal and vertical size of the design element.

2

Width

Apply the Token value to the horizontal size of the design element only.

3

Height

Apply the Token value to the vertical size of the design element only.

4

Min Width

Apply the Token value to set the smallest allowed horizontal size of an auto-layout frame.

5

Max Width

Apply the Token value to set the largest allowed horizontal size of an auto-layout frame.

6

Min Height

Apply the Token value to set the smallest allowed vertical size of an auto-layout frame.

7

Max Height

Apply the Token value to set the largest allowed vertical size of an auto-layout frame.

For independent styling per side, you can repeat the steps above and apply different Number Tokens to each position of the same design element.

If you apply the Token as Min/Max Width or Height to a frame before auto-layout is applied in Figma, you may have to remove and re-apply the Token after auto-layout has been enabled for the Token Value to apply as expected.

Read Figma's doc on Autolayout here

3. Border Radius

The Border Radius property defines the corner roundness of polygonal shape, frames, groups or graphic elements in Figma when the Token is applied.

1

All

Apply the Token value to the roundness of all corners of the selected design element.

2

Top left

Apply the Token value to the roundness of the corner on the left highest side of the element on the X-axis only.

3

Top right

Apply the Token value to the roundness of the corner on the right highest side of the element on the X-axis only.

4

Bottom right

Apply the Token value to the roundness of the corner on the left lowest side of the element on the X-axis only.

5

Bottom left

Apply the Token value to the roundness of the corner on the right lowest side of the element on the X-axis only.

For independent corner styling, you can repeat the steps above and apply different Number Tokens to each corner position of the same design element.

4. Border Width

A Border Width property defines the thickness of the stroke applied to text layers, polygonal shapes, frames, groups or graphic elements in Figma when the Number Token is applied.

1

All

Apply the Token value to the roundness of all corners of the selected design element.

2

Top left

Apply the Token value to the roundness of the corner on the left highest side of the element on the X-axis only.

3

Top right

Apply the Token value to the roundness of the corner on the right highest side of the element on the X-axis only.

4

Bottom right

Apply the Token value to the roundness of the corner on the left lowest side of the element on the X-axis only.

5

Bottom left

Apply the Token value to the roundness of the corner on the right lowest side of the element on the X-axis only.

For independent border styling, you can repeat the steps above and apply different Number Tokens to each side of the same design element.

If you apply the Border Width property to an element before a stroke is applied in Figma, you may have to remove and re-apply the Dimension Token after the stroke has been enabled for the value to apply as expected.

The plugin supports a Border Composite Token that allows you to reference a Border Width Token to avoid this issue.

5. Background Blur

The Background Blur property of the Number Token defines the intensity of the Layer Blur Effect in Figma when the Token is applied in Figma.

Read Figma's doc on Layer blur here

The Background Blur property must be applied to container design elements, like frames, groups, and polygonal shapes with a reduced opacity color fill applied.

→ Jump to the guide on Color Tokens to learn about reduced opacity colors using color spaces that support alpha.

This property can't yet be Exported to Figma as a reusable Effect Style from the plugin in the same way that Box Shadow Tokens can.

6. X and Y Position

The x position and y position properties of the Number Token define the absolute position of the design element when the Token is applied in Figma.

X Position

  • The element is absolutely positioned on the horizontal axis in relationship to the parent container.

  • If no parent container is present, it positions the element on the Figma canvas.

Y Postion

  • The element is absolutely positioned on the vertical axis in relationship to the parent container.

  • If no parent container is present, it positions the element on the Figma canvas.

If you apply the x/y property to an element before enabling Absolute Position and Auto-layout in Figma, you may have to remove and re-apply the Dimension Token after they are enabled before the value will be applied as expected.

→ Read Figma's docs on Absolute Position

7. Rotation

The rotation property defines the numeric degree of rotation on its access when the Number Token is applied to any design element in Figma.

This means you can assign negative values to control the direction of rotation.

Read Figma's docs on Rotation here

Once a Token has been applied, it will remain attached until you manually remove it.


W3C DTCG Token Format

Number is an official Token type in the W3C Design Token Community Group specifications.

"Represents a number. Numbers can be positive, negative and have fractions. Example uses for number Tokens are gradient stop positions or unitless line heights. The $type property MUST be set to the string number. The value MUST be a JSON number value." - 8.7 Number, DTCG Specifications on W3C

Tokens Studio has approached Number Tokens differently than how it is defined in the current W3C spec to align with Figma's number variables more closely.

However, we will be iterating on Number Tokens in the near future to more closely align with the W3C DTCG specifications.

  • We allow a unit in a Number Token (this will change).

  • We allow a Number Token to be used with many of the same properties the specification defines as requiring a Dimension Token.

  • We don't yet require a Number Token in all use cases the spec defines it as a requirement, such as a "gradient stop position."

Number Tokens are a relatively new addition to the W3C DTCG specification, which defines this Token as being applied to many different design properties.

If we want to fully align with the spec, it requires Tokens Studio to phase out several unofficial Token we introduced long before the Number Token was added to the spec:

SpacingSizingBorder RadiusBorder Width

There is no immediate plan to discontinue support of unofficial Token Types.

We want to build a thoughtful solution to help Tokens Studio users migrate from these 'unofficial Token Types' to Dimension Tokens if that time comes.

Conversation forum on Unofficial Token Types is here.


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.

When transforming Number Tokens, there are specific configurations to be aware of.

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

SD-Transforms Read-Me Doc, ts/size/px

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

SD-Transforms Read-Me Doc, ts/resolveMath

Running the SD-Transforms pre-processor as part of the generic package will prep your Number Tokens for Style Dictionary.

SD-Transforms Read-Me Doc, Using the preprocessor


Resources

Mentioned in this doc:

Figma resources:

CSS resources:

Community resources:

  • None yet!

💡 Something to share? Submit it here!

Known issues and bugs

Tokens Studio Plugin GitHub - Open issues for Token Type Number

  • None yet

🐞 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

💌 Visit https://feedback.tokens.studio/ to contribute or subscribe to updates.

Last updated

Was this helpful?