css-is-awesome 1.19.2 → 1.21.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)
 
@@ -168,7 +168,7 @@ Why it matters: components call `cia.space(4)`, which resolves to `var(--space-4
 
 Two `<link media>` themes still work under the new selector model: a stylesheet whose `media` doesn't match is loaded but never applied, so only the matching file's `:root` block lands.
 
-Validator: `node scripts/theme-validator.js path/to/theme.css` (or `--all` for every shipped theme). Every theme must declare every required contract token (127 required in contract 1.1; missing required tokens always fail, missing optional ones are reported as info). The audit also runs a WCAG 2.2 AA contrast check over 22 pairs; **a11y FAILs are fatal by default** as of v0.7. Pass `--allow-a11y-fail` to downgrade contrast failures to a report-only warning (the older `--strict` flag is accepted as a no-op alias). `--border-default` is treated as decorative per WCAG 2.2 SC 1.4.11 and reports as info, not FAIL.
+Validator: `node scripts/theme-validator.js path/to/theme.css` (or `--all` for every shipped theme). Every theme must declare every required contract token (127 required in contract 1.3; missing required tokens always fail, missing optional ones are reported as info). The audit also runs a WCAG 2.2 AA contrast check over 22 pairs; **a11y FAILs are fatal by default** as of v0.7. Pass `--allow-a11y-fail` to downgrade contrast failures to a report-only warning (the older `--strict` flag is accepted as a no-op alias). `--border-default` is treated as decorative per WCAG 2.2 SC 1.4.11 and reports as info, not FAIL.
 
 ### Theme init (Next.js / SSR consumers)
 
@@ -338,15 +338,16 @@ Or run this in-repo copy directly — needs its SDK peer deps installed manually
 }
 ```
 
-Either way it exposes **33 tools** across 8 families:
+Either way it exposes **34 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`
+- **Theme upgrades** — `fix_theme` (rewrite deprecated tokens to their replacements; returns text, never writes)
 - **Doc readers** — `read_llm_txt`, `read_changelog`, `read_migration`, `read_theming`, `read_agents`, `read_contract`, `read_three_tiers`, `read_readme`, `read_versioning`
 - **Helpers** — `assemble_prompt` (bundle context), `resolve_size` (snap a design px value to cia's 4px grid — call this whenever a design tool hands you a raw px value), `validate_theme` (run the real theme validator — contract + contrast — on a CSS string before you ship it), `theme_from_tokens` (DTCG / Tokens Studio / flat token JSON → a complete theme.css, base-inherited and validated; same function as `cia theme from-tokens`), `get_token_map` (that path → token mapping as data, or how one path resolves — read it instead of re-deriving the rules)
 
@@ -366,7 +367,12 @@ Either way it exposes **33 tools** across 8 families:
   default boilerplate), unmapped paths pass through verbatim and are reported, a `--dark` file or paired
   `color-light`/`color-dark` groups become `light-dark()`, and the validator + WCAG audit run before anything is
   written. Same function as the MCP `theme_from_tokens` tool; `npx cia theme map [--json] [--path <token.path>]` prints the design-token → cia-token mapping that verb applies (same data as the MCP `get_token_map` tool), for anyone who needs to map one token name the way the converter would. Run any verb with `--help`. (`cia init` remains
-  planned.)
+  planned.) `npx cia fix-theme <theme.css> [--write]` moves a theme onto
+  current token names: it renames any DEPRECATED token to its replacement,
+  changing the property only — values, comments and ordering survive, so the
+  rendered theme is identical. Prints by default; writes only with `--write`;
+  a block already declaring the replacement is reported, never merged. Same
+  function as the MCP `fix_theme` tool.
 - **JSON token export** — Tokens Studio-format sample in `figma-tokens/tokens.json`; it round-trips through `cia theme from-tokens` (paired light/dark groups → one `light-dark()` theme).
 - **`llm.txt`** — at the repo root and served from the docs site; single-fetch
   summary for any AI agent. Also readable over MCP via `read_llm_txt`.

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+# [1.21.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.20.0...v1.21.0) (2026-09-23)
+
+
+### Features
+
+* **cli:** cia fix-theme — rename deprecated tokens to their replacements ([665d871](https://github.com/Jerry2d3d/css-is-awesome/commit/665d87129f578d1ac38f410ce7461f37bbe24357))
+
+# [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)
@@ -632,3 +635,10 @@ A PR that adds a new contract glyph must:
 Per-theme override glyphs are NEVER required by the contract — themes
 opt in glyph-by-glyph by declaring `--cia-icon-<name>` and shipping the
 replacement file alongside.
+>
+> **Deprecations are machine-readable.** Every one lives in the `deprecated` map in
+> [`scripts/theme-contract.json`](./scripts/theme-contract.json) with the token it replaces,
+> when it was deprecated and when it goes. The validator prints it, `get_token` returns it,
+> `npx cia analyze` flags it in your stylesheets, and `npx cia fix-theme <file> --write`
+> renames it for you — property only, so the theme renders identically. `check:contract`
+> fails the build if a deprecation points at a token that does not exist.

package/MIGRATION.md

@@ -2,6 +2,64 @@
 
 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 |
+
+Nothing here needs doing. If you would rather move onto the current name now,
+`npx cia fix-theme <your-theme.css>` shows what it would change and
+`--write` applies it. It renames the property and nothing else, so the theme
+renders identically; a block already declaring `--page-hero-bg` is reported
+rather than merged.
+
+### 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

@@ -14,7 +14,7 @@
 
 **Read [`llm.txt`](./llm.txt) first.** One file, the whole system: install path, hard rules, the mixin vocabulary, and the traps that make agents write wrong cia code. It ships in the npm package, so it's at `node_modules/css-is-awesome/llm.txt` in any project that has cia.
 
-**Then connect the MCP server** and stop guessing at signatures. It answers from the real source — 33 tools covering themes, mixins, functions, tokens, recipes, components, theme validation, theme generation from design tokens and the token mapping itself.
+**Then connect the MCP server** and stop guessing at signatures. It answers from the real source — 34 tools covering themes, mixins, functions, tokens, recipes, components, theme validation, theme generation from design tokens and the token mapping itself.
 
 ```json
 {
@@ -79,7 +79,7 @@ Author your own class names; the mixin handles the styling. Mixins for buttons,
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/css-is-awesome@1/dist/css-is-awesome.min.css">
 ```
 
-Theme first (sets the tokens), library second. **No `data-theme` attribute needed** — a single theme file styles the page on its own. Swap the URL to swap the theme; the HTML never changes. Bundle tiers — `dist/tokens.css` (2.2 KB gz, `:where(:root)` vars only), `dist/css-is-awesome.core.min.css` (2.4 KB gz, tokens + resets), `dist/css-is-awesome.min.css` (7.3 KB gz, full).
+Theme first (sets the tokens), library second. **No `data-theme` attribute needed** — a single theme file styles the page on its own. Swap the URL to swap the theme; the HTML never changes. Bundle tiers — `dist/tokens.css` (2.2 KB gz, `:where(:root)` vars only), `dist/css-is-awesome.core.min.css` (2.4 KB gz, tokens + resets), `dist/css-is-awesome.min.css` (8.0 KB gz, full).
 
 ### 3. Bare tags (opt-in Pico-mode)
 
@@ -145,11 +145,13 @@ 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
 
-Every theme declares the same slots: **surfaces · ink · lines · primary · seal · accent · code · type · space · radius · shadow · blur · glow · motion**. Components read tokens, themes set tokens, nothing else. 127 required, 36 optional.
+Every theme declares the same slots: **surfaces · ink · lines · primary · seal · accent · code · type · space · radius · shadow · blur · glow · motion**. Components read tokens, themes set tokens, nothing else. 127 required, 49 optional.
 
 **Themes own the spacing scale.** A theme declares the numbered scale `--space-0` … `--space-9` (contract-required), which is exactly what `cia.space(4)` compiles to — so a theme can ship tighter or airier rhythm without touching a component. The six t-shirt names (`--space-2xs/xs/sm/md/lg/xl`) are optional; the library emits them as references (`--space-md: var(--space-4)`), so they track the numbered scale automatically.
 
@@ -221,6 +223,7 @@ The CLI also carries the registry and the health check:
 
 ```bash
 npx cia add --list          # browse the recipe book
+npx cia fix-theme t.css     # move a theme onto current token names (--write to apply)
 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, off-contract tokens (typos),
@@ -301,7 +304,7 @@ The scope is kept narrow: 8 `!important` declarations, all inside `@media print`
 
 ## MCP server (for AI agents)
 
-cia ships a Model Context Protocol stdio server (JSON-RPC over stdio, protocol `2024-11-05`) exposing **33 tools** across 8 families (themes, mixins, functions, tokens · 127 required of them, animations, components, recipes, doc readers) plus `assemble_prompt` (context bundles) , `resolve_size` (snap design px values to cia's 4px grid) `validate_theme` (run the real theme validator on CSS you just wrote) `theme_from_tokens` (design-tokens JSON → a complete, validated theme.css) and `get_token_map` (that mapping as data, or how one path resolves). Any MCP-aware client (Claude Code, Cursor, Aider, Gemini, Copilot) can then query cia's real design system — mixin signatures, tokens, themes, recipes — instead of guessing, without grep-walking the repo. Full reference: [`/docs/mcp`](https://cssisawesome.com/docs/mcp/).
+cia ships a Model Context Protocol stdio server (JSON-RPC over stdio, protocol `2024-11-05`) exposing **34 tools** across 8 families (themes, mixins, functions, tokens · 127 required of them, animations, components, recipes, doc readers) plus `assemble_prompt` (context bundles) , `resolve_size` (snap design px values to cia's 4px grid) `validate_theme` (run the real theme validator on CSS you just wrote) `theme_from_tokens` (design-tokens JSON → a complete, validated theme.css) and `get_token_map` (that mapping as data, or how one path resolves). Any MCP-aware client (Claude Code, Cursor, Aider, Gemini, Copilot) can then query cia's real design system — mixin signatures, tokens, themes, recipes — instead of guessing, without grep-walking the repo. Full reference: [`/docs/mcp`](https://cssisawesome.com/docs/mcp/).
 
 **Recommended — zero install:** use the dedicated [`css-is-awesome-mcp`](https://www.npmjs.com/package/css-is-awesome-mcp) package. It depends on `css-is-awesome` and resolves your installed version's real source, so it's never out of sync — and the MCP SDK ships as a real dependency, not an optional peer you have to remember to add.
 
@@ -364,6 +367,8 @@ It also hosts the **[playground](https://cssisawesome.com/playground/)**: write
 | `npm run build:css:all` | Compile all bundles (full + core + utilities + minified) + themes + token types |
 | `npm run build:css:themes` | Rebuild the 24 per-theme CSS files in `public/themes/` **and** regenerate the all-in-one `public/theme.css` bundle |
 | `npm run check:theme-drift` | Rebuild the themes into a scratch copy and fail if the committed artifacts don't match their SCSS sources |
+| `npm run check:contract` | Diff the token contract against the last release tag and fail if the required/optional lists changed without the version bump [`VERSIONING.md`](./VERSIONING.md) requires |
+| `npm run check:rtl` | Audit the SCSS for physical properties that should be logical (`margin-left` → `margin-inline-start`) |
 | `npm run build:token-types` | Generate `dist/tokens.d.ts` from the contract |
 | `npm run dtcg-to-scss` | Convert DTCG-format design tokens into cia SCSS |
 | `npm run lint` | ESLint on the Next.js app |
@@ -372,6 +377,9 @@ It also hosts the **[playground](https://cssisawesome.com/playground/)**: write
 | `npm run validate-icons` | Validate the `core` icon pack against the 49-glyph contract |
 | `npm run validate-api` | Assert the `css-is-awesome/api` barrel stays zero-emit |
 | `npm run validate-package` | Pack + install into a temp project and compile every documented `@use` form — catches breakage that in-repo checks can't see |
+| `npm run test:surfaces` | Assert cia never applies a page surface automatically — the guarantee that adding hero/band tokens changes nobody's existing page |
+| `npm run test:tokens` | Exercise the design-tokens converter (DTCG / Tokens Studio / flat) against fixtures |
+| `npm run verify:playground` | Compile real samples through the playground's in-browser Sass path in Node |
 | `npm run pack:consumer` | Pack and install this build into a local consumer (defaults to `../boiler-project-ai`); `--dry-run` supported |
 | `npm test` | Playwright suite — axe a11y checks + per-theme visual snapshots |
 
@@ -406,18 +414,18 @@ Full detail: [`/docs/testing`](https://cssisawesome.com/docs/testing/).
 
 | Bundle | Size | Use case |
 |---|---|---|
-| `dist/tokens.css` | 2.25 KB | Tokens only (`:where(:root)` CSS variables, no rules) — the purest mixin-first emit |
-| `dist/css-is-awesome.core.min.css` | 2.38 KB | Tokens + resets, no utilities or components |
-| `dist/css-is-awesome.utilities.min.css` | 4.75 KB | Every `cia-*` utility class, nothing else |
-| `dist/css-is-awesome.min.css` | 7.96 KB | Full bundle (everything) |
-| Per-theme `themes/<name>/theme.css` | 1.9–3.7 KB | One file per theme, both modes via `light-dark()`, drop-in with no markup change |
+| `dist/tokens.css` | 2.26 KB | Tokens only (`:where(:root)` CSS variables, no rules) — the purest mixin-first emit |
+| `dist/css-is-awesome.core.min.css` | 2.42 KB | Tokens + resets, no utilities or components |
+| `dist/css-is-awesome.utilities.min.css` | 4.79 KB | Every `cia-*` utility class, nothing else |
+| `dist/css-is-awesome.min.css` | 7.99 KB | Full bundle (everything) |
+| Per-theme `themes/<name>/theme.css` | 2.0–3.8 KB | One file per theme, both modes via `light-dark()`, drop-in with no markup change |
 | **Runtime JavaScript shipped in package** | **0 KB** | Nothing in the package is loaded by a page. The Node tooling (`cia` CLI, MCP server, validators) never reaches the browser; JS-driven UI features ship as separate add-on packages. |
 
 ## Status
 
 **Stable, [published on npm](https://www.npmjs.com/package/css-is-awesome)** (first published 2026-09-01). The mixin API, functions, token contract, and theme architecture are stable and under strict SemVer — breaking changes require a major bump. See [`VERSIONING.md`](./VERSIONING.md) for the policy.
 
-The 1.0 surface is the v0.8 mixin-first reframe — twelve mixin renames, theme system collapsed to 8 single-file theme families, six zero-JS components, intrinsic-layout vocabulary, opt-in utilities — plus the recipes book, the Tailwind/Bootstrap migration on-ramp, print/PDF support, the in-browser [Playground](https://cssisawesome.com/playground/), the design-tokens on-ramp (`npx cia theme from-tokens` / `theme map`), and the 33-tool MCP server (now also available zero-install via the companion [`css-is-awesome-mcp`](https://www.npmjs.com/package/css-is-awesome-mcp) package). The npm package ships ZERO runtime JavaScript by hard rule — nothing in it is loaded by a page; its Node tooling (CLI, MCP server, validators) never reaches the browser.
+The 1.0 surface is the v0.8 mixin-first reframe — twelve mixin renames, theme system collapsed to 8 single-file theme families, six zero-JS components, intrinsic-layout vocabulary, opt-in utilities — plus the recipes book, the Tailwind/Bootstrap migration on-ramp, print/PDF support, the in-browser [Playground](https://cssisawesome.com/playground/), the design-tokens on-ramp (`npx cia theme from-tokens` / `theme map`), and the 34-tool MCP server (now also available zero-install via the companion [`css-is-awesome-mcp`](https://www.npmjs.com/package/css-is-awesome-mcp) package). The npm package ships ZERO runtime JavaScript by hard rule — nothing in it is loaded by a page; its Node tooling (CLI, MCP server, validators) never reaches the browser.
 
 See [CHANGELOG.md](./CHANGELOG.md) for the full history and [MIGRATION.md](./MIGRATION.md) for the v0.7 → v0.8 and v0.8 → v1.0 upgrade paths.
 

package/bin/analyze.cjs

@@ -33,6 +33,18 @@ function loadContractTokens() {
   }
 }
 
+// Tokens the contract has superseded. They still resolve — cia deprecates
+// rather than deletes — so this is a warning with a one-command fix, not an
+// error. Read from the same map `cia fix-theme` and the validator use.
+function loadDeprecated() {
+  try {
+    const c = JSON.parse(fs.readFileSync(CONTRACT_PATH, 'utf8'));
+    return c.deprecated && typeof c.deprecated === 'object' ? c.deprecated : {};
+  } catch {
+    return {};
+  }
+}
+
 // 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;
@@ -256,7 +268,7 @@ function missingFocusVisible(strippedSrc) {
   return [{ level: 'info', rule: 'missing-focus-visible', detail: 'interactive :hover/:active styling with no :focus-visible or focus-ring anywhere in this file — keyboard users may get no visible feedback' }];
 }
 
-function analyzeFile(file, symbols, contractTokens, extraNs) {
+function analyzeFile(file, symbols, contractTokens, extraNs, deprecated) {
   const raw = fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
   const src = stripComments(raw);
   const ns = detectNamespaces(src, extraNs);
@@ -280,6 +292,37 @@ function analyzeFile(file, symbols, contractTokens, extraNs) {
       }
     }
   }
+  // deprecated-token: still resolves, but the contract names a successor.
+  // Catches both a declaration (--old: value) and a reference (var(--old)).
+  // A plain scan, not a built regex: custom-property names are distinctive
+  // enough that a substring plus a name-boundary check is exact, and it does
+  // not depend on escaping a token name into a pattern.
+  if (deprecated && Object.keys(deprecated).length) {
+    const isNameChar = (ch) => /[A-Za-z0-9_-]/.test(ch);
+    for (const [tok, def] of Object.entries(deprecated)) {
+      let at = src.indexOf(tok);
+      let hit = false;
+      while (at !== -1) {
+        const after = src[at + tok.length];
+        // Reject a longer name that merely starts with this one.
+        if (after === undefined || !isNameChar(after)) { hit = true; break; }
+        at = src.indexOf(tok, at + 1);
+      }
+      if (!hit) continue;
+      const to = (def && def.replacedBy) || null;
+      let since = '';
+      if (def && def.since) {
+        since = ' (contract ' + def.since + (def.removeIn ? ', removed in ' + def.removeIn : '') + ')';
+      }
+      findings.push({
+        level: 'warn',
+        rule: 'deprecated-token',
+        detail: tok + ' is deprecated' + since + (to ? ' — use ' + to : '') +
+          '; your value still works. Run `npx cia fix-theme <file>` to rename it.',
+      });
+    }
+  }
+
   // 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.
@@ -325,6 +368,7 @@ const RULE_CATEGORY = {
   'unknown-symbol': 'API',
   'space-scale': 'Spacing',
   'off-contract-token': 'Contract',
+  'deprecated-token': 'Contract',
   'off-scale-length': 'Spacing',
   'hard-coded-color': 'Color',
   bem: 'Naming',
@@ -364,8 +408,9 @@ async function run(args) {
 
   const symbols = collectSymbols();
   const contractTokens = loadContractTokens();
+  const deprecated = loadDeprecated();
   const files = walkScss(target);
-  const results = files.map((f) => analyzeFile(f, symbols, contractTokens, extraNs)).filter((r) => r.findings.length || r.namespaces.length);
+  const results = files.map((f) => analyzeFile(f, symbols, contractTokens, extraNs, deprecated)).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]++;

package/bin/cia.cjs

@@ -43,6 +43,9 @@ Commands:
                           theme.css. \`cia theme from-tokens --help\`.
   theme map               The path → token mapping from-tokens applies, as
                           data: a table, \`--json\`, or \`--path <p>\` for one.
+  fix-theme <file>        Move a theme onto current token names: rewrites
+                          deprecated tokens to their replacements. Prints by
+                          default, \`--write\` applies.
 
 Examples:
   cia migrate tailwind ./tailwind.config.js
@@ -50,6 +53,7 @@ Examples:
   cia analyze src/styles
   cia theme from-tokens tokens.json --name acme --out src/styles/acme.css
   cia theme map --path color.text.primary
+  cia fix-theme src/styles/acme.css --write
 
 Run \`cia <command> --help\` for command-specific help.
 `;
@@ -158,6 +162,12 @@ async function main() {
     return;
   }
 
+  if (command === 'fix-theme') {
+    const { run } = require('./fix-theme.cjs');
+    await run(rest);
+    return;
+  }
+
   if (command === 'theme') {
     const [sub, ...themeArgs] = rest;
     if (!sub || sub === '-h' || sub === '--help' || sub === 'help') {

package/bin/fix-theme.cjs

@@ -0,0 +1,151 @@
+/**
+ * cia fix-theme — rewrite a theme's deprecated tokens to their replacements.
+ *
+ * The CLI face of scripts/fix-theme.cjs (the MCP tool `fix_theme` and the
+ * in-process `handlers.fix_theme` are the same function). cia deprecates a
+ * token rather than deleting it, so the old declaration keeps working — this
+ * is the one command that moves you onto the current name.
+ *
+ * Only the property name changes. Values, comments, ordering and whitespace
+ * survive byte-for-byte, so applying this cannot alter how the theme looks.
+ *
+ * Reads and prints by default; writes only with --write.
+ *
+ * Exit codes: 0 nothing to do or fixed, 1 collisions need a human, 2 usage /
+ * input error.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const HELP = `cia fix-theme — move a theme onto current token names
+
+Usage:
+  cia fix-theme <theme.css> [options]
+
+Options:
+  --write        Apply the changes to the file (default: print, change nothing)
+  --json         Machine-readable { css, changes, unchanged, summary }
+  -h, --help     This text
+
+What it does:
+  cia deprecates a token instead of deleting it, so your existing declaration
+  keeps working. This renames it to the replacement the contract names. Only
+  the property name moves — the value, your comments, the ordering and the
+  whitespace are untouched, so the rendered theme is identical.
+
+  If a block already declares the replacement, that line is left alone and
+  reported: merging two values is your decision, not the tool's.
+
+Examples:
+  cia fix-theme src/styles/acme.css            # show me what would change
+  cia fix-theme src/styles/acme.css --write    # do it
+  cia fix-theme src/styles/acme.css --json     # for a script
+`;
+
+const isTTY = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (code, s) => (isTTY ? `[${code}m${s}` : s);
+const bold = (s) => c('1', s);
+const dim = (s) => c('2', s);
+const green = (s) => c('32', s);
+const yellow = (s) => c('33', s);
+const red = (s) => c('31', s);
+
+function parseArgs(argv) {
+  const out = { file: null, write: false, json: false, help: false };
+  for (const a of argv) {
+    if (a === '--write') out.write = true;
+    else if (a === '--json') out.json = true;
+    else if (a === '-h' || a === '--help' || a === 'help') out.help = true;
+    else if (a.startsWith('-')) throw new Error(`unknown option '${a}'`);
+    else if (out.file == null) out.file = a;
+    else throw new Error(`unexpected extra argument '${a}'`);
+  }
+  return out;
+}
+
+async function run(argv) {
+  let args;
+  try {
+    args = parseArgs(argv || []);
+  } catch (err) {
+    process.stderr.write(`${red('error:')} ${err.message}\n\n${HELP}`);
+    process.exitCode = 2;
+    return;
+  }
+  if (args.help || !args.file) {
+    process.stdout.write(HELP);
+    if (!args.help) process.exitCode = 2;
+    return;
+  }
+
+  const abs = path.resolve(args.file);
+  let css;
+  try {
+    css = fs.readFileSync(abs, 'utf8');
+  } catch (err) {
+    process.stderr.write(`${red('error:')} could not read ${args.file} — ${err.message}\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const { fixTheme } = require(path.join(__dirname, '..', 'scripts', 'fix-theme.cjs'));
+  let result;
+  try {
+    result = fixTheme({ css });
+  } catch (err) {
+    process.stderr.write(`${red('error:')} ${err.message}\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const rewrites = result.changes.filter((x) => x.kind === 'rewrite');
+  const conflicts = result.changes.filter((x) => x.kind === 'conflict');
+
+  if (args.json) {
+    process.stdout.write(
+      JSON.stringify(
+        { file: args.file, written: args.write && rewrites.length > 0, ...result },
+        null,
+        2
+      ) + '\n'
+    );
+  } else {
+    const rel = path.relative(process.cwd(), abs) || args.file;
+    if (!result.changes.length) {
+      process.stdout.write(`${green('✓')} ${bold(rel)} ${dim('— no deprecated tokens; already current')}\n`);
+      return;
+    }
+    process.stdout.write(`${bold(rel)}\n`);
+    for (const ch of rewrites) {
+      process.stdout.write(`  ${green('→')} line ${ch.line}: ${ch.from} ${dim('→')} ${bold(ch.to)}\n`);
+      process.stdout.write(`      ${dim(ch.reason)}\n`);
+    }
+    for (const ch of conflicts) {
+      process.stdout.write(`  ${yellow('!')} line ${ch.line}: ${ch.from} ${dim('left as-is')}\n`);
+      process.stdout.write(`      ${dim(ch.reason)}\n`);
+    }
+  }
+
+  if (args.write && rewrites.length) {
+    try {
+      fs.writeFileSync(abs, result.css);
+    } catch (err) {
+      process.stderr.write(`${red('error:')} could not write ${args.file} — ${err.message}\n`);
+      process.exitCode = 2;
+      return;
+    }
+    if (!args.json) {
+      process.stdout.write(`\n${green('✓')} wrote ${rewrites.length} change(s) to ${bold(path.relative(process.cwd(), abs) || args.file)}\n`);
+    }
+  } else if (rewrites.length && !args.json) {
+    process.stdout.write(`\n${dim('nothing written — re-run with --write to apply')}\n`);
+  }
+
+  // Collisions are the one case a human has to settle, so say so in the exit
+  // code too: a pipeline should stop rather than assume the theme is current.
+  if (conflicts.length) process.exitCode = 1;
+}
+
+module.exports = { run, parseArgs, HELP };

package/llm.txt

@@ -49,9 +49,9 @@ silent.
 - **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|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.
+- **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. `fix-theme <theme.css> [--write]` renames DEPRECATED tokens to their replacements (property only — values, comments and ordering survive, so the theme renders identically; prints by default, writes with `--write`; a block already declaring the replacement is reported, never merged).
 - **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`. **34 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:
@@ -198,4 +198,4 @@ Humans first. AI's role is to compose, not to lead the pitch.
 
 ---
 
-*Generated 2026-05-21 for cia v0.8. Updated 2026-05-23 for the v1.0 architecture lock, 2026-08-30 for the theme single-source rework (24 themes, 127+36 contract, themeable spacing, `:root, :root[data-theme]` selector), 2026-09-04 for the shipped recipes count (5), the mobile-nav mixin family, and the dropdown popover guard, and 2026-09-19 for the 32-recipe book, 33-tool MCP, contract 1.2 (127 + 41 in 10 features), the playground and the design-tokens on-ramp. Update when the API surface changes.*
+*Generated 2026-05-21 for cia v0.8. Updated 2026-05-23 for the v1.0 architecture lock, 2026-08-30 for the theme single-source rework (24 themes, 127+36 contract, themeable spacing, `:root, :root[data-theme]` selector), 2026-09-04 for the shipped recipes count (5), the mobile-nav mixin family, and the dropdown popover guard, and 2026-09-19 for the 32-recipe book, 33-tool MCP, contract 1.2 (127 + 41 in 10 features), the playground and the design-tokens on-ramp, and 2026-09-24 for contract 1.3 (127 required + 49 optional across 11 feature groups) and the page-surfaces hero/band tokens. Update when the API surface changes.*