How it works
Design and Engineering maintainers collaborate together to define design tokens in JSON format. Designers can make use of Tokens Studio if they prefer it over editing files directly.
Once a new version is ready, we run Style Dictionary, which buids and translates the JSON into any format we need. Teams then get notified about upgraded packages they can use as dependencies in their project.
We also import and upgrade design tokens to this site and our Storybook for documentation purposes.
Expressions and references
We usually try to define tokens in their unresolved state, meaning we try to include how we came to said value. This makes our visual language more understandable and easier to maintain, storing design decisions forever as small piece of code.
Referenced token
In example below, we define a spacing token as expression using decisions we’ve already made on global level - we want spacing to always start from the default value (base), and want to interact with current information density (factor). So, maintainers define this token as:
Create a variable called spacing.2.
Link it to spacing.base, which is our global spacing grid value of 1rem.
Take into account the current information density that’s stored as spacing.factor.
Make the spacing.2 12.5% of the base value.
{
"density": {
"spacing": {
"2": {
"$type": "dimension",
"$value": "({density.spacing.base} * {density.spacing.factor}) * 0.125"
}
}
}
}
Example of token that uses expression and references.
As user, you don’t need to keep track of references and expressions. You’ll simply see variable name and resolved value, for example:
//Our design tokens//
--pb-spacing-2: "2px";
//Button properties//
.container {
padding: var(--pb-spacing-2);
}