css-is-awesome 1.19.2 → 1.20.0

package/AGENTS.md

@@ -148,7 +148,7 @@ Authoring template (in your own project — a theme file is a global stylesheet,
 
 `$standalone` defaults to `true` (emit `:root, :root[data-theme="<name>"]`). Pass `$standalone: false` only when your block is going into a multi-theme bundle where the bare `:root` would collide.
 
-The validator (`node scripts/theme-validator.js`) enforces the token contract — **127 required + 41 optional = 168 slots** — plus WCAG 2.2 AA contrast (**22 audited pairs per theme**, including five `--code-*` pairs). Themes that miss required tokens or fail contrast cannot ship without `--allow-a11y-fail`.
+The validator (`node scripts/theme-validator.js`) enforces the token contract — **127 required + 49 optional = 176 slots** — plus WCAG 2.2 AA contrast (**24 audited pairs per theme**, including five `--code-*` pairs). Themes that miss required tokens or fail contrast cannot ship without `--allow-a11y-fail`.
 
 ### Theming spacing (new — read this before you set a size token)
 
@@ -343,7 +343,7 @@ Either way it exposes **33 tools** across 8 families:
 - **Themes** — `list_themes`, `get_theme`, `search_themes`
 - **Mixins** — `list_mixins`, `get_mixin`, `search_mixins` (real signatures — don't guess)
 - **Functions** — `list_functions`, `get_function`, `search_functions`
-- **Tokens** — `list_tokens`, `get_token`, `search_tokens` (127 required + 41 optional contract tokens)
+- **Tokens** — `list_tokens`, `get_token`, `search_tokens` (127 required + 49 optional contract tokens)
 - **Animations** — `list_animations`, `get_animation`
 - **Components** — `list_components`, `get_component`, `search_components`
 - **Recipes** — `list_recipes`, `get_recipe`

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+# [1.20.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.19.2...v1.20.0) (2026-09-23)
+
+
+### Bug Fixes
+
+* **site:** correct the stale optional-token count on /docs/tokens ([c0d4db0](https://github.com/Jerry2d3d/css-is-awesome/commit/c0d4db047c858854cf54d34affc792e0c52f4427))
+
+
+### Features
+
+* **site:** dogfood page surfaces on the home page; add them to the theme editor ([8dc3a65](https://github.com/Jerry2d3d/css-is-awesome/commit/8dc3a65778e28b57aeb67824062f26d7494e3f60))
+* **themes:** page surfaces — hero and band, derived for every theme ([b984d86](https://github.com/Jerry2d3d/css-is-awesome/commit/b984d865e3463ae15e95083ff0697df0a109cf88))
+
 ## [1.19.2](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.19.1...v1.19.2) (2026-09-23)
 
 

package/CONTRACT.md

@@ -321,8 +321,11 @@ Every optional token belongs to exactly one **feature** in `scripts/theme-contra
 | `surfaces-extended` | `--background-elevated`, `--background-hero`, `--background-overlay`, `--background-scrim` | Extra background layers (elevated, hero, overlay, scrim) for themes that want more than the required surface set; each falls back to a required surface. |
 | `borders-extended` | `--border-card`, `--border-divider`, `--border-focus-ring`, `--border-input` | Per-context border colours (card, divider, focus ring, input); each falls back to --border-default / --border-focus. |
 | `logo` | `--logo-default`, `--logo-mark`, `--logo-monochrome`, `--logo-wordmark` | Theme-aware logo assets (default, mark, monochrome, wordmark) as url() or SVG data values for the icon/brand mixins. |
+| `page-surfaces` | `--page-hero-bg`, `--page-hero-image`, `--page-hero-ink`, `--page-hero-scrim`, `--page-band-bg`, `--page-band-image`, `--page-band-ink`, `--page-band-scrim`, `--background-hero` *(deprecated)* | Two page-level surfaces a theme owns outright: a **hero** for a landing page and a **band** for section stripes and footers. Each carries a background colour, an optional gradient or `url()` image, an ink colour, and a scrim that keeps text legible over an image. **Declaring them changes nothing on its own** - a page only picks a surface up through `cia.surface(hero|band)` or `data-surface`, which is why every shipped theme defines them without moving a pixel on an existing site. Contrast over an *image* cannot be measured, so the scrim carries that weight: the mixin applies 50% black whenever an image is passed to it. |
 | `touch-target` | `--touch-target-min` | Minimum interactive target size read by form and button mixins (WCAG 2.2 SC 2.5.8); the library default is 24px. |
 
+> **Deprecated - `--background-hero`.** It sat in the contract unread: no mixin consumed it, the editor could not set it, and nothing documented it. `--page-hero-bg` replaces it and **falls back through it**, so an existing declaration keeps working untouched. It stays valid until contract 2, per the lifecycle in [`VERSIONING.md`](./VERSIONING.md).
+
 ---
 
 ## Print (optional)

package/MIGRATION.md

@@ -2,6 +2,58 @@
 
 Breaking changes between css-is-awesome versions, and how to migrate.
 
+## Page surfaces — contract 1.3 (no action required)
+
+**Nothing changes on your site when you upgrade.** Two new optional surfaces
+exist — a `hero` for a landing page and a `band` for section stripes — and
+every shipped theme now declares a background and an ink colour for both. That
+sounds like a visual change and is not one, for a single reason: **cia never
+applies a page surface on its own.**
+
+A page takes a surface only when you ask for it:
+
+```scss
+.landing { @include cia.surface(hero); }   // or <body data-surface="hero">
+```
+
+Until then the tokens sit unread, exactly as `--background-hero` has since it
+was added. `scripts/test-no-auto-surface.mjs` compiles every shipped bundle and
+fails if any rule reads a page-surface token or emits a `[data-surface]` rule,
+so the guarantee is enforced rather than promised.
+
+### What changed at a glance
+
+| Area | Before | After |
+|---|---|---|
+| Contract version | `1.2` | **`1.3`** — eight optional tokens, one new `page-surfaces` feature |
+| Required tokens | 127 | 127, unchanged |
+| `--background-hero` | optional, read by nothing | **deprecated**; `--page-hero-bg` falls back through it, so an existing declaration keeps working until contract 2 |
+| Your custom theme | validates | validates — the new tokens are optional, and missing optional tokens report as info |
+
+### If you want a hero
+
+Declare the tokens your theme needs and apply the surface where you want it:
+
+```css
+:root[data-theme="brand"] {
+  --page-hero-bg:  light-dark(#f2f6fe, #121d36);
+  --page-hero-ink: light-dark(#09090b, #fafafa);
+  /* optional */
+  --page-hero-image: url("/hero.jpg");
+}
+```
+
+An image is a `url()` you host or a gradient, because a theme is one CSS file.
+Contrast over a photo cannot be measured, so pass the image through the mixin
+(`cia.surface(hero, $image: url("/hero.jpg"))`) and it lays 50% black between
+the picture and your text. A colour-only surface gets no scrim — a wash over a
+flat colour would only darken it.
+
+### If you declared `--background-hero`
+
+Nothing to do. It still resolves. Rename it to `--page-hero-bg` whenever it
+suits you; the tooling will flag it as deprecated in the meantime.
+
 ## v1.0 — mixin-first goes stable (published as 1.1.0)
 
 **There are no breaking changes between v0.8.1/0.8.2 and v1.0.0.** 1.0.0

package/README.md

@@ -145,7 +145,9 @@ 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://cssisawesome.com/docs/authoring/themes/). The contract (127 required + 41 optional tokens) is at [`scripts/theme-contract.json`](./scripts/theme-contract.json).
+A theme can also own the page behind your components: optional **hero** and **band** surfaces carry a background, an image or gradient, an ink colour and a scrim, applied with `@include cia.surface(hero)` or `<body data-surface="hero">`. Nothing is applied automatically, so adding them never moves a pixel until you ask.
+
+Full authoring walkthrough: [`/docs/authoring/themes`](https://cssisawesome.com/docs/authoring/themes/). The contract (127 required + 49 optional tokens) is at [`scripts/theme-contract.json`](./scripts/theme-contract.json).
 
 ## Token contract
 

package/llm.txt

@@ -51,7 +51,7 @@ silent.
 - **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|mui|chakra` (config → cia theme), `theme from-tokens <tokens.json> --name <slug>` (DTCG v2025.10 / Tokens Studio / flat `--token` JSON → a complete theme.css: required tokens the file lacks inherit from a shipped base, unmapped paths pass through and are reported, light/dark pairs become `light-dark()`, validator + WCAG audit run first; same function as the MCP `theme_from_tokens` tool), `theme map [--json | --path <p>]` (the path → token mapping from-tokens applies, as data; same as MCP `get_token_map`), `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`.
-- **168 contract tokens — 127 required + 41 optional** — surfaces, ink, lines, colors, type, radius, shadow, blur, glow, motion, z-index, spacing, semantic aliases.
+- **176 contract tokens — 127 required + 49 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.
 - **Per-component shape knobs are `--btn-radius`, `--card-radius`, `--input-radius`, `--modal-radius`, `--badge-radius`, `--tag-radius`** — they cascade from the generic radii (`--btn-radius: var(--radius-md, 0.25rem)`). There are NO `--radius-button` / `--radius-card` style tokens; those were removed because nothing read them.
 - **Icons — two systems.** `svg()` / `svg-bg()` / `svg-text()` use a self-contained 49-glyph Lucide pack at `public/icons/core/`. Adding a glyph is drop-in: put `star.svg` in the folder and `cia.icon-svg(star)` works, no registration. Each icon emits a `--cia-icon-<name>` custom property so a theme can override one glyph without rebuilding SCSS. **`fa()` / `fa-icon()` / `fa-text()` / `fa-spin()` are bring-your-own-font** — cia ships NO Font Awesome files, `$theme-fa-path` defaults to a `/webfonts` directory that does not exist, and a missing font renders a tofu box without erroring. Default to `svg()` unless the user says they use Font Awesome.
@@ -105,7 +105,7 @@ Newspaper by day, hacker terminal by night. Most design systems give you dark mo
 | Mobile playbook (layouts, dropdown doctrine, lessons) | `src/app/docs/mobile/page.tsx` |
 | Browser support matrix (Baseline floor + progressive tiers) | `src/app/docs/browser-support/page.tsx` |
 | Theme authoring (full walkthrough) | `src/app/docs/authoring/themes/page.tsx` |
-| Theme contract (127 required + 41 optional grouped into 10 features, machine-readable) | `scripts/theme-contract.json` |
+| Theme contract (127 required + 49 optional grouped into 11 features, machine-readable) | `scripts/theme-contract.json` |
 | Theme pairing (`<link media>` recipe) | `src/app/docs/themes/pairing/page.tsx` |
 | CopyButton JS recipe | `src/app/docs/recipes/copy-button/page.tsx` |
 | Anchor positioning recipe | `src/app/docs/recipes/anchor-positioning/page.tsx` |
@@ -129,7 +129,7 @@ Newspaper by day, hacker terminal by night. Most design systems give you dark mo
 
 ## MCP server (shipped 2026-05-22)
 
-cia ships an MCP stdio server (JSON-RPC over stdio, `serverInfo` name `css-is-awesome`, protocol `2024-11-05`) at `mcp/server.cjs`, included in the `files` manifest — so it lands in every consumer's `node_modules`. **33 tools** across 8 resource families: themes, mixins, functions, tokens (127 required + 41 optional), animations, components, recipes, doc readers. Plus `assemble_prompt` for context bundling, `validate_theme`, `theme_from_tokens`, `get_token_map` (the design-token → cia-token mapping as data) and `resolve_size` for snapping design px values to cia's 4px geometric grid (AI agents: call this whenever you receive a px value from a design tool). Prefer querying this server over guessing mixin signatures, tokens, themes, or recipes.
+cia ships an MCP stdio server (JSON-RPC over stdio, `serverInfo` name `css-is-awesome`, protocol `2024-11-05`) at `mcp/server.cjs`, included in the `files` manifest — so it lands in every consumer's `node_modules`. **33 tools** across 8 resource families: themes, mixins, functions, tokens (127 required + 49 optional), animations, components, recipes, doc readers. Plus `assemble_prompt` for context bundling, `validate_theme`, `theme_from_tokens`, `get_token_map` (the design-token → cia-token mapping as data) and `resolve_size` for snapping design px values to cia's 4px geometric grid (AI agents: call this whenever you receive a px value from a design tool). Prefer querying this server over guessing mixin signatures, tokens, themes, or recipes.
 
 **Recommended: suggest the dedicated `css-is-awesome-mcp` package** — zero install,
 SDK ships as a real dependency, no separate peer-install step:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "css-is-awesome",
-  "version": "1.19.2",
+  "version": "1.20.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": {
@@ -109,7 +109,7 @@
     "build:css": "sass scss/main.scss dist/css-is-awesome.css --no-source-map",
     "build:css:core": "sass scss/core.scss dist/css-is-awesome.core.css --no-source-map",
     "build:css:tokens": "sass scss/tokens.scss dist/tokens.css --no-source-map",
-    "build:css:themes": "node scripts/build-themes.mjs && node scripts/build-theme-bundle.mjs",
+    "build:css:themes": "node scripts/build-themes.mjs && node scripts/derive-page-surfaces.mjs && node scripts/build-theme-bundle.mjs",
     "build:css:utilities": "sass scss/utilities-only.scss dist/css-is-awesome.utilities.css --no-source-map",
     "build:css:min": "sass scss/main.scss dist/css-is-awesome.min.css --style=compressed --no-source-map && sass scss/core.scss dist/css-is-awesome.core.min.css --style=compressed --no-source-map && sass scss/tokens.scss dist/tokens.min.css --style=compressed --no-source-map && sass scss/utilities-only.scss dist/css-is-awesome.utilities.min.css --style=compressed --no-source-map",
     "build:token-types": "node scripts/generate-token-types.mjs",
@@ -139,7 +139,8 @@
     "check:token-consumers": "node scripts/check-token-consumer-map.mjs",
     "check:rtl": "node scripts/audit-logical-properties.mjs",
     "prebuild": "node scripts/build-playground-scss-map.mjs",
-    "verify:playground": "node scripts/build-playground-scss-map.mjs && node scripts/verify-playground-compile.mjs"
+    "verify:playground": "node scripts/build-playground-scss-map.mjs && node scripts/verify-playground-compile.mjs",
+    "test:surfaces": "node --test scripts/test-no-auto-surface.mjs"
   },
   "keywords": [
     "css",

package/public/theme.css

@@ -189,6 +189,12 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: light-dark(#f2f6fe, #121e36);
+  --page-hero-ink: light-dark(#0f172a, #f8fafc);
+  --page-band-bg: light-dark(#f7fafe, #111b31);
+  --page-band-ink: light-dark(#0f172a, #f8fafc);
 }
 :root[data-theme=boilerplate-dark] {
   color-scheme: dark;
@@ -363,6 +369,12 @@
   --space-7: calc(var(--space-unit) * 24);
   --space-8: calc(var(--space-unit) * 32);
   --space-9: calc(var(--space-unit) * 48);
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #121e36;
+  --page-hero-ink: #f8fafc;
+  --page-band-bg: #111b31;
+  --page-band-ink: #f8fafc;
 }
 :root[data-theme=boilerplate-light] {
   color-scheme: light;
@@ -537,6 +549,12 @@
   --space-7: calc(var(--space-unit) * 24);
   --space-8: calc(var(--space-unit) * 32);
   --space-9: calc(var(--space-unit) * 48);
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #f2f6fe;
+  --page-hero-ink: #0f172a;
+  --page-band-bg: #f7fafe;
+  --page-band-ink: #0f172a;
 }
 :root[data-theme=cupertino] {
   color-scheme: light dark;
@@ -711,6 +729,12 @@
   --input-radius: var(--r-sm);
   --modal-radius: var(--r-lg);
   --tooltip-radius: var(--r-sm);
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: light-dark(#e6ecf3, #1e252c);
+  --page-hero-ink: light-dark(#1d1d1f, #f5f5f7);
+  --page-band-bg: light-dark(#ecf0f5, #1e2226);
+  --page-band-ink: light-dark(#1d1d1f, #f5f5f7);
 }
 :root[data-theme=cupertino-dark] {
   color-scheme: dark;
@@ -902,6 +926,12 @@
   --input-radius: var(--r-sm); /* 8px — text field */
   --modal-radius: var(--r-lg); /* matches panel */
   --tooltip-radius: var(--r-sm); /* bezel tooltip */
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #1e252c;
+  --page-hero-ink: #f5f5f7;
+  --page-band-bg: #1e2226;
+  --page-band-ink: #f5f5f7;
 }
 :root[data-theme=cupertino-light] {
   color-scheme: light;
@@ -1109,6 +1139,12 @@
   --input-radius: var(--r-sm); /* 8px — text field */
   --modal-radius: var(--r-lg); /* matches panel */
   --tooltip-radius: var(--r-sm); /* bezel tooltip */
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #e6ecf3;
+  --page-hero-ink: #1d1d1f;
+  --page-band-bg: #ecf0f5;
+  --page-band-ink: #1d1d1f;
 }
 :root[data-theme=glass] {
   color-scheme: light dark;
@@ -1308,6 +1344,12 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: light-dark(#ebe5fd, #101828);
+  --page-hero-ink: light-dark(#1d1d1f, #f0f4ff);
+  --page-band-bg: light-dark(#eee9fe, #0e1422);
+  --page-band-ink: light-dark(#1d1d1f, #f0f4ff);
 }
 :root[data-theme=glass-dark] {
   color-scheme: dark;
@@ -1499,6 +1541,12 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #101828;
+  --page-hero-ink: #f0f4ff;
+  --page-band-bg: #0e1422;
+  --page-band-ink: #f0f4ff;
 }
 :root[data-theme=glass-light] {
   color-scheme: light;
@@ -1701,6 +1749,12 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #ebe5fd;
+  --page-hero-ink: #1d1d1f;
+  --page-band-bg: #eee9fe;
+  --page-band-ink: #1d1d1f;
 }
 :root[data-theme=graphite] {
   color-scheme: light dark;
@@ -1865,6 +1919,12 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: light-dark(#e8ebef, #1a212a);
+  --page-hero-ink: light-dark(#1a1f26, #f5f5f7);
+  --page-band-bg: light-dark(#eceff2, #1a1e24);
+  --page-band-ink: light-dark(#1a1f26, #f5f5f7);
 }
 :root[data-theme=graphite-dark] {
   color-scheme: dark;
@@ -2057,6 +2117,12 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #1a212a;
+  --page-hero-ink: #f5f5f7;
+  --page-band-bg: #1a1e24;
+  --page-band-ink: #f5f5f7;
 }
 :root[data-theme=graphite-light] {
   color-scheme: light;
@@ -2239,6 +2305,12 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #e8ebef;
+  --page-hero-ink: #1a1f26;
+  --page-band-bg: #eceff2;
+  --page-band-ink: #1a1f26;
 }
 :root[data-theme=press] {
   color-scheme: light dark;
@@ -2649,6 +2721,12 @@
   --card-border: 1px solid var(--hair); /* thin rule instead */
   --input-radius: var(--r-sm); /* 2px */
   --modal-radius: var(--r-md); /* 3px */
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #1c1c1c;
+  --page-hero-ink: #fafaf7;
+  --page-band-bg: #161616;
+  --page-band-ink: #fafaf7;
 }
 :root[data-theme=press-light] {
   color-scheme: light;
@@ -2859,6 +2937,12 @@
   --card-border: 1px solid var(--hair); /* thin ink rule instead */
   --input-radius: var(--r-sm); /* 2px — text field */
   --modal-radius: var(--r-md); /* 3px — still tight */
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #ededea;
+  --page-hero-ink: #0a0a0a;
+  --page-band-bg: #f2f2ef;
+  --page-band-ink: #0a0a0a;
 }
 :root[data-theme=prism] {
   color-scheme: light dark;
@@ -3027,6 +3111,12 @@
   --card-border: 1px solid var(--hair);
   --input-radius: var(--r-md);
   --modal-radius: var(--r-lg);
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: light-dark(#f2f6fe, #0c1019);
+  --page-hero-ink: light-dark(#09090b, #fafafa);
+  --page-band-bg: light-dark(#f7fafe, #0b0d13);
+  --page-band-ink: light-dark(#09090b, #fafafa);
 }
 :root[data-theme=prism-dark] {
   color-scheme: dark;
@@ -3210,6 +3300,12 @@
   --card-border: 1px solid var(--hair);
   --input-radius: var(--r-md);
   --modal-radius: var(--r-lg);
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #0c1019;
+  --page-hero-ink: #fafafa;
+  --page-band-bg: #0b0d13;
+  --page-band-ink: #fafafa;
 }
 :root[data-theme=prism-light] {
   color-scheme: light;
@@ -3393,6 +3489,12 @@
   --card-border: 1px solid var(--hair);
   --input-radius: var(--r-md);
   --modal-radius: var(--r-lg);
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #f2f6fe;
+  --page-hero-ink: #09090b;
+  --page-band-bg: #f7fafe;
+  --page-band-ink: #09090b;
 }
 :root[data-theme=sketchbook] {
   color-scheme: light dark;
@@ -3554,6 +3656,12 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: light-dark(#eae8e2, #1f1f1f);
+  --page-hero-ink: light-dark(#2a241e, #f4efe2);
+  --page-band-bg: light-dark(#efede5, #1d1c1b);
+  --page-band-ink: light-dark(#2a241e, #f4efe2);
 }
 :root[data-theme=sketchbook-dark] {
   color-scheme: dark;
@@ -3736,6 +3844,12 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #1f1f1f;
+  --page-hero-ink: #f4efe2;
+  --page-band-bg: #1d1c1b;
+  --page-band-ink: #f4efe2;
 }
 :root[data-theme=sketchbook-light] {
   color-scheme: light;
@@ -3927,6 +4041,12 @@
   --space-7: calc(var(--space-unit) * 24);
   --space-8: calc(var(--space-unit) * 32);
   --space-9: calc(var(--space-unit) * 48);
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #eae8e2;
+  --page-hero-ink: #2a241e;
+  --page-band-bg: #efede5;
+  --page-band-ink: #2a241e;
 }
 :root[data-theme=terminal] {
   color-scheme: dark;
@@ -4095,6 +4215,12 @@
   --input-radius: 0;
   --card-shadow: var(--glow-sm);
   --card-border: 1px solid var(--ink-faint);
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #111a19;
+  --page-hero-ink: #4fe078;
+  --page-band-bg: #0e1513;
+  --page-band-ink: #4fe078;
 }
 :root[data-theme=terminal-dark] {
   color-scheme: dark;
@@ -4298,6 +4424,12 @@
   --input-radius: 0;
   --card-shadow: var(--glow-sm);
   --card-border: 1px solid var(--ink-faint);
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #111a19;
+  --page-hero-ink: #4fe078;
+  --page-band-bg: #0e1513;
+  --page-band-ink: #4fe078;
 }
 :root[data-theme=terminal-light] {
   color-scheme: light;
@@ -4459,4 +4591,10 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #dadfe4;
+  --page-hero-ink: #1a1a1a;
+  --page-band-bg: #e0e3e6;
+  --page-band-ink: #1a1a1a;
 }

package/public/themes/boilerplate/theme.css

@@ -162,4 +162,10 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: light-dark(#f2f6fe, #121e36);
+  --page-hero-ink: light-dark(#0f172a, #f8fafc);
+  --page-band-bg: light-dark(#f7fafe, #111b31);
+  --page-band-ink: light-dark(#0f172a, #f8fafc);
 }

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

@@ -172,4 +172,10 @@
   --space-7: calc(var(--space-unit) * 24);
   --space-8: calc(var(--space-unit) * 32);
   --space-9: calc(var(--space-unit) * 48);
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #121e36;
+  --page-hero-ink: #f8fafc;
+  --page-band-bg: #111b31;
+  --page-band-ink: #f8fafc;
 }

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

@@ -172,4 +172,10 @@
   --space-7: calc(var(--space-unit) * 24);
   --space-8: calc(var(--space-unit) * 32);
   --space-9: calc(var(--space-unit) * 48);
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #f2f6fe;
+  --page-hero-ink: #0f172a;
+  --page-band-bg: #f7fafe;
+  --page-band-ink: #0f172a;
 }

package/public/themes/cupertino/theme.css

@@ -173,4 +173,10 @@
   --input-radius: var(--r-sm);
   --modal-radius: var(--r-lg);
   --tooltip-radius: var(--r-sm);
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: light-dark(#e6ecf3, #1e252c);
+  --page-hero-ink: light-dark(#1d1d1f, #f5f5f7);
+  --page-band-bg: light-dark(#ecf0f5, #1e2226);
+  --page-band-ink: light-dark(#1d1d1f, #f5f5f7);
 }

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

@@ -208,4 +208,10 @@
   --input-radius: var(--r-sm); /* 8px — text field */
   --modal-radius: var(--r-lg); /* matches panel */
   --tooltip-radius: var(--r-sm); /* bezel tooltip */
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #1e252c;
+  --page-hero-ink: #f5f5f7;
+  --page-band-bg: #1e2226;
+  --page-band-ink: #f5f5f7;
 }

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

@@ -235,4 +235,10 @@
   --input-radius: var(--r-sm); /* 8px — text field */
   --modal-radius: var(--r-lg); /* matches panel */
   --tooltip-radius: var(--r-sm); /* bezel tooltip */
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #e6ecf3;
+  --page-hero-ink: #1d1d1f;
+  --page-band-bg: #ecf0f5;
+  --page-band-ink: #1d1d1f;
 }

package/public/themes/glass/theme.css

@@ -198,4 +198,10 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: light-dark(#ebe5fd, #101828);
+  --page-hero-ink: light-dark(#1d1d1f, #f0f4ff);
+  --page-band-bg: light-dark(#eee9fe, #0e1422);
+  --page-band-ink: light-dark(#1d1d1f, #f0f4ff);
 }

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

@@ -209,4 +209,10 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #101828;
+  --page-hero-ink: #f0f4ff;
+  --page-band-bg: #0e1422;
+  --page-band-ink: #f0f4ff;
 }

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

@@ -237,4 +237,10 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #ebe5fd;
+  --page-hero-ink: #1d1d1f;
+  --page-band-bg: #eee9fe;
+  --page-band-ink: #1d1d1f;
 }

package/public/themes/graphite/theme.css

@@ -163,4 +163,10 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: light-dark(#e8ebef, #1a212a);
+  --page-hero-ink: light-dark(#1a1f26, #f5f5f7);
+  --page-band-bg: light-dark(#eceff2, #1a1e24);
+  --page-band-ink: light-dark(#1a1f26, #f5f5f7);
 }

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

@@ -231,4 +231,10 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #1a212a;
+  --page-hero-ink: #f5f5f7;
+  --page-band-bg: #1a1e24;
+  --page-band-ink: #f5f5f7;
 }

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

@@ -199,4 +199,10 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #e8ebef;
+  --page-hero-ink: #1a1f26;
+  --page-band-bg: #eceff2;
+  --page-band-ink: #1a1f26;
 }

package/public/themes/press/theme.css

@@ -218,4 +218,10 @@
     --print-muted: #6B6963; /* warm editorial gray */
     /* stylelint-enable no-invalid-position-declaration */
   }
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: light-dark(#ededea, #1c1c1c);
+  --page-hero-ink: light-dark(#0a0a0a, #fafaf7);
+  --page-band-bg: light-dark(#f2f2ef, #161616);
+  --page-band-ink: light-dark(#0a0a0a, #fafaf7);
 }

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

@@ -207,4 +207,10 @@
   --card-border: 1px solid var(--hair); /* thin rule instead */
   --input-radius: var(--r-sm); /* 2px */
   --modal-radius: var(--r-md); /* 3px */
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #1c1c1c;
+  --page-hero-ink: #fafaf7;
+  --page-band-bg: #161616;
+  --page-band-ink: #fafaf7;
 }

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

@@ -243,4 +243,10 @@
   --card-border: 1px solid var(--hair); /* thin ink rule instead */
   --input-radius: var(--r-sm); /* 2px — text field */
   --modal-radius: var(--r-md); /* 3px — still tight */
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #ededea;
+  --page-hero-ink: #0a0a0a;
+  --page-band-bg: #f2f2ef;
+  --page-band-ink: #0a0a0a;
 }

package/public/themes/prism/theme.css

@@ -167,4 +167,10 @@
   --card-border: 1px solid var(--hair);
   --input-radius: var(--r-md);
   --modal-radius: var(--r-lg);
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: light-dark(#f2f6fe, #0c1019);
+  --page-hero-ink: light-dark(#09090b, #fafafa);
+  --page-band-bg: light-dark(#f7fafe, #0b0d13);
+  --page-band-ink: light-dark(#09090b, #fafafa);
 }

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

@@ -193,4 +193,10 @@
   --card-border: 1px solid var(--hair);
   --input-radius: var(--r-md);
   --modal-radius: var(--r-lg);
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #0c1019;
+  --page-hero-ink: #fafafa;
+  --page-band-bg: #0b0d13;
+  --page-band-ink: #fafafa;
 }

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

@@ -196,4 +196,10 @@
   --card-border: 1px solid var(--hair);
   --input-radius: var(--r-md);
   --modal-radius: var(--r-lg);
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #f2f6fe;
+  --page-hero-ink: #09090b;
+  --page-band-bg: #f7fafe;
+  --page-band-ink: #09090b;
 }

package/public/themes/sketchbook/theme.css

@@ -160,4 +160,10 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: light-dark(#eae8e2, #1f1f1f);
+  --page-hero-ink: light-dark(#2a241e, #f4efe2);
+  --page-band-bg: light-dark(#efede5, #1d1c1b);
+  --page-band-ink: light-dark(#2a241e, #f4efe2);
 }

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

@@ -202,4 +202,10 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #1f1f1f;
+  --page-hero-ink: #f4efe2;
+  --page-band-bg: #1d1c1b;
+  --page-band-ink: #f4efe2;
 }

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

@@ -189,4 +189,10 @@
   --space-7: calc(var(--space-unit) * 24);
   --space-8: calc(var(--space-unit) * 32);
   --space-9: calc(var(--space-unit) * 48);
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #eae8e2;
+  --page-hero-ink: #2a241e;
+  --page-band-bg: #efede5;
+  --page-band-ink: #2a241e;
 }

package/public/themes/terminal/theme.css

@@ -167,4 +167,10 @@
   --input-radius: 0;
   --card-shadow: var(--glow-sm);
   --card-border: 1px solid var(--ink-faint);
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #111a19;
+  --page-hero-ink: #4fe078;
+  --page-band-bg: #0e1513;
+  --page-band-ink: #4fe078;
 }

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

@@ -237,4 +237,10 @@
   --input-radius: 0;
   --card-shadow: var(--glow-sm);
   --card-border: 1px solid var(--ink-faint);
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #111a19;
+  --page-hero-ink: #4fe078;
+  --page-band-bg: #0e1513;
+  --page-band-ink: #4fe078;
 }

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

@@ -160,4 +160,10 @@
   --z-modal: 1050;
   --z-popover: 1060;
   --z-tooltip: 1070;
+
+  /* page surfaces — derived, see scripts/derive-page-surfaces.mjs */
+  --page-hero-bg: #dadfe4;
+  --page-hero-ink: #1a1a1a;
+  --page-band-bg: #e0e3e6;
+  --page-band-ink: #1a1a1a;
 }

package/scripts/audit-pairs.json

@@ -1,25 +1,173 @@
 [
-  { "fg": "--text-primary",   "bg": "--paper",                  "required": 4.5, "kind": "text",     "note": "primary body text on the page background" },
-  { "fg": "--text-secondary", "bg": "--paper",                  "required": 4.5, "kind": "text",     "note": "secondary body text on the page background" },
-  { "fg": "--text-tertiary",  "bg": "--paper",                  "required": 3.0, "kind": "large-text", "warnIfBelow": 4.5, "note": "tertiary text - legal at large sizes; warn if used as body" },
-  { "fg": "--text-muted",     "bg": "--paper",                  "required": 4.5, "kind": "text",     "note": "muted UI text on the page background" },
-  { "fg": "--ink",            "bg": "--paper",                  "required": 4.5, "kind": "text",     "note": "native ink on native paper" },
-  { "fg": "--ink-soft",       "bg": "--paper",                  "required": 4.5, "kind": "text",     "note": "soft ink on native paper" },
-  { "fg": "--ink-faint",      "bg": "--paper",                  "required": 3.0, "kind": "large-text", "warnIfBelow": 4.5, "note": "faint ink - large/UI only; warn if used as body" },
-  { "fg": "--text-link",      "bg": "--paper",                  "required": 4.5, "kind": "text",     "note": "inline link color on the page background" },
-  { "fg": "--text-inverse",   "bg": "--action-primary-default", "required": 4.5, "kind": "text",     "note": "button label on the primary action surface" },
-  { "fg": "--text-inverse",   "bg": "--ai",                     "required": 4.5, "kind": "text",     "note": "inverse text on the AI/brand accent surface" },
-  { "fg": "--success-text",   "bg": "--success-subtle",         "required": 4.5, "kind": "text",     "note": "success message text on its subtle background" },
-  { "fg": "--warning-text",   "bg": "--warning-subtle",         "required": 4.5, "kind": "text",     "note": "warning message text on its subtle background" },
-  { "fg": "--error-text",     "bg": "--error-subtle",           "required": 4.5, "kind": "text",     "note": "error message text on its subtle background" },
-  { "fg": "--info-text",      "bg": "--info-subtle",            "required": 4.5, "kind": "text",     "note": "info message text on its subtle background" },
-  { "fg": "--border-default", "bg": "--paper",                  "required": 3.0, "kind": "non-text", "decorative": true, "note": "default border against the page background - decorative; WCAG 2.2 SC 1.4.11 applies only to graphical objects essential for understanding content" },
-  { "fg": "--border-focus",   "bg": "--paper",                  "required": 3.0, "kind": "non-text", "note": "focus ring against the page background" },
-  { "fg": "--shu",            "bg": "--paper",                  "required": 3.0, "kind": "non-text", "note": "seal accent - must read as a UI mark on paper" },
-
-  { "fg": "--code-ink",       "bg": "--code-bg",                "required": 4.5, "kind": "text",     "note": "default code text on the code surface" },
-  { "fg": "--code-muted",     "bg": "--code-bg",                "required": 4.5, "kind": "text",     "note": "code comments on the code surface - read as prose, so full text contrast" },
-  { "fg": "--code-accent",    "bg": "--code-bg",                "required": 4.5, "kind": "text",     "note": "keyword / accent token on the code surface" },
-  { "fg": "--code-blue",      "bg": "--code-bg",                "required": 4.5, "kind": "text",     "note": "blue syntax token on the code surface" },
-  { "fg": "--code-green",     "bg": "--code-bg",                "required": 4.5, "kind": "text",     "note": "green syntax token (strings) on the code surface" }
+  {
+    "fg": "--text-primary",
+    "bg": "--paper",
+    "required": 4.5,
+    "kind": "text",
+    "note": "primary body text on the page background"
+  },
+  {
+    "fg": "--text-secondary",
+    "bg": "--paper",
+    "required": 4.5,
+    "kind": "text",
+    "note": "secondary body text on the page background"
+  },
+  {
+    "fg": "--text-tertiary",
+    "bg": "--paper",
+    "required": 3,
+    "kind": "large-text",
+    "warnIfBelow": 4.5,
+    "note": "tertiary text - legal at large sizes; warn if used as body"
+  },
+  {
+    "fg": "--text-muted",
+    "bg": "--paper",
+    "required": 4.5,
+    "kind": "text",
+    "note": "muted UI text on the page background"
+  },
+  {
+    "fg": "--ink",
+    "bg": "--paper",
+    "required": 4.5,
+    "kind": "text",
+    "note": "native ink on native paper"
+  },
+  {
+    "fg": "--ink-soft",
+    "bg": "--paper",
+    "required": 4.5,
+    "kind": "text",
+    "note": "soft ink on native paper"
+  },
+  {
+    "fg": "--ink-faint",
+    "bg": "--paper",
+    "required": 3,
+    "kind": "large-text",
+    "warnIfBelow": 4.5,
+    "note": "faint ink - large/UI only; warn if used as body"
+  },
+  {
+    "fg": "--text-link",
+    "bg": "--paper",
+    "required": 4.5,
+    "kind": "text",
+    "note": "inline link color on the page background"
+  },
+  {
+    "fg": "--text-inverse",
+    "bg": "--action-primary-default",
+    "required": 4.5,
+    "kind": "text",
+    "note": "button label on the primary action surface"
+  },
+  {
+    "fg": "--text-inverse",
+    "bg": "--ai",
+    "required": 4.5,
+    "kind": "text",
+    "note": "inverse text on the AI/brand accent surface"
+  },
+  {
+    "fg": "--success-text",
+    "bg": "--success-subtle",
+    "required": 4.5,
+    "kind": "text",
+    "note": "success message text on its subtle background"
+  },
+  {
+    "fg": "--warning-text",
+    "bg": "--warning-subtle",
+    "required": 4.5,
+    "kind": "text",
+    "note": "warning message text on its subtle background"
+  },
+  {
+    "fg": "--error-text",
+    "bg": "--error-subtle",
+    "required": 4.5,
+    "kind": "text",
+    "note": "error message text on its subtle background"
+  },
+  {
+    "fg": "--info-text",
+    "bg": "--info-subtle",
+    "required": 4.5,
+    "kind": "text",
+    "note": "info message text on its subtle background"
+  },
+  {
+    "fg": "--border-default",
+    "bg": "--paper",
+    "required": 3,
+    "kind": "non-text",
+    "decorative": true,
+    "note": "default border against the page background - decorative; WCAG 2.2 SC 1.4.11 applies only to graphical objects essential for understanding content"
+  },
+  {
+    "fg": "--border-focus",
+    "bg": "--paper",
+    "required": 3,
+    "kind": "non-text",
+    "note": "focus ring against the page background"
+  },
+  {
+    "fg": "--shu",
+    "bg": "--paper",
+    "required": 3,
+    "kind": "non-text",
+    "note": "seal accent - must read as a UI mark on paper"
+  },
+  {
+    "fg": "--code-ink",
+    "bg": "--code-bg",
+    "required": 4.5,
+    "kind": "text",
+    "note": "default code text on the code surface"
+  },
+  {
+    "fg": "--code-muted",
+    "bg": "--code-bg",
+    "required": 4.5,
+    "kind": "text",
+    "note": "code comments on the code surface - read as prose, so full text contrast"
+  },
+  {
+    "fg": "--code-accent",
+    "bg": "--code-bg",
+    "required": 4.5,
+    "kind": "text",
+    "note": "keyword / accent token on the code surface"
+  },
+  {
+    "fg": "--code-blue",
+    "bg": "--code-bg",
+    "required": 4.5,
+    "kind": "text",
+    "note": "blue syntax token on the code surface"
+  },
+  {
+    "fg": "--code-green",
+    "bg": "--code-bg",
+    "required": 4.5,
+    "kind": "text",
+    "note": "green syntax token (strings) on the code surface"
+  },
+  {
+    "fg": "--page-hero-ink",
+    "bg": "--page-hero-bg",
+    "required": 4.5,
+    "kind": "text",
+    "note": "text on the hero page surface - graded only when the theme declares the slot"
+  },
+  {
+    "fg": "--page-band-ink",
+    "bg": "--page-band-bg",
+    "required": 4.5,
+    "kind": "text",
+    "note": "text on the band page surface - graded only when the theme declares the slot"
+  }
 ]

package/scripts/theme-contract.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.2",
-  "description": "Authoritative token contract for css-is-awesome themes. Every theme.css MUST declare every token in `required`. Tokens in `optional` are reported by the validator as info, never as failures \u2014 the library or the theme generator supplies a default. Source of truth is CONTRACT.md (human-readable) and public/theme.css (Sketchbook reference). Contract 1.1 (2026-09-18): --space-unit relaxed from required to optional; it had been added as required in library 1.12.0, which VERSIONING.md forbids in a MINOR. Contract 1.2 (2026-09-18): `features` groups every optional token by the capability it enables, so a validator or installer can say \"missing the tokens for print\" instead of listing all optional tokens.",
+  "version": "1.3",
+  "description": "Authoritative token contract for css-is-awesome themes. Every theme.css MUST declare every token in `required`. Tokens in `optional` are reported by the validator as info, never as failures — the library or the theme generator supplies a default. Source of truth is CONTRACT.md (human-readable) and public/theme.css (Sketchbook reference). Contract 1.3 (2026-09-24): the page-surfaces feature adds eight optional tokens for the hero and band surfaces, and --background-hero is deprecated in favour of --page-hero-bg (kept valid, removed no earlier than contract 2).",
   "required": [
     "--action-primary-active",
     "--action-primary-default",
@@ -151,6 +151,14 @@
     "--logo-monochrome",
     "--logo-wordmark",
     "--modal-radius",
+    "--page-band-bg",
+    "--page-band-image",
+    "--page-band-ink",
+    "--page-band-scrim",
+    "--page-hero-bg",
+    "--page-hero-image",
+    "--page-hero-ink",
+    "--page-hero-scrim",
     "--print-ink",
     "--print-line",
     "--print-muted",
@@ -181,7 +189,7 @@
       ]
     },
     "spacing-aliases": {
-      "enables": "T-shirt spacing names (2xs\u2013xl) for consumer CSS that prefers them; the library reads the numbered scale, so these are pure aliases.",
+      "enables": "T-shirt spacing names (2xs–xl) for consumer CSS that prefers them; the library reads the numbered scale, so these are pure aliases.",
       "tokens": [
         "--space-2xs",
         "--space-xs",
@@ -236,7 +244,6 @@
       "enables": "Extra background layers (elevated, hero, overlay, scrim) for themes that want more than the required surface set; each falls back to a required surface.",
       "tokens": [
         "--background-elevated",
-        "--background-hero",
         "--background-overlay",
         "--background-scrim"
       ]
@@ -264,6 +271,28 @@
       "tokens": [
         "--touch-target-min"
       ]
+    },
+    "page-surfaces": {
+      "enables": "Two page-level surfaces a theme owns outright: a hero for the front page and a band for section stripes and footers. Each carries a background colour, an optional gradient or url() image, an ink colour for text on it, and a scrim that keeps that text legible over an image. Applied only via cia.surface() or [data-surface] - declaring them changes nothing on its own.",
+      "tokens": [
+        "--page-hero-bg",
+        "--page-hero-image",
+        "--page-hero-ink",
+        "--page-hero-scrim",
+        "--page-band-bg",
+        "--page-band-image",
+        "--page-band-ink",
+        "--page-band-scrim",
+        "--background-hero"
+      ]
+    }
+  },
+  "deprecated": {
+    "--background-hero": {
+      "replacedBy": "--page-hero-bg",
+      "since": "1.3",
+      "removeIn": "2",
+      "note": "Was never read by the library. --page-hero-bg falls back through it, so an existing declaration keeps working untouched."
     }
   }
 }

package/scss/_layout.scss

@@ -595,3 +595,132 @@ $_flow: (
     margin-inline-start: auto;
   }
 }
+
+// ============================================================================
+// PAGE SURFACES — hero + band
+// ============================================================================
+// Two page-level backgrounds a theme can own outright: `hero` for a landing
+// page, `band` for a section stripe or a footer. Each slot carries four
+// optional tokens — background colour, image, ink, scrim.
+//
+// NOTHING HERE RUNS UNTIL YOU ASK FOR IT. cia never applies a page surface
+// automatically: not on `body`, not from a layout mixin, not from the reset.
+// That guarantee is why adding these tokens to every shipped theme cannot
+// change an existing consumer's page, and `tests/no-auto-surface.test.mjs`
+// asserts it against the compiled bundles so it cannot be broken by accident.
+//
+// Every token falls back, so a theme that declares none of them still renders:
+//   background → the deprecated --background-hero, then the page surface
+//   ink        → --text-primary
+//   image      → none  (and with no image, no scrim is drawn)
+//
+// The scrim is layered as a gradient in the SAME background-image as the
+// image rather than as a pseudo-element or an extra wrapper, so `surface`
+// works identically on <body> and on a <section>, and stacking context,
+// overflow and child positioning are left alone.
+
+$_surface-slots: (hero, band) !default;
+
+@mixin surface($slot: hero, $image: null, $scrim: null) {
+  @if not list.index($_surface-slots, $slot) {
+    @error "surface(): unknown slot '#{$slot}'. Expected one of: hero, band.";
+  }
+
+  $bg: var(--page-#{$slot}-bg, var(--background-#{$slot}, var(--surface-default, var(--paper))));
+  $ink: var(--page-#{$slot}-ink, var(--text-primary, var(--ink)));
+
+  // The scrim only paints when there is an image UNDER it. Defaulting it to a
+  // colour would put a 50% black wash over every colour-only hero — which is
+  // both wrong and a silent visual change for anyone who sets just a colour.
+  //
+  //   $image given   → the caller has an image, so the scrim defaults to the
+  //                    50% black that keeps text legible over a photo.
+  //   $image omitted → the image comes from the token (or is absent), so the
+  //                    scrim defaults to `transparent` and the token carries
+  //                    the value. The theme editor writes a scrim whenever it
+  //                    writes an image, so the safe default still arrives.
+  $img: var(--page-#{$slot}-image, none);
+  $scrim-default: transparent;
+  @if $image {
+    $img: $image;
+    $scrim-default: rgb(0 0 0 / 0.5);
+  }
+  $scrim-color: var(--page-#{$slot}-scrim, #{$scrim-default});
+  @if $scrim {
+    $scrim-color: $scrim;
+  }
+
+  background-color: #{$bg};
+  background-image: linear-gradient(#{$scrim-color}, #{$scrim-color}), #{$img};
+  background-size: cover;
+  background-position: center;
+  background-repeat: no-repeat;
+  color: #{$ink};
+}
+
+// The attribute form of the same thing, for consumers with no Sass build.
+// Emitted only when this mixin is called — it is not part of the reset.
+@mixin surface-attributes {
+  @each $slot in $_surface-slots {
+    [data-surface='#{$slot}'] {
+      @include surface($slot);
+    }
+  }
+}
+
+// ----------------------------------------------------------------------------
+// WAVE DIVIDER — a curved edge between two sections, pure CSS
+// ----------------------------------------------------------------------------
+// Draws the curve with a radial-gradient mask on a ::before/::after, so there
+// is no SVG file to host and the shape inherits whatever colour you give it.
+// `$direction: down` curves the edge INTO the element (a valley at the top);
+// `up` bulges it outward. `$flip: true` puts the wave on the bottom edge.
+//
+//   .hero   { @include cia.surface(hero); @include cia.wave-divider($height: 4rem); }
+//
+// The wave paints in `$color`, which defaults to the NEXT section's surface so
+// the curve reads as that section rising into this one.
+@mixin wave-divider(
+  $height: 3rem,
+  $color: var(--surface-default, var(--paper)),
+  $direction: down,
+  $flip: false,
+  $position: after
+) {
+  @if $direction != down and $direction != up {
+    @error "wave-divider(): $direction must be `down` or `up`, got `#{$direction}`.";
+  }
+  @if $position != after and $position != before {
+    @error "wave-divider(): $position must be `after` or `before`, got `#{$position}`.";
+  }
+
+  position: relative;
+  isolation: isolate;
+
+  &::#{$position} {
+    content: '';
+    position: absolute;
+    inset-inline: 0;
+    block-size: $height;
+    pointer-events: none;
+    z-index: 1;
+
+    @if $flip {
+      inset-block-start: calc(100% - #{$height});
+    } @else {
+      inset-block-end: calc(100% - #{$height});
+    }
+
+    // An ellipse wider than the box gives a shallow, natural curve rather
+    // than the circular arc a border-radius would produce.
+    @if $direction == down {
+      background: #{$color};
+      // stylelint-disable-next-line function-no-unknown
+      mask: radial-gradient(120% #{$height} at 50% 0%, transparent 99%, #000 100%);
+    } @else {
+      background: #{$color};
+      // stylelint-disable-next-line function-no-unknown
+      mask: radial-gradient(120% #{$height} at 50% 100%, #000 99%, transparent 100%);
+    }
+  }
+}