README
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.