postcss-design-token-function

A PostCSS to add custom functions for accessing your design tokens.

Installation

npm install postcss-design-token-function

Usage

In JavaScript, simply pass an object with your design token information along with the name of the function by which you will retrieve that data in your CSS. Values can be simple strings or nested objects, which are useful for cases where you have naturally nested design details (e.g., values for your color palette).

// dependencies
import fs from 'fs';
import postcss from 'postcss';
import designTokenFunction from 'postcss-design-token-function';

// css to be processed
const css = fs.readFileSync('input.css', 'utf8');

// your colors
const colors = {
  white: '#F2F5FF',
  blue: {
    light: '#A2CEFF',
    base: '#5898FF',
  },
};

// process css
var output = postcss()
  .use(designTokenFunction({
    name: 'color',
    data: colors,
  }))
  .process(css)
  .css

And, in CSS, used the color function to reference your color palette. You can use the shade option to reference the nested shades, if provided (omitting a shade will default to using the base key of a nested color):

.foo {
  background: color(white);
  border: 1px solid color(blue, shade: light);
  color: color(blue, base);
}

Which will generate:

.foo {
  background: #F2F5FF;
  border: 1px solid #A2CEFF;
  color: #5898FF;
}

Options

The following is a complete list of the possible options you can pass this plugin:

postcss().use(
  designTokenFunction({
    // the actual function to look for; here, `colour(white)` becomes valid.
    name: 'colour',

    // The design token data to reference in your function calls. Must be an object,
    // optionally with multiple levels of nested objects.
    data: {},

    // the key to look for at any level of nesting when no variation is provided
    // (and one is needed; that is, there is a nested object in your design tokens).
    // By default, this plugin will look for a 'base' key.
    base: 'default',
  })
)

Note that you can generate functions for different design tokens by executing this plugin multiple times with each token's data provided in turn.