CORE-2731: Generate a global CSS token file from the theme

[OpenStaxClaude]

Jira: CORE-2731 (sub-task of CORE-1685)
Follows ui-components#143 (CORE-2720), which did the same thing there.

Why

The styled-components migration has been copying theme values into CSS by hand. Measured on main at f00f987:

• 102 CSS files hold 226 color literals; 154 duplicate a value that already exists in theme.ts — #424242 34× across 26 files, #fff 26× across 16, #d5d5d5 18×. (The audit added here finds 184, because it also catches bare white keywords and colors inside shorthands that a hex grep misses.)
• A token file already existed and was losing: Phase 0 hand-wrote a 21-token :root block into src/index.css, referenced 63 times against those 154 literals. Colors only — no z-index or padding tokens — and nothing kept it in step with theme.ts.
• The theme was not the only source of truth, and one of the others was already drifting. Links.constants.ts declares linkColor = '#027EB5' and linkHover = '#0064A0' — the two most common "off-theme" colors in the CSS at 17 occurrences each, every CSS copy lowercase against the uppercase TS original. content/components/constants.ts was a third (mainContentBackground = '#fff').

What this does

Splits the theme data out. theme.ts imports css from styled-components/macro for the breakpoints.mobile() helpers, so a build-time generator importing it would drag styled-components into the build. The pure data — color, padding, zIndex, the breakpoint sizes — moves to src/app/themeData.ts with no imports at all. theme.ts spreads it back into its default export, so every theme.color.x path and all ~200 consumers are untouched. This is a step the epic needs regardless; theme.ts is one of the 26 files still on styled-components.

Generates the token file. src/app/themeCss.ts owns the projection; src/app/theme.css is generated from it, never hand-edited. 80 tokens: --color-* (kebab-case of the JS path, so all 21 existing names are preserved exactly), --z-index-* (the 15 computed keys), --padding-page-*. Hex is lowercased on the way out, so a token's value has one spelling and color-hex-case is satisfied without touching the published JS values.

script/generate-theme-css.ts runs via node ./script/entry generate-theme-css — the repo's existing TS-script idiom, so unlike ui-components no tsc-into-a-temp-dir dance was needed. Wired into build and prestart. Deliberately not into build:css: pretest runs build:css, so generating there would regenerate the file immediately before the suite and make the freshness check pass vacuously.

Absorbs the other sources. Link colors live in themeData.ts and are re-exported by Links.constants.ts, so its 8 JS importers are unchanged but there is now one source and three tokens. mainContentBackground points at the theme's white.

Enforces it. src/app/theme.spec.ts:

1. the committed theme.css equals the generator's output — one equality, so a missing token, an orphan token and a stale value all fail the same way;
2. every color token resolves to real channels (guards the index the audit is built on);
3. no stylesheet duplicates a theme color, beyond a locked baseline;
4. no stylesheet introduces an unrecognised color, beyond that baseline;
5. no stylesheet reads a --color-*/--z-index-*/--padding-* token that does not exist;
6. no breakpoint sits within 1em of a theme breakpoint without being one.

(5) found two real cases: BookBanner.css read --z-index-big and --z-index-mini, component-local variables sitting in the global family's namespace. They are derived from --z-index-navbar, so CSS now computes them with calc() and the two JS bindings are gone.

(6) is the cheap mitigation for the breakpoint gap. @media (min-width: var(--x)) is not valid CSS, so 75em stays duplicated 144 times. Banning component-specific breakpoints would be wrong — Footer legitimately uses 37.5em, 60.1em and 90em — so instead it catches the failure the duplication actually causes: a value meant to be a theme breakpoint but mistyped as 74em, which silently stops matching.

The baseline is a ratchet, not a skip. Checks (3) and (4) are locked to src/app/theme.baseline.json — 184 duplicated literals and 37 unrecognised colors as of this commit. So enforcement starts now: a new hardcoded #424242 fails CI today, and the list can only shrink as the sweep PRs land. yarn generate:theme-baseline regenerates it and prints the counts, which should only go down. This is why the sweep is not in this PR: it is ~50 files of values-only edits and wants reviewing against screenshots separately.

Verification

• src/test/cssColors.ts parses declarations rather than grepping for hex, so rgba(), hsl(), named colors in shorthands and colors in gradient stops are all covered. It descends into var()/color-mix()/gradients, passes a translucent color whose opaque channels are a theme value (rgba(0, 0, 0, 0.2) is black at 20% and has no token form) while still refusing a new hue through rgba(), and fails rather than passing silently on anything it cannot resolve to channels. 96 tests cover exactly this — without them "CI enforces the palette" would be an assertion rather than a tested guarantee. There is also a guard that the file walk found something, so the suite cannot pass vacuously.
• The audit is shared between the spec and the baseline generator, so the baseline cannot be generated by different logic than it is checked with.
• Round trip verified: changing palette.black without regenerating fails the spec; regenerating passes it.
• No visual change is intended in this PR — the only rendered-output changes are BookBanner's two calc() z-indexes, which resolve to the same 69 and 68 as before.

Status

Ready for review. CI green. The sweep follows in separate PRs under the same ticket.

Not yet done: the screenshot suite. No visual change is intended and the only rendered-output change is BookBanner's two calc() z-indexes, which I have now verified in Chrome resolve to the same 69 and 68 as the bindings they replaced — but that is reasoning plus a unit check, not a pixel diff, so the suite is still worth running before merge.

Review rounds

Copilot found nine issues across four rounds; all are fixed. The ones worth knowing about:

• The audit mis-keyed percentage channels. rgb(50%, 50%, 50%) scaled by the decimal 2.55 keys as 127,127,127 while #808080 keys as 128,128,128, so the two spellings of one grey never matched.
• #ggg parsed as a color. Only the expanded length was checked, not the digits, so a malformed theme value would have passed the "every token resolves" guard while generating invalid CSS.
• Named colors were read outside color positions, so animation-name: red and font-family: black were palette violations. Bare identifiers are now gated on the property; hex and the color functions stay in scope everywhere.
• Two holes in the baseline ratchet. Occurrences were keyed by file plus literal, so removing one #fff and adding another elsewhere in the same file left the sorted baseline unchanged. They are now keyed by the declaration — selector, at-rule and property. Then a second hole in that fix: stripNoise blanked string contents before the context was recorded, so [data-loading="true"] and [data-loading="false"] collapsed to one identity. Blanking is now length-preserving and context is sliced from a copy that keeps strings.

🤖 Generated with Claude Code

[Copilot]

🔵 Needs a closer look

It introduces new build-time generation plus repo-wide stylesheet enforcement logic that can have broad CI/runtime impact and merits final human verification before merge.

Review details

• Files reviewed: 24/24 changed files
• Comments generated: 0 new
• Review effort level: Lite