@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

{
  "color": {
    "primary": {
      "text": "white",
      "background": "tomato"
    }
  }
}

Style dictionary

{
  "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

color:
  primary:
    text: white
    background: tomato

tokens.css (:root)

Importing the tokens.yaml file

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

Output

:root{
    --myprefix--color-primary-text: white;
    --myprefix--color-primary-background: tomato;
}

tokens.css (:host)

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" 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

:host{
    --color-primary: var(--myprefix--color-primary);
    --color-secondary: var(--myprefix--color-secondary);
}

Tokens

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.

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

:host{
    --primary: var(--myprefix--color-primary);
    --secondary: var(--myprefix--color-secondary);
}

Tokens

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