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;
    withSDTFView?: string;
  };
}

Options

Parameter
Required
Type
Default
Description

selectorTemplate

false

string

tokenNameTemplate

false

string

tokenNotInCollectionNameTemplate

false

string

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.

withSDTFView

false

string

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