CSS-in-JS microlibrary for making design systems approachable with React
## π‘ Motivation
When styling HTML elements, [quite a few approaches](https://seek-oss.github.io/treat/background#backstory) 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` or `px` for defining horizontal padding
### π§ In development
- **Responsive values** defined as an array
- **Pseudo-class** support
## π Usage
0. Install the package and its peer dependencies:
```sh
npm install glaze treat react-treat
```
1. Define a theme, preferably by overriding the [default tokens](https://github.com/kripod/glaze/blob/master/packages/glaze/src/theme.ts):
```js
/* theme.treat.js */
import { createTheme, defaultTokens } from 'glaze';
export default createTheme({
...defaultTokens,
// Customization
scales: {
...defaultTokens.scales,
color: {
red: '#f8485e',
},
},
});
```
_Keeping the runtime as small as possible, only a few tokens (`breakpoints`, `shorthands` and `aliases`) are embedded into production JavaScript bundles. Other values can only be accessed exclusively for styling, as shown later._
2. Apply the theme through `ThemeProvider`:
> π The [Gatsby plugin for glaze](https://www.npmjs.com/package/gatsby-plugin-glaze) does this unobtrusively.
```jsx
import { ThemeProvider } from 'glaze';
import theme from './theme.treat';
export default function Layout({ children }) {
return {children};
}
```
3. Style elements with the `sx` function:
```jsx
import { useStyling } from 'glaze';
export default function Component() {
const sx = useStyling();
return (
Hello, world!
);
}
```
4. Set up [static style extraction](https://seek-oss.github.io/treat/setup/) with the help of [treat][].
> π The [Gatsby plugin for treat](https://www.npmjs.com/package/gatsby-plugin-treat) does this unobtrusively.
- Afterwards, selector-based CSS rules may be created with [`globalStyle`](https://seek-oss.github.io/treat/styling-api/#globalstyle) in `*.treat.js` files. They have to be applied as a side effect, e.g. from a top-level layout component:
```js
import './globalStyles.treat.js';
```
5. Configure [server-side rendering](./docs/server-side-rendering.md) 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
1. Transform each alias to its corresponding CSS property name or custom shorthand
2. Resolve values from the scales available
- CSS properties associated with a custom shorthand are resolved one by one
### Example
Given the theme below:
```js
import { createTheme } from 'glaze';
export default createTheme({
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:
1. `{ px: 4 }`
2. `{ paddingX: 4 }`, after transforming aliases
3. `{ paddingLeft: 4, paddingRight: 4 }`, after unfolding custom shorthands
4. `{ paddingLeft: '1rem', paddingRight: '1rem' }`, after applying matchers
## β¨ Contributors
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
This project follows the [all-contributors](https://github.com/all-contributors/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][].
[tailwind css]: https://tailwindcss.com/
[stylesheet]: https://github.com/giuseppeg/style-sheet
[css-zero]: https://github.com/CraigCav/css-zero
[theme ui]: https://theme-ui.com/
[emotion]: https://emotion.sh/
[treat]: https://seek-oss.github.io/treat/
[twemoji]: https://twemoji.twitter.com/
