npm - css-is-awesome - Versions diffs - 1.1.0 - Mend

css-is-awesome 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (198) hide show

package/AGENTS.md +343 -0
package/CHANGELOG.md +1036 -0
package/CLAUDE.md +9 -0
package/CONTRACT.md +580 -0
package/GEMINI.md +9 -0
package/LICENSE +21 -0
package/LICENSE-third-party +88 -0
package/MIGRATION.md +312 -0
package/README.md +380 -0
package/ROADMAP.md +714 -0
package/THEMING.md +290 -0
package/THREE-TIERS.md +158 -0
package/VERSIONING.md +200 -0
package/_index.scss +34 -0
package/api.scss +16 -0
package/bin/README.md +57 -0
package/bin/cia.cjs +114 -0
package/bin/migrate-bootstrap.cjs +427 -0
package/bin/migrate-tailwind.cjs +832 -0
package/css-is-awesome.instructions.md +533 -0
package/dist/css-is-awesome.core.css +598 -0
package/dist/css-is-awesome.core.min.css +1 -0
package/dist/css-is-awesome.css +3733 -0
package/dist/css-is-awesome.min.css +1 -0
package/dist/css-is-awesome.utilities.css +2445 -0
package/dist/css-is-awesome.utilities.min.css +1 -0
package/dist/tokens.css +508 -0
package/dist/tokens.d.ts +266 -0
package/dist/tokens.min.css +1 -0
package/figma-tokens/README.md +57 -0
package/figma-tokens/primitives-brand.scss +121 -0
package/figma-tokens/semantic-dark.scss +61 -0
package/figma-tokens/semantic-light.scss +61 -0
package/figma-tokens/tokens.json +144 -0
package/llm.txt +183 -0
package/mcp/server.cjs +1495 -0
package/package.json +199 -0
package/public/icons/README.md +278 -0
package/public/icons/arrow-right.svg +4 -0
package/public/icons/check.svg +4 -0
package/public/icons/chevron-down.svg +4 -0
package/public/icons/close.svg +4 -0
package/public/icons/core/arrow-down.svg +13 -0
package/public/icons/core/arrow-left.svg +13 -0
package/public/icons/core/arrow-right.svg +13 -0
package/public/icons/core/arrow-up.svg +13 -0
package/public/icons/core/bell.svg +13 -0
package/public/icons/core/calendar.svg +15 -0
package/public/icons/core/check.svg +12 -0
package/public/icons/core/chevron-down.svg +12 -0
package/public/icons/core/chevron-left.svg +12 -0
package/public/icons/core/chevron-right.svg +12 -0
package/public/icons/core/chevron-up.svg +12 -0
package/public/icons/core/clock.svg +13 -0
package/public/icons/core/close.svg +13 -0
package/public/icons/core/copy.svg +13 -0
package/public/icons/core/download.svg +14 -0
package/public/icons/core/edit.svg +13 -0
package/public/icons/core/error.svg +14 -0
package/public/icons/core/external-link.svg +14 -0
package/public/icons/core/eye-off.svg +15 -0
package/public/icons/core/eye.svg +13 -0
package/public/icons/core/filter.svg +12 -0
package/public/icons/core/heart.svg +12 -0
package/public/icons/core/help.svg +14 -0
package/public/icons/core/home.svg +13 -0
package/public/icons/core/info.svg +14 -0
package/public/icons/core/loading.svg +12 -0
package/public/icons/core/lock.svg +13 -0
package/public/icons/core/mail.svg +13 -0
package/public/icons/core/menu.svg +14 -0
package/public/icons/core/message.svg +12 -0
package/public/icons/core/minus.svg +12 -0
package/public/icons/core/more-horizontal.svg +14 -0
package/public/icons/core/pause.svg +13 -0
package/public/icons/core/play.svg +12 -0
package/public/icons/core/plus.svg +13 -0
package/public/icons/core/refresh.svg +15 -0
package/public/icons/core/save.svg +14 -0
package/public/icons/core/search.svg +13 -0
package/public/icons/core/settings.svg +13 -0
package/public/icons/core/share.svg +14 -0
package/public/icons/core/sort.svg +15 -0
package/public/icons/core/star.svg +12 -0
package/public/icons/core/success.svg +13 -0
package/public/icons/core/trash.svg +16 -0
package/public/icons/core/unlock.svg +13 -0
package/public/icons/core/upload.svg +14 -0
package/public/icons/core/user.svg +13 -0
package/public/icons/core/users.svg +15 -0
package/public/icons/core/warning.svg +14 -0
package/public/icons/download.svg +4 -0
package/public/icons/edit.svg +4 -0
package/public/icons/menu.svg +4 -0
package/public/icons/search.svg +4 -0
package/public/theme.css +4179 -0
package/public/themes/README.md +102 -0
package/public/themes/boilerplate/theme.css +154 -0
package/public/themes/boilerplate-dark/theme.css +171 -0
package/public/themes/boilerplate-light/theme.css +171 -0
package/public/themes/cupertino/theme.css +165 -0
package/public/themes/cupertino-dark/theme.css +200 -0
package/public/themes/cupertino-light/theme.css +227 -0
package/public/themes/glass/theme.css +190 -0
package/public/themes/glass-dark/theme.css +201 -0
package/public/themes/glass-light/theme.css +229 -0
package/public/themes/graphite/theme.css +155 -0
package/public/themes/graphite-dark/theme.css +223 -0
package/public/themes/graphite-light/theme.css +191 -0
package/public/themes/press/theme.css +189 -0
package/public/themes/press-dark/theme.css +199 -0
package/public/themes/press-light/theme.css +235 -0
package/public/themes/prism/theme.css +159 -0
package/public/themes/prism-dark/theme.css +185 -0
package/public/themes/prism-light/theme.css +188 -0
package/public/themes/sketchbook/theme.css +152 -0
package/public/themes/sketchbook-dark/theme.css +194 -0
package/public/themes/sketchbook-light/theme.css +188 -0
package/public/themes/terminal/theme.css +159 -0
package/public/themes/terminal-dark/theme.css +229 -0
package/public/themes/terminal-light/theme.css +152 -0
package/scripts/README.md +70 -0
package/scripts/icon-contract.json +67 -0
package/scripts/icon-validator.js +205 -0
package/scripts/prepare-dist.mjs +65 -0
package/scripts/theme-a11y.js +415 -0
package/scripts/theme-contract.json +171 -0
package/scripts/theme-validator.js +674 -0
package/scss/README.md +55 -0
package/scss/_animations-utilities.scss +107 -0
package/scss/_animations.scss +248 -0
package/scss/_app-styles.scss +15 -0
package/scss/_generator.scss +174 -0
package/scss/_icons.scss +475 -0
package/scss/_index.scss +17 -0
package/scss/_layout.scss +597 -0
package/scss/_mixins.scss +1036 -0
package/scss/_system.scss +291 -0
package/scss/_utilities.scss +377 -0
package/scss/api.scss +61 -0
package/scss/components/_accordion.scss +72 -0
package/scss/components/_buttons.scss +171 -0
package/scss/components/_copy-button.scss +69 -0
package/scss/components/_data.scss +190 -0
package/scss/components/_feedback.scss +197 -0
package/scss/components/_forms.scss +272 -0
package/scss/components/_index.scss +17 -0
package/scss/components/_navigation.scss +186 -0
package/scss/components/_overlay.scss +259 -0
package/scss/components/_stepper.scss +159 -0
package/scss/components/_tabs.scss +72 -0
package/scss/core.scss +54 -0
package/scss/examples/_theming.scss +107 -0
package/scss/examples/_usage.scss +317 -0
package/scss/main.scss +64 -0
package/scss/recipes/README.md +110 -0
package/scss/recipes/_bare-tags.scss +232 -0
package/scss/recipes/_recipe-template.md +119 -0
package/scss/recipes/combobox.md +509 -0
package/scss/recipes/dialog.md +265 -0
package/scss/recipes/print-to-pdf.md +263 -0
package/scss/theme/README.md +67 -0
package/scss/theme/_brand.scss +18 -0
package/scss/theme/_colors-dark.scss +68 -0
package/scss/theme/_colors-light.scss +70 -0
package/scss/theme/_components.scss +94 -0
package/scss/theme/_icons.scss +104 -0
package/scss/theme/_index.scss +62 -0
package/scss/theme/_shadows.scss +65 -0
package/scss/theme/_shape.scss +13 -0
package/scss/theme/_typography.scss +9 -0
package/scss/theme/registry.json +447 -0
package/scss/themes/boilerplate-dark.scss +212 -0
package/scss/themes/boilerplate-light.scss +209 -0
package/scss/themes/boilerplate.scss +181 -0
package/scss/themes/cupertino-dark.scss +238 -0
package/scss/themes/cupertino-light.scss +266 -0
package/scss/themes/cupertino.scss +194 -0
package/scss/themes/glass-dark.scss +238 -0
package/scss/themes/glass-light.scss +266 -0
package/scss/themes/glass.scss +220 -0
package/scss/themes/graphite-dark.scss +260 -0
package/scss/themes/graphite-light.scss +228 -0
package/scss/themes/graphite.scss +182 -0
package/scss/themes/press-dark.scss +237 -0
package/scss/themes/press-light.scss +273 -0
package/scss/themes/press.scss +241 -0
package/scss/themes/prism-dark.scss +217 -0
package/scss/themes/prism-light.scss +220 -0
package/scss/themes/prism.scss +190 -0
package/scss/themes/sketchbook-dark.scss +231 -0
package/scss/themes/sketchbook-light.scss +231 -0
package/scss/themes/sketchbook.scss +178 -0
package/scss/themes/terminal-dark.scss +267 -0
package/scss/themes/terminal-light.scss +175 -0
package/scss/themes/terminal.scss +185 -0
package/scss/tokens.scss +23 -0
package/scss/utilities-only.scss +4 -0

package/THEMING.md ADDED Viewed

@@ -0,0 +1,290 @@
+# Theming Guide
+css-is-awesome is fully themeable. Pick the method that fits your stack.
+## Built-in theme names
+24 themes, in 8 families. Each family ships three files:
+- `<family>` — dual-mode, both light and dark in one file via native `light-dark()`
+- `<family>-light` — light only
+- `<family>-dark` — dark only
+The families are `boilerplate`, `sketchbook`, `press`, `prism`, `cupertino`,
+`glass`, `graphite`, `terminal`. (`terminal` is dark-only by design — CRT
+phosphor; `terminal-light` is its daylight companion.)
+### The selector model — why `data-theme` is usually optional
+Every theme file emits:
+```css
+:root, :root[data-theme="press-dark"] { … }
+```
+The bare `:root` half means **dropping a single theme file in restyles the page
+with no markup change**. Link it, or copy it over your `theme.css`, and you're
+done — you do *not* need to set `<html data-theme="…">` to match.
+`data-theme` is still **required** for the all-in-one bundle (`public/theme.css`),
+which carries all 24 themes in one file. There the bare `:root` is omitted, and
+the attribute is the only thing distinguishing one theme from another:
+```html
+<link rel="stylesheet" href="/theme.css">
+<html data-theme="press-dark">
+```
+If you're authoring your own theme with the `theme()` mixin, the same switch is
+the `$standalone` argument:
+```scss
+@mixin theme($name, $scheme: light dark, $standalone: true) { … }
+```
+`$standalone: true` (the default) emits `:root, :root[data-theme="<name>"]`.
+Pass `$standalone: false` when the theme is going into a multi-theme bundle.
+### Library defaults sit under `:where(:root)`
+cia's own default token values emit under `:where(:root)`, specificity `0,0,0`.
+Any theme declaration — `:root`, `[data-theme]`, whatever — outranks them
+regardless of load order. That's `:where()`, deliberately, not `@layer`; cia
+never asks a consumer to adopt layers.
+See [`CHANGELOG.md`](./CHANGELOG.md) for the timeline and
+[`MIGRATION.md`](./MIGRATION.md) for upgrade steps.
+---
+## Quick Brand Swap (3 lines)
+Replace the default Royal Blue brand with your own colors — just set these CSS custom properties:
+```css
+:root {
+  --brand-primary: #E11D48;
+  --action-primary-default: #E11D48;
+  --action-primary-hover: #BE123C;
+}
+```
+That's it. Every button, link accent, and focus ring now uses your brand color.
+Load this *after* the theme file — a theme's `:root` block and your `:root`
+block have the same specificity, so source order decides.
+---
+## Method 1: CSS Custom Properties (Runtime)
+Override any token at `:root`. Works with the compiled CSS — no build step needed.
+```css
+:root {
+  /* Brand */
+  --brand-primary: #E11D48;
+  --brand-primary-hover: #BE123C;
+  --brand-primary-active: #9F1239;
+  /* Actions (tie to brand) */
+  --action-primary-default: #E11D48;
+  --action-primary-hover: #BE123C;
+  --action-primary-active: #9F1239;
+  /* Typography */
+  --font-primary: "Poppins", sans-serif;
+  /* Shape */
+  --radius-md: 0.5rem;
+  --radius-lg: 1rem;
+  /* Spacing — the numbered scale is the source of truth */
+  --space-4: 1.25rem;
+}
+```
+### Spacing is themeable
+Set the **numbered** scale (`--space-0` … `--space-9`). That's what
+`cia.space(4)` compiles to — `var(--space-4)` — so changing `--space-4` changes
+every component that asks for step 4.
+The t-shirt names (`--space-2xs/xs/sm/md/lg/xl`) are optional aliases, emitted
+as *references* into that scale:
+```css
+--space-xs: var(--space-1);
+--space-sm: var(--space-2);
+--space-md: var(--space-4);
+--space-lg: var(--space-5);
+--space-xl: var(--space-6);
+```
+So they follow the numbered scale automatically — you rarely need to set them.
+Setting `--space-md` to a literal only re-points that one alias; it does not
+change what `space(4)` resolves to.
+### Component shape tokens
+`--btn-radius`, `--card-radius`, `--input-radius`, `--modal-radius`,
+`--badge-radius` and `--tag-radius` are what the components actually read, and
+they cascade from the generic scale by default:
+```css
+--btn-radius: var(--radius-md, 0.25rem);
+```
+Move `--radius-*` to reshape everything; set one component token to make a
+single exception. (There is no `--radius-button` / `--radius-card` /
+`--radius-input` / `--radius-modal` / `--radius-avatar` / `--radius-badge` —
+those names were removed because nothing read them.)
+### Available token families
+| Prefix | Examples |
+|--------|----------|
+| `--brand-*` | `primary`, `secondary`, `accent` + hover/active |
+| `--background-*` | `default`, `subtle`, `navbar` |
+| `--surface-*` | `default`, `subtle`, `muted`, `emphasis` |
+| `--text-*` | `primary`, `secondary`, `muted`, `inverse`, `link` |
+| `--border-*` | `default`, `subtle`, `emphasis`, `focus` |
+| `--action-primary-*` | `default`, `hover`, `active` |
+| `--action-secondary-*` | `default`, `hover`, `active` |
+| `--success/warning/error/info-*` | `default`, `hover`, `subtle`, `text` |
+| `--font-*` | `primary`, `serif`, `mono` |
+| `--font-size-*` | `xs` through `6xl` |
+| `--font-weight-*` | `light`, `normal`, `medium`, `semibold`, `bold`, `black` |
+| `--line-height-*` | `none`, `tight`, `snug`, `normal`, `relaxed`, `loose` |
+| `--radius-*` | `none`, `sm`, `md`, `lg`, `xl`, `2xl`, `full` |
+| `--*-radius` | `btn`, `card`, `input`, `modal`, `badge`, `tag` — optional, default to the `--radius-*` scale |
+| `--shadow-*` | `sm`, `md`, `lg`, `xl`, `2xl`, `inner`, `none` |
+| `--space-*` | `0` through `9` (the scale themes declare) — plus optional aliases `2xs`, `xs`, `sm`, `md`, `lg`, `xl` |
+| `--z-*` | `hide`, `base`, `dropdown`, `sticky`, `fixed`, `backdrop`, `modal`, `popover`, `tooltip`, `toast` |
+| `--duration-*` | `instant`, `fast`, `normal`, `slow`, `slower` |
+| `--opacity-*` | `0` through `100` |
+---
+## Method 2: SCSS Overrides (Compile-Time)
+Override theme maps when importing. Full control over every token.
+```scss
+@use "css-is-awesome/scss/theme" with (
+  $brand: (
+    primary:        #E11D48,
+    primary-hover:  #BE123C,
+    primary-active: #9F1239,
+    secondary:      #8B5CF6,
+    secondary-hover:#7C3AED,
+    secondary-active:#6D28D9,
+    accent:         #06B6D4,
+    accent-hover:   #0891B2,
+  )
+);
+@use "css-is-awesome/scss/generator";
+@include generator.generate-theme;
+```
+You can override any theme map: `$brand`, `$colors-light`, `$colors-dark`, `$fonts`, `$radius`, `$shadows-light`, `$shadows-dark`.
+---
+## Method 3: Multi-Brand Theming
+Use `data-theme` attributes for brand + mode combinations. Scope them the way
+cia's own themes do — `:root[data-theme="…"]`, specificity `0,2,0` — so they
+outrank any bare `:root` block from a dropped-in theme file:
+```css
+:root[data-theme="brand-a-light"] {
+  --brand-primary: #E11D48;
+  --action-primary-default: #E11D48;
+  --action-primary-hover: #BE123C;
+  --action-primary-active: #9F1239;
+}
+:root[data-theme="brand-a-dark"] {
+  --brand-primary: #FB7185;
+  --action-primary-default: #FB7185;
+  --action-primary-hover: #F43F5E;
+  --action-primary-active: #E11D48;
+  --background-default: #0A0A0A;
+  --surface-default: #151515;
+  --text-primary: #FFF;
+  --border-default: #2A2A2A;
+}
+```
+Switch brands in JS:
+```js
+document.documentElement.setAttribute("data-theme", "brand-a-dark");
+```
+See `scss/examples/_theming.scss` for complete Brand A (Rose) and Brand B (Teal) examples.
+---
+## Theme Switching
+**cia ships zero JavaScript.** There is no `ciaTheme` object and no
+theme-switching script in the package — switching is four lines you own.
+### You may not need to switch at all
+A dual-mode theme (the unsuffixed ones: `sketchbook`, `prism`, `glass` …)
+already follows the operating system. Its colours are `light-dark()` pairs and
+its `color-scheme` is `light dark`, so light and dark both work with no
+attribute, no script, and no listener. Ship one file and you are done.
+You only need the code below to let a user override the OS — a manual
+light/dark toggle, or a picker across several themes.
+### Switching modes
+Set `color-scheme` on the root element:
+```js
+document.documentElement.style.colorScheme = 'dark';   // or 'light', or '' for auto
+```
+### Switching themes
+Set the attribute. This requires the multi-theme bundle
+(`public/theme.css`), which carries every theme keyed by `data-theme`:
+```js
+document.documentElement.dataset.theme = 'prism';
+```
+With a single theme file you do not need this — the file's bare `:root`
+already applies. See [The selector model](#the-selector-model--why-data-theme-is-usually-optional).
+### Avoiding the flash
+Persisting a choice means reading it before first paint. Inline this in
+`<head>`, above your stylesheet links — an external script would load too late
+and the wrong theme would paint first:
+```html
+<script>
+  try {
+    const t = localStorage.getItem('theme');
+    if (t) document.documentElement.dataset.theme = t;
+    const m = localStorage.getItem('mode');
+    if (m) document.documentElement.style.colorScheme = m;
+  } catch (e) { /* private mode — fall through to the default */ }
+</script>
+```
+Then write to `localStorage` whenever the user chooses. That is the whole
+feature; a dependency would not make it shorter.
+---
+## Figma Token Sync
+Import `figma-tokens/tokens.json` into [Tokens Studio for Figma](https://tokens.studio/) to keep design and code in sync. The JSON follows the Tokens Studio format with `value` and `type` fields.

package/THREE-TIERS.md ADDED Viewed

@@ -0,0 +1,158 @@
+# Three Tiers, One Source of Truth
+css-is-awesome ships three authoring surfaces for the same components. Pick the tier that matches your stack — they all resolve to the same mixin output, so styling stays consistent across an app that mixes them.
+> One router mixin per component. Three doors into it.
+---
+## Tier 1 — Drop-in CSS + HTML (no build)
+```html
+<link rel="stylesheet" href="css-is-awesome.min.css">
+<link rel="stylesheet" href="theme-sketchbook.css">
+<main class="cia-container">
+  <h1>Welcome</h1>
+  <a class="cia-btn-primary" href="/start">Get started</a>
+  <a class="cia-btn-outline" href="/docs">Read docs</a>
+  <article class="cia-card">
+    <h4>Sketchbook theme</h4>
+    <p>Warm paper, sumi ink, indigo accent.</p>
+  </article>
+</main>
+```
+**Audience:** designers, marketing pages, prototypes, anyone without a build step.
+**Rules:** one class per element. No BEM, no `__element` / `--modifier` chains. One CSS file, one theme file, ship.
+---
+## Tier 2 — SCSS mixins + HTML (with build)
+```scss
+// component styles (Card.module.scss, app.scss, …)
+@use 'css-is-awesome/api' as cia;   // one zero-emit barrel — the whole API
+.hero-cta {
+  @include cia.btn(primary, $px: 6, $r: full);
+  @include cia.elevation(2);
+}
+.checkout-cancel { @include cia.btn(outline); }
+.product-card    { @include cia.card-base($shadow: 2); }
+```
+> Prefer granular imports? `@use 'css-is-awesome/scss/components/buttons' as b;` etc. still work — the `/api` barrel just bundles them under one namespace.
+```html
+<a class="hero-cta" href="/buy">Buy now</a>
+<a class="checkout-cancel" href="/cart">Back to cart</a>
+<article class="product-card">…</article>
+```
+**Audience:** product teams that want their own domain vocabulary in markup (`hero-cta`, `product-card`) without giving up a design system.
+**Rules:** author your own class names. Variant is an argument to the mixin, not a class modifier. Every parameter overridable.
+### The rule that makes Tier 2 work: change the input, not the output
+Your class name, cia's mixin inside it, and **every customization goes through the mixin's arguments**. The mixin is a knob-board — each look-and-feel dimension is an input, so restyling never means writing the CSS the mixin already controls.
+```scss
+// ✅ change the knob
+.filter-bar { @include cia.flex($direction: column, $align: start, $gap: 2); }
+// ❌ call the mixin, then fight it
+.filter-bar {
+  @include cia.flex($justify: between);
+  align-items: flex-start;   // $align: start already does this
+  flex-direction: column;    // $direction: column already does this
+}
+```
+Both compile. The second is worse in a way that compounds: those two hand-written lines are now invisible to the design system. They don't follow a token, they don't respond to a theme swap, and the next person can't tell whether they were a deliberate exception or a missing argument.
+**If a visual dimension can only be reached by overriding in CSS, that is a missing input — add it to the mixin.** That's the rule cia holds itself to, and it's why `space()`, `transition()` and `animate()` all accept raw values as well as scale keys: a consumer should never have to abandon a mixin to keep one specific number.
+### Where raw CSS *is* correct
+Not everything is cia's job, and pretending otherwise produces worse code than writing plain CSS. Write ordinary CSS when the thing you are styling is genuinely yours:
+- **Bespoke identity** — a rotated stamp, a brand illustration, a logo's overflow trick. Preserve the exact values; don't token-swap something whose specific-ness is the point.
+- **One-off geometry** — a `clip-path`, a `grid-template-areas` for a layout only this page has, an animation of your own product's mascot.
+- **Anything cia has no mixin for.** Reach for a mixin first, check `get_mixin` over MCP if unsure, and write CSS when the answer is genuinely "there isn't one."
+The split to hold in your head: **cia owns the system values — colour, spacing, type, radius, motion, elevation. You own the composition and the things that make your product look like itself.** Mixing the two is fine. Re-implementing the first half by hand is the mistake.
+---
+## Tier 3 — Bare tags (opt-in Pico-mode)
+```scss
+// app.scss — one line styles the whole site
+@use 'css-is-awesome/scss/recipes/bare-tags';
+```
+```html
+<h1>Welcome</h1>
+<button>Save</button>
+<table>…</table>
+<input type="email">
+```
+**Audience:** content-heavy sites, blog posts, READMEs rendered as HTML, anywhere the author doesn't want to think about classes.
+**Rules:** zero classes required. The recipe styles every common bare tag at specificity `0,0,1` — no `@layer`, no `:where()`. Any class-based selector you add wins automatically.
+---
+## The same button across all three tiers
+```html
+<!-- Tier 1 -->
+<button class="cia-btn-primary">Save</button>
+<!-- Tier 2 -->
+<button class="save-btn">Save</button>
+```
+```scss
+.save-btn { @include b.btn(primary); }
+```
+```html
+<!-- Tier 3 -->
+<button>Save</button>
+```
+All three resolve to the same `btn(primary)` mixin output. Mix them in one app — a Tier 3 bare `<button>` and a Tier 1 `.cia-btn-primary` render identically.
+---
+## Architecture
+- **Single source of truth.** One mixin per component (`btn`, `card`, `input`, `alert`, …) with private internals.
+- **Router pattern.** `btn(variant)` dispatches to private mixins. Variant is an arg, not a class modifier — that's why there's no BEM.
+- **Tier 1** = router output baked into single utility classes (`.cia-btn-primary`, `.cia-btn-outline`, …).
+- **Tier 2** = direct router `@include` in author SCSS under custom class names.
+- **Tier 3** = router `@include` applied to bare tag selectors via the recipe.
+- **Tier 4 (React).** Components in `src/` wrap the same mixins through CSS Modules. Same output, framework-aware ergonomics.
+Change the router, every tier updates. Add a variant once, every tier gets it.
+---
+## Picking a tier
+| You're building… | Use |
+|---|---|
+| A landing page, prototype, or a static site with no build | Tier 1 |
+| A product app where designers want semantic class names | Tier 2 |
+| A content site, blog, or generated HTML where classes are noise | Tier 3 |
+| A React/Next app | Tier 4 — see `src/` and the docs site |
+Tiers compose. A Tier 2 product can drop in a Tier 3 recipe for its `/blog` route, and a Tier 1 marketing page can sit next to a Tier 4 app under the same theme file.
+---
+## See also
+- [README.md](./README.md) — install, quick start, scripts
+- [THEMING.md](./THEMING.md) — token contract, custom themes, dark mode
+- [css-is-awesome.instructions.md](./css-is-awesome.instructions.md) — authoring rules in one page

package/VERSIONING.md ADDED Viewed

@@ -0,0 +1,200 @@
+# Versioning Policy
+How `css-is-awesome` versions its public surfaces, deprecates old APIs, and records changes. This document owns the **policy**; release mechanics (tag, build, publish) live in [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+## Public surfaces
+`css-is-awesome` ships three versioned public surfaces. A change to any of them is a versioned change.
+| Surface             | Lives in                                   | Consumed as                                |
+| ------------------- | ------------------------------------------ | ------------------------------------------ |
+| CSS class names     | `dist/*.css`                               | HTML / SCSS / React class strings          |
+| SCSS mixin API      | `scss/` (`_mixins.scss`, `_layout.scss`, …) | Authors who `@use "css-is-awesome/scss/main"` |
+| Token contract      | [`CONTRACT.md`](./CONTRACT.md) + [`scripts/theme-contract.json`](./scripts/theme-contract.json) | Themes declared in a `:root { … }` block   |
+The **library version** lives in [`package.json`](./package.json). The **contract version** lives in the `version` field of `scripts/theme-contract.json`. They move together on most MAJOR bumps but are independent: a library MINOR can ship without bumping the contract.
+---
+## 1. Semantic Versioning
+This project follows [SemVer 2.0.0](https://semver.org/spec/v2.0.0.html) — `MAJOR.MINOR.PATCH`.
+### MAJOR — `x.0.0`
+Any change that can break a consumer upgrading blindly.
+| Change                                                                    | Example                                                |
+| ------------------------------------------------------------------------- | ------------------------------------------------------ |
+| Public CSS class renamed or removed                                       | `.btn-primary` → `.btn-cta`                            |
+| SCSS mixin renamed, removed, or breaking signature change                 | `m.btn($variant)` now requires `$size`                 |
+| SCSS mixin default changes rendered output                                | `m.card()` default radius flips from `md` → `lg`       |
+| Contract: required token renamed or removed                               | `--surface-default` → `--surface-base`                 |
+| Contract: `version` field bumps to a new major (`"1"` → `"2"`)            | Required-token removal in `scripts/theme-contract.json` |
+| React component removed, renamed, or incompatible prop change             | `<Button variant>` values narrowed                     |
+| Peer-dependency floor rises                                               | `react: >=18` → `react: >=19`                          |
+### MINOR — `0.x.0`
+Additive, non-breaking changes.
+| Change                                                       | Example                                           |
+| ------------------------------------------------------------ | ------------------------------------------------- |
+| New public CSS class                                         | `.cia-grid-auto-fit` added                        |
+| New public SCSS mixin                                        | `m.cluster($gap)` added                           |
+| New optional token added to contract (`"1"` → `"1.1"`)       | `--dropdown-offset-y` added to component section  |
+| New React component                                          | `<DataTable>` added                               |
+| Additive component prop with a sensible default              | `<Button loading>` added, defaults to `false`     |
+| New utility class (`.cia-*`)                                 | `.cia-text-balance` added                         |
+### PATCH — `0.0.x`
+Internal-only or visually-identical changes.
+| Change                                                    | Example                                            |
+| --------------------------------------------------------- | -------------------------------------------------- |
+| Bug fix that does not change public API                   | Focus ring no longer clipped on `.btn-ghost`       |
+| Documentation content change                              | Typo fix in `CONTRACT.md`                          |
+| Build output micro-optimization with no visual change     | Redundant `0` removed from compiled shadows        |
+| Security patch that does not change public API            | Upstream Sass `@import` path sanitization          |
+| Dependency bump within an already-allowed range           | `sass ^1.97.1` → `sass ^1.98.0`                    |
+---
+## 2. Pre-1.0 rules
+While the library is pre-1.0 (`0.x.x`), the rules above apply with one carve-out: we reserve the right to ship a genuinely-breaking change as a **MINOR** bump if it is the right call for the system's long-term shape. Every such change is:
+1. Called out loudly in the `CHANGELOG.md` entry under `### Changed` with a **BREAKING** prefix.
+2. Called out again in the release notes with a migration snippet.
+**`1.0.0` locks the contract.** After 1.0, breaking changes require a MAJOR bump, no exceptions.
+---
+## 3. Deprecation policy
+Every public symbol — CSS class, SCSS mixin, React prop, contract token — follows the same lifecycle: **deprecate → warn → remove**.
+### Lifecycle
+1. **Mark** the symbol with an inline `@deprecated` comment citing the replacement and the intended removal version.
+2. **Warn** at use-time:
+    - React components / hooks → `console.warn(…)` once per session (dedupe by symbol name).
+    - SCSS mixins → `@warn "m.old-name is deprecated, use m.new-name (removed in 1.0)";`.
+    - CSS classes / tokens → no runtime warning possible; rely on the `@deprecated` JSDoc and changelog.
+3. **Announce** in the next MINOR release's `CHANGELOG.md` under `### Deprecated`.
+4. **Keep functional** for **at least one full MINOR release cycle** after the deprecation lands.
+5. **Remove** only in a MAJOR bump.
+### Example — deprecating a mixin
+```scss
+// scss/_mixins.scss
+/// @deprecated Use `m.btn-primary` with `$bg: action-secondary-default` override.
+///             Removed in 1.0.
+@mixin btn-secondary($size: md) {
+  @warn "m.btn-secondary is deprecated; use m.btn-primary with $bg: action-secondary-default. Removed in 1.0.";
+  @include btn-primary($size, $bg: action-secondary-default);
+}
+```
+### Example — deprecating a token
+A deprecated contract token:
+1. Stays in `scripts/theme-contract.json` under `required` so existing themes keep validating.
+2. Gets a `> **Deprecated — removed in contract v2.**` note in its row in `CONTRACT.md`.
+3. Bumps the contract `version` by a minor step (e.g. `"1.1"` → `"1.2"`).
+4. Is removed from `required` only when the contract `version` bumps to the next major (`"2"`), which coincides with the next library MAJOR.
+---
+## 4. Changelog format
+Changelog follows [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/) verbatim. Each release entry uses these sections, in this order, omitting any that are empty:
+- `Added` — new features.
+- `Changed` — changes to existing functionality.
+- `Deprecated` — soon-to-be-removed features.
+- `Removed` — removed features.
+- `Fixed` — bug fixes.
+- `Security` — vulnerabilities and mitigations.
+Entries are written in past tense, grouped by section, and link issue / PR numbers. The top of [`CHANGELOG.md`](./CHANGELOG.md) always carries an `## [Unreleased]` section where in-flight changes accumulate between releases.
+### Example release block
+```md
+## [0.6.0] - 2026-05-12
+### Added
+- `<DataTable>` component with generic row typing and optional pagination (#142).
+- Theme validator now supports `--watch` mode (#138).
+### Changed
+- `Pagination` props: native `HTMLAttributes.onChange` is `Omit`ped so the custom `onChange(page)` stops colliding. Non-breaking for existing consumers (#140).
+### Deprecated
+- `m.btn-secondary` — use `m.btn-primary` with `$bg: action-secondary-default` override. Removed in 1.0 (#143).
+### Fixed
+- Theme picker no longer injected duplicate `<link>` elements on first paint (#145).
+```
+---
+## 5. Conventional Commits → Changelog
+Commits follow [Conventional Commits](https://www.conventionalcommits.org/). The prefix maps to a changelog section:
+| Commit prefix                             | Changelog section               |
+| ----------------------------------------- | ------------------------------- |
+| `feat:`                                   | `Added`                         |
+| `feat!:` or `BREAKING CHANGE:` footer     | `Changed` (breaking — MAJOR)    |
+| `fix:`                                    | `Fixed`                         |
+| `perf:`                                   | `Changed`                       |
+| `docs:`                                   | *omit*                          |
+| `refactor:`                               | *omit*                          |
+| `test:`                                   | *omit*                          |
+| `chore:`                                  | *omit*                          |
+| `build:` / `ci:`                          | *omit*                          |
+A commit can carry a `Deprecates:` footer to force an entry under `### Deprecated`, or a `Security:` footer to force `### Security`, regardless of prefix.
+---
+## 6. Release process
+The policy in this document tells you **what** a version number means. The mechanics of cutting a release — tagging, building `dist/*.css`, validating themes, publishing to npm — live in [`CONTRIBUTING.md`](./CONTRIBUTING.md) and are automated per Epic 5.
+Every release, at minimum:
+1. Promotes `## [Unreleased]` to `## [x.y.z] - YYYY-MM-DD` in `CHANGELOG.md`.
+2. Bumps `version` in `package.json` per the rules in §1.
+3. Bumps `version` in `scripts/theme-contract.json` if the contract changed.
+4. Runs `npm run validate-themes` — must pass.
+5. Rebuilds `dist/*.css` via `npm run build:css:all`.
+6. Tags the commit `vX.Y.Z` and pushes.
+---
+## 7. How to read the version
+Two version numbers, two files:
+| Version             | Source                                                        | Bumps on                                                                  |
+| ------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Library version     | `version` field of [`package.json`](./package.json)           | Any change to CSS / SCSS / React public surfaces per §1.                  |
+| Contract version    | `version` field of [`scripts/theme-contract.json`](./scripts/theme-contract.json) | Contract-only changes (new optional token → minor; required token renamed or removed → major). |
+They usually move together on a library MAJOR. They move independently on MINOR and PATCH.
+---
+## See also
+- [`CHANGELOG.md`](./CHANGELOG.md) — the actual change log.
+- [`CONTRACT.md`](./CONTRACT.md) — the token contract.
+- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — release mechanics and contributor workflow.
+- [`ROADMAP.md`](./ROADMAP.md) — where the library is headed toward `1.0.0`.

package/_index.scss ADDED Viewed

@@ -0,0 +1,34 @@
+// ============================================================================
+// Package-root shim for `@use 'css-is-awesome'`
+// ============================================================================
+// Sass does NOT read package.json "exports". It resolves a bare specifier by
+// looking for a file on disk relative to a load path — for `css-is-awesome`
+// that means `node_modules/css-is-awesome/_index.scss`. Without this file the
+// README's headline example fails on a clean install.
+//
+// This file must behave the way `exports["."].sass` does, or Sass users and
+// bundler users get different results from the same import. It forwards BOTH
+// halves deliberately:
+//
+//   @forward './scss/index'  — the authoring API (mixins, functions, token
+//                              maps) plus the global .cia-anim-* utilities.
+//                              Without this, `@use 'css-is-awesome' as cia;`
+//                              exports no members and `cia.btn()` fails to
+//                              resolve: scss/main.scss uses `@use`, not
+//                              `@forward`, so it re-exports nothing.
+//
+//   @use './scss/main'       — emits the tokens, resets and base rules.
+//                              Without this the import prints no `:root` block
+//                              at all, contradicting the documented "emit the
+//                              tokens once at your root" model. That exact
+//                              regression shipped briefly and is now asserted
+//                              by validate-package.
+//
+// Sass evaluates each module once, so modules shared by the two halves
+// (animations-utilities in particular) are not emitted twice — verified.
+//
+// This is the GLOBAL entry point: it emits ~72 KB and belongs in a root
+// stylesheet, included once. Component stylesheets want `css-is-awesome/api`,
+// which is zero-emit and safe under Next.js CSS Modules pure mode.
+@forward './scss/index';
+@use './scss/main';