Design Tokens as Custom Properties

[jacobrask]

The current approach of the design-tokens plugin is not compatible with design systems that use design tokens as CSS Custom Properties, which I think is is an unfortunate choice for a great tool otherwise focused on advancing CSS.

The reasoning seems to be

Semantically, design tokens are constants, they aren't meant to change dynamically during the lifespan of a visit.

I'd like to argue the opposite, that many design tokens just represent a "slot" in a theme, and not a specific color.

Design tokens are often multi-tiered, where you would have a set of core tokens that are static, but semantic/decision tokens that may change.

Let's take the example from the docs

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

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

I would suggest modelling this as

:root, [data-color-mode=light] {
  --acme-color-background-primary: white;
}
[data-color-mode=dark] {
  --acme-color-background-primary: black;
}

It can even be extended with

.checkout, .checkout[data-color-mode=light] {
  --acme-color-background-primary: palegreen;
}
.checkout[data-color-mode=dark] {
  --acme-color-background-primary: darkgreen;
}

And then anyone building components would do

@import url('@acme/design-system/tokens.css');

.foo {
  background-color: var(--acme-color-background-primary);
}

With the way the design tokens plugin works today, would you be able to support a design system like this?

[romainmenke]

Hi @jacobrask

Thank you for your interest in the design tokens plugin!

---

Semantically, design tokens are constants, they aren't meant to change dynamically during the lifespan of a visit.

I'd like to argue the opposite, that many design tokens just represent a "slot" in a theme, and not a specific color.

I think this depends on your perspective and the time scale taken into consideration.
When considering values over the entire lifespan of a design, then design tokens are variables.
When considering values over the lifespan of a single page visit, then design tokens are constants.

For our purposes a design token is a constant because there is nothing that will alter the value except for the design token source file.

But this is different from another perspective.
The above only applies if you are building a final product.

If you are building a framework that will be personalised by end users, then you want to give them the ability to override token values.

This can be done with our plugin :

@design-tokens url('./framework-tokens.json') format('style-dictionary3');
@design-tokens url('./personal-override-tokens.json') format('style-dictionary3');

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

Or by assigning to variables yourself :

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

.foo {
  --framework-color-background-primary: design-token('color.background.primary');
}

/* user code */
.foo {
  --framework-color-background-primary: purple;
}

[romainmenke]

We also tried to build a tool that will work nicely with the upcoming attempt to have a standardised tokens format.

Within this format there is no defined way (yet) to combine and override values.
We have requested clarification on this : design-tokens/community-group#123

We think having a mechanic to combine aliases and overrides from other files will allow users to publish configurable design systems.

[jacobrask]

For our purposes a design token is a constant because there is nothing that will alter the value except for the design token source file.

There are many reasons to change the value of a design token at runtime, dark mode would be the most common one. It's also not uncommon to want to style a specific section of your site differently. With CSS variables this can be done with a single class name - as long as all components consume CSS Custom Properties.

What I'm after is an easier and safer way for developers to consume these properties.

To continue the example to explain multi-tiered tokens, you might have Core or Reference Tokens that are static, and they could use the design-tokens plugin. In this case core.color.white and color.background.primary are both design tokens, but one is a core token and the other is a semantic or decision token.

:root, [data-color-mode=light] {
  --acme-color-background-primary: design-token('core.color.white');
}
[data-color-mode=dark] {
  --acme-color-background-primary: design-token('core.color.black');
}

Consumers of the design system would never access core.color.white directly, so this would only benefit the creators of a design system or CSS framework and not the majority of developers.

See for example Material Tokens, where md.sys.color.primary should be a CSS Custom Property but md.ref.palette.primary40 and md.ref.palette.primary80 should be static values.

[romainmenke]

There are many reasons to change the value of a design token at runtime, dark mode would be the most common one. It's also not uncommon to want to style a specific section of your site differently. With CSS variables this can be done with a single class name - as long as all components consume CSS Custom Properties.

This is relevant for that : design-tokens/community-group#169
If something like this is added to the specification we can generate CSS with conditionals (i.e. @media). Currently this does not exist and tokens are purely constants.

We will however never refactor this plugin to generate/produce CSS variables.
There are plugins that do this and they do this fine.

There is value in diversity here :)

From our perspective it doesn't make sense to generate CSS variables.
We want to be able to do this :

• Design token files define how a single token changes value for multiple conditions
• CSS files consume only the relevant tokens
• Give CSS authors full control over the technical aspects
• Produce the best CSS for the above.

We do not want to generate something like this CSS :

:root, [data-color-mode=light] {
  --acme-color-background-primary: #fff;
}
[data-color-mode=dark] {
  --acme-color-background-primary: #000;
}

.foo {
  background-color: var(--acme-color-background-primary);
}

We want authors to write :

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

And we want to generate this :

.foo {
  background-color: #fff;
}

@media (prefers-color-scheme: dark) {
  .foo {
    background-color: #000;
  }
}

This unlocks a lot more features :

• better fallback and polyfill values for older browsers because we avoid var()
• better dev tooling because there is a direct link between tokens and where they are used
• easier to maintain because there is a direct link between tokens and where they are used

We are actively engaging with the design tokens community group to this end.