to-css-custom-properties

This parser helps you transform design tokens into CSS Custom Properties.

Interface

interface parser {
  name: 'to-css-custom-properties';
  output: {
    type: 'file';
    filePath: string;
  };
  options?: {
    tokenNameTemplate?: string;
    selectorTemplate?: string;
    tokenNotInCollectionNameTemplate?: string;
    includeCoreTokensInScopes?: boolean;
    allowUnresolvable?: boolean;
  };
}

Options

ParameterRequiredTypeDefaultDescription

selectorTemplate

false

string

The pattern used to generate the CSS selector name(s). It must match mustache template syntax. You can use collection, mode and groups names.

tokenNameTemplate

false

string

The pattern used to generate token names. It must match mustache template syntax. You can use collection, mode,groups and token names.

tokenNotInCollectionNameTemplate

false

string

The pattern used to generate token names when they are located outside of collections. It must match mustache template syntax. You can use mode,groups and token names.

includeCoreTokensInScopes

false

boolean

false

When set to true, you will have both core tokens and alias tokens in each CSS scopes thus making alias tokens always resolvable.

allowUnresolvable

false

boolean

false

When set to true, you'll be able to generate alias CSS variables targeting tokens which are not generating in the same scope or file (e.g., if you want a primitive.css and semantic.css files). When set to true, tokens will be named with the tokenNotInCollectionNameTemplate option.

Basic usage

A design token can have modes, be nested in groups and be part of a collection. The following use case will generate a single CSS file containing core tokens and semantic tokens.

{
  "colors": {
    "$collection": { "$modes": ["light", "dark"] },
    "core": {
      "blue-100": {
        "$type": "color",
        "$description": "token 1 aliased with n modes within collection within n groups",
        "$value": {
          "light": {
            "red": 219,
            "blue": 254,
            "alpha": 1,
            "green": 236,
            "model": "rgb"
          },
          "dark": {
            "red": 41,
            "blue": 67,
            "alpha": 1,
            "green": 52,
            "model": "rgb"
          }
        }
      },
      "blue-700": {
        "$type": "color",
        "$description": "token 2 aliased with n modes within collection within n groups",
        "$value": {
          "light": {
            "red": 17,
            "blue": 249,
            "alpha": 1,
            "green": 125,
            "model": "rgb"
          },
          "dark": {
            "red": 96,
            "blue": 250,
            "alpha": 1,
            "green": 168,
            "model": "rgb"
          }
        }
      }
    },
    "semantic": {
      "background": {
        "button": {
          "primary": {
            "hover": {
              "$type": "color",
              "$description": "alias token with n modes within collection within n groups",
              "$value": {
                "dark": {
                  "$mode": "dark",
                  "$alias": "colors.core.blue-100"
                },
                "light": {
                  "$mode": "light",
                  "$alias": "colors.core.blue-700"
                }
              }
            }
          }
        }
      }
    }  
  }
}

Head towards our templates section to see how you can use this parser with others to suit a common use case when working with CSS.

Last updated