README.md

May 10, 2021 · View on GitHub

Atomic CSS-in-JS with a featherweight runtime

Backstory

Design systems embrace a component-oriented mindset. Inspired by Tailwind CSS, utility classes provide reusable styles with no unwanted side-effects. However, they have to be generated upfront.

Atomicity generalizes the former concept by instantiating style rules on demand. Serving as a solid foundation for constraint-based layouts, atomic CSS-in-JS has come to fluorish at scale.

Key features

🎳 Support for shorthand properties
🍱 Reliable pseudo selector ordering
🔐 Type safety with autocompletion
🦖 Auto-prefixing and fallback values
📚 Embedded JSDoc reference
🐾 Negligible runtime footprint
💫 Works without a framework

Getting started

Install the library with a package manager of choice, e.g.:

npm install otion

Additionally, configure frameworks as shown below:

Create React App (example, sandbox)
Gatsby (plugin, example, sandbox)
Next.js (example, sandbox)

Example

The following demo covers a wide range of use-cases.

As a core function, css returns a space-separated string of unique class names. Each property–value pair is only injected once to the library-managed style sheet.

Please refer to the core package manual for further information.

import { css, keyframes } from "otion";

// Animation keyframes are lazily initialized
const pulse = keyframes({
  from: { opacity: 1 },
  to: { opacity: 0 }
});

// Use of JSX is optional, as the solution is framework-agnostic
function Component() {
  return (
    <>
      <p className={css({ color: "blue" })}>I am blue</p>
      <p
        className={css({
          color: "blue",
          ":hover": {
            animation: `${pulse} 3s infinite alternate`
          }
        })}
      >
        I am also blue, reusing the CSS class injected by my sibling
      </p>
      <p
        className={css({
          color: "blue",
          "@media": {
            "(min-width: 768px)": {
              color: "orange"
            }
          }
        })}
      >
        I am orange if your viewport is wider than 768px
      </p>
    </>
  );
}

Is this ready for production?

The project is marked with a '0.Y.Z' version until thorough automatic tests are written for it. However, existing functionality should be safe to use.

If you decide to give otion a try, module aliasing may help migrating between CSS-in-JS libraries:

/* package.json */
{
  "devDependencies": {
    "emotion": "npm:otion@^X.Y.Z" // Could also be done in reverse
  }
}

Please bear in mind that while the APIs of otion and Emotion are similar, they're not totally interchangeable. For example, custom selectors and conditional group rules have no type-safe syntax in Emotion.

Contributors

Thanks goes to these wonderful people (emoji key):

_{Kristóf Poduszló} 🚧 💻 📖 💡 🤔 🚇	_efflam 🐛 🤔	_{Katja Lutz} 🐛 🤔	_{Mark Kvetny} 🤔	_{Jared Palmer} 📖	_{Tiago Souza} 📖 📦 💡 💻	_{Eddy Wilson} 🤔 🐛
_{Samuel Hobl} 🐛	_{Juho Vepsäläinen} 📖	_{Daniel Emod Kovacs} 🐛

This project follows the all-contributors specification. Contributions of any kind welcome!

Acknowledgements

The project's name is an ode to Emotion, an extensive CSS-in-JS runtime. Similar libraries had great impact on the initial development process, including but not limited to:

Styled Components, with its thoroughly tested approaches
Styletron, for openly discussing the caveats of atomic styling
glamor, by its simplistic and comprehensible implementation

The logo's ocean emoji is courtesy of Twemoji.