css-is-awesome 1.8.0 → 1.8.2

package/AGENTS.md

@@ -26,7 +26,12 @@ When asked to add a UI element, follow this order:
 4. **All values come from tokens.** Never hardcode `#3A5FCD`, `1rem`, `8px`. Use `cia.color(primary)`, `cia.space(4)`, `cia.radius(md)`.
 5. **No BEM.** No `__element` / `--modifier` chains. `cia-` is a single-class namespace prefix, not BEM.
 6. **No JavaScript.** Cia ships zero JS in the npm package. The 6 interactive components (accordion, modal, tooltip, dropdown, tabs, copy-button) use native HTML primitives — `<details name>`, `<dialog>`, `[popover]`, radio + `:has()`. Mobile navigation follows the same doctrine: the `hamburger` / `drawer` / `sheet` / `dock` mixin family rides `[popover]` + CSS Grid — see the `mobile-nav` recipe (hamburger + drawer) and the `bottom-nav` recipe (dock + sheets). **This rule binds cia, not you.** If you're *consuming* cia (building an app/component library on top of it), write JavaScript/framework components freely — React, SVG charts, interactivity, all of it — and use cia purely for styling (mixins + tokens). Compose the mixins to build any visual you want; you are not limited to cia's pre-made component mixins.
-7. **Pages stack by named grid areas — the layout mixins own the shell.** Every page's structure is declared once as `grid-template-areas` (`"navbar" "hero" … "footer"`), and each section claims its slot with `grid-area`. Never hand-write that: use `cia.page-layout(default | sidebar-left | sidebar-right | holy-grail)` for a full viewport shell (100dvh, sticky footer, auto mobile collapse), `cia.layout((sidebar content toc), $tracks: …)` for custom rows of regions, and `cia.page-header` / `cia.page-main` / `cia.page-footer` / `cia.area(name)` for the children. Named areas are the single source of truth for stacking — mobile is just a different `grid-template-areas`, not a pile of margin overrides. Baseline since 2020.
+7. **Grid is the skeleton; Flex is the quick moves.** Three levels, strictly:
+   - **The page shell is CSS Grid with landmark-named areas.** The body's areas ARE the document's landmarks — `nav`, `main`, `footer` — so the area map reads like the page and screen readers get the structure for free. Declared once via `cia.page-layout(default | sidebar-left | sidebar-right | holy-grail)` (100dvh, sticky footer, auto mobile collapse) or `cia.layout((sidebar content toc), $tracks: …)`; children claim slots with `cia.page-header` / `cia.page-main` / `cia.page-footer` / `cia.area(name)`. Baseline since 2020.
+   - **The doctrine scales inward: any control-dense region gets its own named-area grid.** A docs article (`header / demo / usage / tabs / footer`), a selections rail (`filter / list`), a dashboard — when a region has many controls, name its rows with `cia.layout(...)` too. Nested grids all the way down where density warrants; the grid's `gap` is the region's entire vertical rhythm (children carry no rhythm margins).
+   - **Flex lives at the leaves** — simple rows and columns you flip with one command: `@include cia.flex($direction: column)` turns a row into a stack. Flex arranges the contents of a slot the grid gave it; it never builds the page.
+
+   Mobile is just a different `grid-template-areas` map — restack, hide (with `display: none`; omitting an area does not hide its element), reorder — never a pile of margin overrides. Never hand-write `grid-template-areas`; the layout mixins own it.
 8. **On phones, things take the space they're in.** Below the mobile breakpoint an interactive surface fills its *container* — 100% of the column it lives in, inside the page's existing padding and formatting (never edge-to-edge past the page's gutters, never a floating mid-width popup). Triggers stretch to 100% with `justify-content: space-between` (label left, affordance right). A top-layer popover menu can't size to its container directly, so match its trigger via CSS anchor positioning (`anchor-name` on the trigger; `inset-inline: anchor(start) anchor(end)` under `@supports (anchor-name: --a)`) — opening directly under the trigger, with `position-try-fallbacks: flip-block` so it flips above when it would run off the bottom of the screen — with viewport-minus-gutters as the no-anchor fallback — and set it at `&[popover]` specificity, since the dropdown mixin's `inset: unset` reset otherwise wins. Also set `width: auto`: the UA's `[popover] { width: fit-content }` otherwise beats both inset edges and the menu hugs its content. `cia.sheet`, `cia.drawer($side: top|bottom)` and `cia.dock` already obey the rule. **Deliberate exception — code blocks:** on phones, code is allowed to run off into a horizontal scroll *inside its own box* (`white-space: pre; overflow-x: auto`) — never wrap, shrink, or reflow code to fit, and never let it widen the page; the copy button carries usability for long lines.
 9. **Style semantic state off ARIA, not a parallel `data-*`.** When a state has an ARIA source of truth, hook your styles to *that* attribute: `[aria-selected="true"]`, `[aria-expanded="true"]`, `[aria-invalid="true"]`, `:disabled, [aria-disabled="true"]`, `[aria-pressed="true"]`, `[aria-checked="true"]`, `[aria-current]`, `[role="tab"]`. Then the state can't be styled without setting the ARIA a screen reader needs — **accessible-by-construction**, one source of truth for looks + a11y. Reserve `data-*` for **cosmetic-only** variants (`data-size`, `data-variant`, `data-color`) that carry no ARIA meaning. cia's own components already do this where native HTML doesn't cover it (`[aria-current="page"]`, `[aria-selected="true"]`, `[role="option"]`).
 
@@ -275,11 +280,11 @@ self-contained and needs no setup.
 
 ## Where to read deeper
 
-Live docs site: **https://jerry2d3d.github.io/css-is-awesome/** — mixin reference, recipes, theme authoring, MCP setup.
+Live docs site: **https://cssisawesome.com** (mirror: https://jerry2d3d.github.io/css-is-awesome/) — mixin reference, recipes, theme authoring, MCP setup, mobile playbook.
 
 Inside this package (all whitelisted in `files`):
 
-- **`css-is-awesome.instructions.md`** — full authoring rules (~14 KB, Cursor/Copilot pick up via `applyTo: "**"` frontmatter)
+- **`css-is-awesome.instructions.md`** — full authoring rules (~25 KB, Cursor/Copilot pick up via `applyTo: "**"` frontmatter)
 - **`README.md`** — install, scripts, links
 - **`THREE-TIERS.md`** — full tier explanation with examples
 - **`THEMING.md`** — theme contract and dark-mode pattern
@@ -344,4 +349,4 @@ The markdown files above, the `cia` CLI, and the MCP server are the source of tr
 
 ---
 
-If you're a human reading this and want full developer docs, start at `README.md` or the docs site: https://jerry2d3d.github.io/css-is-awesome/.
+If you're a human reading this and want full developer docs, start at `README.md` or the docs site: https://cssisawesome.com.

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+## [1.8.2](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.8.1...v1.8.2) (2026-09-05)
+
+
+### Bug Fixes
+
+* **site:** ComponentDoc must be a client component ([fd6ab31](https://github.com/Jerry2d3d/css-is-awesome/commit/fd6ab3117fb06d37c9ee1da4d1071324cae87338))
+* **tabs:** tab list is a <nav> - the div list shifted every panel index ([5099145](https://github.com/Jerry2d3d/css-is-awesome/commit/50991455c0646ffa7ec468166d29d239cbc4c235)), closes [#1](https://github.com/Jerry2d3d/css-is-awesome/issues/1)
+
+
+### Features
+
+* **site:** component docs are data - DocEntry registry + article grid (phase 3) ([98d2419](https://github.com/Jerry2d3d/css-is-awesome/commit/98d2419af9b543a6d09888d54a4f1d4b1ca757f6))
+* **site:** docs rail anatomy (Boiler handoff, phases 1+2) + the full layout doctrine written down ([fa1fa8b](https://github.com/Jerry2d3d/css-is-awesome/commit/fa1fa8b4e182793f1806d4e13af051394ad7cf8b)), closes [#7](https://github.com/Jerry2d3d/css-is-awesome/issues/7)
+
+## [1.8.1](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.8.0...v1.8.1) (2026-09-04)
+
+
+### Bug Fixes
+
+* **docs:** full documentation currency sweep - root markdown, site pages, three theme sources ([d64642a](https://github.com/Jerry2d3d/css-is-awesome/commit/d64642ab58c8dbeffb1c205df181115a9a5864d9))
+* **mobile:** docs footer yields to the dock below lg ([65eb664](https://github.com/Jerry2d3d/css-is-awesome/commit/65eb66465a7c5c193bd4f6a0eb5c3b8296ebbbda))
+* **site:** footer on the blog, themes, and docs routes ([1bd98b2](https://github.com/Jerry2d3d/css-is-awesome/commit/1bd98b2356b49a2b8da60abcd4a8d3222fd23c21))
+
+
+### Features
+
+* **site:** GitHub and npm links in the landing nav ([b797625](https://github.com/Jerry2d3d/css-is-awesome/commit/b79762514844ad703c5894a7e32485a9d90b0753))
+
 # [1.8.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.7.0...v1.8.0) (2026-09-04)
 
 

package/CONTRACT.md

@@ -3,11 +3,11 @@
 Every theme declares these tokens. The [theme validator](./scripts/theme-validator.js) enforces completeness on every PR against the machine-readable companion at [`scripts/theme-contract.json`](./scripts/theme-contract.json).
 
 - **Source of truth:** this document.
-- **Reference implementation:** [`public/theme.css`](./public/theme.css) (Sketchbook).
+- **Reference implementation:** [`public/themes/sketchbook/theme.css`](./public/themes/sketchbook/theme.css) (Sketchbook). (`public/theme.css` is the all-theme bundle.)
 - **Validate a theme:** `node scripts/theme-validator.js <path-to-theme.css>`
 - **Validate every theme in the repo:** `npm run validate-themes`
 
-A theme file is a single `:root { … }` block plus (optionally) an `@import` for fonts. No component CSS lives in a theme file. Tokens only.
+A theme file is a single token block plus (optionally) an `@import` for fonts — authored via `cia.theme()`, which emits it as `:root, :root[data-theme="<name>"]`. No component CSS lives in a theme file. Tokens only.
 
 ---
 
@@ -18,7 +18,7 @@ Library mixins resolve every token through a `var(--token, fallback)` pattern, s
 | Mixin call                       | Emitted CSS                              | Required token       |
 | -------------------------------- | ---------------------------------------- | -------------------- |
 | `m.color(surface-default)`       | `var(--surface-default, #fff)`           | `--surface-default`  |
-| `m.space(md)`                    | `var(--space-md, 1rem)`                  | `--space-md`         |
+| `m.space(4)`                     | `var(--space-4, 1rem)`                   | `--space-4`          |
 | `m.radius(lg)`                   | `var(--radius-lg, 0.5rem)`               | `--radius-lg`        |
 | `m.shadow(md)`                   | `var(--shadow-md, …)`                    | `--shadow-md`        |
 | `m.font-family(primary)`         | `var(--font-primary, sans-serif)`        | `--font-primary`     |
@@ -218,14 +218,22 @@ These are the raw pigment tokens. Semantic aliases below reference them. In othe
 
 ## Space scale
 
-| Token         | Type   | Example   | Purpose                     |
-| ------------- | ------ | --------- | --------------------------- |
-| `--space-2xs` | length | `0.25rem` | Hairline gap / 2xs padding  |
-| `--space-xs`  | length | `0.5rem`  | Tight gap / xs padding      |
-| `--space-sm`  | length | `0.75rem` | Compact gap / sm padding    |
-| `--space-md`  | length | `1rem`    | Default gap / md padding    |
-| `--space-lg`  | length | `1.5rem`  | Comfortable gap / lg padding |
-| `--space-xl`  | length | `2rem`    | Section gap / xl padding    |
+The **numbered scale is the source of truth and is contract-required**: a theme declares `--space-0` … `--space-9`, and `cia.space(N)` compiles to `var(--space-N)` — so a theme can re-proportion the page, not just recolor it.
+
+| Token                       | Type   | Example (default rhythm)          | Purpose                          |
+| --------------------------- | ------ | --------------------------------- | -------------------------------- |
+| `--space-0` … `--space-9`   | length | `0`, `0.25rem`, `0.5rem`, … `6rem` | The numbered scale — **required** |
+
+The t-shirt names are **optional aliases**. The library emits `xs`–`xl` as `var()` references into the numbered scale, so they follow it automatically; `--space-2xs` sits outside the numbered scale and emits as a literal:
+
+| Token         | Type   | Emitted as         | Purpose                     |
+| ------------- | ------ | ------------------ | --------------------------- |
+| `--space-2xs` | length | `0.25rem` (literal) | Hairline gap / 2xs padding  |
+| `--space-xs`  | length | `var(--space-1)`   | Tight gap / xs padding      |
+| `--space-sm`  | length | `var(--space-2)`   | Compact gap / sm padding    |
+| `--space-md`  | length | `var(--space-4)`   | Default gap / md padding    |
+| `--space-lg`  | length | `var(--space-5)`   | Comfortable gap / lg padding |
+| `--space-xl`  | length | `var(--space-6)`   | Section gap / xl padding    |
 
 ---
 
@@ -425,9 +433,20 @@ onto `--paper` so the math reflects what users actually see.
 | `--warning-text` on `--warning-subtle`                | 4.5 : 1  | text     |
 | `--error-text` on `--error-subtle`                    | 4.5 : 1  | text     |
 | `--info-text` on `--info-subtle`                      | 4.5 : 1  | text     |
-| `--border-default` on `--paper`                       | 3.0 : 1  | non-text |
+| `--border-default` on `--paper`                       | 3.0 : 1  | non-text (decorative — reported as info, never FAIL) |
 | `--border-focus` on `--paper`                         | 3.0 : 1  | non-text |
 | `--shu` on `--paper`                                  | 3.0 : 1  | non-text |
+| `--code-ink` on `--code-bg`                           | 4.5 : 1  | text     |
+| `--code-muted` on `--code-bg`                         | 4.5 : 1  | text     |
+| `--code-accent` on `--code-bg`                        | 4.5 : 1  | text     |
+| `--code-blue` on `--code-bg`                          | 4.5 : 1  | text     |
+| `--code-green` on `--code-bg`                         | 4.5 : 1  | text     |
+
+That's **22 audited pairs per theme**, the five `--code-*` pairs included —
+syntax highlighting is body text, so it carries the full 4.5:1 requirement.
+For dual-mode themes the audit evaluates **both** `light-dark()` branches and
+keeps the worse result. `--border-default` is treated as decorative per WCAG
+2.2 SC 1.4.11 and reports as info, not FAIL.
 
 Each pair is reported as **PASS**, **WARN** (close to threshold; `--text-tertiary`
 and `--ink-faint` warn when they pass the 3:1 large-text bar but fall below the
@@ -450,7 +469,7 @@ The contract is versioned via `scripts/theme-contract.json` (`version: "1"`).
 - **Minor bump** (`"1" → "1.1"`): adds OPTIONAL tokens. Existing themes remain valid.
 - **Major bump** (`"1" → "2"`): renames or removes REQUIRED tokens. Existing themes must migrate.
 
-Any PR that adds a new `m.color(X)` / `m.space(X)` / `m.radius(X)` reference in the library must add `--X` to both this document and `scripts/theme-contract.json`, and add a declaration to every theme in `public/theme.css` and `public/themes/*/theme.css`. The `npm run validate-themes` check in CI will block the merge otherwise.
+Any PR that adds a new `m.color(X)` / `m.space(X)` / `m.radius(X)` reference in the library must add `--X` to both this document and `scripts/theme-contract.json`, and add a declaration to every theme source in `scss/themes/*.scss` (then `npm run build:css:themes` — the CSS under `public/` is generated, never hand-edited). The `npm run validate-themes` check in CI will block the merge otherwise.
 
 ---
 

package/README.md

@@ -6,9 +6,9 @@
 
 **Bring your own selectors. We bring the design system.** One CSS file per theme — drop it in and the page restyles, no markup change. 24 themes. Zero JavaScript in the npm package. Six browser-native interactive components. Small enough to read in an afternoon.
 
-**Docs:** [jerry2d3d.github.io/css-is-awesome](https://jerry2d3d.github.io/css-is-awesome/) · **Install:** `npm install css-is-awesome`
+**Docs:** [cssisawesome.com](https://cssisawesome.com/) · **Install:** `npm install css-is-awesome`
 
-> **Shipped in 1.0.0:** a **recipes book** for building any component in any framework using cia mixins — five recipes today (`dialog`, `combobox`, `print-to-pdf`, `mobile-nav`, `bottom-nav`), with `datepicker`, `data-table` and `command-palette` queued. AI agents read recipes via MCP and generate components in your stack; humans read them at [`/docs/recipes`](https://jerry2d3d.github.io/css-is-awesome/docs/recipes/).
+> **Shipped in 1.0.0:** a **recipes book** for building any component in any framework using cia mixins — five recipes today (`dialog`, `combobox`, `print-to-pdf`, `mobile-nav`, `bottom-nav`), with `datepicker`, `data-table` and `command-palette` queued. AI agents read recipes via MCP and generate components in your stack; humans read them at [`/docs/recipes`](https://cssisawesome.com/docs/recipes/).
 
 ## For AI agents — start here
 
@@ -33,7 +33,7 @@ npm install -D @modelcontextprotocol/sdk zod   # required — npm will NOT insta
 
 The SDK and `zod` are declared as *optional* peer dependencies, so a plain `npm install css-is-awesome` skips them and the server exits with `@modelcontextprotocol/sdk is not installed`. Install both. `npx css-is-awesome-mcp` does **not** work around this — npx fetches the package but not its optional peers.
 
-Why it matters more here than for older frameworks: no model has memorised cia's API the way it has memorised Tailwind's class names. Without `llm.txt` or MCP, an agent will confidently invent a Tailwind-shaped API. With them, it reads the real thing. Details at [`/docs/mcp`](https://jerry2d3d.github.io/css-is-awesome/docs/mcp/).
+Why it matters more here than for older frameworks: no model has memorised cia's API the way it has memorised Tailwind's class names. Without `llm.txt` or MCP, an agent will confidently invent a Tailwind-shaped API. With them, it reads the real thing. Details at [`/docs/mcp`](https://cssisawesome.com/docs/mcp/).
 
 ## Three ways to use it
 
@@ -59,7 +59,7 @@ npm install -D sass
 <link rel="stylesheet" href="/cia/themes/boilerplate/theme.css">
 ```
 
-Author your own class names; the mixin handles the styling. Mixins for buttons, forms, layout, typography, color, motion, plus the six zero-JS components: `accordion`, `modal`, `tooltip`, `dropdown`, `tabs`, `copy-button` — plus the mobile navigation family (`hamburger`, `drawer`, `sheet`, `dock`) and print-to-PDF via a pure-CSS `@media print` layer. Full reference at [`/docs/mixins`](https://jerry2d3d.github.io/css-is-awesome/docs/mixins/).
+Author your own class names; the mixin handles the styling. Mixins for buttons, forms, layout, typography, color, motion, plus the six zero-JS components: `accordion`, `modal`, `tooltip`, `dropdown`, `tabs`, `copy-button` — plus the mobile navigation family (`hamburger`, `drawer`, `sheet`, `dock`) and print-to-PDF via a pure-CSS `@media print` layer. Full reference at [`/docs/mixins`](https://cssisawesome.com/docs/mixins/).
 
 **Two imports, two jobs.** Emit the tokens once from your root/global stylesheet (`@use 'css-is-awesome';` or `<link>` a theme file), then import the **zero-emit authoring barrel** in each component stylesheet:
 
@@ -122,7 +122,7 @@ One line styles the whole site. Zero classes. Wrapped in `:where()` (specificity
 <link rel="stylesheet" href="/themes/terminal-dark/theme.css"    media="(prefers-color-scheme: dark)">
 ```
 
-Newspaper by day, hacker terminal by night. No JS, no mixin — pure browser behavior. Most design systems give you dark mode; cia lets you ship a second brand at night. See [`/docs/themes/pairing`](https://jerry2d3d.github.io/css-is-awesome/docs/themes/pairing/).
+Newspaper by day, hacker terminal by night. No JS, no mixin — pure browser behavior. Most design systems give you dark mode; cia lets you ship a second brand at night. See [`/docs/themes/pairing`](https://cssisawesome.com/docs/themes/pairing/).
 
 Each theme is one file of CSS custom properties. Tokens only — no component rules. See `public/themes/<name>/theme.css` for the compiled output and `scss/themes/<name>.scss` for the sources. Full contract documented in [THEMING.md](./THEMING.md).
 
@@ -149,7 +149,7 @@ node scripts/theme-validator.js public/themes/midnight/theme.css
 #    <link rel="stylesheet" href="/themes/midnight/theme.css">
 ```
 
-Full authoring walkthrough: [`/docs/authoring/themes`](https://jerry2d3d.github.io/css-is-awesome/docs/authoring/themes/). The contract (127 required + 36 optional tokens) is at [`scripts/theme-contract.json`](./scripts/theme-contract.json).
+Full authoring walkthrough: [`/docs/authoring/themes`](https://cssisawesome.com/docs/authoring/themes/). The contract (127 required + 36 optional tokens) is at [`scripts/theme-contract.json`](./scripts/theme-contract.json).
 
 ## Token contract
 
@@ -204,9 +204,11 @@ cia ships **no component library** — deliberately. Interactive patterns arrive
 
 **Shipped:** `dialog`, `combobox`, `print-to-pdf`, `mobile-nav`, `bottom-nav`. Queued next: `datepicker`, `data-table`, `command-palette`.
 
-**Mobile navigation is system API, not an exercise for the reader.** Four mixins — `cia.hamburger`, `cia.drawer`, `cia.sheet`, `cia.dock` — cover both phone layouts: the **flex layout** (one fluid nav/main/footer shell that reshapes with the screen, hamburger opening a slide-in drawer — recipe [`mobile-nav`](./scss/recipes/mobile-nav.md)) and the **app layout** (a fixed bottom dock whose slots open slide-up sheets — recipe [`bottom-nav`](./scss/recipes/bottom-nav.md)). Zero JavaScript: everything rides CSS Grid and the native Popover API — the browser owns open state, `aria-expanded`, Esc and light dismiss. The docs site dogfoods the app layout on phones. The same doctrine extends to dropdowns: on phones an interactive surface takes the space it's in, so a `cia.dropdown` menu opens 1px under its full-width trigger at the trigger's exact width — CSS anchor positioning, flipping above when the screen bottom would clip it. The full spec is the [mobile playbook](https://jerry2d3d.github.io/css-is-awesome/docs/mobile/).
+**Layout doctrine: Grid is the skeleton, Flex is the quick moves.** The page shell is CSS Grid with landmark-named areas (`nav / main / footer` — the map reads like the page); any control-dense region inside gets its own named-area grid whose `gap` carries all vertical rhythm; flex lives at the leaves for one-command flips (`cia.flex($direction: column)`). `cia.page-layout()` and `cia.layout()` own the maps — mobile is a different area map, never margin overrides.
 
-Humans read them at [`/docs/recipes`](https://jerry2d3d.github.io/css-is-awesome/docs/recipes/); AI agents pull them over MCP with `list_recipes` / `get_recipe`.
+**Mobile navigation is system API, not an exercise for the reader.** Four mixins — `cia.hamburger`, `cia.drawer`, `cia.sheet`, `cia.dock` — cover both phone layouts: the **flex layout** (one fluid nav/main/footer shell that reshapes with the screen, hamburger opening a slide-in drawer — recipe [`mobile-nav`](./scss/recipes/mobile-nav.md)) and the **app layout** (a fixed bottom dock whose slots open slide-up sheets — recipe [`bottom-nav`](./scss/recipes/bottom-nav.md)). Zero JavaScript: everything rides CSS Grid and the native Popover API — the browser owns open state, `aria-expanded`, Esc and light dismiss. The docs site dogfoods the app layout on phones. The same doctrine extends to dropdowns: on phones an interactive surface takes the space it's in, so a `cia.dropdown` menu opens 1px under its full-width trigger at the trigger's exact width — CSS anchor positioning, flipping above when the screen bottom would clip it. The full spec is the [mobile playbook](https://cssisawesome.com/docs/mobile/).
+
+Humans read them at [`/docs/recipes`](https://cssisawesome.com/docs/recipes/); AI agents pull them over MCP with `list_recipes` / `get_recipe`.
 
 ## Migrating from Tailwind or Bootstrap
 
@@ -217,7 +219,7 @@ npx cia migrate tailwind ./tailwind.config.js   # auto-detects tailwind.config.*
 npx cia migrate bootstrap ./scss/_variables.scss
 ```
 
-Both accept `--help` for the full option list. Prose walkthroughs live at [`/docs/migration-tailwind`](https://jerry2d3d.github.io/css-is-awesome/docs/migration-tailwind/) and [`/docs/migration-bootstrap`](https://jerry2d3d.github.io/css-is-awesome/docs/migration-bootstrap/).
+Both accept `--help` for the full option list. Prose walkthroughs live at [`/docs/migration-tailwind`](https://cssisawesome.com/docs/migration-tailwind/) and [`/docs/migration-bootstrap`](https://cssisawesome.com/docs/migration-bootstrap/).
 
 ## Print / PDF (zero JS)
 
@@ -256,7 +258,7 @@ The scope is kept narrow: 8 `!important` declarations, all inside `@media print`
 
 ## MCP server (for AI agents)
 
-cia ships a Model Context Protocol stdio server (JSON-RPC over stdio, protocol `2024-11-05`) at [`mcp/server.cjs`](./mcp/server.cjs), exposed as the `css-is-awesome-mcp` bin. It's in the `files` manifest, so it lands in every consumer's `node_modules`. Any MCP-aware client (Claude Code, Cursor, Aider, Gemini, Copilot) can then query cia's real design system — mixin signatures, tokens, themes, recipes — instead of guessing, without grep-walking the repo. Exposes **30 tools** across 8 families (themes, mixins, functions, tokens · 127 required of them, animations, components, recipes, doc readers) plus `assemble_prompt` (context bundles) and `resolve_size` (snap design px values to cia's 4px grid). Full reference: [`/docs/mcp`](https://jerry2d3d.github.io/css-is-awesome/docs/mcp/).
+cia ships a Model Context Protocol stdio server (JSON-RPC over stdio, protocol `2024-11-05`) at [`mcp/server.cjs`](./mcp/server.cjs), exposed as the `css-is-awesome-mcp` bin. It's in the `files` manifest, so it lands in every consumer's `node_modules`. Any MCP-aware client (Claude Code, Cursor, Aider, Gemini, Copilot) can then query cia's real design system — mixin signatures, tokens, themes, recipes — instead of guessing, without grep-walking the repo. Exposes **30 tools** across 8 families (themes, mixins, functions, tokens · 127 required of them, animations, components, recipes, doc readers) plus `assemble_prompt` (context bundles) and `resolve_size` (snap design px values to cia's 4px grid). Full reference: [`/docs/mcp`](https://cssisawesome.com/docs/mcp/).
 
 **Setup is two steps — do both, or the server won't start.**
 
@@ -283,7 +285,7 @@ cia ships a Model Context Protocol stdio server (JSON-RPC over stdio, protocol `
 
 ## Docs site
 
-The docs site is live at **https://jerry2d3d.github.io/css-is-awesome/** — it auto-deploys from `main` via GitHub Pages. To run it locally:
+The docs site is live at **https://cssisawesome.com** (production — Vercel, deployed from the `prod-css-is-awesome` branch), with a GitHub Pages mirror at **https://jerry2d3d.github.io/css-is-awesome/** that auto-deploys from `main`. To run it locally:
 
 ```bash
 git clone https://github.com/Jerry2d3d/css-is-awesome.git
@@ -292,7 +294,7 @@ npm install
 npm run dev          # http://localhost:5173
 ```
 
-The docs site is a Next.js 15 app at `src/` that dogfoods the library — every page uses CSS Modules composed from the same tokens and mixins the library ships.
+The docs site is a Next.js 16 app at `src/` that dogfoods the library — every page uses CSS Modules composed from the same tokens and mixins the library ships.
 
 ## Scripts
 
@@ -317,7 +319,7 @@ The docs site is a Next.js 15 app at `src/` that dogfoods the library — every
 
 ## Testing
 
-Eleven checks, all gated in CI on every PR. Each one exists because the failure it catches actually happened.
+Twelve checks, all gated in CI on every PR. Each one exists because the failure it catches actually happened.
 
 | Check | What it proves |
 |---|---|
@@ -327,11 +329,12 @@ Eleven checks, all gated in CI on every PR. Each one exists because the failure
 | `validate-icons` | the 49-glyph core pack is intact (extras allowed) |
 | `validate-api` | the `/api` barrel still emits zero CSS until a mixin is called |
 | `validate-package` | packs → installs into a temp project → compiles all **10** documented `@use` specifiers |
-| `coverage:api` | calls **174/174** public mixins + functions and asserts the output |
+| `coverage:api` | calls **183/183** public mixins + functions and asserts the output |
 | `coverage:mcp` | calls **30/30** MCP tools over stdio |
-| `test` | Playwright — 50 tests: route smoke, axe a11y, per-theme visual snapshots, theme-editor behaviour |
+| `validate-recipes` | every recipe's SCSS compiles and its documented mixin calls resolve |
+| `test` | Playwright — route smoke, axe a11y, per-theme visual snapshots, theme-editor behaviour, across three engines |
 
-**Call-and-assert coverage.** SCSS has no line-coverage tooling, so cia measures whether every part of the public API is actually callable: parse every public `@mixin`/`@function`, generate a fixture that calls it, compile, and assert it works — no `null` leaking into CSS, functions return a value, mixins emit. **174/174 SCSS units and 30/30 MCP tools**, with CI failing below 98%. A unit with no fixture counts as uncovered, so skipping a test lowers the number rather than hiding.
+**Call-and-assert coverage.** SCSS has no line-coverage tooling, so cia measures whether every part of the public API is actually callable: parse every public `@mixin`/`@function`, generate a fixture that calls it, compile, and assert it works — no `null` leaking into CSS, functions return a value, mixins emit. **183/183 SCSS units and 30/30 MCP tools**, with CI failing below 98%. A unit with no fixture counts as uncovered, so skipping a test lowers the number rather than hiding.
 
 **What 100% means here:** every public mixin and function is invoked and produces sane output. It catches renames, broken signatures and undefined variables — it found one on its first run, an undefined `$icon-size` that broke four icon mixins. It does **not** prove the CSS is visually correct; that's a deliberate trade against golden-file snapshots, which would churn dozens of files on any token change. Page-level visual correctness is covered by the Playwright snapshots instead.
 
@@ -339,7 +342,7 @@ Eleven checks, all gated in CI on every PR. Each one exists because the failure
 
 **Known gaps**, stated plainly: **a11y runs on routes, not component states** — axe checks a set of pages; individual component states are not swept. (Cross-engine coverage used to be the gap here; the suite now runs chromium, firefox and webkit, which matters because cia leans on `light-dark()`, `:has()`, `[popover]` and `mask`.)
 
-Full detail: [`/docs/testing`](https://jerry2d3d.github.io/css-is-awesome/docs/testing/).
+Full detail: [`/docs/testing`](https://cssisawesome.com/docs/testing/).
 
 ## Size (gzipped)
 

package/ROADMAP.md

@@ -138,7 +138,7 @@ Shared chrome + reusable building blocks now live in `src/components/`:
 - [ ] Sections: Tokens (color/spacing/type grids — DONE), Utilities (searchable table — TODO), Mixins API (TODO), Migration from Bootstrap (started; needs polish).
 - [x] Live color swatches, spacing visualizers, type scale preview — `/docs/tokens` reads `getComputedStyle` after mount and re-resolves on theme swap via `useThemeAttribute`.
 - [x] Copy-to-clipboard code snippets — every `<Example.Code>` has a Copy button (CopyButton client island, secure-context fallback to execCommand).
-- [ ] Deploy to the external host + link from README + `package.json` `homepage` (Pages workflow exists; live URL not yet linked from README).
+- [x] Deploy to the external host + link from README — done: GitHub Pages mirror live and linked, and production at https://cssisawesome.com on Vercel since 2026-09-04 (deploys from the `prod-css-is-awesome` branch).
 
 ### New pages
 - [x] **`/themes` gallery** — all 6 themes with live-swap preview + download per tile. Uses `ThemeTile` component. (Now at `/themes/gallery`; `/themes` is the editor.)
@@ -265,9 +265,10 @@ out-of-date copy that contradicts the rest of the site. Fix the
 content before doing any CSS work on these files so the dogfood
 pass doesn't restyle copy that's about to be replaced.
 
-**`/blog`** — All 7 posts are fiction with `href="#"`. Dates run
-Feb–Apr 2026 and excerpts read like real posts that don't exist.
-Decide:
+**`/blog`** — *Resolved 2026-08-17: a real markdown-driven `/blog` +
+`/blog/[slug]` shipped with 7 posts written from the commit history
+(see Phase 5.95) — effectively Path A, all seven.* Original decision
+for the record:
 - [ ] **Path A — Ship a subset for real.** Pick 2-3 of the 7 drafted
   topics ("Why the overflow stays", "Five voices, one system",
   "Planning a CLI and an MCP server" are the strongest hooks) and
@@ -341,7 +342,7 @@ docs-site quality only.
 
 ## Phase 5.95 — Post-1.0 hardening (2026-08-17 → 08-18)
 
-**v1.0.0 was cut 2026-08-17** (`253610a`, tagged) at 24 of 42 stories, deliberately: no external users yet, so the SemVer commitment cost nothing. **Not published to npm** — the `@1` CDN URLs will 404 until it is.
+**v1.0.0 was cut 2026-08-17** (`253610a`, tagged) at 24 of 42 stories, deliberately: no external users yet, so the SemVer commitment cost nothing. **First published to npm 2026-09-01**; semantic-release has cut every version since (the current one is always the `version` field of `package.json` — never hand-type it).
 
 What the cut surfaced, in the order it hurt:
 
@@ -353,7 +354,7 @@ What the cut surfaced, in the order it hurt:
 - [x] **Visual baselines stale since 2026-05-03**, keeping CI red. Keyed by `{platform}`, win32 set regenerated. **Linux set still needs one manual run of the "Update visual snapshots" workflow.**
 - [x] Release friction: `pack:consumer` collapses the three-step pack → re-pin → install dance into one command.
 
-**Still open:** publish to npm; run the snapshot workflow once to green CI; the 18 remaining v1.0 stories (Playground is 0/7).
+**Still open:** run the snapshot workflow once to create the linux baseline set; the remaining v1.0 stories (Playground is 0/7). ~~Publish to npm~~ — done 2026-09-01.
 
 ---
 
@@ -361,6 +362,8 @@ What the cut surfaced, in the order it hurt:
 
 **Locked 2026-05-23** after long architecture synthesis (panel review + Gemini external read + Jerry instinct refinement).
 
+> **Status 2026-09-04:** v1.0.0 cut 2026-08-17, first npm publish 2026-09-01; releases continue via semantic-release. The sprint checklist below is preserved as written — unchecked items are genuinely still open (see the "Definition of the best" list for per-item status).
+
 **Goal:** Ship v1.0 as a humans-first design system whose AI-friendliness is the bonus. Five tracks, ~42 user stories, ~18-26 working days.
 
 ### Priority ladder (the v1.0 pitch order)
@@ -412,11 +415,11 @@ See [`roadmap/epics/v1-0/post-v1-ideas.md`](./roadmap/epics/v1-0/post-v1-ideas.m
 
 ### Definition of "the best out there" after this sprint
 
-- [ ] Migration CLI handles real Tailwind + Bootstrap configs end-to-end
-- [ ] 11+ recipes shipped across overlay / input / data / navigation / feedback
+- [x] Migration CLI handles real Tailwind + Bootstrap configs end-to-end (`npx cia migrate` shipped)
+- [ ] 11+ recipes shipped across overlay / input / data / navigation / feedback (5 shipped as of 2026-09-04: dialog, combobox, print-to-pdf, mobile-nav, bottom-nav)
 - [ ] `/playground` functional in-browser; every recipe page links to a starter URL
 - [ ] Inline contrast validator runs live in the theme editor
-- [ ] First 3 blog posts published with citations + dated decision receipts
+- [x] Blog shipped for real — markdown-driven `/blog` with 7 posts written from the commit history (2026-08-17)
 - [ ] boilerplate-slim ships React + Angular + HTML (34 each)
 - [ ] `/showcase` rebuilt + `/docs/migrate-from-shadcn` guide published
 - [ ] Boiler dogfoods cia + ≥5 external testers have built something real
@@ -483,7 +486,7 @@ The original Phase 6 ("Ecosystem v1.1+") below describes legacy items some of wh
 - [x] GitHub Action: CI (build + lint), Release (semver + npm publish + changelog) — semantic-release wired up since v0.7.
 - [x] Badge suite in README (npm version, license, semantic-release) — shipped.
 - [x] Contribution guide + issue templates — `CONTRIBUTING.md` + `CONTRIBUTING-THEMES.md` shipped.
-- [ ] TypeScript token definitions (`tokens.d.ts`) — type-safe token access from JS
+- [x] TypeScript token definitions (`tokens.d.ts`) — shipped; generated from the contract via `npm run build:token-types`, exported as `css-is-awesome/tokens.d.ts`
 - [ ] PostCSS plugin for tree-shaking unused utilities
 - [ ] Starter templates: plain HTML, Vite, Next.js, Astro
 - [ ] Storybook or Ladle instance — lives in Gremlin UI's repo, not here (see Phase 8).
@@ -494,11 +497,11 @@ The original Phase 6 ("Ecosystem v1.1+") below describes legacy items some of wh
 
 **Goal:** Move from "another design system" to "the obvious choice for SCSS-first teams who want zero-JS theming." Items from the Gemini critique that widen the moat once the foundations are stable.
 
-- [ ] **Zero-JS interactive components** — tabs, accordion, modal, popover, tooltip built on `:has()`, the popover API, and `@container`. Biggest moat vs shadcn — they need a runtime, we don't.
+- [x] **Zero-JS interactive components** — shipped in v0.8/v1.0: accordion, modal, tooltip, dropdown, tabs, copy-button on `<details name>`, `<dialog>`, `[popover]`, radio + `:has()`; plus the mobile navigation family (hamburger / drawer / sheet / dock, 2026-08). Biggest moat vs shadcn — they need a runtime, we don't.
 - [x] **A11y linter inside `theme-validator.js`** — WCAG 2.2 AA contrast checks on 17 token pairs per theme. **FAIL-by-default as of v0.7** (commit `4e1bbf1`, 2026-05-11) after triaging every theme; zero FAILs across all 22 theme blocks. `--allow-a11y-fail` opts out; `--strict` is retained as a no-op alias for backwards compat. `--border-default` is treated as decorative (informational only) per WCAG 2.2 SC 1.4.11.
-- [ ] **SCSS↔TS token bridge** — generate `tokens.d.ts` from the contract so consumers get type-safe token access in JS/TS.
-- [ ] **Intrinsic layout mixins** — stack/cluster/switcher (Every Layout patterns) as first-class mixins so consumers stop hand-rolling flex utilities.
-- [ ] **Tailwind→Awesome migration CLI** — parses Tailwind class strings in a project and suggests `cia-*` utility or mixin equivalents; lowest-friction path for migrants.
+- [x] **SCSS↔TS token bridge** — shipped: `npm run build:token-types` generates `dist/tokens.d.ts` from the contract.
+- [x] **Intrinsic layout mixins** — shipped in the v1.0 surface: `stack` / `cluster` / `switcher` / `sidebar` as first-class mixins.
+- [x] **Tailwind→Awesome migration CLI** — shipped as `npx cia migrate tailwind` (config-level conversion into a cia theme; the class-string-scanning variant described here was not built).
 - [ ] **Component depth audit** — catalog gaps vs Bootstrap (modal, toast, popover, tooltip, accordion, breadcrumb, pagination, badge, avatar, dropdown, offcanvas) and prioritize zero-JS implementations.
 
 ---
@@ -541,9 +544,9 @@ Naming "Gremlin UI" / "Gremlin Components" / "Companion Boilerplate" — all ret
 
 1. ~~**Utility naming:** stay close to Bootstrap (`.p-3`) or Tailwind-like (`.p-md`)?~~ **Decided:** Tailwind-style (`.cia-p-md`) with `cia-` prefix.
 2. ~~**Namespace:** should utilities be prefixed?~~ **Decided:** yes, `cia-` on everything.
-3. **Default CSS output:** include utilities by default or opt-in? Still open.
-4. **Browser support target:** modern evergreen only, or include a legacy build? Still open.
-5. **Sizing scale:** refactor `xs/sm/md/lg/xl/2xl/3xl/4xl` → numbered `1–9` with aliases? **Pending — blocks the theme token contract.**
+3. ~~**Default CSS output:** include utilities by default or opt-in?~~ **Decided (v0.8):** opt-in on the Sass path (`$utilities: true`); pre-built CDN bundles still ship every utility.
+4. **Browser support target:** modern evergreen only, or include a legacy build? Still open (in practice: modern evergreen — the system leans on `light-dark()`, `:has()`, `[popover]`).
+5. ~~**Sizing scale:** refactor `xs/sm/md/lg/xl/2xl/3xl/4xl` → numbered `1–9` with aliases?~~ **Decided (locked 2026-05-04):** numbered scale is the source of truth; t-shirt names are optional aliases.
 
 ---
 
@@ -567,12 +570,12 @@ Items 1-13, 15, 16, the a11y linter triage, and the theme-editor import round-tr
 19. ~~A11y linter triage~~ — done 2026-05-11 (commit `4e1bbf1`). Zero FAILs across all 22 theme blocks. `--border-default` reclassified as decorative (info status) per WCAG 2.2 SC 1.4.11. Validator now FAILs by default; `--allow-a11y-fail` opts out; `--strict` retained as a no-op alias.
 20. ~~Theme-editor import~~ — upload `.css` to keep editing landed 2026-05-12 (uncommitted on `main`; round-trips a previously-downloaded theme file).
 
-### Open / next up — Phase 5 is the live gate
+### Open / next up — Phase 5 was the live gate (since resolved)
 
-**Phase 5 (publish v0.7) is the correct next step.** A11y is at zero FAILs, validator is FAIL-by-default, tarball is clean, boilerplate theme + Lucide icons ship, theme editor round-trips. Only the publish command itself + a downstream smoke install remain.
+**Phase 5 (publish v0.7) was the correct next step at the time.** A11y is at zero FAILs, validator is FAIL-by-default, tarball is clean, boilerplate theme + Lucide icons ship, theme editor round-trips. Only the publish command itself + a downstream smoke install remain.
 
-8. **`npm publish` 0.7.0** — bump version, `npm publish --access public`. Awaiting explicit user go.
-9. **Boilerplate consumer install from registry** — depends on #8.
+8. ~~**`npm publish`**~~ — done. The package shipped via semantic-release through the 0.7/0.8 line; the 1.x line first published to the public registry 2026-09-01.
+9. ~~**Boilerplate consumer install**~~ — done. boiler-project-ai consumes cia (all components + app pages migrated to the `cia` import, 2026-07-11).
 
 ### After v0.7 ships
 
@@ -583,9 +586,9 @@ Items 1-13, 15, 16, the a11y linter triage, and the theme-editor import round-tr
 
 ### Smaller items still on the board
 
-- **Utilities searchable table** at `/docs/utilities` (placeholder content currently). Last big docs gap before launch.
-- **Mixins API reference** at `/docs/mixins`. Last big docs gap before launch.
-- **README homepage URL** + Pages-deploy verification.
+- ~~**Utilities searchable table** at `/docs/utilities`~~ — shipped (route live on the docs site).
+- ~~**Mixins API reference** at `/docs/mixins`~~ — shipped (README links it as the full reference).
+- ~~**README homepage URL** + Pages-deploy verification~~ — done; Pages mirror + cssisawesome.com production both live.
 - **Icon index page** listing every glyph in every pack.
 - **Pull Sketchbook docs-flourishes** (seal, draft stamp, brush rules) out of any future "base system" port.
 
@@ -599,7 +602,7 @@ Items 1-13, 15, 16, the a11y linter triage, and the theme-editor import round-tr
 
 All of the following must be true before Season 1 production begins:
 
-- [ ] cia v1.0.0 published to npm
+- [x] cia published to npm (first publish 2026-09-01; 1.x line live)
 - [ ] All v1.0 epic acceptance criteria met (42 stories shipped or explicitly punted)
 - [ ] No planned mixin renames or API changes within the next 6 months
 - [ ] Recipes book stable — at least 11 recipes shipped and not changing

package/THREE-TIERS.md

@@ -9,8 +9,8 @@ css-is-awesome ships three authoring surfaces for the same components. Pick the
 ## Tier 1 — Drop-in CSS + HTML (no build)
 
 ```html
+<link rel="stylesheet" href="themes/sketchbook/theme.css">
 <link rel="stylesheet" href="css-is-awesome.min.css">
-<link rel="stylesheet" href="theme-sketchbook.css">
 
 <main class="cia-container">
   <h1>Welcome</h1>
@@ -100,7 +100,7 @@ The split to hold in your head: **cia owns the system values — colour, spacing
 ```
 
 **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.
+**Rules:** zero classes required. The recipe styles every common bare tag wrapped in `:where()` (specificity `0,0,0`) — no `@layer`. Any selector you add — even another bare tag — wins automatically.
 
 ---
 

package/VERSIONING.md

@@ -9,7 +9,7 @@ How `css-is-awesome` versions its public surfaces, deprecates old APIs, and reco
 | 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"` |
+| SCSS mixin API      | `scss/` (`_mixins.scss`, `_layout.scss`, …) | Authors who `@use 'css-is-awesome'` / `@use 'css-is-awesome/api'` |
 | 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.
@@ -31,8 +31,7 @@ Any change that can break a consumer upgrading blindly.
 | 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`                          |
+| Optional-peer floor rises                                                 | `@modelcontextprotocol/sdk` minimum raised             |
 
 ### MINOR — `0.x.0`
 
@@ -43,8 +42,7 @@ Additive, non-breaking changes.
 | 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 theme or recipe shipped                                  | `prism` family added; `mobile-nav` recipe added   |
 | New utility class (`.cia-*`)                                 | `.cia-text-balance` added                         |
 
 ### PATCH — `0.0.x`
@@ -61,14 +59,14 @@ Internal-only or visually-identical changes.
 
 ---
 
-## 2. Pre-1.0 rules
+## 2. Pre-1.0 rules (historical)
 
-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:
+While the library was pre-1.0 (`0.x.x`), the rules above applied with one carve-out: we reserved the right to ship a genuinely-breaking change as a **MINOR** bump when it was the right call for the system's long-term shape (the v0.7 theme renames and the v0.8 mixin-first reframe both used it). Every such change was:
 
-1. Called out loudly in the `CHANGELOG.md` entry under `### Changed` with a **BREAKING** prefix.
+1. Called out loudly in the `CHANGELOG.md` entry 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.
+**`1.0.0` locked the contract** (cut 2026-08-17). Breaking changes now require a MAJOR bump, no exceptions.
 
 ---
 
@@ -80,9 +78,8 @@ Every public symbol — CSS class, SCSS mixin, React prop, contract token — fo
 
 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.
+    - SCSS mixins → `@warn "m.old-name is deprecated, use m.new-name (removed in 2.0)";`.
+    - CSS classes / tokens → no runtime warning possible; rely on the `@deprecated` comment 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.
@@ -92,9 +89,9 @@ Every public symbol — CSS class, SCSS mixin, React prop, contract token — fo
 ```scss
 // scss/_mixins.scss
 /// @deprecated Use `m.btn-primary` with `$bg: action-secondary-default` override.
-///             Removed in 1.0.
+///             Removed in 2.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.";
+  @warn "m.btn-secondary is deprecated; use m.btn-primary with $bg: action-secondary-default. Removed in 2.0.";
   @include btn-primary($size, $bg: action-secondary-default);
 }
 ```
@@ -112,70 +109,63 @@ A deprecated contract token:
 
 ## 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:
+**[`CHANGELOG.md`](./CHANGELOG.md) is GENERATED — never edit it by hand.** [semantic-release](https://github.com/semantic-release/semantic-release) writes each release entry from the Conventional Commits that landed since the previous tag, grouped under the conventional-changelog headings:
 
-- `Added` — new features.
-- `Changed` — changes to existing functionality.
-- `Deprecated` — soon-to-be-removed features.
-- `Removed` — removed features.
-- `Fixed` — bug fixes.
-- `Security` — vulnerabilities and mitigations.
+- `Features` — from `feat:` commits.
+- `Bug Fixes` — from `fix:` commits.
+- `Performance Improvements` — from `perf:` commits.
 
-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.
+**Version pace — the number belongs to the PACKAGE, not the website.**
+The docs site lives in this repo but ships nowhere in the npm tarball, so
+site-only work must not spend minor versions. The rules (enforced by a
+`releaseRules` override in `.releaserc.json`, adopted 2026-09-04 after
+site `feat` commits marched 1.1 → 1.8 in a week):
 
-### Example release block
+- Library API work (new/changed mixins, tokens, recipes, packaged docs) —
+  normal Conventional Commits semantics: `feat` → minor, `fix` → patch.
+- Site-only work — scope it `(site)` or `(docs-site)`: `feat(site)` is
+  demoted to a **patch**, `fix(site)` patches, `chore`/`docs` don't
+  release at all. Prefer `chore(site)` when nothing packaged changed and
+  no npm release is needed — production deploys come from the
+  `prod-css-is-awesome` branch, not from npm.
+- MAJOR (2.0.0) is reserved for real breaking changes to the public
+  surfaces above — nothing else may reach it.
+- `BREAKING CHANGES` — from `feat!:` / `fix!:` or a `BREAKING CHANGE:` footer.
 
-```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).
-```
+Each entry links the commit (and any referenced issue / PR numbers) automatically. There is no hand-maintained `Unreleased` section — in-flight changes are simply the commits on `main` that no tag covers yet.
 
 ---
 
-## 5. Conventional Commits → Changelog
+## 5. Conventional Commits → Release
 
-Commits follow [Conventional Commits](https://www.conventionalcommits.org/). The prefix maps to a changelog section:
+Commits follow [Conventional Commits](https://www.conventionalcommits.org/). The prefix decides both the version bump and the 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*                          |
+| Commit prefix                             | Bump    | Changelog section          |
+| ----------------------------------------- | ------- | -------------------------- |
+| `feat:`                                   | MINOR   | `Features`                 |
+| `feat!:` or `BREAKING CHANGE:` footer     | MAJOR   | `BREAKING CHANGES`         |
+| `fix:`                                    | PATCH   | `Bug Fixes`                |
+| `perf:`                                   | PATCH   | `Performance Improvements` |
+| `docs:`                                   | *no release* | *omit*                |
+| `refactor:`                               | *no release* | *omit*                |
+| `test:`                                   | *no release* | *omit*                |
+| `chore:`                                  | *no release* | *omit*                |
+| `build:` / `ci:`                          | *no release* | *omit*                |
 
-A commit can carry a `Deprecates:` footer to force an entry under `### Deprecated`, or a `Security:` footer to force `### Security`, regardless of prefix.
+Deprecations are announced in the deprecating commit's body (and land in the release notes through it), plus an inline `@deprecated` comment per §3.
 
 ---
 
 ## 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.
+The policy in this document tells you **what** a version number means. The mechanics are automated: on every push to `main` that contains a releasable commit, semantic-release computes the next version from the commit messages, regenerates `CHANGELOG.md`, builds the bundles (`prepublishOnly` runs `build:css:all`), tags `vX.Y.Z`, and publishes to npm. Nobody hand-types a version number anywhere — the hero, the MCP server, and the docs all read it from `package.json`.
+
+What remains manual:
 
-Every release, at minimum:
+1. Bumping `version` in `scripts/theme-contract.json` when the contract itself changes (§7).
+2. The CI gates (lint, validators, coverage, size budget, Playwright) — a red PR never reaches `main`, so a release is never cut from a failing tree.
 
-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.
+Contributor-facing workflow detail lives in [`CONTRIBUTING.md`](./CONTRIBUTING.md).
 
 ---
 
@@ -185,7 +175,7 @@ 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.                  |
+| Library version     | `version` field of [`package.json`](./package.json)           | Any change to the CSS / SCSS / contract 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.
@@ -197,4 +187,4 @@ They usually move together on a library MAJOR. They move independently on MINOR
 - [`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`.
+- [`ROADMAP.md`](./ROADMAP.md) — where the library is headed.

package/css-is-awesome.instructions.md

@@ -385,7 +385,7 @@ Library defaults emit under **`:where(:root)`** (specificity 0,0,0), so any them
 
 **Never hand-edit `public/theme.css` or `public/themes/**/theme.css`.** They are generated from `scss/themes/*.scss` and gated by `check:theme-drift`.
 
-See `/docs/authoring/themes` on the docs site (https://jerry2d3d.github.io/css-is-awesome/docs/authoring/themes/) for the full guide.
+See `/docs/authoring/themes` on the docs site (https://cssisawesome.com/docs/authoring/themes/) for the full guide.
 
 ### Spacing is themeable — set the numbered step
 
@@ -489,7 +489,7 @@ How to reach them:
 
 - **AI agents** — `list_recipes` / `get_recipe(name)` over MCP. Prefer this over
   writing an interactive pattern from memory; the recipe encodes the a11y work.
-- **Humans** — `/docs/recipes` on the docs site (https://jerry2d3d.github.io/css-is-awesome/docs/recipes/), or read the markdown directly.
+- **Humans** — `/docs/recipes` on the docs site (https://cssisawesome.com/docs/recipes/), or read the markdown directly.
 
 Note the two different things living in `scss/recipes/`: `<slug>.md` files are
 *pattern* recipes (read them, don't import them), while `_<slug>.scss` files —

package/dist/tokens.d.ts

@@ -1,4 +1,4 @@
-// Generated from scripts/theme-contract.json on 2026-09-04.
+// Generated from scripts/theme-contract.json on 2026-09-05.
 // Do not edit by hand. Run `npm run build:token-types` to regenerate.
 
 /** Every CSS custom property cia themes are required to declare. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "css-is-awesome",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "description": "A token-driven SCSS design system with light/dark theming, semantic color tokens, and a 800+ LOC mixin API.",
   "homepage": "https://github.com/Jerry2d3d/css-is-awesome#readme",
   "bugs": {

package/public/theme.css

@@ -320,11 +320,14 @@
   --error-text: #fca5a5;
   /* Space scale */
   --space-2xs: 0.25rem;
-  --space-xs: 0.5rem;
-  --space-sm: 0.75rem;
-  --space-md: 1rem;
-  --space-lg: 1.5rem;
-  --space-xl: 2rem;
+  --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);
+  --space-2xl: var(--space-7);
+  --space-3xl: var(--space-8);
+  --space-4xl: var(--space-9);
   /* Radius alias */
   --radius-sm: var(--r-sm);
   --radius-md: var(--r-md);
@@ -490,11 +493,14 @@
   --error-text: #b91c1c;
   /* Space scale */
   --space-2xs: 0.25rem;
-  --space-xs: 0.5rem;
-  --space-sm: 0.75rem;
-  --space-md: 1rem;
-  --space-lg: 1.5rem;
-  --space-xl: 2rem;
+  --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);
+  --space-2xl: var(--space-7);
+  --space-3xl: var(--space-8);
+  --space-4xl: var(--space-9);
   /* Radius alias */
   --radius-sm: var(--r-sm);
   --radius-md: var(--r-md);
@@ -3818,11 +3824,14 @@
   ---------------------------------------------------------- */
   /* Space scale (rem for accessibility) */
   --space-2xs: 0.25rem;
-  --space-xs: 0.5rem;
-  --space-sm: 0.75rem;
-  --space-md: 1rem;
-  --space-lg: 1.5rem;
-  --space-xl: 2rem;
+  --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);
+  --space-2xl: var(--space-7);
+  --space-3xl: var(--space-8);
+  --space-4xl: var(--space-9);
   /* Radius alias — mirrors --r-* with standard names so
   `m.radius(size)` in the library finds --radius-<size>. */
   --radius-sm: var(--r-sm);

package/public/themes/boilerplate-dark/theme.css

@@ -130,11 +130,14 @@
   --error-text: #fca5a5;
   /* Space scale */
   --space-2xs: 0.25rem;
-  --space-xs: 0.5rem;
-  --space-sm: 0.75rem;
-  --space-md: 1rem;
-  --space-lg: 1.5rem;
-  --space-xl: 2rem;
+  --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);
+  --space-2xl: var(--space-7);
+  --space-3xl: var(--space-8);
+  --space-4xl: var(--space-9);
   /* Radius alias */
   --radius-sm: var(--r-sm);
   --radius-md: var(--r-md);

package/public/themes/boilerplate-light/theme.css

@@ -130,11 +130,14 @@
   --error-text: #b91c1c;
   /* Space scale */
   --space-2xs: 0.25rem;
-  --space-xs: 0.5rem;
-  --space-sm: 0.75rem;
-  --space-md: 1rem;
-  --space-lg: 1.5rem;
-  --space-xl: 2rem;
+  --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);
+  --space-2xl: var(--space-7);
+  --space-3xl: var(--space-8);
+  --space-4xl: var(--space-9);
   /* Radius alias */
   --radius-sm: var(--r-sm);
   --radius-md: var(--r-md);

package/public/themes/sketchbook-light/theme.css

@@ -146,11 +146,14 @@
   ---------------------------------------------------------- */
   /* Space scale (rem for accessibility) */
   --space-2xs: 0.25rem;
-  --space-xs: 0.5rem;
-  --space-sm: 0.75rem;
-  --space-md: 1rem;
-  --space-lg: 1.5rem;
-  --space-xl: 2rem;
+  --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);
+  --space-2xl: var(--space-7);
+  --space-3xl: var(--space-8);
+  --space-4xl: var(--space-9);
   /* Radius alias — mirrors --r-* with standard names so
   `m.radius(size)` in the library finds --radius-<size>. */
   --radius-sm: var(--r-sm);

package/scss/components/_tabs.scss

@@ -8,14 +8,22 @@
 //   <div class="cia-tabs">
 //     <input type="radio" name="t" id="t1" checked>
 //     <input type="radio" name="t" id="t2">
-//     <div class="cia-tab-list" role="tablist">
+//     <nav class="cia-tab-list" role="tablist">
 //       <label for="t1" role="tab">Tab 1</label>
 //       <label for="t2" role="tab">Tab 2</label>
-//     </div>
+//     </nav>
 //     <div class="cia-tab-panel" role="tabpanel">Content 1</div>
 //     <div class="cia-tab-panel" role="tabpanel">Content 2</div>
 //   </div>
 //
+// ⚠️ CONTRACT: the tab list must NOT share the panels' element type.
+// Panel switching indexes panels with :nth-of-type(), which counts by
+// ELEMENT TYPE among siblings — a <div> tab list would be div #1, every
+// panel's index would shift by one, and tab 1 would show no panel while
+// the labels still highlighted correctly (we shipped exactly that; fixed
+// 2026-09-04 by making the documented list a <nav>). CSS has no
+// nth-of-class, so the markup carries this rule instead of the selector.
+//
 // A11y baseline: keyboard nav (Tab + arrows + Space) and screen-reader text
 // are native. For full aria-selected sync ship the tiny opt-in JS shim
 // documented at /docs/components/tabs#aria.

package/scss/themes/boilerplate-dark.scss

@@ -167,11 +167,14 @@
 
   /* Space scale */
   --space-2xs: 0.25rem;
-  --space-xs:  0.5rem;
-  --space-sm:  0.75rem;
-  --space-md:  1rem;
-  --space-lg:  1.5rem;
-  --space-xl:  2rem;
+  --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);
+  --space-2xl: var(--space-7);
+  --space-3xl: var(--space-8);
+  --space-4xl: var(--space-9);
 
   /* Radius alias */
   --radius-sm:   var(--r-sm);

package/scss/themes/boilerplate-light.scss

@@ -164,11 +164,14 @@
 
   /* Space scale */
   --space-2xs: 0.25rem;
-  --space-xs:  0.5rem;
-  --space-sm:  0.75rem;
-  --space-md:  1rem;
-  --space-lg:  1.5rem;
-  --space-xl:  2rem;
+  --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);
+  --space-2xl: var(--space-7);
+  --space-3xl: var(--space-8);
+  --space-4xl: var(--space-9);
 
   /* Radius alias */
   --radius-sm:   var(--r-sm);

package/scss/themes/sketchbook-light.scss

@@ -185,11 +185,14 @@
 
   /* Space scale (rem for accessibility) */
   --space-2xs: 0.25rem;
-  --space-xs:  0.5rem;
-  --space-sm:  0.75rem;
-  --space-md:  1rem;
-  --space-lg:  1.5rem;
-  --space-xl:  2rem;
+  --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);
+  --space-2xl: var(--space-7);
+  --space-3xl: var(--space-8);
+  --space-4xl: var(--space-9);
 
   /* Radius alias — mirrors --r-* with standard names so
   `m.radius(size)` in the library finds --radius-<size>. */