CSS is Awesome

Install css-is-awesome

cia is mixin-first. The primary API is @use 'css-is-awesome/api' as cia; + @include cia.btn(primary) on whatever selector you choose. Utility classes are an opt-in convenience for non-Sass consumers — the npm package ships zero JavaScript.

Quick start (Sass)

The 30-second path. One install, one @use, write your own selectors against the mixin API.

# install
npm install css-is-awesome
// app.scss
@use 'css-is-awesome' as cia;

.checkout-cta { @include cia.btn(primary); }
.faq-item     { @include cia.accordion; }
.modal        { @include cia.modal; }
<!-- one theme file — no markup change required -->
<link rel="stylesheet" href="/cia/themes/boilerplate.css">

That’s the whole pitch. One <link> for the theme, one @use for the mixins, your own selectors do the wiring.

Every shipped theme file emits :root, :root[data-theme="name"], so dropping a single file in as your theme.css reskins the page on its own — data-theme is optional in the single-file case. Swap the file for a different theme and nothing else has to change.

The attribute is required for the multi-theme bundle (public/theme.css, which carries all 24 themes in one file). There the data-theme value on <html> is the only thing that distinguishes one theme from the next.

<!-- the 24-theme bundle: the attribute picks which theme applies -->
<link rel="stylesheet" href="/cia/theme.css">
<html data-theme="boilerplate">

Pick your path

Four delivery shapes. Each ships the same tokens and components — only the consumption differs.

CDN

The fastest path. Two <link> tags via jsDelivr (auto-mirrored from npm). Theme first so the library can read its tokens.

<!-- in your <head> -->
<link rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/css-is-awesome@1/public/theme.css">
<link rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/css-is-awesome@1/dist/css-is-awesome.min.css">

public/theme.css is the bundle — all 24 themes in one file — so set <html data-theme="…"> to pick one. If you only need a single theme, link public/themes/<name>/theme.css instead and skip the attribute entirely.

Verify by dropping a button into the body — if it renders with the theme’s primary color, you’re wired up.

<body>
  <button class="cia-btn-primary">Verify</button>
</body>

Subresource Integrity (SRI)

For security-conscious environments, pin each <link> to a hash. jsDelivr auto-generates an .sha384 sidecar for every published file — fetch it once at the version you intend to ship and paste the value into integrity.

# fetch the sha384 for the version you're pinning
curl https://cdn.jsdelivr.net/npm/css-is-awesome@1/dist/css-is-awesome.min.css.sha384
curl https://cdn.jsdelivr.net/npm/css-is-awesome@1/public/theme.css.sha384
<!-- pinned <link> tags with integrity + crossorigin -->
<link rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/css-is-awesome@1/public/theme.css"
      integrity="sha384-…paste from above…"
      crossorigin="anonymous">
<link rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/css-is-awesome@1/dist/css-is-awesome.min.css"
      integrity="sha384-…paste from above…"
      crossorigin="anonymous">

Re-fetch the hash on every version bump — pinned versions intentionally fail to load if the file mutates upstream.

npm + SCSS

For Sass-driven projects. Install the package, then @use what you need. The simplest path is to pull the entire system in one line via scss/main; reach for the smaller subpaths when you only want the mixin API.

# install
npm install css-is-awesome
// app.scss — full system, generates CSS at this load point
@use 'css-is-awesome/scss/main';

That single line emits tokens, base resets, animations, utilities, and component classes. From here, author your own classes against the mixin API.

// Card.module.scss — zero-emit barrel, you control the output
@use 'css-is-awesome/api' as cia;

.hero-cta {
  @include cia.btn(primary, $px: 6, $r: full);
  @include cia.elevation(2);
}

Available subpaths: scss/main, scss/mixins, scss/utilities, scss/animations, scss/icons, scss/layout, scss/system, scss/theme, scss/components/<name> (buttons, data, feedback, forms, navigation, overlay), and scss/recipes/<name> (e.g. bare-tags). The scss/main entry already pulls in everything, so don’t re-include components you’ve already loaded through it.

React + Next.js

Import the stylesheets once in your root app/layout.tsx. This example uses the bundle, so it sets the active theme on the <html> element; a single-theme import needs no attribute. Components read tokens via var(--…), so you can mix and match anywhere in your tree.

// app/layout.tsx
import "css-is-awesome/theme";       // 1. tokens (all 24 themes, one file)
import "css-is-awesome/min.css";     // 2. compiled library (utilities + components)

export default function RootLayout({ children }) {
  return (
    <html lang="en" data-theme="sketchbook">
      <body>{children}</body>
    </html>
  );
}

Once the theme is active, any component can pull a token straight off CSS custom properties — no hooks, no context.

<div style={{ color: "var(--ink)" }}>
  Ink-colored text, regardless of which theme is active.
</div>

To switch themes at runtime, flip document.documentElement.dataset.theme — every token updates in one paint. Or swap css-is-awesome/min.css for css-is-awesome/core.css (tokens + resets only) when you want to author the rest yourself.

Download a theme file

Every shipped theme is a single theme.css file. Grab one, place it in your project, and link to it — the file emits :root as well as its own [data-theme] selector, so it takes effect with no markup change. This path also works for any custom theme you self-host.

24 files ship, in eight families of three: the base name auto-switches light and dark via light-dark(), while -light and -dark pin a single mode. (Terminal is the exception — terminal is dark-only by design and terminal-light is a separate daylight identity.)

Drop the file into your project (for example public/themes/ or assets/css/) and reference it with a standard <link>, paired with the compiled library.

<link rel="stylesheet" href="./path/to/theme.css">
<link rel="stylesheet" href="./path/to/css-is-awesome.min.css">

Verify

However you installed, a styled success badge is the quickest smoke test. If this renders as a filled pill with the theme’s success color, you’re done.

Installed
import Badge from "@/components/Badge";

<Badge status="success">Installed</Badge>
Theme