npm install @csstools/postcss-design-tokens --save-dev
PostCSS Design Tokens lets you use design tokens in your CSS source files.
{
"color": {
"background": {
"primary": { "value": "#fff" }
}
},
"size": {
"spacing": {
"small": { "value": "16px" },
"medium": { "value": "18px" },
"medium-alias": { "value": "{size.spacing.medium}" }
}
},
"viewport": {
"medium": { "value": "35rem" }
}
}
@design-tokens url('./tokens.json') format('style-dictionary3');
.foo {
color: design-token('color.background.primary');
padding-top: design-token('size.spacing.small');
padding-left: design-token('size.spacing.small' to px);
padding-bottom: design-token('size.spacing.small' to rem);
}
@media (min-width: design-token('viewport.medium')) {
.foo {
padding-bottom: design-token('size.spacing.medium-alias' to rem);
}
}
/* becomes */
.foo {
color: #fff;
padding-top: 16px;
padding-left: 16px;
padding-bottom: 1rem;
}
@media (min-width: 35rem) {
.foo {
padding-bottom: 1.125rem;
}
}
Add PostCSS Design Tokens to your project:
npm install postcss @csstools/postcss-design-tokens --save-dev
Use it as a PostCSS plugin:
const postcss = require('postcss');
const postcssDesignTokens = require('@csstools/postcss-design-tokens');
postcss([
postcssDesignTokens(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
At this time there is no standardized format for design tokens. Although there is an ongoing effort to create this, we feel it is still too early to adopt this.
For the moment we only support Style Dictionary.
Use style-dictionary3
in @design-tokens
rules to pick this format.
The is
option determines which design tokens are used.
This allows you to generate multiple themed stylesheets
by running PostCSS multiple times with different configurations.
By default only @design-tokens
without any when('foo')
conditions are used.
This plugin itself does not produce multiple outputs, it only provides an API to change the output.
For these two token files :
{
"color": {
"background": {
"primary": { "value": "#0ff" }
}
}
}
{
"color": {
"background": {
"primary": { "value": "#f0f" }
}
}
}
And this CSS :
@design-tokens url('./tokens-brand-1.json') format('style-dictionary3');
@design-tokens url('./tokens-brand-2.json') when('brand-2') format('style-dictionary3');
.foo {
color: design-token('color.background.primary');
}
You can configure :
postcssDesignTokens()
@design-tokens url('./tokens-brand-1.json') format('style-dictionary3');
@design-tokens url('./tokens-brand-2.json') when('brand-2') format('style-dictionary3');
.foo {
color: design-token('color.background.primary');
}
/* becomes */
.foo {
color: #0ff;
}
postcssDesignTokens({ is: ['brand-2'] })
@design-tokens url('./tokens-brand-1.json') format('style-dictionary3');
@design-tokens url('./tokens-brand-2.json') when('brand-2') format('style-dictionary3');
.foo {
color: design-token('color.background.primary');
}
/* becomes */
.foo {
color: #f0f;
}
The unitsAndValues
option allows you to control some aspects of how design values are converted to CSS.
rem
<-> px
for example can only be calculated when we know the root font size.
defaults to 16
postcssDesignTokens({
unitsAndValues: {
rootFontSize: 20,
},
})
@design-tokens url('./tokens.json') format('style-dictionary3');
.foo {
color: design-token('color.background.primary');
padding-top: design-token('size.spacing.small');
padding-left: design-token('size.spacing.small' to px);
padding-bottom: design-token('size.spacing.small' to rem);
}
@media (min-width: design-token('viewport.medium')) {
.foo {
padding-bottom: design-token('size.spacing.medium-alias' to rem);
}
}
/* becomes */
.foo {
color: #fff;
padding-top: 16px;
padding-left: 16px;
padding-bottom: 0.8rem;
}
@media (min-width: 35rem) {
.foo {
padding-bottom: 0.9rem;
}
}
The importAtRuleName
option allows you to set a custom alias for @design-tokens
.
postcssDesignTokens({ importAtRuleName: 'tokens' })
@tokens url('./tokens.json') format('style-dictionary3');
.foo {
color: design-token('color.background.primary');
padding-top: design-token('size.spacing.small');
padding-left: design-token('size.spacing.small' to px);
padding-bottom: design-token('size.spacing.small' to rem);
}
/* becomes */
.foo {
color: #fff;
padding-top: 16px;
padding-left: 16px;
padding-bottom: 1rem;
}
The valueFunctionName
option allows you to set a custom alias for design-token
.
postcssDesignTokens({ valueFunctionName: 'token' })
@design-tokens url('./tokens.json') format('style-dictionary3');
.foo {
color: token('color.background.primary');
padding-top: token('size.spacing.small');
padding-left: token('size.spacing.small' to px);
padding-bottom: token('size.spacing.small' to rem);
}
/* becomes */
.foo {
color: #fff;
padding-top: 16px;
padding-left: 16px;
padding-bottom: 1rem;
}
PostCSS Design Tokens is non-standard and is not part of any official CSS Specification.
This is all very new and we hope that one day design tokens will become first class citizens in editors and other tools. Until then we will do our best to provide extensions. These will have rough edges but should illustrate were we want to go.
editor | plugin |
---|---|
VSCode | CSSTools Design Tokens |
The @design-tokens
rule is used to import design tokens from a JSON file into your CSS.
@design-tokens url('./tokens.json') format('style-dictionary3');
@design-tokens url('./tokens.json') format('style-dictionary3');
@design-tokens url('./tokens-dark-mode.json') format('style-dictionary3') when('dark');
You can also import tokens from an npm
package:
@design-tokens url('node_modules:my-npm-package/tokens.json') format('style-dictionary3');
@design-tokens url('node_modules:my-npm-package/tokens-dark-mode.json') format('style-dictionary3') when('dark');
@design-tokens [ <url> | <string> ]
[ when(<theme-condition>*) ]?
format(<format-name>);
<theme-condition> = <string>
<format-name> = [ 'style-dictionary3' ]
All @design-tokens
rules in a document are evaluated in order of appearance.
If a token with the same path and name already exists it will be overridden.
All @design-tokens
rules are evaluated before any design-token()
functions.
@design-tokens
rules can be conditional through when
conditions. Multiple values can be specified in when
.
Multiple conditions always have an AND
relationship.
/* only evaluated when tooling receives 'blue' and 'muted' as arguments */ @design-tokens url('./tokens.json') format('style-dictionary3') when('blue' 'muted');
@design-tokens
rules can never be made conditional through @supports
, @media
or other conditional rules.
@media (min-width: 500px) { @design-tokens url('./tokens.json') format('style-dictionary3'); /* always evaluated */ }
Any form of nesting is meaningless, @design-tokens
will always be evaluated as if they were declared at the top level.
The design-token()
function takes a token path and returns the token value.
.foo {
color: design-token('color.background.primary');
}
design-token() = design-token( <token-path> [ to <unit> ]? )
<token-path> = <string>
<unit> = [ px | rem | ... ]
The plugin can convert px
to rem
and rem
to px
via the unitsandvalues
plugin options.
When a design token is unit-less any unit
can be assigned with to
.
Stylelint is able to check for unknown property values. Setting the correct configuration for this rule makes it possible to check even non-standard syntax.
// Disallow unknown values for properties within declarations.
'declaration-property-value-no-unknown': [
true,
{
propertiesSyntax: {
color: '| <design-token()>',
// ... more properties ...
},
typesSyntax: {
'<design-token()>': 'design-token( <string> [ to <ident> ]? )',
},
},
],