@michelangelo-design/postcss v1.0.0-0

Contents

• Install
• Usage
• Limitations

Install

First, you'll need to install postcss:

yarn add -D postcss

Second, you'll need to install the plugin:

yarn add -D @michelangelo-design/postcss

Usage

As of now, this plugin is geared towards a one time transformation to adopt a new color palette. It is not intended to persist in your codebase.

For that reason, it is recommended that you use this plugin for a Node postcss script and not as a Webpack loader.

Here is an example:

// migrate-palette.js
const michelangelo = require("@michelangelo-design/postcss")
const postcss = require("postcss")

const css = // import css or use [glob](https://www.npmjs.com/package/glob)
            // to get multiple css files that you can iterate over and apply postcss to

const options = {
  tokens: {
    "--primary": "yellow",
    "--secondary": "green",
    "--accent": "blue",
  },
  oldTokens: {
    "--primary": "pink",
    "--secondary": "red",
    "--accent": "orange",
  },
  oldToNewTokenMapping: {
    pink: "yellow",
    red: "green",
    orange: "blue",
  },
}

postcss().use(plugin(options)).process(css).then(result => {
  // do something with result
  // like writing to a file
})

In the example above, tokens (a object of key-value pairs representing your color palette) is the only required option. When provided, it will convert all colors in your css that aren't in the tokens palette to the closest color in the new palette.

Optionally, you can provide oldTokens and oldToNewTokenMapping. oldTokens is a object of key-value pairs representing the old palette. When provided without a oldToNewTokenMapping, the plugin will attempt to create a mapping (key-value pairs where the key is an old colors and the value is the new color that is to replace the old color):

tokens: {
  "--primary": "red",
  "--secondary": "green",
},
oldTokens: {
  "--primary": "green",
  "--secondary": "yellow",
},

// generated mapping when `oldToNewTokenMapping` is not provided as an option
{
  "green": "red",
  "yellow": "green"
}

The automatically generated mapping works in the case that the tokens and the oldTokens have the same amount of colors. And, the order of tokens is the same (like in the example above.)

If there is a greater difference between the old and new tokens (which is likely), you'll have to manually provide the old to new tokens mapping via the oldToNewTokenMapping option.

You can potentially extended the code used by the plugin to generate a simple mapping.

Limitations

1) Currently, it does not update the "root" selector to detect and add new variables. However, it will transform all current variables to an updated color. 2) Also, it does not remove outdated variables in the "root" selector even though it updates the color. 3) As mentioned, you have to manually provide the old to new token mapping if it is a more complex migration.