# @csstools/postcss-design-tokens

> Use design tokens in your CSS

Latest version **5.0.2** (published 2026-10-01) · MIT-0 license · 0 weekly downloads

## Install

```sh
npm install @csstools/postcss-design-tokens
pnpm add @csstools/postcss-design-tokens
yarn add @csstools/postcss-design-tokens
bun add @csstools/postcss-design-tokens
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 5.0.2 |
| Published | 2026-10-01 |
| First published | 2022-05-23 |
| Weekly downloads | 0 |
| License | MIT-0 |
| TypeScript types | none |
| Module format | ESM |
| Node | >=20.19.0 |
| Dependencies | 3 |
| Unpacked size | 23 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1057 |
| Maintainers | jonathantneal, alaguna, romainmenke |
| Keywords | css, design-token, postcss, postcss-plugin, token |

## Links

- npm: https://www.npmjs.com/package/@csstools/postcss-design-tokens
- Repository: https://github.com/csstools/postcss-plugins
- Homepage: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-design-tokens#readme
- Issues: https://github.com/csstools/postcss-plugins/issues
- Funding: https://github.com/sponsors/csstools
- npm.io page: https://npm.io/package/@csstools/postcss-design-tokens

## Dependencies (3)

- [postcss-value-parser](https://npm.io/package/postcss-value-parser.md) ^4.2.0
- [@csstools/css-tokenizer](https://npm.io/package/@csstools/css-tokenizer.md) ^4.0.2
- [@csstools/css-parser-algorithms](https://npm.io/package/@csstools/css-parser-algorithms.md) ^4.0.2

## Alternatives

- [style-dictionary](https://npm.io/package/style-dictionary.md) — 2.0M weekly downloads
- [postcss-merge-idents](https://npm.io/package/postcss-merge-idents.md) — 1.7M weekly downloads
- [@fontsource/noto-sans](https://npm.io/package/@fontsource/noto-sans.md) — 93.0K weekly downloads
- [uglifycss](https://npm.io/package/uglifycss.md) — 71.6K weekly downloads
- [mat4-interpolate](https://npm.io/package/mat4-interpolate.md) — 23.3K weekly downloads

## Recent versions

- 5.0.2 (latest) — 2026-10-01
- 5.0.1 — 2026-09-25
- 5.0.0 — 2026-01-14
- 4.0.5 — 2025-05-27
- 4.0.4 — 2024-11-01
- 4.0.3 — 2024-10-23
- 4.0.2 — 2024-10-10
- 4.0.1 — 2024-08-18
- 4.0.0 — 2024-08-03
- 3.1.9 — 2024-07-06
- 3.1.8 — 2024-06-29
- 3.1.7 — 2024-05-04
- 3.1.6 — 2024-05-04
- 3.1.5 — 2024-03-13
- 3.1.4 — 2024-02-19
- … 15 more at https://npm.io/package/@csstools/postcss-design-tokens/versions

## README

# PostCSS Design Tokens [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][PostCSS]

`npm install @csstools/postcss-design-tokens --save-dev`

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

```json
{
	"color": {
		"background": {
			"primary": { "value": "#fff" }
		}
	},
	"size": {
		"spacing": {
			"small": { "value": "16px" },
			"medium": { "value": "18px" },
			"medium-alias": { "value": "{size.spacing.medium}" }
		}
	},
	"viewport": {
		"medium": { "value": "35rem" }
	}
}
```

```css
@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;
	}
}
```

## Usage

Add [PostCSS Design Tokens] to your project:

```bash
npm install postcss @csstools/postcss-design-tokens --save-dev
```

Use it as a [PostCSS] plugin:

```js
const postcss = require('postcss');
const postcssDesignTokens = require('@csstools/postcss-design-tokens');

postcss([
	postcssDesignTokens(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```



## Formats

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](https://amzn.github.io/style-dictionary/#/).
Use `style-dictionary3` in `@design-tokens` rules to pick this format.

## Options

### is

The `is` option determines which design tokens are used.<br>
This allows you to generate multiple themed stylesheets<br>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._

#### Example usage

**For these two token files :**

```json
{
	"color": {
		"background": {
			"primary": { "value": "#0ff" }
		}
	}
}
```

```json
{
	"color": {
		"background": {
			"primary": { "value": "#f0f" }
		}
	}
}
```

**And this CSS :**

```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 :**

##### No `is` option.

```js
postcssDesignTokens()
```

```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');
}

/* becomes */

.foo {
	color: #0ff;
}
```

##### `is` option set to 'brand-2'.

```js
postcssDesignTokens({ is: ['brand-2'] })
```

```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');
}

/* becomes */

.foo {
	color: #f0f;
}
```

### unitsAndValues

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.

#### rootFontSize

defaults to `16`

```js
postcssDesignTokens({
	unitsAndValues: {
		rootFontSize: 20,
	},
})
```

```css
@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;
	}
}
```

### Customize function and at rule names

#### importAtRuleName

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

```js
postcssDesignTokens({ importAtRuleName: 'tokens' })
```

```css
@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;
}
```

#### valueFunctionName

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

```js
postcssDesignTokens({ valueFunctionName: 'token' })
```

```css
@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;
}
```

## Syntax

[PostCSS Design Tokens] is non-standard and is not part of any official CSS Specification.

### Editor support

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](https://marketplace.visualstudio.com/items?itemName=RomainMenke.csstools-design-tokens) |

### `@design-tokens` rule

The `@design-tokens` rule is used to import design tokens from a JSON file into your CSS.

```css
@design-tokens url('./tokens.json') format('style-dictionary3');
```

```css
@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:

```css
@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`.<br>
Multiple conditions always have an `AND` relationship.

> ```css
> /* 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.

> ```css
> @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.


### `design-token()` function

The `design-token()` function takes a token path and returns the token value.

```css
.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`](#unitsandvalues) plugin options.
When a design token is unit-less any `unit` can be assigned with `to`.

#### [Stylelint](https://stylelint.io/user-guide/rules/declaration-property-value-no-unknown/#propertiessyntax--property-syntax-)

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.

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

## Further reading

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

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test

[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-design-tokens

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Design Tokens]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-design-tokens
[Why we think PostCSS Design Tokens is needed]: https://github.com/csstools/postcss-plugins/wiki/Why-we-think-PostCSS-Design-Tokens-is-needed
[About Design Tokens (Adobe Spectrum)]: https://spectrum.adobe.com/page/design-tokens/

---
_Source: https://npm.io/package/@csstools/postcss-design-tokens · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._