cursedbelt 5.2.0 → 5.3.0

package/dist/styles-areas/core.css

@@ -144,3 +144,15 @@
 @source inline("w-[var(--control-h-lg)] w-[var(--control-h-md)] w-[var(--control-h-sm)] w-auto w-full w-px white");
 @source inline("whitespace-nowrap whitespace-pre-wrap wrap wrap-break-word z z-10 z-20 z-30 z-40 z-50");
 @source inline("z-[var(--z-popover)]");
+
+/*
+ * Theme variables cursedbelt's components read BY NAME (`var(--color-card)` in a style prop).
+ * Tailwind emits a theme variable only when the app's own pass sees it used, and a `var()` here is
+ * that use — `@source inline` cannot mark one. 9 variable(s), derived by
+ * scripts/generateUtilityStyles.ts → themeVariablesReadByName(). Nothing reads this property.
+ */
+@layer theme {
+  :root, :host {
+    --cb-theme-read-by-name: var(--color-accent) var(--color-border) var(--color-card) var(--color-muted) var(--color-popover) var(--duration-base) var(--ease-out) var(--text-caption) var(--text-sm);
+  }
+}

package/dist/styles-areas/spreadsheet.css

@@ -18,10 +18,10 @@
  * after an app's responsive variant (task 2124). An app that imports every area gets exactly
  * what `cursedbelt/styles-utilities.css` emits — proved rule by rule in
  * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
- * 4 candidate(s).
+ * 2 candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are
  * import closures rather than a hand-written list, is scripts/styleAreas.ts.
  */
-@source inline("--font-sans --text-sm col collapse");
+@source inline("col collapse");

package/dist/styles-areas/workbook-viewer.css

@@ -18,10 +18,10 @@
  * after an app's responsive variant (task 2124). An app that imports every area gets exactly
  * what `cursedbelt/styles-utilities.css` emits — proved rule by rule in
  * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
- * 7 candidate(s).
+ * 5 candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are
  * import closures rather than a hand-written list, is scripts/styleAreas.ts.
  */
-@source inline("--font-sans --text-sm col collapse min-w-16 w w-48");
+@source inline("col collapse min-w-16 w w-48");

package/dist/styles-utilities.css

@@ -4969,3 +4969,15 @@
     }
   }
 }
+
+/*
+ * Theme variables cursedbelt's components read BY NAME (`var(--color-card)` in a style prop).
+ * Tailwind emits a theme variable only when the app's own pass sees it used, and a `var()` here is
+ * that use — `@source inline` cannot mark one. 9 variable(s), derived by
+ * scripts/generateUtilityStyles.ts → themeVariablesReadByName(). Nothing reads this property.
+ */
+@layer theme {
+  :root, :host {
+    --cb-theme-read-by-name: var(--color-accent) var(--color-border) var(--color-card) var(--color-muted) var(--color-popover) var(--duration-base) var(--ease-out) var(--text-caption) var(--text-sm);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt",
-	"version": "5.2.0",
+	"version": "5.3.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The React design system of the cursedbelt split — components, styles, theme. cursedbelt-core below it; server tier in cursedbelt-server.",

package/scripts/checkAreaStyles.spec.ts

@@ -11,7 +11,11 @@ import {
   onlyAsPropertyName,
   onlyInMergeTables,
   readBeltSheets,
+  readThemeVariables,
+  themeVariablesIn,
   tokensInJs,
+  undefinedThemeVariables,
+  variablesDeclared,
 } from './checkAreaStyles';
 import { compileStylesheet } from './generateUtilityStyles';
 
@@ -226,3 +230,66 @@ describe('🔴 the ORDER check — a base utility after a variant that sets the
     }
   });
 });
+
+describe('🔴 the THEME VARIABLE check — a `var()` of a theme variable no built stylesheet declares (5.3.0)', () => {
+  // station's DataTable frozen column and DropIndicator, verbatim in shape from its minified bundle.
+  const STATION_JS =
+    'style:Je?{"--cb-frozen-bg":ke%2===1?"color-mix(in srgb, var(--color-muted) 50%, var(--color-card))":"var(--color-card)"}:void 0,' +
+    'function ni({orientation:e,side:t,color:r}){const n=r??"var(--color-accent)"}';
+  const APP = '@import "tailwindcss" source(none);\n@import "./styles-static.css";\n';
+  const THEME_READ_BLOCK = /\n\/\*\n \* Theme variables cursedbelt's components read BY NAME[\s\S]*$/;
+
+  test("station's pre-fix shape — core WITHOUT the theme-read block — is RED on exactly the three it lost", async () => {
+    const core = readBeltSheets().areas.core ?? '';
+    expect(core).toMatch(THEME_READ_BLOCK); // the block exists, so stripping it below is the 5.2.0 core
+    const preFix = (await compileStylesheet(`${APP}${core.replace(THEME_READ_BLOCK, '\n')}\n@import "./theme.css";\n`)).build([]);
+    expect(undefinedThemeVariables({ js: [STATION_JS], css: [preFix] }, readThemeVariables())).toEqual([
+      '--color-accent',
+      '--color-card',
+      '--color-muted',
+    ]);
+  });
+
+  test('the fix: the shipped core makes the app\'s ONE pass declare every theme variable a component reads by name', async () => {
+    const fixed = (await compileStylesheet(`${APP}@import "./styles-areas/core.css";\n@import "./theme.css";\n`)).build([]);
+    expect(undefinedThemeVariables({ js: [STATION_JS], css: [fixed] }, readThemeVariables())).toEqual([]);
+    // …and what core names is what the check scopes to — every one a theme variable.
+    const block = THEME_READ_BLOCK.exec(readBeltSheets().areas.core ?? '')?.[0] ?? '';
+    const named = [...block.matchAll(/var\((--[\w-]+)\)/g)].map((m) => m[1]);
+    const theme = readThemeVariables();
+    expect(named.filter((n) => !theme.has(n as string))).toEqual([]);
+    for (const v of ['--color-card', '--color-muted', '--color-accent', '--text-caption']) expect(named).toContain(v);
+  });
+
+  test('scope: a runtime-set or plain custom property is not a theme variable, and a fallback does not excuse one', () => {
+    const theme = new Set(['--color-card']);
+    const js = ['"var(--offset-right)" "var(--radix-popper-available-height)" "var(--color-card, white)"'];
+    expect(undefinedThemeVariables({ js, css: [''] }, theme)).toEqual(['--color-card']);
+    expect(undefinedThemeVariables({ js, css: [':root{--color-card:var(--card)}'] }, theme)).toEqual([]);
+  });
+
+  test('themeVariablesIn reads every @theme form and skips Tailwind\'s `initial` (unset) keys', () => {
+    const css =
+      '@theme inline { --color-card: var(--card); }\n@theme default { --text-sm: .875rem; ' +
+      '--default-font-feature-settings: --theme(--font-sans--font-feature-settings, initial); --x: initial; }\n:root { --card: #fff; }';
+    expect([...themeVariablesIn(css)].sort()).toEqual(['--color-card', '--text-sm']);
+    expect(readThemeVariables().has('--color-card')).toBe(true); // theme.css
+    expect(readThemeVariables().has('--ease-out')).toBe(true); // tailwindcss/theme.css, resolved
+    expect([...variablesDeclared('@property --tw-x{syntax:"*"}.a{--b:1;color:var(--c)}')].sort()).toEqual(['--b', '--tw-x']);
+  });
+
+  test('the CLI exits 1 on a build that reads an undeclared theme variable, naming it', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'belt-theme-var-check-'));
+    try {
+      mkdirSync(join(dir, 'assets'));
+      writeFileSync(join(dir, 'assets', 'index.js'), `const c="truncate";${STATION_JS}`);
+      writeFileSync(join(dir, 'assets', 'index.css'), '@layer theme{:root{--color-muted:var(--muted);--color-accent:var(--accent)}}@layer utilities{.truncate{overflow:hidden}}');
+      const r = Bun.spawnSync(['bun', join(import.meta.dir, 'checkAreaStyles.ts'), dir], { stdout: 'pipe', stderr: 'pipe' });
+      expect(r.exitCode).toBe(1);
+      expect(r.stderr.toString()).toContain('--color-card');
+      expect(r.stderr.toString()).not.toContain('--color-muted');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/scripts/checkAreaStyles.ts

@@ -29,12 +29,20 @@
  * {@link cascadeFaults}: a base utility after a variant that sets the same property is two sorted
  * Tailwind passes concatenated, and the base wins at every width. Both halves exit 1.
  *
+ * ── …and whether every THEME variable the build reads is defined (5.3.0) ────────────────
+ * {@link undefinedThemeVariables}: a `var(--color-card)` in the built JS or CSS whose `--color-card`
+ * no built stylesheet declares. Tailwind prunes theme variables nothing in its pass names, and a
+ * component that reads one by name from a style prop is invisible to the class check above — the
+ * hole station's frozen DataTable column fell through (F4, 2026-09-23). Exit 1 as well.
+ *
  * Usage, from an app, after its build:
  *   bun node_modules/cursedbelt/scripts/checkAreaStyles.ts dist
- * Exit 0 = complete, 1 = a class is unstyled (listed with its area), 2 = could not measure
+ * Exit 0 = complete, 1 = a class is unstyled (listed with its area), a base utility follows a
+ * variant, or a theme variable read is declared nowhere; 2 = could not measure
  * (no JS or no CSS under the directory — a check that measured nothing has not passed).
  */
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -271,6 +279,81 @@ export function cascadeFaults(cssTexts: readonly string[]): CascadeFault[] {
   return faults;
 }
 
+// ── the THEME VARIABLE check (5.3.0) ───────────────────────────────────────────────────
+
+/**
+ * Every custom property an `@theme` block declares (any `@theme inline`/`static`/… form). These — and
+ * only these — are what Tailwind PRUNES: it emits a theme variable into `:root` only when its pass
+ * sees it used. Every other custom property is written down by a stylesheet unconditionally or set
+ * at runtime (`--radix-*`, sonner's `--offset`, a component's `--cb-frozen-bg`), and an area split
+ * cannot lose it — which is why the check is scoped here and needs no allowlist.
+ */
+export function themeVariablesIn(css: string): Set<string> {
+  const out = new Set<string>();
+  const code = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  for (const m of code.matchAll(/@theme\b[^{]*\{/g)) {
+    let depth = 1;
+    let i = (m.index ?? 0) + m[0].length;
+    const start = i;
+    for (; i < code.length && depth > 0; i++) {
+      if (code[i] === '{') depth++;
+      else if (code[i] === '}') depth--;
+    }
+    for (const d of code.slice(start, i).matchAll(/(?:^|[;{\s])(--[\w-]+)\s*:\s*([^;}]*)/g)) {
+      // `initial` is Tailwind's "unset" — `--default-font-feature-settings: --theme(--font-sans--…, initial)`
+      // is declared only when the app sets the key it names, and preflight reads it with a fallback.
+      // Measured on station's union build: the four `--default-*-settings` were the only noise.
+      if (/^(?:initial|--theme\([^)]*,\s*initial\))$/.test((d[2] as string).trim())) continue;
+      out.add(d[1] as string);
+    }
+  }
+  return out;
+}
+
+/** Every custom property a stylesheet DECLARES: `--x:` in any block, or `@property --x`. */
+export function variablesDeclared(css: string): Set<string> {
+  const out = new Set<string>();
+  const code = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  for (const m of code.matchAll(/(?:^|[;{\s])(--[\w-]+)\s*:/g)) out.add(m[1] as string);
+  for (const m of code.matchAll(/@property\s+(--[\w-]+)/g)) out.add(m[1] as string);
+  return out;
+}
+
+/** Every `var(--x…)` a text reads — a JS bundle's style strings or a stylesheet's values. */
+export function variablesReferenced(text: string): Set<string> {
+  return new Set([...text.matchAll(/var\(\s*(--[\w-]+)/g)].map((m) => m[1] as string));
+}
+
+/**
+ * 🔴 The THEME variables the built JS or CSS reads with `var()` that no built stylesheet declares.
+ * Each one is a value that silently resolves to nothing — `var(--color-card)` as a background is
+ * transparent, not an error. A fallback (`var(--x, red)`) does not excuse one: it renders, but not
+ * as the theme says, which is the same divergence from the union.
+ */
+export function undefinedThemeVariables(input: { js: string[]; css: string[] }, theme: ReadonlySet<string>): string[] {
+  const declared = new Set<string>();
+  for (const css of input.css) for (const name of variablesDeclared(css)) declared.add(name);
+  const read = new Set<string>();
+  for (const text of [...input.js, ...input.css]) for (const name of variablesReferenced(text)) read.add(name);
+  return [...read].filter((name) => theme.has(name) && !declared.has(name)).sort();
+}
+
+/**
+ * The theme a cursedbelt consumer compiles against: this package's `theme.css` and
+ * `styles-static.css`, and Tailwind's own `theme.css` (resolved from this package, which in an app
+ * is the app's copy). 🔴 Throws rather than shrinking the set when Tailwind cannot be found — a
+ * check over half the theme would pass on exactly the variables it cannot see.
+ */
+export function readThemeVariables(src: string | undefined = SRC): Set<string> {
+  if (!src) throw new Error("cursedbelt's src/ is not beside this script — the package is incomplete");
+  const tailwindTheme = createRequire(join(src, '..', 'package.json')).resolve('tailwindcss/theme.css');
+  const out = new Set<string>();
+  for (const file of [join(src, 'theme.css'), join(src, 'styles-static.css'), tailwindTheme]) {
+    for (const name of themeVariablesIn(readFileSync(file, 'utf8'))) out.add(name);
+  }
+  return out;
+}
+
 function filesUnder(dir: string, ext: string, out: string[] = []): string[] {
   for (const entry of readdirSync(dir)) {
     if (entry === 'node_modules') continue;
@@ -290,13 +373,15 @@ export interface AreaCheckResult {
   referenced: number;
   /** {@link cascadeFaults} over the built CSS — base utilities that override a variant. */
   outOfOrder: CascadeFault[];
+  /** {@link undefinedThemeVariables} — theme variables read by `var()` and declared by no built CSS. */
+  undefinedVariables: string[];
 }
 
 /** The measurement, over explicit texts — what the spec drives. */
 export function checkAreaStyles(
   input: { js: string[]; css: string[] },
   belt: { union: string; areas: Record<string, string> },
-): Omit<AreaCheckResult, 'jsFiles' | 'cssFiles' | 'outOfOrder'> {
+): Omit<AreaCheckResult, 'jsFiles' | 'cssFiles' | 'outOfOrder' | 'undefinedVariables'> {
   const union = classesInCss(belt.union);
   const areaOf = new Map<string, string>();
   for (const [area, css] of Object.entries(belt.areas)) {
@@ -332,7 +417,14 @@ export function checkDist(distDir: string): AreaCheckResult {
     readBeltSheets(),
   );
   const cssTexts = cssFiles.map((f) => readFileSync(f, 'utf8'));
-  return { ...result, outOfOrder: cascadeFaults(cssTexts), jsFiles: jsFiles.length, cssFiles: cssFiles.length };
+  const jsTexts = jsFiles.map((f) => readFileSync(f, 'utf8'));
+  return {
+    ...result,
+    outOfOrder: cascadeFaults(cssTexts),
+    undefinedVariables: undefinedThemeVariables({ js: jsTexts, css: cssTexts }, readThemeVariables()),
+    jsFiles: jsFiles.length,
+    cssFiles: cssFiles.length,
+  };
 }
 
 if (import.meta.main) {
@@ -353,11 +445,21 @@ if (import.meta.main) {
     console.error('  Two sorted Tailwind passes were concatenated — cursedbelt ≤ 5.0.x precompiled areas after the app\'s own.');
     console.error('  cursedbelt ≥ 5.1.0 areas are candidates for the app\'s ONE pass: upgrade, and rebuild.');
   }
+  if (result.undefinedVariables.length > 0) {
+    console.error(
+      `✗ ${result.undefinedVariables.length} theme variable(s) the build reads with var() are declared by NO built stylesheet — ` +
+        'each resolves to nothing (a transparent background, an unset size):',
+    );
+    console.error(`    ${result.undefinedVariables.join(' ')}`);
+    console.error('  Tailwind emits a theme variable only when its pass sees it used. cursedbelt ≥ 5.3.0 names every one its');
+    console.error('  components read in styles-areas/core.css — import core, on ≥ 5.3.0. A variable of the app\'s own: name it');
+    console.error('  in a file the app\'s Tailwind pass scans.');
+  }
   if (result.missing.length === 0) {
-    if (result.outOfOrder.length > 0) process.exit(1);
+    if (result.outOfOrder.length > 0 || result.undefinedVariables.length > 0) process.exit(1);
     console.log(
       `✓ belt area styles complete: all ${result.referenced} cursedbelt classes the build references are styled, ` +
-        `and no base utility follows a variant (${result.jsFiles} js, ${result.cssFiles} css).`,
+        `no base utility follows a variant, and every theme variable read is declared (${result.jsFiles} js, ${result.cssFiles} css).`,
     );
     process.exit(0);
   }

package/scripts/generateAreaStyles.ts

@@ -84,7 +84,7 @@
  */
 import { REPO_ROOT, STATIC_STYLESHEET, readStylesheets } from './generateStaticStyles';
 import { classesInCss } from './checkAreaStyles';
-import { UTILITY_INPUT, compileStylesheet } from './generateUtilityStyles';
+import { UTILITY_INPUT, compileStylesheet, themeReadBlock, themeVariablesReadByName } from './generateUtilityStyles';
 import {
 	AREA_DIR,
 	AREAS,
@@ -195,7 +195,7 @@ export const inlineCandidates = async (candidates: readonly string[], area: stri
 	// Tailwind escapes a selector the CSS.escape way; a candidate whose escaped form is in the
 	// output is kept even when unescaping would not round-trip it (a `…` from a doc comment did not).
 	// A `--token` candidate is a THEME VARIABLE the modules read (\`var(--text-sm)\` in a style
-	// prop): Tailwind emits it into \`:root\` only because the scan saw it, so it stays too.
+	// prop). It is kept for the proof below, then dropped from what is written — see the return.
 	const kept = writable.filter(
 		(c) => emitted.has(c) || full.includes(`.${cssEscape(c)}`) || (/^--[\w-]+$/.test(c) && full.includes(`${c}:`)),
 	);
@@ -207,7 +207,11 @@ export const inlineCandidates = async (candidates: readonly string[], area: stri
 				'widen the filter rather than lose it.',
 		);
 	}
-	return kept;
+	// …but a `--token` is not WRITTEN: `@source inline` cannot mark a theme variable (tailwindcss
+	// 4.3.3 adds inline candidates without the `--` branch scanned ones take — measured), so one
+	// here would claim a variable the app never gets. `core` carries every one of them instead,
+	// as a `var()` the app's pass does see (`themeReadBlock`, 5.3.0).
+	return kept.filter((c) => !/^--[\w-]+$/.test(c));
 };
 
 /** `CSS.escape` for a class name — what Tailwind writes into a selector. */
@@ -291,6 +295,10 @@ export const buildAreaStyles = async (): Promise<BuiltArea[]> => {
 		raw.set(area.name, await candidatesIn(closures.get(area.name) as Set<string>));
 	}
 
+	// 🔴 The theme variables components read BY NAME go in core, whole: an area is candidates, and
+	// no candidate can make the app's pass emit one (`themeVariablesReadByName` has the measurement).
+	const themeRead = themeReadBlock(await themeVariablesReadByName());
+
 	const built: BuiltArea[] = [];
 	for (const area of AREAS) {
 		const closure = closures.get(area.name) as Set<string>;
@@ -311,7 +319,7 @@ export const buildAreaStyles = async (): Promise<BuiltArea[]> => {
 		}
 		built.push({
 			name: area.name,
-			css: `${banner(area, inline.length, area.name !== CORE)}${inlineSource(inline)}`,
+			css: `${banner(area, inline.length, area.name !== CORE)}${inlineSource(inline)}${area.name === CORE ? themeRead : ''}`,
 			candidates: inline,
 			modules: [...closure].map((f) => f.replace(`${REPO_ROOT}/`, '')).sort(),
 		});

package/scripts/generateUtilityStyles.ts

@@ -58,6 +58,7 @@
 import { compile } from '@tailwindcss/node';
 import { Scanner } from '@tailwindcss/oxide';
 import { REPO_ROOT, STATIC_STYLESHEET, readStylesheets } from './generateStaticStyles';
+import { allModules, candidatesIn, nonModuleFiles } from './styleAreas';
 
 export { REPO_ROOT };
 
@@ -124,6 +125,78 @@ export const compileStylesheet = (
 	input: string,
 ): ReturnType<typeof compile> => compile(input, { base: STYLES_BASE, onDependency: noDependency });
 
+// ── Theme variables the components read BY NAME (5.3.0) ─────────────────────────────────
+
+/**
+ * The custom property whose value names every theme variable {@link themeVariablesReadByName}
+ * returns. Nothing reads it; it exists so the app's Tailwind pass sees a `var()` of each.
+ */
+export const THEME_READ_PROPERTY = '--cb-theme-read-by-name';
+
+/** Every theme a consumer imports, and nothing scanned — what decides "Tailwind would prune this". */
+const THEME_PROBE_INPUT = '@import "tailwindcss" source(none);\n@import "./styles-static.css";\n@import "./theme.css";\n';
+
+/** A collapse tripwire, not a ratchet: 9 on the day it was set (tailwindcss 4.3.3). */
+export const MIN_THEME_READ_BY_NAME = 4;
+
+const declaresVariable = (css: string, name: string): boolean =>
+	new RegExp(`(^|[\\s;{])${name.replace(/[-]/g, '\\-')}\\s*:`).test(css);
+
+/**
+ * 🔴 The THEME variables cursedbelt's components read by NAME, which Tailwind emits only when
+ * something in the app's own pass names them.
+ *
+ * `DataTable` sets `--cb-frozen-bg` inline to `var(--color-card)`, `DropIndicator` paints with
+ * `var(--color-accent)`, `focusViewer.css` sizes a caption with `var(--text-caption)`. Tailwind v4
+ * emits a theme variable into `:root` only when it is USED — by a utility, by a `var()` in CSS it
+ * compiles, or by a `--name` token its scanner finds in a source file. The union route scans this
+ * package's tree, so it sees the names; an area is class candidates, so an app on the areas had
+ * NO `--color-card` and station's frozen DataTable column went transparent (F4, 2026-09-23,
+ * `reports/2026-09-23/2026-09-23-f4-station-desk-flix-final-adoption.md`).
+ *
+ * `@source inline("--color-card")` does NOT fix it — measured on tailwindcss 4.3.3: inline
+ * candidates skip the `--` branch the scanner's candidates take, so they mark nothing. A `var()`
+ * in CSS the app's pass compiles does, so {@link themeReadBlock} writes one.
+ *
+ * DERIVED, never listed: every `--token` the scanner finds in a module or hand-written `.css` under
+ * `src/react` that a theme-only compile emits when named and omits when not. A new
+ * `var(--color-ring)` in a component joins the list at the next `bun run build`;
+ * `scripts/checkAreaStyles.ts` is what fails an app build when one is still missing anyway.
+ */
+export const themeVariablesReadByName = async (): Promise<string[]> => {
+	const files = [...allModules(), ...nonModuleFiles().filter((f) => f.endsWith('.css'))];
+	const named = [...(await candidatesIn(files))].filter((c) => /^--[\w-]+$/.test(c)).sort();
+	const bare = (await compileStylesheet(THEME_PROBE_INPUT)).build([]);
+	const marked = (await compileStylesheet(THEME_PROBE_INPUT)).build(named);
+	const pruned = named.filter((v) => declaresVariable(marked, v) && !declaresVariable(bare, v));
+	if (pruned.length < MIN_THEME_READ_BY_NAME) {
+		throw new Error(
+			`only ${pruned.length} theme variable(s) read by name were found (floor ${MIN_THEME_READ_BY_NAME}) — ` +
+				`a collapsed scan of ${files.length} file(s), not a design system that stopped reading them.`,
+		);
+	}
+	return pruned;
+};
+
+/**
+ * The declaration that makes an app's Tailwind pass emit `vars`: one custom property on `:root`
+ * whose value `var()`s each of them. The VALUES stay the theme's, so an app that re-themes a
+ * variable keeps its own; this names them and defines nothing.
+ */
+export const themeReadBlock = (vars: readonly string[]): string => `
+/*
+ * Theme variables cursedbelt's components read BY NAME (\`var(--color-card)\` in a style prop).
+ * Tailwind emits a theme variable only when the app's own pass sees it used, and a \`var()\` here is
+ * that use — \`@source inline\` cannot mark one. ${vars.length} variable(s), derived by
+ * scripts/generateUtilityStyles.ts → themeVariablesReadByName(). Nothing reads this property.
+ */
+@layer theme {
+  :root, :host {
+    ${THEME_READ_PROPERTY}: ${vars.map((v) => `var(${v})`).join(' ')};
+  }
+}
+`;
+
 /** The banner the artifact carries, so a reader never mistakes it for a source file. */
 export const BANNER = `/*
  * cursedbelt component utilities — GENERATED BUILD ARTIFACT. Never hand-edit.
@@ -177,7 +250,9 @@ export const buildUtilityStyles = async (): Promise<{ css: string; candidates: s
 				`${STYLES_BASE}/react exists and is not excluded by a .gitignore.`,
 		);
 	}
-	return { css: `${BANNER}${compiled.build(candidates)}`, candidates };
+	// The theme variables components read by name ride along: the pair's consumer scans nothing
+	// of this package either, so it has the areas' hole exactly (see themeVariablesReadByName).
+	return { css: `${BANNER}${compiled.build(candidates)}${themeReadBlock(await themeVariablesReadByName())}`, candidates };
 };
 
 /** The artifact's expected contents and what is on disk right now. */

package/src/styles-areas/core.css

@@ -144,3 +144,15 @@
 @source inline("w-[var(--control-h-lg)] w-[var(--control-h-md)] w-[var(--control-h-sm)] w-auto w-full w-px white");
 @source inline("whitespace-nowrap whitespace-pre-wrap wrap wrap-break-word z z-10 z-20 z-30 z-40 z-50");
 @source inline("z-[var(--z-popover)]");
+
+/*
+ * Theme variables cursedbelt's components read BY NAME (`var(--color-card)` in a style prop).
+ * Tailwind emits a theme variable only when the app's own pass sees it used, and a `var()` here is
+ * that use — `@source inline` cannot mark one. 9 variable(s), derived by
+ * scripts/generateUtilityStyles.ts → themeVariablesReadByName(). Nothing reads this property.
+ */
+@layer theme {
+  :root, :host {
+    --cb-theme-read-by-name: var(--color-accent) var(--color-border) var(--color-card) var(--color-muted) var(--color-popover) var(--duration-base) var(--ease-out) var(--text-caption) var(--text-sm);
+  }
+}

package/src/styles-areas/spreadsheet.css

@@ -18,10 +18,10 @@
  * after an app's responsive variant (task 2124). An app that imports every area gets exactly
  * what `cursedbelt/styles-utilities.css` emits — proved rule by rule in
  * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
- * 4 candidate(s).
+ * 2 candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are
  * import closures rather than a hand-written list, is scripts/styleAreas.ts.
  */
-@source inline("--font-sans --text-sm col collapse");
+@source inline("col collapse");

package/src/styles-areas/workbook-viewer.css

@@ -18,10 +18,10 @@
  * after an app's responsive variant (task 2124). An app that imports every area gets exactly
  * what `cursedbelt/styles-utilities.css` emits — proved rule by rule in
  * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
- * 7 candidate(s).
+ * 5 candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are
  * import closures rather than a hand-written list, is scripts/styleAreas.ts.
  */
-@source inline("--font-sans --text-sm col collapse min-w-16 w w-48");
+@source inline("col collapse min-w-16 w w-48");

package/src/styles-utilities.css

@@ -4969,3 +4969,15 @@
     }
   }
 }
+
+/*
+ * Theme variables cursedbelt's components read BY NAME (`var(--color-card)` in a style prop).
+ * Tailwind emits a theme variable only when the app's own pass sees it used, and a `var()` here is
+ * that use — `@source inline` cannot mark one. 9 variable(s), derived by
+ * scripts/generateUtilityStyles.ts → themeVariablesReadByName(). Nothing reads this property.
+ */
+@layer theme {
+  :root, :host {
+    --cb-theme-read-by-name: var(--color-accent) var(--color-border) var(--color-card) var(--color-muted) var(--color-popover) var(--duration-base) var(--ease-out) var(--text-caption) var(--text-sm);
+  }
+}