Skip to content

Why we think PostCSS Design Tokens is needed

Jump to bottom
Romain Menke edited this page May 23, 2022 · 7 revisions

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 we picked up maintenance for a bunch of plugins to upgrade to PostCSS 8. We realized that there are sub features within PostCSS Custom Properties, PostCSS Env Function, and into PostCSS Preset Env as well. These are 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 different tools and CSS. While env function had the potential to deliver this, it didn't see any further development on the spec and it is a fraction of what it could have been.

The idea of this plugin is to offer a clear path from a design tool to CSS. 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 the JSON directly, inserting values in your 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 {
	/* you control the custom property name */
	--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 are constants, they 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.
  • Not every token name can be expressed as a custom property name.

This does not mean we don't recommend Custom Properties in general, they're great! We just don't think they're a good fit for design tokens. They might have been the best analogue available at the time, but we believe we can do better.

Aside from developer experience we also fear that design tokens as custom properties take away control and options from developers. One effect of this is sites that are not accessible for everyone.

Most design tools allow you to export values as either px or rem but this alone does not enable you to create an accessible website. You will most likely need both to create pages that scale correctly with font size. We want to make it easy to use design tokens without making your job harder or impossible in other areas.

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.

We definitely want to add support for the Design tokens specification as soon as it is ready.

Current Tooling

Clone this wiki locally