@atomico/design-tokens
Accelerates the implementation of design tokens in web components in a sustainable and scalable way
GitHub - atomicojs/design-tokens
GitHub
With @atomico/design-tokens you can:

Resolve scalability and maintenance issues with your design tokens.

Design systems are complex to develop, due to the number of configurations that are shared between all our components, with @atomico/design-tokens we will solve:
  1. 1.
    Naming problems of the custom properties of your design tokens.
  2. 2.
    Legibility of your CSS.

How does @atomico/design-tokens solve the scalability of your design tokens?

For this example we will use Atomico, by the way you can use @atomico/design-tokens with any library.
1
import { css } from "atomico";
2
import { compose, tokens } from "@atomico/design-tokens";
3
​
4
const designTokens = compose(
5
tokens(
6
{
7
size: {
8
xl: "40px",
9
l: "32px",
10
m: "28px",
11
s: "20px",
12
},
13
},
14
"ds"
15
)
16
);
17
​
18
export const tokens = designTokens(css``);
Copied!
The result of the CSS will be the following:
1
:host {
2
--size-xl: var(--ds--size-xl, 40px);
3
--size-l: var(--ds--size-l, 32px);
4
--size-m: var(--ds--size-m, 28px);
5
--size-s: var(--ds--size-s, 20px);
6
}
Copied!
This is a technique that I have created to improve the scalability of design tokens, with it you can:
  1. 1.
    edit token globally using custom properties:
1
:root {
2
--my-ds-size-xl: 50px;
3
}
Copied!
This is also applicable within a selector.
  1. 1.
    Simplify maintenance, since your components will use the custom properties without a prefix:
1
import { c, css } from "atomico";
2
import tokens from "./tokens";
3
function button() {
4
return (
5
<host shadowDom>
6
<slot />
7
</host>
8
);
9
}
10
​
11
button.styles = [
12
tokens,
13
css`
14
:host {
15
height: var(--size-xl);
16
background: var(--color-primary-60);
17
padding: var(--size-xxs) var(--size-xs);
18
}
19
`,
20
];
Copied!

Create utility classes to be used internally by your component system.

I am personally a fan of custom properties, but their use would become repetitive, to avoid this and improve maintenance @atomico/design-tokens introduces classes, a generator of utility classes based on the proposed design tokens, example:
1
import { css } from "atomico";
2
import { compose, tokens, classes } from "@atomico/design-tokens";
3
​
4
const designTokens = compose(
5
classes({
6
size: {
7
xl: "40px",
8
l: "32px",
9
m: "28px",
10
s: "20px",
11
},
12
})
13
);
14
​
15
export const tokensSize = designTokens(
16
css`
17
.gap.--size {
18
gap: var(--size);
19
}
20
`
21
);
Copied!
The classes middleware will parse the CSSStyleSheet to relate the custom propeprtiy --size as a class of .gap, internally the css will be as follows:
1
.gap\.xl {
2
gap: var(--size-xl);
3
}
4
​
5
.gap\.l {
6
gap: var(--size-l);
7
}
8
​
9
.gap\.m {
10
gap: var(--size-m);
11
}
12
​
13
.gap\.s {
14
gap: var(--size-s);
15
}
Copied!
This makes it really simple to reuse the tokens, example:
1
import { c } from "atomico";
2
import { tokensSize } from "./tokens";
3
​
4
function button() {
5
return (
6
<host shadowDom>
7
<button class="gap.xl">
8
<slot />
9
</button>
10
</host>
11
);
12
}
13
​
14
button.styles = tokensSize;
15
​
16
customElements.define("my-button", c(button));
Copied!