@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
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.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
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);
}
​
​

packages - Previous

@atomico/storybook

Example with @atomico/vite

Last modified 2mo ago