PostCSS Magic Token

A function for referencing design tokens and CSS variables intelligently based on the current property and the current selector.

Usage

To reference the primary color for all h2 elements you would write.

h2 {
    color: tok(--primary);
}

This equals the same as writing...

h2 {
    color: var(--h2-color-primary, var(--heading-color-primary, var(--color-primary, var(--color))));
}

In this example, first it looks for a token called --h2-color-primary, if this is not available it then looks to see if there is a token for --heading-color-primary then --color-primary, and then finally as a fallback --color.

When a specific variant of a token is not available, it checks for the next available variant. Below are some examples (some variations have been removed for simplicity).

:root {
    --component-element-property-keyword: value;
    --component-property-keyword: value;
    --element-property-keyword: value;
    --property-variant-keyword: value;
    --property-keyword: value;
    --property: value;
}

Examples

Default values

.default {
    border: tok();
}

Becomes

/* e.g. --border: 1px solid red; */
.default {
    border: var(--border);
}

Keyword values

.keyword {
    color: tok(--primary);
}

Becomes

/* e.g. --color-primary: red;
        --color: black; */
.keyword {
    color: var(--color-primary, var(--color));
}

Element specific

h2 {
    font-size: tok();
}

Becomes

/* e.g. --h2-font-size: 2.5em;
        --font-size: 1em; */
h2 {
    font-size: var(--h2-font-size, var(--font-size));
}

Component specific

Indicate a component using either of the following formats .Component, Component, com-ponent.

.Component {
    color: tok(--primary);
}

Becomes

/* e.g. --component-color-primary: purple;
        --color-primary: blue;
        --color: black; */
.Component {
    color: var(--component-color-primary, var(--color-primary, var(--color)));
}

Property variants

Some properties can include variants. For example margin and padding include variants for inline and block spacing.

.variants {
    padding: tok(--small);
}

Becomes

/* e.g. --padding-block-small: 1em;
        --padding-inline-small: 0.5em;
        --padding-small: 1em; */
.variants  {
    padding: var(--padding-block-small, var(--padding-small, var(--padding)))
        var(--padding-inline-small, var(--padding-small, var(--padding)))
        var(--padding-block-small, var(--padding-small, var(--padding)))
        var(--padding-inline-small, var(--padding-small, var(--padding)));
}

Usage

Add PostCSS Magic Token to your project:

npm install postcss-magic-token --save-dev

Use PostCSS Magic Token to process your CSS:

const postcssMagicToken = require('postcss-magic-token');

postcssMagicToken.process(YOUR_CSS /*, processOptions, pluginOptions */);

Or use it as a PostCSS plugin:

const postcss = require('postcss');
const postcssMagicToken = require('postcss-magic-token');

postcss([
    postcssMagicToken(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);