@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. simple: object declaring only token property and value

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

color:
  primary:
    text: white
    background: tomato

Json

Style dictionary

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

color:
  primary:
    text: white
    background: tomato

tokens.css (:root)

tokens.css (:host)

root: string

Defines the type of root that will use the tokens, by default ":host", example:

@tokens "./tokens.yaml" scope(:root);

Consider the following behaviors:

1. root puede ser cualquier tipo de selector

2. if root is equal to ":root", the build rules will work at the :root/lightDOM level.

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

export const GenericStateTokens = css`
    @tokens "./tokens.yaml" filter(color);
`;

Output CSS

Tokens

From the previous example @atomic/postcss-tokens will only take the tokens from the color property.

use: string

It behaves similarly to filter, but with the big difference that filter preserves the scope structure vs use that shortens it, example:

Input CSS

export const GenericStateTokens = css`
    @tokens "./tokens.yaml" use(color);
`;

Output CSS

Tokens

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);
}