nelonoel / postcss-theme-ui

PostCSS Theme UI lets you access Theme UI variables in your CSS.

Table of Contents

• Introduction
• Setup
• Plugin Options
• Overview
• Responsive Values
• Custom Design Tokens
• Caveats

Introduction

This package is still experimental, but mostly functional with some caveats outlined below. Developer ergonomics may still change based on community feedback. Feel free to file a PR!

Setup

Add PostCSS Theme UI to your project:

npm install postcss-theme-ui --save-dev

Use PostCSS Theme UI to process your CSS:

const postcssThemeUI = require("postcss-theme-ui");

postcssThemeUI.process(YOUR_CSS /*, processOptions, theme */);

Or use it as a PostCSS plugin:

const postcss = require("postcss");
const postcssThemeUI = require("postcss-theme-ui");
const theme = require("./theme");

postcss([postcssThemeUI(theme)]).process(YOUR_CSS /*, processOptions */);

PostCSS Theme UI runs in all Node environments, with special instructions for:

Options

PostCSS Theme UI accepts an object formatted based on the System UI Theme Specification. See sample theme object.

Overview

Given the following theme config:

{
  breakpoints: ["40em", "52em", "64em"],
  colors: { text: '#111', primary: '#06c', error: '#c30' },
  fonts: {
    sans: '"IBM Plex Sans", sans-serif',
    serif: '"IBM Plex Serif", serif'
  },
  fontSizes: [12, 14, 16, 20, 24, 32, 48, 64, 72],
  sizes: ["initial", "48rem", "64rem"],
  space: [0, 4, 8, 16, 32, 64, 128, 256, 512]
}

PostCSS Theme UI maps CSS properties to the appropriate theme field. You can view the full prop mapping here. It supports negative values (for certain properties) and conversion of unitless integers to px.

.example {
  color: primary; /* colors.primary */
  font-size: 6; /* fontSizes[6] */
  margin: 0 auto -1; /* space[0] auto -space[1] */
  padding: 0 3 3px; /* space[0] space[3] 3px */
}

/* becomes */

.example {
  color: #06c;
  font-size: 48px;
  margin: 0 auto -4px;
  padding: 0 16px 3px;
}

Responsive Values

It also provides support for array values that map to your breakpoints for convenient responsive styling. You can call the theme function inside arrays, or use null to skip breakpoints. See Caveats for some limitations.

.card {
  border: th(colors.primary) [1, 2]; /* colors.primary [solid 1px, solid 2px] */
  color: primary; /* colors.primary */
  max-width: [0, null, 2]; /* [sizes], `null` is used to skip breakpoints */
  padding: [1, 2]; /* [space] */
}

/* becomes */

.card {
  border: #07c solid 1px;
  color: #07c;
  max-width: initial;
  padding: 4px;
}
@media screen and (min-width: 40em) {
  .card {
    border: #07c solid 2px;
    padding: 8px;
  }
}
@media screen and (min-width: 52em) {
  .card {
    max-width: 64rem;
  }
}

Custom Design Tokens

If you have design tokens currently not on the Theme UI spec, you can access them via the theme() or th() function.

Say, you want to add a gradients field to your tokens:

// theme config
{
  gradients: [
    "linear-gradient(to right, #DD2476, #FF512F)",
    "linear-gradient(to right, #FFF, #6DD5FA, #2980B9)"
  ];
}

Use them by calling the theme() or th() CSS functions.

.awesome-cta {
  background: th(gradients.0);
}

/* becomes */

.awesome-cta {
  background: linear-gradient(to right, #dd2476, #ff512f);
}

Note: Since we're using PostCSS, we can conveniently plug autoprefixer in our toolchain as well.

Caveats

1. Short hand CSS properties such as font, background, and border will only map to one theme field as defined here. However, You can still access theme variables via the theme function.

.btn {
  border: theme(colors.primary) 1; /* colors.primary borders[1] */
  font: sans theme(fontSizes.1); /* fonts.sans fontSizes[1] */
}

/* becomes */

.btn {
  border: #07c solid 1px;
  font: "IBM Plex Sans", sans-serif 1rem;
}

2. Responsive Values cannot be nested and can only be balanced when used more than once per property. For example, the following won't work at the moment. 😉

.unsupported {
  margin: [0, 1] [0, 1, 2];
  padding: [0, [1, 2]];
}

.fixed {
  margin: [0, 1, 1] [0, 1, 2];
  padding: 0 [1, 2];
}

.equivalent {
  margin-top: [0, 1];
  margin-right: [0, 1, 2];
  margin-bottom: [0, 1];
  margin-left: [0, 1, 2];
  padding: 0 [1, 2];
}

3. Editor syntax highlighting is still a work in progress.