[] lets you use design tokens in your CSS source files.

<tokens.json>

<example.css>

/* becomes */

<example.expect.css>

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 :

<tokens-brand-1.json>

<tokens-brand-2.json>

And this CSS :

<example-conditional.css>

You can configure :

<exportName>()

<example-conditional.css>

/* becomes */

<example-conditional.expect.css>

<exportName>({ is: ['brand-2'] })

<example-conditional.css>

/* becomes */

<example-conditional.brand-2.expect.css>

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

<exportName>({
	unitsAndValues: {
		rootFontSize: 20,
	},
})

<example.css>

/* becomes */

<example.rootFontSize-20.expect.css>

The importAtRuleName option allows you to set a custom alias for @design-tokens.

<exportName>({ importAtRuleName: 'tokens' })

<example-custom-import-at-rule-name.css>

/* becomes */

<example-custom-import-at-rule-name.expect.css>

The valueFunctionName option allows you to set a custom alias for design-token.

<exportName>({ valueFunctionName: 'token' })

<example-custom-value-function-name.css>

/* becomes */

<example-custom-value-function-name.expect.css>

[] 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.

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> ]? )',
			},
		},
	],

• [Why we think PostCSS Design Tokens is needed]
• [About Design Tokens (Adobe Spectrum)]