CSS-in-JS microlibrary for making design systems approachable with React
💡 Motivation
When styling HTML elements, quite a few approaches may come to mind, including:
- Utility-first/Atomic CSS, as implemented by Tailwind CSS, StyleSheet and CSS-Zero
- Fully static, but customizable upfront
- Embraces reusability with no duplicated rules
- Constraint-based layouts, popularized by Theme UI
- Highly dynamic, thankfully to Emotion
- One-off styles can be defined naturally
Baking the benefits outlined above into a single package, glaze was born.
🚀 Key features
- Simple API inspired by inline styles
- Near-zero runtime built upon treat
- Personalizable design tokens inherited from Tailwind CSS and Theme UI
- Composable property aliases and shorthands mapped to scales
- E.g.
paddingX
orpx
for defining horizontal padding
- E.g.
🚧 In development
- Responsive values defined as an array
- Pseudo-class support
📚 Usage
-
Install the package and its peer dependencies:
npm install glaze treat react-treat -
Define a theme, preferably by overriding the default tokens:
/* theme.treat.js */;...defaultTokens// Customizationscales:...defaultTokensscalescolor:red: '#f8485e';Keeping the runtime as small as possible, only a few tokens (
breakpoints
,shorthands
andaliases
) are embedded into production JavaScript bundles. Other values can only be accessed exclusively for styling, as shown later. -
Apply the theme through
ThemeProvider
:📝 The Gatsby plugin for glaze does this unobtrusively.
import ThemeProvider from 'glaze';import theme from './theme.treat';{return <ThemeProvider =>children</ThemeProvider>;} -
Style elements with the
sx
function:import useStyling from 'glaze';{const sx = ;return<p=>Hello world!</p>;} -
Set up static style extraction with the help of treat.
📝 The Gatsby plugin for treat does this unobtrusively.
-
Afterwards, selector-based CSS rules may be created with
globalStyle
in*.treat.js
files. They have to be applied as a side effect, e.g. from a top-level layout component:;
-
-
Configure server-side rendering for dynamically created styles.
🤔 How it works
- The
sx
function maps themed values to statically generated class names- If that fails, the style gets injected dynamically through the CSSOM
- Dynamic styles which are not in use by any component get removed
Rule handling
- Transform each alias to its corresponding CSS property name or custom shorthand
- Resolve values from the scales available
- CSS properties associated with a custom shorthand are resolved one by one
Example
Given the theme below:
; scales: spacing: 4: '1rem' shorthands: paddingX: 'paddingLeft' 'paddingRight' aliases: px: 'paddingX' matchers: paddingLeft: 'spacing' paddingRight: 'spacing' ;
An sx
parameter is matched to CSS rules as follows:
{ px: 4 }
{ paddingX: 4 }
, after transforming aliases{ paddingLeft: 4, paddingRight: 4 }
, after unfolding custom shorthands{ paddingLeft: '1rem', paddingRight: '1rem' }
, after applying matchers
✨ Contributors
Thanks goes to these wonderful people (emoji key):
Kristóf Poduszló 🚧 💻 📖 💡 🤔 🚇 |
Jess Telford 📖 |
Corentin Leruth 📖 💻 ⚠️ |
This project follows the all-contributors specification. Contributions of any kind welcome!
Acknowledgements
Without its predecessors, glaze wouldn't exist. Thanks for all the wonderful people who have contributed towards the project, even indirectly.
The logo's donut emoji is courtesy of Twemoji.