css-is-awesome 1.10.3 → 1.11.1

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-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.
+- **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), defines a themeable print palette (`--print-ink/-paper/-line/-muted`, default ink-on-white) and rebinds the theme's colour tokens (`--ink`, `--surface-*`, `--border-*`, `--code-*`) onto it, so every theme — dark-only included — prints legible ink-on-paper; override a `--print-*` token to restyle paper (a letterhead), in a theme's own `@media print` or a `<link media="print">` sheet. Three opt-in flags, all default OFF: `$link-urls` + `$link-origin` (print each link's full destination via `attr(href)`), `$page-numbers` (sheet numbers in the `@page` footer). `$legible` is a deprecated no-op — the rebind supersedes it. 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).
@@ -342,8 +342,10 @@ The SDK is an optional peer dep — `npm install -D @modelcontextprotocol/sdk zo
   dumps a cia theme; `npx cia add <recipe>` (`--list` to browse) copies a recipe
   from the book into the project — own the pattern; `npx cia analyze [path]`
   audits a project's stylesheets against the installed API — dead `cia.*` symbols,
-  the `space()` 1–9 scale trap, hard-coded hex colors, BEM chains — with a health
-  score and CI-ready exit codes. Run any verb with `--help`. (`cia init` remains
+  the `space()` 1–9 scale trap, off-contract tokens (near-miss typos only), hard-coded
+  hex colors, BEM chains — with a health score and CI-ready exit codes. Low-noise on
+  color: a hex in a `var(--token, #hex)` fallback is token-driven, and a literal inside
+  `@media print` is an intentional paper colour — neither is flagged. Run any verb with `--help`. (`cia init` remains
   planned.)
 - **JSON token export** — DTCG-format token list in `figma-tokens/`.
 - **`llm.txt`** — at the repo root and served from the docs site; single-fetch

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [1.11.1](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.11.0...v1.11.1) (2026-09-09)
+
+
+### Features
+
+* **site:** second print example — a letter with letterhead + footer ([4891391](https://github.com/Jerry2d3d/css-is-awesome/commit/4891391bf29aaa0489473318e7ad0face04a772e))
+
+# [1.11.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.10.3...v1.11.0) (2026-09-09)
+
+
+### Features
+
+* **cli:** analyzer off-contract-token rule + print/var-aware color analysis ([6cd1eeb](https://github.com/Jerry2d3d/css-is-awesome/commit/6cd1eeb5feb082cc9c1bf5330d9c540b4cb332d7)), closes [hi#signal](https://github.com/hi/issues/signal) [#hex](https://github.com/Jerry2d3d/css-is-awesome/issues/hex)
+* **cli:** graded, categorized analyzer report (EPIC-06 F3.1) ([ee56cdb](https://github.com/Jerry2d3d/css-is-awesome/commit/ee56cdbd17695f115226c4faeee6382a6041e7d5))
+* **print:** letterhead recipe + Press newsprint print identity ([5963b0c](https://github.com/Jerry2d3d/css-is-awesome/commit/5963b0cce30eb1ce26d59230423477e41990747f))
+* **print:** themeable print palette + token rebind; deprecate $legible ([bf4c657](https://github.com/Jerry2d3d/css-is-awesome/commit/bf4c65783ec22d03eed2b9836928151597828124))
+* **site:** ACME letterhead invoice demo for the print theme ([5d5ed81](https://github.com/Jerry2d3d/css-is-awesome/commit/5d5ed81bf6f9c8490f2173f9d79b37f8f15fd7df))
+* **site:** theme-editor print mode — paper-preview modal (EPIC-08 F5) ([1cfc83e](https://github.com/Jerry2d3d/css-is-awesome/commit/1cfc83e6c1a68eb39b144669802061710337c99c))
+
 ## [1.10.3](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.10.2...v1.10.3) (2026-09-07)
 
 

package/README.md

@@ -8,7 +8,7 @@
 
 **Docs:** [cssisawesome.com](https://cssisawesome.com/) · **Install:** `npm install css-is-awesome`
 
-> **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/).
+> **The recipes book:** build any component in any framework using cia mixins — seven recipes today (`dialog`, `combobox`, `print-to-pdf`, `print-spec`, `letterhead`, `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
 
@@ -202,7 +202,7 @@ Missing font files don't error, so a silent tofu box is the failure mode. If you
 
 cia ships **no component library** — deliberately. Interactive patterns arrive as *recipes*: portable markdown files at [`scss/recipes/`](./scss/recipes/) that give you the correct HTML, the `cia.X` mixin calls to style it, and an a11y checklist graded against WCAG 2.2 AA. Copy the pattern into your own framework; you own the component, cia owns the styling and the accessibility homework.
 
-**Shipped:** `dialog`, `combobox`, `print-to-pdf`, `print-spec`, `mobile-nav`, `bottom-nav`. Queued next: `datepicker`, `data-table`, `command-palette`.
+**Shipped:** `dialog`, `combobox`, `print-to-pdf`, `print-spec`, `letterhead`, `mobile-nav`, `bottom-nav`. Queued next: `datepicker`, `data-table`, `command-palette`.
 
 **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.
 
@@ -227,10 +227,11 @@ The CLI also carries the registry and the health check:
 npx cia add --list          # browse the recipe book
 npx cia add bottom-nav      # copy a recipe into your project — you own the pattern
 npx cia analyze src/styles  # design-system health: dead cia.* symbols, the
-                            # space() scale trap, hard-coded colors, BEM creep
+                            # space() scale trap, off-contract tokens (typos),
+                            # hard-coded colors, BEM creep
 ```
 
-`cia analyze` reads the real API surface from the installed package and exits non-zero on errors, so it slots straight into CI.
+`cia analyze` reads the real API surface from the installed package and exits non-zero on errors, so it slots straight into CI. It's deliberately low-noise about color: a hex used as a `var(--token, #hex)` fallback is token-driven (not flagged), and a literal inside `@media print` is an intentional paper colour (print escapes theme colours by design). Off-contract-token findings only fire on a **near-miss** of a real token — a typo like `--inkk` — never on your own custom tokens. The default output is a **graded report** — a health score, a section per concern (Contract / Spacing / Color / Naming / Layout / API) with a `✓` when clean, and a suggested fix on each finding; add `--verbose` for the flat per-file list or `--json` for the machine shape.
 
 ## Print / PDF (zero JS)
 
@@ -241,7 +242,7 @@ 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 flags: ($size, $margin, $freeze-animations, $legible, $link-urls, $link-origin, $page-numbers)
+@include cia.print-base;                   // optional flags: ($size, $margin, $freeze-animations, $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
@@ -250,7 +251,30 @@ Print support is a pure-CSS layer — the browser's native **Print → Save as P
 
 `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.
+Inside `@media print`, `print-base` always forces `color-scheme: light`, so paired `light-dark()` themes print their light branch for free. It also defines a **print palette** — `--print-ink`, `--print-paper`, `--print-line`, `--print-muted` (default ink-on-white with light grays) — and rebinds the theme's own colour tokens (`--ink`, `--surface-*`, `--border-*`, `--code-*`) onto it, so every theme prints as clean ink-on-paper and dark-only themes (Terminal) are legible with no flag. Three opt-in flags (all default off) take it further: `$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. (`$legible` is now a **deprecated no-op** — the token rebind supersedes it; passing it warns.) The docs site and the theme editor at `/themes` turn those flags on to print themselves as paginated spec documents.
+
+### A print theme
+
+Those four `--print-*` tokens are ordinary custom properties, so print is themeable like any other surface. The default every theme inherits is clean black-on-white with light grays; a theme (or a single project) opts into its own paper identity only if it wants one — override the tokens and every element re-inks, no component touched:
+
+```scss
+// A letterhead: navy ink, silver rules. Put this in a theme's own @media print
+// block, or ship it as a print-only stylesheet loaded with <link media="print">.
+@media print {
+  :root {
+    --print-ink:   #16233f; // deep navy
+    --print-muted: #5b6b86;
+    --print-line:  #c7ccd6; // silver hairlines
+    // --print-paper stays #fff
+  }
+}
+```
+
+Loading it as a paired print sheet is the same mechanism as paired light/dark themes:
+
+```html
+<link rel="stylesheet" href="/themes/letterhead/print.css" media="print">
+```
 
 **See it work.** Two live demonstrations back the walkthroughs. The [`print-spec`](./scss/recipes/print-spec.md) recipe paginates a page into a spec document (cover + table index, one page per section, honest sheet numbers). And [`/examples/print-to-pdf`](https://cssisawesome.com/examples/print-to-pdf/) is a real invoice you `Ctrl+P`: on paper the site chrome and the button vanish, the invoice fills the whole sheet, its links print as full followable URLs (`$link-urls` + `$link-origin`), a sheet number appears, and a **print-only QR code** — generated at build time as inline SVG, zero browser JS, no image fetch — links the paper back to the live [invoice-online](https://cssisawesome.com/examples/print-to-pdf/online) page. Full walkthroughs: the [`print-to-pdf`](./scss/recipes/print-to-pdf.md) and [`print-spec`](./scss/recipes/print-spec.md) recipes.
 

package/bin/analyze.cjs

@@ -19,6 +19,32 @@ const fs = require('fs');
 const path = require('path');
 
 const PKG_SCSS = path.join(__dirname, '..', 'scss');
+const CONTRACT_PATH = path.join(__dirname, '..', 'scripts', 'theme-contract.json');
+
+// All contract token names (required + optional). Used to catch typo'd tokens —
+// a var(--x) that's a near-miss of a real token silently breaks the style.
+// The contract is optional; if it can't be read the rule simply goes quiet.
+function loadContractTokens() {
+  try {
+    const c = JSON.parse(fs.readFileSync(CONTRACT_PATH, 'utf8'));
+    return new Set([...(c.required || []), ...(c.optional || [])]);
+  } catch {
+    return new Set();
+  }
+}
+
+// Tiny Levenshtein (zero-dep). Only called on var(--x) misses, so cost is trivial.
+function editDistance(a, b) {
+  const m = a.length, n = b.length;
+  const d = Array.from({ length: m + 1 }, (_, i) => [i, ...Array(n).fill(0)]);
+  for (let j = 0; j <= n; j++) d[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+  }
+  return d[m][n];
+}
 
 const HELP = `cia analyze — design-system health check
 
@@ -33,6 +59,7 @@ Options:
                      Auto-detected per file from @use lines; use this when
                      imports are aliased through an intermediate file.
   --json             Machine-readable report on stdout.
+  --verbose          The per-file listing instead of the graded report.
   --strict           Exit 1 on warnings too (default: errors only).
 
 Examples:
@@ -106,7 +133,47 @@ function stripComments(src) {
   return src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
 }
 
-function analyzeFile(file, symbols, extraNs) {
+// A hex inside a `var(--token, #hex)` fallback is token-driven, not a hard-coded
+// color — that's the correct pattern (token first, literal only if unset).
+// Strip var() expressions innermost-first so nested fallbacks
+// (`var(--a, var(--b, #fff))`) collapse too, leaving only genuine literals.
+function stripVarExpr(src) {
+  let prev;
+  let s = src;
+  do {
+    prev = s;
+    s = s.replace(/var\([^()]*\)/g, '');
+  } while (s !== prev);
+  return s;
+}
+
+// Literals inside an @media print block are intentional: print deliberately
+// escapes theme colours (ink-on-white for legibility, grays for rules) so a
+// hard-coded #000/#fff there is correct, not a smell. Remove print @media
+// blocks — brace-balanced, so nested selectors are handled — before the
+// hard-coded-color scan. Non-print @media queries are kept and still scanned.
+function stripPrintBlocks(src) {
+  let out = '';
+  let i = 0;
+  while (i < src.length) {
+    const at = src.indexOf('@media', i);
+    if (at === -1) { out += src.slice(i); break; }
+    const braceOpen = src.indexOf('{', at);
+    if (braceOpen === -1) { out += src.slice(i); break; }
+    out += src.slice(i, at);
+    let depth = 0;
+    let j = braceOpen;
+    for (; j < src.length; j++) {
+      if (src[j] === '{') depth++;
+      else if (src[j] === '}' && --depth === 0) { j++; break; }
+    }
+    if (!/\bprint\b/.test(src.slice(at + 6, braceOpen))) out += src.slice(at, j);
+    i = j;
+  }
+  return out;
+}
+
+function analyzeFile(file, symbols, contractTokens, extraNs) {
   const raw = fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
   const src = stripComments(raw);
   const ns = detectNamespaces(src, extraNs);
@@ -130,7 +197,29 @@ function analyzeFile(file, symbols, extraNs) {
       }
     }
   }
-  for (const m of src.matchAll(/#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/g)) {
+  // off-contract-token: a var(--x) that's a near-miss of a real contract token
+  // (a typo → the declaration silently fails). Pure custom tokens — not close to
+  // any contract token — are the consumer's own and are left alone.
+  if (contractTokens && contractTokens.size) {
+    const seen = new Set();
+    for (const m of src.matchAll(/var\(\s*(--[\w-]+)/g)) {
+      const tok = m[1];
+      if (contractTokens.has(tok) || seen.has(tok)) continue;
+      seen.add(tok);
+      let best = null;
+      let bestD = Infinity;
+      for (const known of contractTokens) {
+        const d = editDistance(tok, known);
+        if (d < bestD) { bestD = d; best = known; }
+      }
+      if (best && bestD > 0 && bestD <= 2) {
+        findings.push({ level: 'warn', rule: 'off-contract-token', detail: `${tok} — not a contract token; did you mean ${best}?` });
+      }
+    }
+  }
+  // Genuine literal colors only — a hex used as a var() fallback is token-driven,
+  // and a hex inside @media print is an intentional paper colour.
+  for (const m of stripVarExpr(stripPrintBlocks(src)).matchAll(/#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/g)) {
     findings.push({ level: 'warn', rule: 'hard-coded-color', detail: `${m[0]} — values should come from tokens (cia.color(...) / var(--...))` });
   }
   for (const m of src.matchAll(/\.[a-zA-Z][\w]*(?:__|--)[\w-]+/g)) {
@@ -144,6 +233,31 @@ function analyzeFile(file, symbols, extraNs) {
 
 // ── report ──────────────────────────────────────────────────────────────────
 
+// Every rule belongs to a category, so the default report reads as a graded
+// health check (a section per concern) rather than a flat dump. Categories with
+// no findings print a ✓.
+const RULE_CATEGORY = {
+  'unknown-symbol': 'API',
+  'space-scale': 'Spacing',
+  'off-contract-token': 'Contract',
+  'hard-coded-color': 'Color',
+  bem: 'Naming',
+  'hand-written-areas': 'Layout',
+};
+// The categories with rules implemented today — shown ✓ when clean so a passing
+// audit reads as coverage, not silence.
+const IMPLEMENTED_CATEGORIES = ['API', 'Contract', 'Spacing', 'Color', 'Naming', 'Layout'];
+
+// Details are authored as "claim — suggested fix"; split so the graded report
+// can put the fix on its own `→` line.
+function splitDetail(detail) {
+  const i = detail.indexOf(' — ');
+  if (i === -1) return { claim: detail, suggestion: '' };
+  return { claim: detail.slice(0, i), suggestion: detail.slice(i + 3) };
+}
+
+const LEVEL_MARK = { error: '✗', warn: '⚠', info: 'ℹ' };
+
 async function run(args) {
   if (args[0] === '-h' || args[0] === '--help' || args[0] === 'help') {
     process.stdout.write(HELP);
@@ -151,6 +265,7 @@ async function run(args) {
   }
   const json = args.includes('--json');
   const strict = args.includes('--strict');
+  const verbose = args.includes('--verbose');
   const nsFlag = args.indexOf('--namespace');
   const extraNs = nsFlag !== -1 && args[nsFlag + 1] ? args[nsFlag + 1].split(',') : [];
   const target = path.resolve(args.find((a) => !a.startsWith('--') && a !== extraNs.join(',')) || '.');
@@ -161,28 +276,72 @@ async function run(args) {
   }
 
   const symbols = collectSymbols();
+  const contractTokens = loadContractTokens();
   const files = walkScss(target);
-  const results = files.map((f) => analyzeFile(f, symbols, extraNs)).filter((r) => r.findings.length || r.namespaces.length);
+  const results = files.map((f) => analyzeFile(f, symbols, contractTokens, extraNs)).filter((r) => r.findings.length || r.namespaces.length);
 
   const counts = { error: 0, warn: 0, info: 0 };
   for (const r of results) for (const f of r.findings) counts[f.level]++;
   const ciaFiles = results.filter((r) => r.namespaces.length).length;
   const health = Math.max(0, 100 - counts.error * 10 - counts.warn * 2 - counts.info);
 
+  // Enrich every finding with its category and a split-out suggestion — additive
+  // fields, so `--json` consumers of counts/health/results keep working.
+  for (const r of results) {
+    for (const f of r.findings) {
+      f.category = RULE_CATEGORY[f.rule] || 'Other';
+      const { suggestion } = splitDetail(f.detail);
+      if (suggestion) f.suggestion = suggestion;
+    }
+  }
+
+  const rel = path.relative(process.cwd(), target) || '.';
+  const out = (s) => process.stdout.write(s);
+
   if (json) {
-    process.stdout.write(JSON.stringify({ target, files: files.length, ciaFiles, apiSymbols: symbols.size, counts, health, results }, null, 2) + '\n');
-  } else {
-    process.stdout.write(`\ncia analyze — ${path.relative(process.cwd(), target) || '.'}\n`);
-    process.stdout.write(`${files.length} scss file(s), ${ciaFiles} using cia, ${symbols.size} API symbols known\n\n`);
+    out(JSON.stringify({ target, files: files.length, ciaFiles, apiSymbols: symbols.size, counts, health, results }, null, 2) + '\n');
+  } else if (verbose) {
+    // The per-file listing — every finding under its file, unabridged.
+    out(`\ncia analyze — ${rel}\n`);
+    out(`${files.length} scss file(s), ${ciaFiles} using cia, ${symbols.size} API symbols known\n\n`);
     for (const r of results) {
       if (!r.findings.length) continue;
-      process.stdout.write(`${path.relative(process.cwd(), r.file)}\n`);
+      out(`${path.relative(process.cwd(), r.file)}\n`);
       for (const f of r.findings) {
-        const mark = f.level === 'error' ? '✗' : f.level === 'warn' ? '⚠' : 'ℹ';
-        process.stdout.write(`  ${mark} [${f.rule}] ${f.detail}\n`);
+        out(`  ${LEVEL_MARK[f.level]} [${f.rule}] ${f.detail}\n`);
       }
     }
-    process.stdout.write(`\nDesign-system health: ${health}%  (${counts.error} error, ${counts.warn} warn, ${counts.info} info)\n`);
+    out(`\nDesign-system health: ${health}%  (${counts.error} error, ${counts.warn} warn, ${counts.info} info)\n`);
+  } else {
+    // The graded report — a section per category, ✓ when clean, each finding
+    // with its file and a suggested fix on its own line.
+    const all = [];
+    for (const r of results) {
+      for (const f of r.findings) all.push({ ...f, file: path.relative(process.cwd(), r.file) });
+    }
+    const extraCats = [...new Set(all.map((f) => f.category))].filter((c) => !IMPLEMENTED_CATEGORIES.includes(c));
+    const cats = [...IMPLEMENTED_CATEGORIES, ...extraCats];
+
+    out(`\ncia analyze — ${rel}\n`);
+    out(`${files.length} scss file(s) · ${ciaFiles} using cia · ${symbols.size} API symbols\n\n`);
+    out(`Design-system health: ${health}/100\n\n`);
+
+    for (const cat of cats) {
+      const items = all.filter((f) => f.category === cat);
+      if (!items.length) {
+        out(`  ${cat.padEnd(9)} ✓\n`);
+        continue;
+      }
+      const worst = items.some((i) => i.level === 'error') ? 'error' : items.some((i) => i.level === 'warn') ? 'warn' : 'info';
+      out(`  ${cat.padEnd(9)} ${LEVEL_MARK[worst]} ${items.length}\n`);
+      for (const it of items) {
+        out(`    ${LEVEL_MARK[it.level]} ${it.file}  ${it.suggestion ? it.claim ?? splitDetail(it.detail).claim : it.detail}\n`);
+        if (it.suggestion) out(`       → ${it.suggestion}\n`);
+      }
+    }
+
+    const tally = `${counts.error} error · ${counts.warn} warn · ${counts.info} info`;
+    out(`\n${tally}${counts.error || counts.warn || counts.info ? ' · run with --verbose for the per-file list' : ''}\n`);
   }
 
   if (counts.error > 0 || (strict && counts.warn > 0)) process.exit(1);

package/css-is-awesome.instructions.md

@@ -176,13 +176,17 @@ browser's native Print → Save as PDF is the generator; cia just supplies the
   ROOT** — it emits `@page` (invalid when nested in a selector), freezes
   animations so nothing prints invisible, and emits the print variable
   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
+  paired `light-dark()` themes print their light branch for free. It also
+  defines a **print palette** — `--print-ink`, `--print-paper`, `--print-line`,
+  `--print-muted` (default ink-on-white with grays) — and rebinds the theme's
+  own colour tokens (`--ink`, `--surface-*`, `--border-*`, `--code-*`) onto it,
+  so every theme, dark-only (Terminal) included, prints legible ink-on-paper;
+  override a `--print-*` token to restyle paper (a letterhead). Three opt-in
+  flags (all default OFF): `$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.
+  bottom-center margin box. `$legible` is retained as a **deprecated no-op** —
+  the rebind supersedes it and passing it warns.
 - **`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.

package/dist/tokens.d.ts

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

package/llm.txt

@@ -45,10 +45,10 @@ 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. **`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).
+- **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), defines a themeable print palette (`--print-ink` / `--print-paper` / `--print-line` / `--print-muted`, default ink-on-white with grays) and rebinds the theme's own colour tokens (`--ink`, `--surface-*`, `--border-*`, `--code-*`) onto it — so every theme, dark-only (Terminal) included, prints legible ink-on-paper, and overriding a `--print-*` token restyles paper (a letterhead) without touching a component. Three opt-in flags, all default OFF:** `$link-urls` + `$link-origin` (print each link's full destination via `attr(href)`), `$page-numbers` (sheet numbers in the `@page` footer). `$legible` is a DEPRECATED no-op — the token rebind supersedes it and passing it warns.
 - **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).
+- **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, off-contract tokens (near-miss typos of real tokens only, never your own custom tokens), hard-coded hex, BEM; health score, CI exit codes). Low-noise on color: a hex in a `var(--token, #hex)` fallback is token-driven and a literal inside `@media print` is an intentional paper colour — neither is flagged.
 - **Mobile navigation family** — `cia.hamburger` / `cia.drawer` / `cia.sheet` / `cia.dock` ride `[popover]` + CSS Grid, zero JS; recipes `mobile-nav` (hamburger + drawer) and `bottom-nav` (dock + sheets). House rule: **on phones things take the space they're in** — a `cia.dropdown` menu opens 1px under its full-width trigger at the trigger's exact width via CSS anchor positioning (`position-try-fallbacks: flip-block` flips it above at the screen bottom; set `width: auto` at `&[popover]` specificity or the UA's `[popover] { width: fit-content }` and the mixin's inset reset win). Full spec: AGENTS.md quick decision #8 and `/docs/mobile`.
 - **163 contract tokens — 127 required + 36 optional** — surfaces, ink, lines, colors, type, radius, shadow, blur, glow, motion, z-index, spacing, semantic aliases.
 - **Spacing is themeable, and the numbered scale is the knob.** Themes declare `--space-0` … `--space-9` (contract-required). The t-shirt names (`--space-md`, `--space-lg` …) are contract-OPTIONAL and emitted by the library as `var()` aliases onto the numbered steps. `space(4)` compiles to `var(--space-4)`, so **theme the numbered step, never the alias** — setting `--space-md` alone leaves every component untouched. Library defaults emit under `:where(:root)` (specificity 0,0,0) so any theme declaration outranks them regardless of load order.
@@ -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 — 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.
+**Shipped today — 7 recipes: dialog, combobox, print-to-pdf, print-spec, letterhead, 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.10.3",
+  "version": "1.11.1",
   "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

@@ -2405,6 +2405,14 @@
   --card-border: 1px solid var(--hair); /* thin rule instead */
   --input-radius: var(--r-sm); /* 2px */
   --modal-radius: var(--r-md); /* 3px */
+  /* ----------------------------------------------------------------
+     PRINT — Press's own paper identity (opt-in per-theme override).
+     Sass hoists this @media out of the theme selector, so it emits as
+     `@media print { :root, :root[data-theme="press"] { … } }` and
+     overrides print-base's default palette on paper only. Newsprint:
+     a faint warm stock, warm near-black ink, press-red masthead rules.
+     Every other theme inherits print-base's plain ink-on-white.
+     ---------------------------------------------------------------- */
 }
 :root[data-theme=press-dark] {
   color-scheme: dark;

package/public/themes/press/theme.css

@@ -196,4 +196,25 @@
   --card-border: 1px solid var(--hair); /* thin rule instead */
   --input-radius: var(--r-sm); /* 2px */
   --modal-radius: var(--r-md); /* 3px */
+  /* ----------------------------------------------------------------
+     PRINT — Press's own paper identity (opt-in per-theme override).
+     Sass hoists this @media out of the theme selector, so it emits as
+     `@media print { :root, :root[data-theme="press"] { … } }` and
+     overrides print-base's default palette on paper only. Newsprint:
+     a faint warm stock, warm near-black ink, press-red masthead rules.
+     Every other theme inherits print-base's plain ink-on-white.
+     ---------------------------------------------------------------- */
+}
+@media print {
+  :root, :root[data-theme=press] {
+    /* stylelint-disable no-invalid-position-declaration -- these are custom-property
+       overrides scoped to the theme selector m.theme() supplies; the position is valid
+       once the mixin wraps them (emits `@media print { :root, :root[data-theme=press] }`),
+       but stylelint can't see the mixin's parent selector statically. */
+    --print-paper: #FBFAF6; /* faint warm newsprint stock */
+    --print-ink: #0A0A0A; /* warm near-black */
+    --print-line: #D93025; /* press red — the masthead rule */
+    --print-muted: #6B6963; /* warm editorial gray */
+    /* stylelint-enable no-invalid-position-declaration */
+  }
 }

package/scripts/theme-contract.json

@@ -151,6 +151,10 @@
     "--logo-monochrome",
     "--logo-wordmark",
     "--modal-radius",
+    "--print-ink",
+    "--print-line",
+    "--print-muted",
+    "--print-paper",
     "--shadow-button",
     "--shadow-card",
     "--shadow-dropdown",

package/scss/_mixins.scss

@@ -598,6 +598,14 @@ $_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
+//
+// Also emits a themeable PRINT PALETTE — --print-ink / --print-paper /
+// --print-line / --print-muted (default ink-on-white) — and rebinds the theme's
+// colour tokens (--ink, --surface-*, --border-*, --code-*) onto it inside
+// @media print, so every theme (dark-only included) prints legible ink-on-paper.
+// Override a --print-* token (in a theme's @media print, or a <link media=print>
+// sheet) to restyle paper. $legible is a deprecated no-op — the rebind supersedes
+// it and passing it warns.
 @mixin print-base(
   $freeze-animations: true,
   $size: letter,
@@ -607,6 +615,10 @@ $_type-scale: (
   $link-origin: null,
   $page-numbers: false
 ) {
+  @if $legible {
+    @warn "print-base: $legible is deprecated and now a no-op — print rebinds --ink onto --print-ink for every theme, so dark-only themes are legible without it. Remove the flag; override --print-* tokens to restyle paper.";
+  }
+
   :root {
     --is-print: 0;
     --print-hide: none;
@@ -619,22 +631,48 @@ $_type-scale: (
 
       // 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.
+      // on the (already white) sheet, for free.
       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);
-      }
+      // Print palette — themeable. Override these (in a theme's own @media
+      // print, or a <link media="print"> theme file) to restyle paper: navy
+      // ink, a letterhead rule, a grayscale draft. Default: ink on white.
+      --print-ink:   #000;
+      --print-paper: #fff;
+      --print-line:  #999;
+      --print-muted: #666;
+
+      // Rebind the theme's colour tokens onto the print palette, so every
+      // element that reads --ink / --surface / --border prints ink-on-paper
+      // and re-inks when a --print-* token is overridden. Supersedes the old
+      // $legible remap: dark-only themes (Terminal) are legible with no flag.
+      --ink:            var(--print-ink);
+      --ink-soft:       var(--print-muted);
+      --ink-faint:      var(--print-muted);
+      --muted:          var(--print-muted);
+      --text-primary:   var(--print-ink);
+      --text-secondary: var(--print-muted);
+      --text-tertiary:  var(--print-muted);
+
+      --paper:              var(--print-paper);
+      --paper-raised:       var(--print-paper);
+      --paper-sunk:         var(--print-paper);
+      --surface-default:    var(--print-paper);
+      --surface-raised:     var(--print-paper);
+      --surface-sunk:       var(--print-paper);
+      --background-default: var(--print-paper);
+
+      --border-default: var(--print-line);
+      --hair:           var(--print-line);
+
+      --code-bg:    var(--print-paper);
+      --code-ink:   var(--print-ink);
+      --code-muted: var(--print-muted);
     }
 
+    // Paper floor: ink on white regardless of what the app sets on <body>.
+    body { background: var(--print-paper); color: var(--print-ink); }
+
     @page { size: $size; margin: $margin; }
 
     @if $page-numbers {
@@ -651,14 +689,14 @@ $_type-scale: (
       a[href^="http"]::after {
         content: " (" attr(href) ")";
         font-size: 0.85em;
-        color: color-mix(in sRGB, CanvasText 60%, Canvas);
+        color: var(--print-muted);
         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);
+          color: var(--print-muted);
           word-break: break-all;
         }
       }

package/scss/recipes/letterhead.md

@@ -0,0 +1,156 @@
+---
+name: letterhead
+description: A print-only letterhead — a branded header (name, address, a rule) that appears only when the page is printed, styled with cia's print-only mixin and the themeable --print-* palette.
+category: layout
+complexity: simple
+cia-version: ">=1.11.0"
+---
+
+## Use this when
+
+You have a page — an invoice, a quote, a report — that people **print**, and
+you want a branded header on the paper that isn't on the screen: a company
+name, an address line, a rule under it. A letterhead. It's not a theme and it's
+not a colour scheme — it's a small piece of **markup you add**, styled with
+cia's print helpers so it shows on paper only and matches the print palette.
+
+Pair it with [`print-to-pdf`](./print-to-pdf.md) (the page *is* the document) or
+[`print-spec`](./print-spec.md) (a paginated spec document).
+
+## Structure (raw HTML)
+
+```html
+<article class="doc">
+  <!-- Only rendered on paper. On screen your site chrome carries identity. -->
+  <header class="letterhead">
+    <p class="letterhead-name">ACME CORPORATION</p>
+    <p class="letterhead-tag">Threat mitigation since 1949</p>
+    <p class="letterhead-addr">1 Cliffside Drive · Painted Desert Mesa · acme.example</p>
+  </header>
+
+  <!-- …the rest of the document… -->
+</article>
+```
+
+## Styling (cia mixins)
+
+`cia.print-only` hides the block on screen and reveals it in `@media print`. It
+reads the **print palette** — `--print-ink`, `--print-line`, `--print-muted` —
+that `cia.print-base` defines, so the letterhead always matches the paper look
+and follows any per-theme print override (a newsprint red rule, a navy ink).
+
+```scss
+@use 'css-is-awesome/api' as cia;
+
+// Requires cia.print-base once at the stylesheet ROOT (it defines --print-*).
+.letterhead {
+  @include cia.print-only;
+  margin-block-end: 1rem;
+  padding-block-end: 0.5rem;
+  border-block-end: 3px double var(--print-line);   // the paper's rule colour
+  text-align: center;
+}
+
+.letterhead-name {
+  margin: 0;
+  font-family: var(--font-display);
+  font-size: 1.9rem;
+  letter-spacing: 0.14em;
+  color: var(--print-ink);                            // the paper's ink
+}
+.letterhead-tag  { margin: 0.15rem 0 0; font-style: italic; color: var(--print-muted); }
+.letterhead-addr { margin: 0.35rem 0 0; font-family: var(--font-mono); font-size: 0.62rem; color: var(--print-muted); }
+```
+
+Read `--print-*` directly rather than `--ink` / `--border-default`: in print
+those are already rebound onto the palette, but naming the print tokens states
+the intent and survives a per-theme print override unchanged.
+
+## Interactivity
+
+**Zero JS.** A letterhead is static markup — there is nothing to wire. It is
+absent from the screen (`print-only` sets `display: none`) and present on paper
+because `@media print` reveals it. No script, no state, no server.
+
+## A11y checklist
+
+- [ ] The letterhead is branding, not content — never put information the reader needs *only* here; it is absent from the screen, so the on-screen header must carry the real identity and links ([WCAG 2.2 SC 1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html))
+- [ ] Keep the wordmark a `<p>`, not a heading, so a print-only `<h1>` doesn't fork the document outline between screen and paper ([WCAG 2.2 SC 2.4.6 Headings and Labels](https://www.w3.org/WAI/WCAG22/Understanding/headings-and-labels.html))
+- [ ] A logo `<img>` carries a real `alt` (the company name), or `alt=""` when adjacent text already names it ([WCAG 2.2 SC 1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html))
+- [ ] Ink-on-paper contrast meets the minimum — `--print-ink` on `--print-paper` is dark-on-light by default; keep any per-theme override readable ([WCAG 2.2 SC 1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html))
+
+## Framework examples
+
+The letterhead is static markup — no props, no lifecycle, no client code. Every
+stack renders the same header; the visibility and styling live entirely in the
+`@media print` CSS above.
+
+### React
+
+```tsx
+export function Letterhead() {
+  return (
+    <header className="letterhead">
+      <p className="letterhead-name">ACME CORPORATION</p>
+      <p className="letterhead-addr">1 Cliffside Drive · acme.example</p>
+    </header>
+  );
+}
+```
+
+### Vue
+
+```vue
+<template>
+  <header class="letterhead">
+    <p class="letterhead-name">ACME CORPORATION</p>
+    <p class="letterhead-addr">1 Cliffside Drive · acme.example</p>
+  </header>
+</template>
+```
+
+### Svelte
+
+```svelte
+<header class="letterhead">
+  <p class="letterhead-name">ACME CORPORATION</p>
+  <p class="letterhead-addr">1 Cliffside Drive · acme.example</p>
+</header>
+```
+
+### Vanilla
+
+```html
+<header class="letterhead">
+  <p class="letterhead-name">ACME CORPORATION</p>
+  <p class="letterhead-addr">1 Cliffside Drive · acme.example</p>
+</header>
+```
+
+## Variants
+
+- **Newsprint rule.** A theme (e.g. Press) overrides `--print-line` in its own
+  `@media print` block; the letterhead's rule turns that colour automatically —
+  no change to the letterhead itself.
+- **Logo instead of a wordmark.** Swap `.letterhead-name` for an `<img>` (give
+  it `alt`). Prefer an inline SVG or a build-time data URI so nothing is fetched
+  at print time.
+- **Footer letterhead.** The same pattern as a `print-only` footer — page-foot
+  address and a rule — using `margin-block-start: auto` inside a full-page flex
+  column to pin it to the bottom (see [`print-to-pdf`](./print-to-pdf.md)).
+
+## Pitfalls
+
+- **`print-base` must be included once at the stylesheet root**, or the
+  `--print-*` tokens are undefined and the rule/ink fall back to initial values.
+- **Don't duplicate identity on screen.** Because it is `print-only`, let your
+  normal on-screen header carry the brand; the letterhead is for paper alone.
+- **A full-bleed coloured band costs toner.** Prefer ink, a rule, and restraint;
+  let `--print-paper` stay near-white unless a theme deliberately wants a tint.
+
+## Related recipes
+
+- [`print-to-pdf`](./print-to-pdf.md) — the page *is* the document; save it as a
+  faithful PDF. The letterhead lives on top of this.
+- [`print-spec`](./print-spec.md) — paginate a page into a spec document with a
+  cover, index, and printed sheet numbers.

package/scss/recipes/print-spec.md

@@ -67,16 +67,16 @@ Four moves, all pure CSS: `print-base` once at the root, `print-only` on the ind
 @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.
+// polish flags. Each defaults OFF, so nothing changes for existing callers
+// until you opt in:
 //   $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.
+// print-base also forces `color-scheme: light` in print for free (PAIRED
+// light-dark() themes land on their light branch), and rebinds the theme's
+// colour tokens onto a print palette (--print-ink/-paper/-line/-muted, default
+// ink-on-white) so every theme — dark-only included — prints legible.
 @include cia.print-base(
-  $legible: true,
   $link-urls: true,
   $link-origin: 'https://example.com',
   $page-numbers: true
@@ -90,11 +90,14 @@ Four moves, all pure CSS: `print-base` once at the root, `print-only` on the ind
 }
 ```
 
-`$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).
+Print colour is handled by the palette, not a flag: `print-base` rebinds the
+theme's `--ink`, `--surface-*`, `--border-*` and `--code-*` onto `--print-ink`,
+`--print-paper`, `--print-line` and `--print-muted` (default ink-on-white), so
+every theme — dark-only ones included — prints legible with no setting. Override
+a `--print-*` token to restyle paper (a navy letterhead, silver rules). The old
+`$legible` flag is a deprecated no-op. `$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`.
 

package/scss/themes/press.scss

@@ -249,4 +249,24 @@
   --card-border:  1px solid var(--hair);         /* thin rule instead */
   --input-radius: var(--r-sm);                  /* 2px */
   --modal-radius: var(--r-md);                  /* 3px */
+
+  /* ----------------------------------------------------------------
+     PRINT — Press's own paper identity (opt-in per-theme override).
+     Sass hoists this @media out of the theme selector, so it emits as
+     `@media print { :root, :root[data-theme="press"] { … } }` and
+     overrides print-base's default palette on paper only. Newsprint:
+     a faint warm stock, warm near-black ink, press-red masthead rules.
+     Every other theme inherits print-base's plain ink-on-white.
+     ---------------------------------------------------------------- */
+  @media print {
+    /* stylelint-disable no-invalid-position-declaration -- these are custom-property
+       overrides scoped to the theme selector m.theme() supplies; the position is valid
+       once the mixin wraps them (emits `@media print { :root, :root[data-theme=press] }`),
+       but stylelint can't see the mixin's parent selector statically. */
+    --print-paper: #FBFAF6;   /* faint warm newsprint stock */
+    --print-ink:   #0A0A0A;   /* warm near-black */
+    --print-line:  #D93025;   /* press red — the masthead rule */
+    --print-muted: #6B6963;   /* warm editorial gray */
+    /* stylelint-enable no-invalid-position-declaration */
+  }
 }