postcss-custom-colors

A PostCSS plugin to add color functions that reference hues and shades of your color palette.

Installation

npm install postcss-custom-colors

Usage

In JavaScript, simply pass your named colors to this plugin when declaring it for use with PostCSS. Your colors can be simple strings, or can have nested colors beneath them (this is useful for declaring shades/ tints).

// dependencies
import fs from 'fs';
import postcss from 'postcss';
import customColors from 'postcss-custom-colors';

// 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(customColors(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); /* equivalent to color(blue, shade: base) */
}

Which will generate:

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

Options

In addition to the color palette passed to custom-colors, you can pass an options object that lets you customize the names of the function, modifier key, and default value key:

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

    // the modifier key to use; here, `color(blue, value: light)` becomes valid.
    shadeName: 'value',

    // the base key name; here, `color(blue)` will refer to the light blue.
    baseName: 'light',
  })
)