English
Search…
⌃K
Links

@atomico/postcss-tokens

Makes it easy to manage tokens as CSS custom properties for design system development
@atomico/postcss-tokens works through yaml or json files that declare tokens to be later imported from CSS files using the @tokens atRule. Through @tokens you can define if the resource to be generated should be global in scope (:root) or at the webcomponent level (:host)

Token syntax

Tokens are declared using YAML to JSON files, token declarations can be:
  1. 1.
    simple: object declaring only token property and value
  2. 2.
    variations by attributes: object that declares the tokens according to the assignment of an attribute at the webcomponent level

Example of simple tokens

Yaml
Json
Style dictionary
color:
primary:
text: white
background: tomato
{
"color": {
"primary": {
"text": "white",
"background": "tomato"
}
}
}
{
"color": {
"primary": {
"text": { "value": "white" },
"background": { "value": "tomato" }
}
}
}

Example of variations by attributes

This type of declaration allows assigning tokens according to the attribute of a webcomponent
Yaml
space:
around: 1rem
between: 1rem
safe: .5rem
[size=small]:
around: .8rem
between: .8rem
safe: .4rem
Thanks to this type of declaration you will be able to manage the variations directly from the token file.

AtRule @tokens

This atRule allows importing yaml or json files to be used as custom properties, example:
tokens.yaml
tokens.css (:root)
tokens.css (:host)
color:
primary:
text: white
background: tomato
Importing the tokens.yaml file
@tokens "./tokens.yaml" (root: ":root");
Output
:root{
--myprefix--color-primary-text: white;
--myprefix--color-primary-background: tomato;
}
Importing the tokens.yaml file
@tokens "./tokens.yaml";
Output
:host{
--color-primary-text: var(--myprefix--color-primary-text);
--color-primary-background: var(--myprefix--color-primary-background);
}

root: string

Defines the type of root that will use the tokens, by default ":host", example:
@tokens "./tokens.yaml" (root: ":root");
Consider the following behaviors:
  1. 1.
    root puede ser cualquier tipo de selector
  2. 2.
    if root is equal to ":root", the build rules will work at the :root/lightDOM level.
  3. 3.
    if root is equal to ":host", the generation rules will work at the :host/shadowDOM level.

filter: string

It will only take the tokens assigned in the filter to create the custom properties, example:
Input CSS
Output CSS
Tokens
export const GenericStateTokens = css`
@tokens "./tokens.yaml" (filter: color);
`;
:host{
--color-primary: var(--myprefix--color-primary);
--color-secondary: var(--myprefix--color-secondary);
}
size:
small: 1rem
normal: 2rem
color:
primary: red
secondary: gold
From the previous example @atomic/postcss-tokens will only take the tokens from the color property.

import: string

It behaves similarly to filter, but with the big difference that filter preserves the scope structure vs import that shortens it, example:
Input CSS
Output CSS
Tokens
export const GenericStateTokens = css`
@tokens "./tokens.yaml" (import: color);
`;
:host{
--primary: var(--myprefix--color-primary);
--secondary: var(--myprefix--color-secondary);
}
size:
small: 1rem
normal: 2rem
color:
primary: red
secondary: gold

Configuration in postcss

prefix: string

Define el prefijo para las custom properties

defaultValue : boolean

Define que las customProperties que trabaje a nivel de shadowDom poseeran un valor por defecto si no se declara el tokens en :root, ejemplo:
:host{
--color-primary: var(--my-ds--color-primary, red);
}