Border - Composite Token Type
Add visual separation to design elements by composing several stroke-related design decisions as a single Border Token.
Each design decision (color, border width, and stroke style) that is a part of the Composite Token is referred to as a property of the Border Token in our guides.

Design decisions
The Border Token defines the stroke styling properties for containers, text elements, and polygonal shapes.
The properties within the Border Token closely align with the border
property in CSS.
Each property composed to create the Border can be defined as it's own Token and referenced within the Border Composite Token:
Color
Border Width
Stroke Style
Possible values
Like all Composite Tokens, you define the value of each property individually.
When you create the Border Token in the plugin, you can reference each Token you've already created as a property or enter a hard-coded value.
Hard coded values
The dedicated Token Type of each property within the Border Composite Token has unique specifications, described in detail in their own technical docs.
Border color
Border Color defines a solid, reduced opacity, or modified color value written in any color space supported by a Color Token.
You can also use the color picker to create the value by selecting the swatch to the left of the input.
Border Width
Border width defines the thickness of a stroke around a design element and accepts numeric values, ideally with a unit of measure.
For example 1px
Stroke Style
Stroke Style defines the line shape. It's value is written as a string depending on your desired style.
solid
creates a continuous line.
dashed
creates a line of many small sections.
You can adjust the fine-grained settings for the dash using the Figma UI as there currently isn't a Token Specification for it.
Tokens Studio does not have a dedicated Token Type for Stroke Style at this time.
Values that reference another Token
Like all Composite Tokens, you may reference an existing Token as the value for each individual property, as described above ↑.
If you'd prefer to reference an existing Border Composite Token as the value instead of defining each Property, select the Token's Reference mode button (2x2 circle icon).

When trying to reference another Token as the Value for a Border Token, you will see:
Tokens 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:
border
However, like all Token Types, you can "force" a reference by manually entering the Token Name between curly brackets.
For example {token.name.here}
Jump to the guide on Token Values with References by selecting the card below to learn more.
Token Values with ReferencesApply Border Tokens
A Border Token defines the stroke styling of text, polygonal shape, frames, groups or graphic elements in Figma when the Token is applied.
You can apply a Border Token to all sides of the design element at once, or each side independently.
With one or more elements selected in Figma, right-click on the Border Token Name in the Plugin to its options.
Select your desired design property by clicking on it to apply the Tokens value instantly.

For independent border styling, you can repeat the steps above and apply different Border Tokens to each side of the same design element.
Once a Token has been applied, it will remain attached until you manually remove it.
W3C DTCG Token Format
border
is an official token type in the in the W3C Design Token Community Group specifications. 9.3 Border
Tokens Studio has approached our Border Token differently than how it is defined in the current W3C spec:
We allow the
borderWidth
property to be anumber
ordimension
Token Type where the spec defines onlydimension
.We allow unitless numbers where the spec defines a
dimension property
which must include a unit.
The spec allows for a dedicated
borderStyle
Token Type, which we do not yet support.
As we move towards more closely aligning with the W3C DTCG specifications, we may adjust the Border Composite Token in the future.
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 Border Tokens, which are Composite Tokens, there are specific configurations to be aware of.
Composite Tokens require the SD-Transforms option to expand composite Tokens into multiple Tokens
.
Make sure you look at the generic SD-Transforms package to include this option, which allows you to further customize this transformation further using Style Dictionary.
→ SD-Transforms Read-Me Doc, Using the preprocessor → SD-Transforms Read-Me Doc, Using Expand
If the borderWidth
property is entered as a number without a unit, the ts/size/pxx transform will convert the value to a number with pixels as a unit.
→ SD-Transforms Read-Me Doc, ts/size/px
Resources
Mentioned in this doc:
SD-Transforms - Read Me
Style Dictionary - https://styledictionary.com/
Design Tokens Community Group - W3C Draft
Design Tokens Community Group - 9.3 Border
Figma resources:
Design in Figma - Apply and adjust stroke properties
CSS resources:
MDN Web Docs - border
Community resources:
None yet!
💡 Something to share? Submit it here!
Known issues and bugs
Tokens Studio Plugin GitHub - Open Issues for Token Type Border
Caps For Dashed Value in Border Composite Token Does Not Work #2975
The string value
Dashed
orDASHED
does not work as expected, onlydashed
is accepted.
Separated borders override colors #2236
Applying independent borders with different colors does not work as expected.
🐞 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
V2 release - Variables in Stroke Weight and Opacity
💌 Visit https://feedback.tokens.studio/ to contribute or subscribe to updates.

Last updated
Was this helpful?