PostCSS Theme UI lets you access Theme UI variables in your CSS.
Table of Contents
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 = ; postcssThemeUI;
Or use it as a PostCSS plugin:
const postcss = ;const postcssThemeUI = ;const theme = ; ;
PostCSS Theme UI runs in all Node environments, with special instructions for:
Node | PostCSS CLI | Webpack | Create React App | Gulp | Grunt |
---|
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
.
/* becomes */
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.
/* becomes */ {}{}
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.
/* becomes */
Note: Since we're using PostCSS, we can conveniently plug autoprefixer in our toolchain as well.
Caveats
- Short hand CSS properties such as
font
,background
, andborder
will only map to one theme field as defined here. However, You can still access theme variables via thetheme
function.
/* becomes */
- 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];
}
- Editor syntax highlighting is still a work in progress.