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		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.
withSDTFView	false	string		The name of a registered view. See register-view for more details using the CLI or GitHub.

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.

Input

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

Config

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Generate tokens as CSS Custom Properties",
      "parsers": [
        {
          "name": "to-css-custom-properties",
          "output": {
            "type": "file",
            "filePath": "tokens.css"
          },
          "options": {
            "tokenNameTemplate": "--{{groups}}-{{token}}",
            "selectorTemplate": "[data-theme=\"{{mode}}\"]"
          }
        }
      ]
    }
  ]
}

Output

tokens.css

[data-theme="dark"] {
  --core-blue-100: rgb(41, 52, 67);
  --core-blue-700: rgb(96, 168, 250);
  --semantic-background-button-primary-hover: var(--core-blue-100);
}
[data-theme="light"] {
  --core-blue-100: rgb(219, 236, 254);
  --core-blue-700: rgb(17, 125, 249);
  --semantic-background-button-primary-hover: var(--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.