Skip to content
/ glaze Public

CSS-in-JS microlibrary for making design systems approachable with React

License

Notifications You must be signed in to change notification settings

kripod/glaze

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

glaze

CSS-in-JS microlibrary for making design systems approachable with React

npm Language grade: JavaScript Travis (.com) Open Collective backers and sponsors

πŸ’‘ Motivation

This project was born to combine the best of its predecessors into a single solution:

  • Utility-first CSS, as implemented by Tailwind CSS
    • 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
  • Near-zero runtime, made possible by treat
    • Theming support with legacy browsers in mind
    • Static style extraction while retaining type safety

πŸ“š Usage

  1. Install the package and its peer dependencies:

    npm install glaze treat
  2. Define a theme, preferably by overriding the default tokens:

    /* 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.

  3. Apply the theme through ThemeProvider:

    πŸ“ The Gatsby plugin for glaze does this unobtrusively.

    import { ThemeProvider } from 'glaze';
    import theme from './theme.treat';
    
    export default function Layout({ children }) {
      return <ThemeProvider theme={theme}>{children}</ThemeProvider>;
    }
  4. Style elements with the sx function:

    import { useStyling } from 'glaze';
    
    export default function Component() {
      const sx = useStyling();
    
      return (
        <p
          className={sx({
            px: 4, // Sets padding-left and padding-right to 1rem
            color: 'white',
            bg: 'red', // Sets background to #f8485e
          })}
        >
          Hello, world!
        </p>
      );
    }
  5. 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:

      import './globalStyles.treat.js';
  6. 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

  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:

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):


KristΓ³f PoduszlΓ³

🚧 πŸ’» πŸ“– πŸ’‘ πŸ€” πŸš‡

Jess Telford

πŸ“–

Corentin Leruth

πŸ“– πŸ’» ⚠️

Evan Hennessy

πŸ’»

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.