css-is-awesome 1.20.0 → 1.21.0

package/AGENTS.md

@@ -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,7 +338,7 @@ 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)
@@ -347,6 +347,7 @@ Either way it exposes **33 tools** across 8 families:
 - **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,12 @@
 # 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)
 
 

package/CONTRACT.md

@@ -635,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

@@ -30,6 +30,12 @@ so the guarantee is enforced rather than promised.
 | `--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:

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)
 
@@ -151,7 +151,7 @@ Full authoring walkthrough: [`/docs/authoring/themes`](https://cssisawesome.com/
 
 ## 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.
 
@@ -223,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),
@@ -303,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.
 
@@ -366,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 |
@@ -374,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 |
 
@@ -408,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,7 +49,7 @@ 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`.
 - **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.
@@ -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 + 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.
+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.*

package/mcp/server.cjs

@@ -21,9 +21,10 @@
  *   Sizing:        resolve_size
  *   Themes (build): theme_from_tokens — design-tokens JSON → validated theme.css
  *                   get_token_map     — the path → token mapping as data (or one path)
+ *   Themes (fix):   fix_theme         — rewrite deprecated tokens to their replacements
  *   Prompt:        assemble_prompt(intent[, args])
  *
- * 33 tools total.
+ * 34 tools total.
  *
  * Discovery model: filesystem scan, no database. Parses SCSS files with
  * focused regex (no full SCSS AST). Tokens come from the authoritative
@@ -471,7 +472,8 @@ function loadTokenContract() {
     (byCategory[category] = byCategory[category] || []).push(t);
   }
 
-  return { required: contract.required, optional, features, byName, byCategory };
+  const deprecated = contract.deprecated && typeof contract.deprecated === 'object' ? contract.deprecated : {};
+  return { required: contract.required, optional, features, deprecated, byName, byCategory };
 }
 
 /**
@@ -726,14 +728,51 @@ const handlers = {
   // source token the same way without re-deriving the rules.
   get_token_map({ path: tokenPath } = {}) {
     const { tokenMap, resolvePath } = require(path.join(SCRIPTS_DIR, 'tokens-to-theme.cjs'));
-    if (tokenPath == null || tokenPath === '') return tokenMap({ ciaRoot: PROJECT_ROOT });
+    const deprecated = getTokens().deprecated;
+    if (tokenPath == null || tokenPath === '') {
+      // `deprecated` rides along so an agent translating a design file lands
+      // on the CURRENT name in one call, instead of mapping to a token that
+      // is on its way out and finding out later.
+      return { ...tokenMap({ ciaRoot: PROJECT_ROOT }), deprecated };
+    }
     const r = resolvePath(String(tokenPath), { ciaRoot: PROJECT_ROOT });
     const entry = getTokens().byName[r.token] || null;
+    const dep = deprecated[r.token] || null;
     return {
       ...r,
       required: entry ? entry.required : null,
       feature: entry && !entry.required ? (entry.feature || null) : null,
       category: entry ? entry.category : null,
+      deprecated: dep ? { replacedBy: dep.replacedBy || null, since: dep.since || null, removeIn: dep.removeIn || null, note: dep.note || null } : null,
+    };
+  },
+
+  // Rewrite a theme's DEPRECATED token declarations to their replacements.
+  // Returns the corrected text and a per-line account of what moved and why;
+  // it never touches disk, so an agent can show the diff, ask, and only then
+  // write. Renames the property only — a value is never altered, so applying
+  // this cannot change how the theme looks.
+  fix_theme({ css, apply } = {}) {
+    if (typeof css !== 'string' || !css.trim()) {
+      throw new Error('fix_theme: css is required (the compiled theme CSS, not .scss source)');
+    }
+    const { fixTheme, deprecations } = require(path.join(SCRIPTS_DIR, 'fix-theme.cjs'));
+    const result = fixTheme({ css });
+    const rewrites = result.changes.filter((c) => c.kind === 'rewrite');
+    const conflicts = result.changes.filter((c) => c.kind === 'conflict');
+    return {
+      ...result,
+      // `apply` is the caller's stated intent, echoed back. This tool has no
+      // filesystem access in either case — saying so plainly stops an agent
+      // reporting "I updated your theme" when nothing was written.
+      applied: false,
+      requestedApply: Boolean(apply),
+      summary: result.unchanged
+        ? (conflicts.length
+            ? `Nothing rewritten: ${conflicts.length} collision(s) need a human decision.`
+            : 'No deprecated tokens found — this theme is already current.')
+        : `${rewrites.length} declaration(s) renamed${conflicts.length ? `, ${conflicts.length} left for you to resolve` : ''}. Write the returned css yourself; nothing was saved.`,
+      knownDeprecations: deprecations(),
     };
   },
 
@@ -876,10 +915,16 @@ const handlers = {
         referencedBy.push({ name: d.name, kind: d.kind, path: d.path });
       }
     }
+    const dep = getTokens().deprecated[entry.name] || null;
     return {
       name: entry.name,
       category: entry.category,
       required: entry.required,
+      // Contract 1.3+: null unless this token has been superseded. The old
+      // value keeps working — `fix_theme` renames it when the caller asks.
+      deprecated: dep
+        ? { replacedBy: dep.replacedBy || null, since: dep.since || null, removeIn: dep.removeIn || null, note: dep.note || null }
+        : null,
       // Contract 1.2: the feature an OPTIONAL token enables (null for required).
       feature: entry.required ? null : (entry.feature || null),
       themeValues,
@@ -1417,6 +1462,22 @@ async function startServer() {
     },
   }, async (a) => ok(handlers.theme_from_tokens(a || {})));
 
+  server.registerTool('fix_theme', {
+    description:
+      'Upgrade a theme that uses a DEPRECATED token. cia deprecates a token rather than deleting it, so the ' +
+      'old declaration keeps working — but there is a better name now, and this rewrites it for you. Pass the ' +
+      'compiled theme CSS; get back { css, changes, unchanged, summary } where every change names the line, the ' +
+      'old token, its replacement and why it moved. Only the property name changes — values, comments, ordering ' +
+      'and whitespace survive byte-for-byte, so applying it cannot alter how the theme looks. If a block already ' +
+      'declares the replacement the old line is left alone and reported as a conflict, because merging two values ' +
+      'is a judgement call. NOTHING IS WRITTEN TO DISK: this returns text, and the caller decides whether to save ' +
+      'it. Use get_token to see what supersedes a given token, or read knownDeprecations in the result.',
+    inputSchema: {
+      css: z.string().describe('Compiled theme CSS — the :root/[data-theme] block(s), not .scss source.'),
+      apply: z.boolean().optional().describe('Your stated intent, echoed back as requestedApply. This tool cannot write files either way; you save the returned css yourself.'),
+    },
+  }, async (a) => ok(handlers.fix_theme(a || {})));
+
   server.registerTool('get_token_map', {
     description:
       'The design-token → cia-token mapping that theme_from_tokens applies, as data. Without `path`: ' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "css-is-awesome",
-  "version": "1.20.0",
+  "version": "1.21.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": {
@@ -74,6 +74,7 @@
     "scripts/theme-contract.json",
     "scripts/theme-validator.js",
     "scripts/tokens-to-theme.cjs",
+    "scripts/fix-theme.cjs",
     "scripts/theme-a11y.js",
     "scripts/audit-pairs.json",
     "scripts/icon-validator.js",
@@ -123,6 +124,7 @@
     "validate-package": "node scripts/validate-package.mjs",
     "validate-recipes": "node scripts/validate-recipes.mjs",
     "test:tokens": "node --test scripts/test-tokens-to-theme.mjs",
+    "test:fix-theme": "node --test scripts/test-fix-theme.mjs",
     "size-budget": "node scripts/size-budget.mjs",
     "size-report": "node scripts/size-budget.mjs --report",
     "coverage:api": "node scripts/api-coverage.mjs",

package/scripts/fix-theme.cjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// ============================================================================
+// fix-theme.cjs
+// ============================================================================
+// Rewrite a theme's DEPRECATED token declarations to their replacements.
+//
+// WHY THIS EXISTS
+// Until now the tooling could only *say* a token was deprecated. A consumer
+// then had to find it, look up what replaced it, and edit by hand — for a
+// rename that a machine can do exactly. `scripts/theme-contract.json` already
+// carries the `deprecated` map (old token → replacedBy / since / removeIn /
+// note); this turns that map into an offer: here is what changed, here is the
+// corrected file, say the word and it is yours.
+//
+// WHAT IT WILL NOT DO
+//   * It never writes to disk. It returns text. The caller decides — same
+//     contract as themeFromTokens(), for the same reason: a tool that edits
+//     a consumer's file as a side effect of being asked a question is a tool
+//     nobody can trust in a pipeline.
+//   * It never changes a VALUE. Only the property name on the left of the
+//     colon moves. A rename cannot alter how the theme looks.
+//   * It never duplicates. If a block already declares the replacement, the
+//     old line is left exactly where it is and the collision is reported,
+//     because merging two values is a judgement call, not a rewrite.
+//
+// FORMATTING
+// Line-based on purpose. A CSS parser would round-trip the file through an
+// AST and quietly restyle whitespace, comment placement and declaration
+// order — a diff full of noise around the one line that mattered. Here the
+// bytes either side of the property name survive untouched.
+//
+// Usage (library):
+//   const { fixTheme } = require('css-is-awesome/scripts/fix-theme.cjs');
+//   const { css, changes, unchanged } = fixTheme({ css: themeText });
+// ============================================================================
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const CONTRACT_PATH = path.join(__dirname, 'theme-contract.json');
+
+/** Load the token contract, or throw something a human can act on. */
+function loadContract(ciaRoot) {
+  const p = ciaRoot ? path.join(ciaRoot, 'scripts', 'theme-contract.json') : CONTRACT_PATH;
+  let raw;
+  try {
+    raw = fs.readFileSync(p, 'utf8');
+  } catch (err) {
+    throw new Error(`fix-theme: could not read the token contract at ${p} — ${err.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`fix-theme: the token contract at ${p} is not valid JSON — ${err.message}`);
+  }
+}
+
+/**
+ * The deprecations as a flat, serialisable list — the same data `get_token`
+ * and the validator report, so all three can never disagree.
+ */
+function deprecations(opts) {
+  const contract = (opts && opts.contract) || loadContract(opts && opts.ciaRoot);
+  const map = contract.deprecated && typeof contract.deprecated === 'object' ? contract.deprecated : {};
+  return Object.entries(map).map(([token, d]) => ({
+    token,
+    replacedBy: (d && d.replacedBy) || null,
+    since: (d && d.since) || null,
+    removeIn: (d && d.removeIn) || null,
+    note: (d && d.note) || null,
+  }));
+}
+
+// A custom-property declaration: leading whitespace, the name, optional
+// whitespace, the colon. Everything from the colon rightwards is untouched.
+const DECL = /^(\s*)(--[A-Za-z0-9_-]+)(\s*):/;
+
+// Strip /* … */ so a commented-out declaration is never counted as declared
+// nor rewritten. Length is preserved so line numbers stay honest.
+function blankComments(text) {
+  return text.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
+}
+
+/**
+ * Rewrite deprecated declarations.
+ *
+ * @param {object}  o
+ * @param {string}  o.css        theme CSS (compiled, not .scss source)
+ * @param {object} [o.contract]  pre-loaded contract (tests / callers with one)
+ * @param {string} [o.ciaRoot]   resolve the contract from another install
+ * @returns {{css:string, changes:Array, unchanged:boolean, deprecatedFound:string[]}}
+ *   changes[] entries are `{ line, from, to, reason, kind }` where kind is
+ *   'rewrite' (applied) or 'conflict' (left alone, and why).
+ */
+function fixTheme(o) {
+  const opts = o || {};
+  if (typeof opts.css !== 'string') {
+    throw new Error('fix-theme: css is required and must be a string (compiled CSS, not .scss source)');
+  }
+  const contract = opts.contract || loadContract(opts.ciaRoot);
+  const map = contract.deprecated && typeof contract.deprecated === 'object' ? contract.deprecated : {};
+
+  const lines = opts.css.split('\n');
+  const scan = blankComments(opts.css).split('\n');
+
+  // ── Pass 1: which tokens does each brace-scope already declare? ──────────
+  // Scope id changes on every `{`, so two theme blocks in one bundled file
+  // are judged independently — a collision in `[data-theme="a"]` says nothing
+  // about `[data-theme="b"]`.
+  const scopeOf = new Array(lines.length).fill(0);
+  const declaredIn = new Map(); // scopeId -> Set<token>
+  {
+    let depth = 0;
+    const stack = [0];
+    let next = 1;
+    for (let i = 0; i < scan.length; i++) {
+      const line = scan[i];
+      scopeOf[i] = stack[stack.length - 1];
+      const m = DECL.exec(line);
+      if (m) {
+        const id = stack[stack.length - 1];
+        if (!declaredIn.has(id)) declaredIn.set(id, new Set());
+        declaredIn.get(id).add(m[2]);
+      }
+      for (const ch of line) {
+        if (ch === '{') { stack.push(next++); depth++; }
+        else if (ch === '}') { if (stack.length > 1) stack.pop(); depth--; }
+      }
+    }
+  }
+
+  // ── Pass 2: rewrite, or explain why not ─────────────────────────────────
+  const changes = [];
+  const found = new Set();
+  for (let i = 0; i < lines.length; i++) {
+    const m = DECL.exec(scan[i]);
+    if (!m) continue;
+    const token = m[2];
+    const dep = map[token];
+    if (!dep || !dep.replacedBy) continue;
+
+    found.add(token);
+    const replacement = dep.replacedBy;
+    const already = declaredIn.get(scopeOf[i]);
+
+    if (already && already.has(replacement)) {
+      changes.push({
+        line: i + 1,
+        from: token,
+        to: replacement,
+        kind: 'conflict',
+        reason:
+          `${replacement} is already declared in this block, so renaming ${token} would ` +
+          `produce two declarations of the same property and silently pick the last one. ` +
+          `Left untouched — decide which value you want and delete the other.`,
+      });
+      continue;
+    }
+
+    // Rename only the property. Indentation, spacing before the colon, the
+    // value, the semicolon and any trailing comment all survive byte-exact.
+    lines[i] = lines[i].replace(DECL, (_full, indent, _name, gap) => `${indent}${replacement}${gap}:`);
+    changes.push({
+      line: i + 1,
+      from: token,
+      to: replacement,
+      kind: 'rewrite',
+      reason:
+        `${token} is deprecated since contract ${dep.since || '?'} and is removed in ` +
+        `${dep.removeIn || 'a future major'}. ${dep.note || ''}`.trim(),
+    });
+  }
+
+  const rewrites = changes.filter((c) => c.kind === 'rewrite');
+  return {
+    css: rewrites.length ? lines.join('\n') : opts.css,
+    changes,
+    unchanged: rewrites.length === 0,
+    deprecatedFound: [...found].sort(),
+  };
+}
+
+module.exports = { fixTheme, deprecations, loadContract };

package/scripts/theme-validator.js

@@ -354,7 +354,24 @@ function validateTokenSet(declared, contract) {
     const f = featureOf[t] || 'other';
     (optionalMissingByFeature[f] = optionalMissingByFeature[f] || []).push(t);
   }
-  return { ok: missing.length === 0, missing, optionalMissing, optionalMissingByFeature, declaredCount: declared.size };
+  // Contract 1.3+: a token this theme declares that has since been superseded.
+  // Reported separately from the optional-token info line — "you declared
+  // something that still works but has a better name now" is a different
+  // message from "you left a default to the library", and it comes with an
+  // action: `cia fix-theme`.
+  const deprecatedMap = contract.deprecated && typeof contract.deprecated === 'object' ? contract.deprecated : {};
+  const deprecatedUsed = [];
+  for (const [token, def] of Object.entries(deprecatedMap)) {
+    if (declared.has(token)) {
+      deprecatedUsed.push({
+        token,
+        replacedBy: (def && def.replacedBy) || null,
+        since: (def && def.since) || null,
+        removeIn: (def && def.removeIn) || null,
+      });
+    }
+  }
+  return { ok: missing.length === 0, missing, optionalMissing, optionalMissingByFeature, deprecatedUsed, declaredCount: declared.size };
 }
 
 // -----------------------------------------------------------
@@ -380,6 +397,7 @@ function validateText(text, contract, options) {
     missing: [],
     optionalMissing: [],
     optionalMissingByFeature: {},
+    deprecatedUsed: [],
     themes: null,
     a11y: null,
     error: null,
@@ -403,6 +421,7 @@ function validateText(text, contract, options) {
         missing: v.missing,
         optionalMissing: v.optionalMissing,
         optionalMissingByFeature: v.optionalMissingByFeature,
+        deprecatedUsed: v.deprecatedUsed,
         a11y: null,
       };
       if (wantA11y) theme.a11y = a11y.auditThemeTokens({ name: b.name, values: b.values });
@@ -432,6 +451,7 @@ function validateText(text, contract, options) {
   result.missing = v.missing;
   result.optionalMissing = v.optionalMissing;
   result.optionalMissingByFeature = v.optionalMissingByFeature;
+  result.deprecatedUsed = v.deprecatedUsed;
   result.ok = v.ok;
   if (wantA11y) {
     const inferredName = label !== '(pasted CSS)' ? (path.basename(path.dirname(label)) || path.basename(label, '.css')) : 'theme';
@@ -471,6 +491,21 @@ function relForDisplay(p) {
 
 // Optional tokens a theme leaves to the library default. Info only — shown as
 // a count, or listed with --show-optional. Never affects the exit code.
+// A token the theme declares that has been superseded. Never a failure — the
+// old value still works — but it names the replacement and the way to apply it.
+function deprecationInfo(deprecatedUsed, indent) {
+  const list = Array.isArray(deprecatedUsed) ? deprecatedUsed : [];
+  if (!list.length) return;
+  for (const d of list) {
+    console.log(
+      `${indent}${yellow('~')} ${d.token} is deprecated` +
+        (d.since ? ` (since contract ${d.since}` + (d.removeIn ? `, removed in ${d.removeIn}` : '') + ')' : '') +
+        (d.replacedBy ? ` — use ${d.replacedBy}` : '')
+    );
+    console.log(`${indent}  ${dim('your value still works; `npx cia fix-theme <file>` renames it for you')}`);
+  }
+}
+
 function optionalInfo(optionalMissing, byFeature, indent) {
   const list = Array.isArray(optionalMissing) ? optionalMissing : [];
   if (!list.length) return;
@@ -506,6 +541,7 @@ function reportResult(result) {
           `    ${green('✓')} [data-theme="${t.name}"] ${dim(`(${t.declaredCount} tokens)`)}`
         );
         optionalInfo(t.optionalMissing, t.optionalMissingByFeature, '      ');
+        deprecationInfo(t.deprecatedUsed, '      ');
       } else {
         const n = t.missing.length;
         console.log(
@@ -514,6 +550,7 @@ function reportResult(result) {
         for (const token of t.missing) {
           console.log(`        ${red(token)}`);
         }
+        deprecationInfo(t.deprecatedUsed, '      ');
       }
     }
     return;
@@ -525,6 +562,7 @@ function reportResult(result) {
       `${green('✓')} ${bold(rel)} ${dim(`passes (${result.declaredCount} tokens declared)`)}`
     );
     optionalInfo(result.optionalMissing, result.optionalMissingByFeature, '    ');
+    deprecationInfo(result.deprecatedUsed, '    ');
     return;
   }
 
@@ -535,6 +573,7 @@ function reportResult(result) {
   for (const token of result.missing) {
     console.log(`     ${red(token)}`);
   }
+  deprecationInfo(result.deprecatedUsed, '    ');
 }
 
 // -----------------------------------------------------------