css-is-awesome 1.19.2 → 1.21.0

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

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

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

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

package/public/themes/terminal/theme.css

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

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

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

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

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

package/scripts/audit-pairs.json

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

package/scripts/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-contract.json

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

package/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, '    ');
 }
 
 // -----------------------------------------------------------