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;
    includeCoreTokensInScopes?: boolean;
  };
}

Options

Parameter	Required	Type	Default	Description
selectorTemplate	optional	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	optional	string		The pattern used to generate token names. It must match mustache template syntax. You can use collection, mode,groups and token names.
includeCoreTokensInScopes	optional	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.

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}}\"]",
            "includeCoreTokensInScopes": true
          }
        }
      ]
    }
  ]
}

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.