css-is-awesome 1.9.4 → 1.10.0

package/AGENTS.md

@@ -298,7 +298,7 @@ Inside this package (all whitelisted in `files`):
 - **Don't hand-edit `public/themes/**/theme.css` or `public/theme.css`.** They are build artifacts of `scss/themes/*.scss`. Edit the SCSS, run `npm run build:css:themes`, and `npm run check:theme-drift` to prove source and artifact agree.
 - **Don't hand-write a theme's selector.** `@include cia.theme(name)` emits `:root, :root[data-theme="name"]` — both halves, on purpose. Writing `[data-theme=x]` yourself breaks the single-file drop-in; writing a bare `:root` yourself breaks the bundle.
 - **Theme the numbered spacing scale, not the t-shirt aliases.** `--space-0`…`--space-9` are contract-required; `--space-md` and friends are optional `var()` aliases that follow them.
-- **Print/PDF is a pure-CSS layer.** Include `cia.print-base` once at the stylesheet ROOT (it emits `@page`), then `cia.print-hidden` to drop chrome and `cia.print-only` to reveal paper-only content. Read `--is-print` (`0` screen / `1` paper) for custom effects. cia ships **zero JS** for it — the browser's native Print → Save as PDF is the generator.
+- **Print/PDF is a pure-CSS layer.** Include `cia.print-base` once at the stylesheet ROOT (it emits `@page`), then `cia.print-hidden` to drop chrome and `cia.print-only` to reveal paper-only content. Read `--is-print` (`0` screen / `1` paper) for custom effects. cia ships **zero JS** for it — the browser's native Print → Save as PDF is the generator. `print-base` always forces `color-scheme: light` in print (paired `light-dark()` themes print their light branch), plus four opt-in flags, all default OFF: `$legible` (darken body-text tokens so dark-only themes stay readable on white), `$link-urls` + `$link-origin` (print each link's full destination via `attr(href)`), `$page-numbers` (sheet numbers in the `@page` footer). Paginated spec-document output is the `print-spec` recipe.
 - **Do NOT "clean up" the `!important` in the print mixins.** It is load-bearing and deliberate. `@media` contributes no specificity, so `print-hidden` carries only the specificity of the selector it is included in; a later equal-specificity `display` (usually a utility class or a component library) wins in print. Verified in a browser: with `!important` the element hides, without it it prints anyway — a silent, paper-only failure. **`@layer` does not fix this** — layered CSS always loses to unlayered CSS, so a layered print rule loses to any unlayered consumer stylesheet, and `!important` inverts layer order on top of that. cia is unlayered by decision (`.agent/decisions/decided/04-at-layer-decision.md`). Scope is 8 declarations, all inside `@media print`, all variable-driven via `--print-hide` / `--print-show`.
 - **Don't ship JavaScript.** The npm package has zero `.js`/`.mjs` files. JS-dependent features ship as separate add-on packages.
 - **Variants are arguments, not classes.** `cia.btn(primary)`, not `cia-btn cia-btn-primary` (Tier 1 utilities are an exception, but only at consumer level).

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+# [1.10.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.9.5...v1.10.0) (2026-09-06)
+
+
+### Bug Fixes
+
+* **a11y:** TOC summary is not a nested interactive control ([5c65f8e](https://github.com/Jerry2d3d/css-is-awesome/commit/5c65f8e8d9c3318cfe89c9e623fec5a9994127ef))
+* **site:** TOC group carets sit at the right end of the summary ([6186a20](https://github.com/Jerry2d3d/css-is-awesome/commit/6186a20de6158541f2a9743f83b48b112789bf95))
+
+
+### Features
+
+* **print:** legible dark themes, full URLs, and sheet numbers via print-base flags ([213c8bd](https://github.com/Jerry2d3d/css-is-awesome/commit/213c8bdf76454b3ac0c0cfcc13bae7c5224f37aa)), closes [#anchors](https://github.com/Jerry2d3d/css-is-awesome/issues/anchors)
+* **site:** docs TOC collapses into groups - open one, the others close ([0c2ab84](https://github.com/Jerry2d3d/css-is-awesome/commit/0c2ab84e02e5e49ef11c204c67107c047135bf41))
+
+## [1.9.5](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.9.4...v1.9.5) (2026-09-06)
+
+
+### Bug Fixes
+
+* **site:** docs print index harvests on beforeprint - was showing stale headings ([21a066b](https://github.com/Jerry2d3d/css-is-awesome/commit/21a066bdaa7b488f012333e5e07fa6fd34c57086))
+* **site:** docs screen TOC re-harvests per page - was frozen on page one ([e746ab4](https://github.com/Jerry2d3d/css-is-awesome/commit/e746ab47072b407c627e9f375819cad9c3d7abab))
+* **site:** print docs left nav hidden - the On this page bullets are the index ([8fb6b19](https://github.com/Jerry2d3d/css-is-awesome/commit/8fb6b19e656382d7d2c708ba8ef62466d03f4983))
+
 ## [1.9.4](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.9.3...v1.9.4) (2026-09-06)
 
 

package/README.md

@@ -8,7 +8,7 @@
 
 **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://cssisawesome.com/docs/recipes/).
+> **The recipes book:** build any component in any framework using cia mixins — six recipes today (`dialog`, `combobox`, `print-to-pdf`, `print-spec`, `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
 
@@ -241,14 +241,16 @@ Print support is a pure-CSS layer — the browser's native **Print → Save as P
 
 // Once, in a GLOBAL stylesheet — never inside a component module.
 // It emits its own :root block plus @page, so don't wrap it in a selector.
-@include cia.print-base;                   // optional: ($size, $margin, $freeze-animations)
+@include cia.print-base;                   // optional flags: ($size, $margin, $freeze-animations, $legible, $link-urls, $link-origin, $page-numbers)
 
 .site-nav   { @include cia.print-hidden; } // drop chrome on paper
 .print-note { @include cia.print-only; }   // reveal paper-only content
 .invoice    { @include cia.print { border: 1px solid; } } // bare @media print wrapper
 ```
 
-`print-base` also collapses animations to zero duration and pins them to their final frame, so a page snapshotted mid-entrance-fade doesn't print as invisible text. It deliberately does **not** force `opacity: 1` or `transform: none` — that would fix the fade while flattening every intentional use of the same properties (a 0.15 watermark, a 0.4 disabled control, a stamp rotated `-4deg`). Elements that were never animating are left untouched. Read `--is-print` (`0` on screen, `1` on paper) for custom effects. Full walkthrough: the [`print-to-pdf`](./scss/recipes/print-to-pdf.md) recipe.
+`print-base` also collapses animations to zero duration and pins them to their final frame, so a page snapshotted mid-entrance-fade doesn't print as invisible text. It deliberately does **not** force `opacity: 1` or `transform: none` — that would fix the fade while flattening every intentional use of the same properties (a 0.15 watermark, a 0.4 disabled control, a stamp rotated `-4deg`). Elements that were never animating are left untouched. Read `--is-print` (`0` on screen, `1` on paper) for custom effects.
+
+Inside `@media print`, `print-base` always forces `color-scheme: light`, so paired `light-dark()` themes print their light branch for free. Four opt-in flags (all default off) take it further: `$legible` darkens the body-text tokens so dark-only themes (Terminal) stay readable as ink on white; `$link-urls` prints every link's destination via `attr(href)`; `$link-origin` prepends an origin so internal `/…` links resolve to full URLs on paper; `$page-numbers` numbers the sheets in the `@page` footer. The docs site and the theme editor at `/themes` turn those flags on to print themselves as paginated spec documents. Full walkthroughs: the [`print-to-pdf`](./scss/recipes/print-to-pdf.md) and [`print-spec`](./scss/recipes/print-spec.md) recipes.
 
 ### Why the print mixins use `!important`
 

package/css-is-awesome.instructions.md

@@ -171,11 +171,18 @@ browser's native Print → Save as PDF is the generator; cia just supplies the
 
 - **`print`** — bare `@media print { @content }` wrapper. Co-locate it inside
   a selector to override that element on paper.
-- **`print-base($freeze-animations: true, $size: letter, $margin: 0.5in)`** —
+- **`print-base($freeze-animations: true, $size: letter, $margin: 0.5in, $legible: false, $link-urls: false, $link-origin: null, $page-numbers: false)`** —
   page-level defaults, ON by default. Include it **once at the stylesheet
   ROOT** — it emits `@page` (invalid when nested in a selector), freezes
   animations so nothing prints invisible, and emits the print variable
-  control plane.
+  control plane. In `@media print` it always forces `color-scheme: light`, so
+  paired `light-dark()` themes print their light branch for free. Four opt-in
+  flags (all default OFF): `$legible` darkens the body-text tokens (`--ink`,
+  `--muted`…) so dark-only themes (Terminal) stay readable on white — code
+  blocks and accents untouched; `$link-urls` prints each link's destination via
+  `attr(href)`; `$link-origin` prepends an origin to internal `/…` links so they
+  resolve to full URLs; `$page-numbers` puts `counter(page)` in the `@page`
+  bottom-center margin box.
 - **`print-hidden`** — hide an element on paper (the "hide the nav" case).
 - **`print-only`** — show an element only on paper (e.g. an inline URL
   footer); hidden on screen.
@@ -477,8 +484,9 @@ A recipe is a markdown file at `scss/recipes/<name>.md` carrying:
 - an a11y checklist graded against WCAG 2.2 AA
 - framework-neutral notes so it ports to React / Vue / Svelte / vanilla
 
-**Shipped today:** `dialog`, `combobox`, `print-to-pdf`, `mobile-nav`,
-`bottom-nav`. Queued next: `datepicker`, `data-table`, `command-palette`.
+**Shipped today:** `dialog`, `combobox`, `print-to-pdf`, `print-spec`,
+`mobile-nav`, `bottom-nav`. Queued next: `datepicker`, `data-table`,
+`command-palette`.
 
 The two mobile recipes ride the `hamburger` / `drawer` / `sheet` / `dock`
 mixin family — zero JS on the native Popover API. `mobile-nav` is the flex

package/llm.txt

@@ -45,7 +45,7 @@ silent.
 
 ## What cia provides (one-line each)
 
-- **Mixins** — `cia.btn`, `cia.card`, `cia.accordion`, `cia.modal`, `cia.tooltip`, `cia.dropdown`, `cia.tabs`, `cia.copy-button`, `cia.hamburger`, `cia.drawer`, `cia.sheet`, `cia.dock`, `cia.stepper`, `cia.progress`, `cia.wizard-shell`, `cia.sidebar`, `cia.toolbar`, `cia.stack`, `cia.cluster`, `cia.switcher`, `cia.cover`, `cia.frame`, `cia.media`, `cia.contain`, `cia.focus-ring`, `cia.sr-only`, `cia.print`, `cia.print-base`, `cia.print-hidden`, `cia.print-only`, `cia.color`, `cia.space`, `cia.radius`, `cia.shadow`, `cia.font`, `cia.transition`, `cia.animate`, plus many more.
+- **Mixins** — `cia.btn`, `cia.card`, `cia.accordion`, `cia.modal`, `cia.tooltip`, `cia.dropdown`, `cia.tabs`, `cia.copy-button`, `cia.hamburger`, `cia.drawer`, `cia.sheet`, `cia.dock`, `cia.stepper`, `cia.progress`, `cia.wizard-shell`, `cia.sidebar`, `cia.toolbar`, `cia.stack`, `cia.cluster`, `cia.switcher`, `cia.cover`, `cia.frame`, `cia.media`, `cia.contain`, `cia.focus-ring`, `cia.sr-only`, `cia.print`, `cia.print-base`, `cia.print-hidden`, `cia.print-only`, `cia.color`, `cia.space`, `cia.radius`, `cia.shadow`, `cia.font`, `cia.transition`, `cia.animate`, plus many more. **`cia.print-base` always forces `color-scheme: light` in print (paired `light-dark()` themes print their light branch) plus four opt-in flags, all default OFF:** `$legible` (darken body-text tokens so dark-only themes stay readable on white; code/accents untouched), `$link-urls` + `$link-origin` (print each link's full destination via `attr(href)`), `$page-numbers` (sheet numbers in the `@page` footer).
 - **24 themes / 8 families** — boilerplate, sketchbook, press, prism, cupertino, glass, graphite, terminal. Each family ships three files: an unsuffixed dual-mode base (both modes via `light-dark()`) plus pinned `-light` and `-dark` single-mode variants for `<link media>` pairing. Every one has exactly one SCSS source under `scss/themes/`; `public/themes/<name>/theme.css` is BUILD OUTPUT and is gated against its source by `npm run check:theme-drift` — never hand-edit it. MCP `list_themes` returns **24**. Say **24 themes across 8 families** when you need one number.
 - **6 zero-JS interactive components** — accordion (`<details name>`), modal (`<dialog>`), tooltip (`popover="hint"`), dropdown (`[popover]` — the mixin re-asserts the UA's closed state and restores `display: flex` only under `:popover-open`, so menus never render permanently open on popover markup), tabs (radio + `:has()`), copy-button (Clipboard API via consumer-wired JS).
 - **CLI** (`npx cia`) — `migrate tailwind|bootstrap` (config → cia theme), `add <recipe>` (copy a recipe from the book into the project), `analyze [path]` (audit stylesheets against the installed API: dead `cia.*` symbols, the `space()` 1–9 trap, hard-coded hex, BEM; health score, CI exit codes).
@@ -170,7 +170,7 @@ cia ships a **recipes book**: portable patterns for building accessible componen
 
 AI agents read recipes via MCP `list_recipes` / `get_recipe(name)` and generate consumer components in any framework. Humans read them at `/docs/recipes` and copy patterns directly.
 
-**Shipped today — 5 recipes: dialog, combobox, print-to-pdf, mobile-nav, bottom-nav.** Queued next: datepicker, data-table, command-palette. **No component library** — recipes are the deliverable. See `scss/recipes/README.md` for the schema.
+**Shipped today — 6 recipes: dialog, combobox, print-to-pdf, print-spec, mobile-nav, bottom-nav.** Queued next: datepicker, data-table, command-palette. **No component library** — recipes are the deliverable. See `scss/recipes/README.md` for the schema.
 
 ## Priority ladder (the v1.0 pitch order)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "css-is-awesome",
-  "version": "1.9.4",
+  "version": "1.10.0",
   "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/scss/_mixins.scss

@@ -598,7 +598,15 @@ $_type-scale: (
 // Override either locally for a per-element exception — no rule rewrite:
 //   .keep-this { --print-hide: revert; }   // stays on paper despite print-hidden
 //   .pdf-row   { --print-show: flex; }     // print-only block laid out as flex
-@mixin print-base($freeze-animations: true, $size: letter, $margin: 0.5in) {
+@mixin print-base(
+  $freeze-animations: true,
+  $size: letter,
+  $margin: 0.5in,
+  $legible: false,
+  $link-urls: false,
+  $link-origin: null,
+  $page-numbers: false
+) {
   :root {
     --is-print: 0;
     --print-hide: none;
@@ -606,10 +614,57 @@ $_type-scale: (
   }
 
   @media print {
-    :root { --is-print: 1; }
+    :root {
+      --is-print: 1;
+
+      // Paired themes build color as light-dark(): forcing the light scheme
+      // makes them print their light branch — light text becomes dark text
+      // on the (already white) sheet, for free. Dark-only themes use literal
+      // values and ignore this; $legible below covers them.
+      color-scheme: light;
+
+      @if $legible {
+        // Dark-only themes (e.g. Terminal) have literal LIGHT ink — unreadable
+        // once the background drops to white in print. Darken just the body
+        // text tokens; --code-* stay untouched so code blocks keep their ink,
+        // and accents are left alone so links/headings keep the theme's voice.
+        --ink:       CanvasText;
+        --ink-soft:  color-mix(in sRGB, CanvasText 78%, Canvas);
+        --ink-faint: color-mix(in sRGB, CanvasText 60%, Canvas);
+        --muted:     color-mix(in sRGB, CanvasText 70%, Canvas);
+      }
+    }
 
     @page { size: $size; margin: $margin; }
 
+    @if $page-numbers {
+      // Sheet numbers in the bottom-center margin box. Progressive: engines
+      // without margin-box support simply print unnumbered.
+      @page { @bottom-center { content: counter(page); font-size: 9pt; } }
+    }
+
+    @if $link-urls {
+      // Print each link's destination after it, so a paper copy is followable.
+      // External links print their href; internal links prepend $link-origin
+      // to become full URLs; same-page anchors are skipped (the URL adds
+      // nothing there).
+      a[href^="http"]::after {
+        content: " (" attr(href) ")";
+        font-size: 0.85em;
+        color: color-mix(in sRGB, CanvasText 60%, Canvas);
+        word-break: break-all;
+      }
+      @if $link-origin {
+        a[href^="/"]::after {
+          content: " (#{$link-origin}" attr(href) ")";
+          font-size: 0.85em;
+          color: color-mix(in sRGB, CanvasText 60%, Canvas);
+          word-break: break-all;
+        }
+      }
+      a[href^="#"]::after { content: none; }
+    }
+
     @if $freeze-animations {
       // The opacity:0 entrance-fade trap: a page snapshotted mid-animation
       // prints invisible text.

package/scss/recipes/print-spec.md

@@ -0,0 +1,390 @@
+---
+name: print-spec
+description: Turn a live page into a paginated specification document on Ctrl+P — cover + table index, one page per section, printed sheet numbers — with pure-CSS page breaks.
+category: layout
+complexity: medium
+cia-version: ">=1.9.0"
+---
+
+## Use this when
+
+You want `Ctrl/Cmd+P` (or Save-as-PDF) to emit a **spec document** from a page you already have — a cover page with a numbered table index, then every major section starting on its own sheet, with a page number printed in the margin of each. The cia site itself does this: the theme editor at `/themes` prints as a "Theme Specification," and the docs render a print-only "On this page" index. This is the *paginate-it-as-a-spec* recipe. If you only need a page to save as a faithful PDF — a résumé, an invoice, a receipt where the page **is** the document and pagination is incidental — use [`print-to-pdf`](./print-to-pdf.md) instead; it is simpler and this recipe builds on it. Reach for this one when the printed artifact has a *structure of its own* (index → sections → numbered pages) that the screen page does not show.
+
+## Structure (raw HTML)
+
+Three ingredients: **screen chrome** that must vanish on paper, a **cover/index** that appears only on paper, and the **sections** — each one a page. Put `data-cia-recipe` on the root; mark the index and each section with `data-slot` so tooling and your styles can find them.
+
+```html
+<main data-cia-recipe="print-spec">
+  <!-- 1. Screen-only chrome — hidden on paper. -->
+  <nav class="site-nav no-print">…</nav>
+  <aside class="doc-sidebar no-print">…</aside>
+
+  <!-- 2. Cover + table index — PRINT ONLY (hidden on screen).
+       The page numbers are hard-coded in the markup; they are
+       honest because each section forces its own page below,
+       so section k always lands on page k+1. -->
+  <nav class="print-index" data-slot="index" aria-label="Table index">
+    <h2>Table index</h2>
+    <ol>
+      <li><span>Cover &amp; index</span><span class="print-leader" aria-hidden="true"></span><span class="print-page">1</span></li>
+      <li><span>Overview</span><span class="print-leader" aria-hidden="true"></span><span class="print-page">2</span></li>
+      <li><span>Tokens</span><span class="print-leader" aria-hidden="true"></span><span class="print-page">3</span></li>
+      <li><span>Components</span><span class="print-leader" aria-hidden="true"></span><span class="print-page">4</span></li>
+    </ol>
+  </nav>
+
+  <!-- 3. Each section is one printed page. -->
+  <section class="section" data-slot="section" id="overview">
+    <h2>Overview</h2>
+    <p>…</p>
+  </section>
+  <section class="section" data-slot="section" id="tokens">
+    <h2>Tokens</h2>
+    <p>…</p>
+  </section>
+  <section class="section" data-slot="section" id="components">
+    <h2>Components</h2>
+    <p>…</p>
+  </section>
+</main>
+```
+
+Notes on the markup:
+
+- **No button is required.** Every print path — `Ctrl/Cmd+P`, File → Print, the dialog's built-in "Save as PDF" — triggers the same `@media print` layer. A `<button onclick="window.print()">` is a discoverability signpost only (see [`print-to-pdf`](./print-to-pdf.md) for that one line).
+- The index is a real `<nav aria-label="Table index">`, not a decorative block — it is genuine navigation for the printed artifact.
+- The `print-leader` span is the dotted line between a label and its page number; it is `aria-hidden` because it carries no meaning for a screen reader.
+
+## Styling (cia mixins)
+
+Four moves, all pure CSS: `print-base` once at the root, `print-only` on the index, `print-hidden` on the chrome, and `break-before: page` on each section. A `@page` margin box adds the printed sheet number.
+
+**1. In your GLOBAL stylesheet** — `print-base` emits its own `:root` block plus `@page`, so it must sit at the top level of a global/root stylesheet, never inside a `.module.scss` (a top-level `:root` is a hard build error under Next.js CSS Modules pure mode). This is also where the sheet-number `@page` box lives, because it extends the same `@page` box `print-base` opened.
+
+```scss
+// app/globals.scss (or your single root stylesheet) — included ONCE.
+@use 'css-is-awesome/api' as cia;
+
+// The control plane, the @page box, the animation freeze — plus the print
+// polish flags. Each defaults OFF except the two structural ones, so nothing
+// changes for existing callers until you opt in:
+//   $legible      — dark-only themes (literal light ink) print dark body text.
+//   $link-urls    — every link prints its destination, so paper is followable.
+//   $link-origin  — prepended to internal (/…) hrefs so they print as full URLs.
+//   $page-numbers — sheet numbers in the bottom-center margin box.
+// print-base also forces `color-scheme: light` in print for free, so PAIRED
+// themes (light-dark() tokens) land on their light branch automatically.
+@include cia.print-base(
+  $legible: true,
+  $link-urls: true,
+  $link-origin: 'https://example.com',
+  $page-numbers: true
+);
+
+// Hide site chrome on paper.
+.site-nav,
+.doc-sidebar,
+.no-print {
+  @include cia.print-hidden;
+}
+```
+
+`$legible` darkens only the body text tokens (`--ink`, `--ink-soft`,
+`--ink-faint`, `--muted`) — code blocks keep their own `--code-*` ink, and
+accents are left alone so links and headings keep the theme's voice.
+`$link-urls` prints external hrefs directly and internal ones prefixed with
+`$link-origin`; same-page `#anchor` links are skipped (the URL adds nothing).
+
+**2. In the page's COMPONENT stylesheet** — the index show/hide and the per-section page break emit nothing until called, so they are safe in a `.module.scss`.
+
+```scss
+// PrintSpec.module.scss — component stylesheet, so import the zero-emit barrel.
+@use 'css-is-awesome/api' as cia;
+
+// The cover/index is paper-only: hidden on screen, revealed in print.
+.print-index {
+  @include cia.print-only;
+}
+.print-index li {
+  display: flex;
+  align-items: baseline;
+  gap: cia.space(2);
+}
+.print-leader {
+  flex: 1;
+  border-block-end: 1px dotted cia.color(text-muted);
+}
+.print-page {
+  font-family: var(--font-mono, monospace);
+}
+
+// THE KEY MOVE: each section starts a new sheet. This is what makes the
+// index's hard-coded numbers a guarantee rather than a hope — section k
+// is deterministically page k+1.
+.section {
+  @include cia.print { break-before: page; }
+}
+```
+
+Class names are consumer-chosen (`.print-index`, `.section`) — never `cia-*`. For the full account of *why* the print mixins compile to `!important` and why `@layer` cannot replace them, see [`print-to-pdf`](./print-to-pdf.md); the same variable-driven control plane (`--is-print` / `--print-hide` / `--print-show`) powers this recipe.
+
+**Honest numbering.** Hard-coded page numbers in the index are only truthful while every section forces its own break. Drop the `break-before: page` and section 3 might reflow onto page 2 — the index now *lies*. If you cannot guarantee one-page-per-section (long, flowing prose that legitimately spans pages), do not print hard numbers; use the dynamic harvested index below with bullets instead, which is exactly why the docs site prints bullets, not numbers, for article prose.
+
+## Interactivity
+
+**The pagination is pure CSS — zero JavaScript.** `print-only`, `print-hidden`, `break-before: page`, and the `@page` margin box are the entire engine. A **static** spec with a hard-coded table index needs no script at all.
+
+The **only** optional JS is a *dynamic* "On this page" index that harvests the current page's own `<h2>` headings so the printed index matches whatever page is being printed. There are two non-obvious requirements, and getting either wrong ships a stale index:
+
+- **Re-read on navigation.** In an SPA a shared layout persists across client-side route changes, so a harvest that runs once at mount goes stale the moment the user navigates. Key the harvest to the current route.
+- **Re-read on `beforeprint`.** The window fires `beforeprint` immediately before the print dialog snapshots the page. Harvesting there guarantees the printed list reflects the DOM *as printed*, even if the route-keyed read missed a late render. This is the belt-and-braces guarantee.
+
+Harvest `article h2[id]`, store `{ id, text }`, render a `print-only` `<nav>`. Return nothing when there are no headings. The screen never sees it; only paper does.
+
+## A11y checklist
+
+- [ ] The printed index is a real `<nav>` with an `aria-label`, so it is an addressable landmark, not a decorative block ([WAI-ARIA APG: Landmark regions](https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/))
+- [ ] Section headings stay real `<h2>` elements (the harvest reads them, it does not replace them), preserving the document outline ([WCAG 2.2 SC 2.4.6 Headings and Labels](https://www.w3.org/WAI/WCAG22/Understanding/headings-and-labels.html))
+- [ ] Print output follows DOM/reading order — the cover/index precedes the sections in source, so it prints first ([WCAG 2.2 SC 1.3.2 Meaningful Sequence](https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence.html))
+- [ ] Hiding chrome with `print-hidden` removes only navigation and controls, never content the spec needs to make sense ([WCAG 2.2 SC 1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html))
+- [ ] Ink-on-paper contrast meets the minimum — the `color-scheme: light` flip keeps dark text on a light sheet ([WCAG 2.2 SC 1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html))
+- [ ] Purely visual leader dots between a label and its page number are `aria-hidden`, so a screen reader hears "Overview 2", not a run of dots ([WCAG 2.2 SC 1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html))
+
+## Framework examples
+
+Every example is the **optional** dynamic "On this page" index — the only framework-specific code in this recipe. The pagination itself (section breaks, show/hide, sheet numbers) is pure CSS and identical across stacks. Each harvests `article h2[id]`, re-reads on navigation **and** on `beforeprint`, and renders a `print-only` `<nav>`. The static hard-coded index needs none of this.
+
+### React
+
+```tsx
+"use client";
+import { useEffect, useState } from "react";
+import { usePathname } from "next/navigation";
+import styles from "./PrintSpecIndex.module.scss";
+
+// Mirrors the cia docs site's DocsPrintIndex.
+export default function PrintSpecIndex() {
+  const pathname = usePathname();
+  const [headings, setHeadings] = useState<{ id: string; text: string }[]>([]);
+
+  useEffect(() => {
+    const harvest = () => {
+      const article = document.querySelector<HTMLElement>("article");
+      if (!article) return;
+      const nodes = Array.from(article.querySelectorAll<HTMLHeadingElement>("h2[id]"));
+      setHeadings(nodes.map((n) => ({ id: n.id, text: n.textContent ?? "" })));
+    };
+    // Harvest on navigation (pathname dep) AND at the moment of printing.
+    // The shared layout persists across client navigations, so a
+    // pathname-only read can go stale; beforeprint reads the CURRENT DOM.
+    harvest();
+    window.addEventListener("beforeprint", harvest);
+    return () => window.removeEventListener("beforeprint", harvest);
+  }, [pathname]);
+
+  if (headings.length === 0) return null;
+
+  return (
+    <nav className={styles.printIndex} aria-label="On this page">
+      <h2>On this page</h2>
+      <ul>
+        {headings.map((h) => (
+          <li key={h.id}>{h.text}</li>
+        ))}
+      </ul>
+    </nav>
+  );
+}
+```
+
+### Angular
+
+```ts
+import { Component, ElementRef, HostListener, OnDestroy, OnInit } from "@angular/core";
+import { NavigationEnd, Router } from "@angular/router";
+import { Subscription, filter } from "rxjs";
+
+@Component({
+  selector: "print-spec-index",
+  standalone: true,
+  template: `
+    <nav class="print-index" aria-label="On this page" *ngIf="headings.length">
+      <h2>On this page</h2>
+      <ul>
+        <li *ngFor="let h of headings">{{ h.text }}</li>
+      </ul>
+    </nav>
+  `,
+})
+export class PrintSpecIndexComponent implements OnInit, OnDestroy {
+  headings: { id: string; text: string }[] = [];
+  private sub?: Subscription;
+
+  constructor(private router: Router, private host: ElementRef<HTMLElement>) {}
+
+  ngOnInit(): void {
+    this.harvest();
+    // Re-read on every completed navigation — the layout persists.
+    this.sub = this.router.events
+      .pipe(filter((e) => e instanceof NavigationEnd))
+      .subscribe(() => this.harvest());
+  }
+
+  // The guarantee: re-read the CURRENT DOM right before the print dialog.
+  @HostListener("window:beforeprint")
+  harvest(): void {
+    const article = this.host.nativeElement.ownerDocument.querySelector("article");
+    if (!article) return;
+    this.headings = Array.from(article.querySelectorAll<HTMLHeadingElement>("h2[id]")).map(
+      (n) => ({ id: n.id, text: n.textContent ?? "" }),
+    );
+  }
+
+  ngOnDestroy(): void {
+    this.sub?.unsubscribe();
+  }
+}
+```
+
+### Vue
+
+```vue
+<script setup>
+import { ref, onMounted, onUnmounted, watch } from "vue";
+import { useRoute } from "vue-router";
+
+const route = useRoute();
+const headings = ref([]);
+
+const harvest = () => {
+  const article = document.querySelector("article");
+  if (!article) return;
+  headings.value = Array.from(article.querySelectorAll("h2[id]")).map((n) => ({
+    id: n.id,
+    text: n.textContent ?? "",
+  }));
+};
+
+watch(() => route.fullPath, harvest);          // re-read on navigation
+onMounted(() => {
+  harvest();
+  window.addEventListener("beforeprint", harvest); // re-read before print
+});
+onUnmounted(() => window.removeEventListener("beforeprint", harvest));
+</script>
+
+<template>
+  <nav v-if="headings.length" class="print-index" aria-label="On this page">
+    <h2>On this page</h2>
+    <ul>
+      <li v-for="h in headings" :key="h.id">{{ h.text }}</li>
+    </ul>
+  </nav>
+</template>
+```
+
+### Svelte
+
+```svelte
+<script>
+  import { onMount } from "svelte";
+  import { page } from "$app/stores"; // SvelteKit route store
+
+  let headings = [];
+  const harvest = () => {
+    const article = document.querySelector("article");
+    if (!article) return;
+    headings = Array.from(article.querySelectorAll("h2[id]")).map((n) => ({
+      id: n.id,
+      text: n.textContent ?? "",
+    }));
+  };
+
+  $: $page.url.pathname, harvest();            // re-read on navigation
+
+  onMount(() => {
+    harvest();
+    window.addEventListener("beforeprint", harvest); // re-read before print
+    return () => window.removeEventListener("beforeprint", harvest);
+  });
+</script>
+
+{#if headings.length}
+  <nav class="print-index" aria-label="On this page">
+    <h2>On this page</h2>
+    <ul>
+      {#each headings as h (h.id)}
+        <li>{h.text}</li>
+      {/each}
+    </ul>
+  </nav>
+{/if}
+```
+
+### Vanilla (Web Component)
+
+```js
+// No router to hook: in a multi-page site each load re-runs the harvest,
+// so `beforeprint` is the only listener needed. In an SPA, also call
+// harvest() from your router's after-navigation hook.
+class PrintSpecIndex extends HTMLElement {
+  connectedCallback() {
+    this.harvest();
+    this._onBeforePrint = () => this.harvest();
+    window.addEventListener("beforeprint", this._onBeforePrint);
+  }
+  disconnectedCallback() {
+    window.removeEventListener("beforeprint", this._onBeforePrint);
+  }
+  harvest() {
+    const article = document.querySelector("article");
+    const items = article
+      ? Array.from(article.querySelectorAll("h2[id]")).map((n) => `<li>${n.textContent}</li>`)
+      : [];
+    this.innerHTML = items.length
+      ? `<nav class="print-index" aria-label="On this page"><h2>On this page</h2><ul>${items.join("")}</ul></nav>`
+      : "";
+  }
+}
+customElements.define("print-spec-index", PrintSpecIndex);
+
+// Usage: <print-spec-index></print-spec-index>
+// The STATIC hard-coded index needs zero JS — just the markup + CSS above.
+```
+
+## Variants
+
+### Static, hard-coded table index (zero JS)
+
+Skip every framework example. Write the numbers into the markup (the Structure block above) and rely on `break-before: page` to make them true. Deterministic, no runtime, nothing to hydrate. Choose this whenever your sections are guaranteed one page each.
+
+### International paper (A4) / landscape
+
+Pass the size through `print-base` at the root, and set orientation on `@page`:
+
+```scss
+// app/globals.scss — top level, not inside a selector, not in a component module
+@include cia.print-base($size: A4, $margin: 0.75in);
+
+@include cia.print {
+  @page { size: A4 landscape; }
+}
+```
+
+### Bullets instead of numbers (flowing prose)
+
+When a section legitimately spans several pages, drop the page-number column and print the harvested index as plain bullets — an honest "here's what's in this document" without a number that would be a guess. This is what the cia docs do for article prose.
+
+## Pitfalls
+
+- **`print-base` must be root/global.** It emits a `:root` block plus `@page`; inside a `.module.scss` that is a hard build error under Next.js CSS Modules pure mode, and wrapping it in a selector double-nests the `:root` it already writes. It belongs at the top level of a single global stylesheet, included once.
+- **`@page` margin boxes are not universal.** `@bottom-center { content: counter(page) }` is unsupported in some engines, which simply print **unnumbered** sheets — no error, no fallback. Keep the table index's own numbers in the markup so navigation survives; treat the margin-box number as progressive enhancement.
+- **Hard-coded index numbers lie without forced breaks.** The numbers are only honest while every section forces its own page. Remove a `break-before: page` and the index silently points at the wrong pages — a bug that only shows up in print preview. Either guarantee one-page-per-section or switch to the bullets variant.
+- **Forcing `break-before` on flowing prose wastes paper.** A `break-before: page` on every heading of a long article strands half-empty sheets. The docs site deliberately prints *bullets, not numbers* for prose precisely so it does not have to force a break per heading. Reserve forced breaks for genuinely page-sized sections (a component demo, a spec table), not every paragraph.
+- **A stale index from a run-once harvest.** In an SPA the layout persists across navigation, so a mount-only read prints the previous page's headings. Re-read on the route change **and** on `beforeprint` — the `beforeprint` read is the one that guarantees the paper matches the page.
+- **Dark themes print white-on-white** unless the `color-scheme: light` flip is in place (it lands every `light-dark()` token on its light value). See [`print-to-pdf`](./print-to-pdf.md) Pitfalls for the element-level escape hatch.
+
+## Related recipes
+
+- [`print-to-pdf`](./print-to-pdf.md) — the foundation: save a styled page as a faithful PDF with a `@media print` stylesheet. This recipe adds pagination, a cover/index, and sheet numbers on top of it.

package/scss/recipes/print-to-pdf.md

@@ -260,4 +260,5 @@ These are the bugs that *will* bite — each one cost real debugging time. This
 
 ## Related recipes
 
+- [`print-spec`](./print-spec.md) — the paginated-spec companion (cover + table index, one page per section, printed sheet numbers). It builds on this recipe and leans on `print-base`'s opt-in flags — `$legible` (readable dark themes on paper), `$link-urls` / `$link-origin` (full followable URLs), `$page-numbers` (sheet numbers) — which automate the manual URL-and-page-break handling shown above.
 - [`dialog`](./dialog.md) — a print-only summary often lives inside a confirmation dialog before export