Dimension - Token Type
Dimension Tokens define the size, space, radius, or position of a design element as a numeric value with 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
orrem
.For example:
4px

Design decisions
The Dimension Token is used for design decisions requiring a distance and unit of measurement for a specific property of a design element.
This doesn't match the CSS definition for Dimension, which focuses on distance, durations, frequencies, and resolutions.
Many of the properties supported by this token are individually defined in CSS.
Dimension Tokens can be used to define these design properties in Figma:
size
space
border-radius and width
absolute position location
background blur effects
This is a great way to define tokens that might be used in various use cases, such as a sizing scale applied to text elements, icons, and containers.
Dimension Tokens support responsive and static design properties:
Responsive - value in rem units
Example:
2rem
applied as a min-height property on an auto-layout frame applies a 32px min-height value to the frame
Static - value in pixels
Example
32px
applied as border-radius rounds the corner of a frame to 32px
Possible values
According to the W3C DTCG specification, the value of a Dimension Token must include a numeric value and a unit of measure, either Pixels (px) or Rems (rem).
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 ValuesHard-coded values
The syntax used to write numeric values for Dimension Tokens is important.
Be sure to avoid any spaces between numbers and units of measurement.
Units are always written in lowercase.
Dimension Tokens require a number and a unit of measurement without any spaces as the value. For example:
16px
1rem
Avoid between the number and the unit. For example:
16 px
1 rem
Unitless numbers are not allowed. For example:
16
Negative numbers are supported but may not apply to all design properties.
For example, -4px
would work for a spacing
property but not as a border radius
property.
Rem units (rem)
To support responsive design, you can define your Dimension Token in rem units, and the plugin automatically converts the value to the pixel equivalent when applying the Token in Figma.
For example, a Dimension Token with a value of 1rem
, when applied as a will appear as 16px
in Figma.
Rem Units act as a multiplier of the base font size, so when a user changes their preferences to a larger font size or uses a zoom feature in your product, elements defined in rem units will respond accordingly.
The value of 1rem
can be configured in the plugin settings for Base Font Size.
Pixel units (px)
When you have design elements that should remain static even when users change their preferences, the Dimension Token value can be defined in pixel units.
4px
Units not supported
The plugin only supports Dimension Tokens in pixels or rem units, to align with the W3C DTCG specification.
We do not support:
percentage (%)
em units
Values that reference another Token
When trying to reference another Token as the Value for a Dimension 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 =
dimension
However, like all Token Types, you can "force" a reference by manually entering the Token Name between curly brackets.
For example, if you want to reference a Number Token without a unit, you can force the reference by adding the token name, followed by the required unit for a Dimension Token.
{unitless.number}px
Select the card below to jump to the technical docs for more information.
Token Values with ReferencesCompatible Token Types
After you've created Number Tokens, they can be referenced in another Number Token and several compatible Token Types.
Apply Dimension Tokens
A Dimension Token can define the numeric value and unit of measurement 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 Dimension 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.

1. Spacing

The spacing property defines the distance between layers of an auto-layout frame in Figma when the Dimension Token is applied.
For independent styling per side, you can repeat the steps above and apply different Dimension Tokens to each position of the same design element.
2. Sizing

The Sizing property defines the width or height of polygonal shape, frames, groups or graphic elements in Figma when the Dimension Token is applied.
For independent styling per side, you can repeat the steps above and apply different Dimension Tokens to each position of the same design element.
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.
For independent corner styling, you can repeat the steps above and apply different Dimension 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 Dimension Token is applied.
For independent border styling, you can repeat the steps above and apply different Dimension Tokens to each side of the same design element.
5. Background blur
The Background Blur property of the Dimension 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.
6. X and Y Position
The x position and y position properties of the Dimension 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.
Once a Token has been applied, it will remain attached until you manually remove it.
W3C DTCG Token Format
Dimension is an official token type in the W3C Design Token Community Group specifications (8.2 Dimensions).
Dimension 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 the following unofficial Token Types, which we introduced long before the Dimension Token was added to the spec:
SpacingSizingBorder RadiusBorder WidthTransforming 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 Dimension 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 Dimension Tokens for Style Dictionary.
→ SD-Transforms Read-Me Doc, Using the preprocessor
Resources
Mentioned in this doc:
SD-Transforms - Read Me
Style Dictionary - https://styledictionary.com/
Design Tokens Community Group - W3C Draft
Design Tokens Community Group - 8.2 Dimension
Figma resources:
Design in Figma - Explore autolayout properties
Design in Figma - Apply and adjust stroke properties
Design in Figma - Adjust corner radius and smoothing
Design in Figma - Adjust alignment, rotation, and position
Design in Figma - Apply blur effect
CSS resources:
MDN Web Docs - Dimension
Community resources:
None yet!
💡 Something to share? Submit it here!
Known issues and bugs
Tokens Studio Plugin GitHub - Open issues for Token Type Dimension
Background blur > Figma values changed - Community Post on Featurebase
Figma is natively halving/doubling their background blur effect values, creating a disconnect between tokens managed by Token Studio and any parsed output.
Known CSS quirk which can be solved with a custom Style Dictionary transform
🐞 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?