css-is-awesome 1.19.2 → 1.21.0

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

package/public/theme.css

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

package/public/themes/boilerplate/theme.css

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

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

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

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

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

package/public/themes/cupertino/theme.css

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

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

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

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

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

package/public/themes/glass/theme.css

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

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

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

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

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

package/public/themes/graphite/theme.css

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

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

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

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

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

package/public/themes/press/theme.css

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

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

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

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

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

package/public/themes/prism/theme.css

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

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

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

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

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

package/public/themes/sketchbook/theme.css

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