Why we think PostCSS Design Tokens is needed

Hey there!

If you're reading this, it means you want to know what drove us to write a PostCSS Design Tokens. A plugin that's not in any CSS official spec whatsoever. We wanted to capture our feelings and the logic behind this plugin within this wiki page.

The seed

This all started after starting to heavily maintain plugins again to upgrade for PostCSS 8. We realized that there was logic within PostCSS Custom Properties, PostCSS Env Function, and into PostCSS Preset Env as well. This logic might sound familiar and it's in the form of importFrom and exportTo.

While the concept made sense, it opened the door to mysterious bugs and unexpected behavior in some cases. We started to dig and wonder what the main usage of those options was.

As it turns out, it was to use design tokens.

The idea

It is clear that there's a need to bridge between the different tooling and the CSS. While env functions had the potential to deliver this, it didn't see any further development on the spec and it got a fraction of what it could have been its potential.

The idea of this plugin is to offer a clear path from a design tool to CSS code as there's already with other systems. As an example, a Figma file could export to Style Dictionary and from there be consumed by iOS and Android and to CSS only via variables (and on a separate type).

We aim to fill that gap and consume directly the JSON and replace directly the value within the CSS code.

FAQ

Why not output custom properties?

It'd be trivial to allow the plugin to output to custom properties and let you use them. However, that's what we're trying to avoid.

First of all, you can write your own! From this example from the README's

{
	"color": {
		"background": {
			"primary": { "value": "#fff" }
		}
	},
	"size": {
		"spacing": {
			"small": { "value": "16px" }
		}
	}
}

You can then just write:

:root {
	--c-primary: design-token('color.background.primary');
}

Which would output:

:root {
	--c-primary: #fff;
}

On the other hand, we think leveraging custom properties for design tokens purposes has its drawbacks.

• There's a cost in understandability. Having them as globals feels great for whoever wrote the system but it has a steep learning curve for others.
• Semantically, design tokens aren't meant to change dynamically during the lifespan of a visit.
• Even if minimal, there's extra overhead for the browser in terms of parsing custom properties and also in terms of the size of the CSS file. This does not mean we don't recommend Custom Properties, they're great! We just don't think they're meant as design tokens.

What is a Style Dictionary?

Style dictionary is a format for design tokens implemented and maintained by Amazon.

Can you support other formats?

We're open to supporting formats! We chose the one that was kept updated and used by another tooling such as Sketch or Figma.