CORE-2720: Add a global CSS token file generated from the theme

[OpenStaxClaude]

Jira: CORE-2720

2 of 3 — split of #143. main → #149 → #150 → #143.

What this is

The design decision: one place a theme value is written, referenced from CSS, with a test that fails if the two disagree. The sweep of the already-migrated stylesheets onto it is #143.

src/theme/theme.css holds a single :root block. Color tokens are the kebab-case palette key (palette.neutralLighter → --ox-color-neutral-lighter), plus --ox-color-link, --ox-color-link-hover, --ox-z-index-* and --ox-padding-navbar-*. The --ox- prefix avoids collisions with a consuming app's own variables.

The file is generated, not hand-written. themeCss.ts owns the projection; npm run generate:theme-css writes it. build.bash runs it as its first step, before either tsc pass and before the rsync, and publish.bash inherits that via build:clean, so a published package cannot ship a stale file. It is committed as well as generated because jest and ladle read src/ directly and CI runs lint/test rather than build. Deliberately not hooked into pretest — regenerating before the suite would make the freshness check pass vacuously.

Adds the four button variant colors to the palette. theme/buttons.ts had been holding them as bare string literals with nothing recording that they are hover/active variants of orange and darkGray. Purely additive to the published palette.

Enforcement

tokens.spec.ts, on top of #149's engine, checks four things:

1. The committed theme.css is exactly what the generator produces. One equality, so a missing token, an orphan token and a stale value all fail the same way.
2. No component stylesheet writes a color literal that duplicates a theme value.
3. No component stylesheet introduces a color that is neither a theme value nor on the KNOWN_OFF_PALETTE allowlist, each entry carrying a reason. The README says what the check covers, what it excludes on purpose (a bare name outside a color context — animation-name: red is not a color) and the one known gap (escaped property and function names, CORE-2885).
4. No component stylesheet reads an --ox-* token that does not exist — a typo would otherwise fall through to its fallback silently. Matched case-insensitively, since CSS function names are (VAR(--ox-color-palee) is a real reference); the lookup itself stays case-sensitive, since property names are, so var(--OX-color-pale) is reported too. The name runs to the end of the CSS identifier, non-ASCII included — [\w-]+ truncated var(--ox-color-redé) to a token that exists and passed it. Escaped spellings still read literally and are deferred to CORE-2885 with the rest of the escape decoding; that one errs toward a CI failure on valid CSS rather than a silent pass.

The one wrinkle in the split

Check 2 cannot pass yet: 16 stylesheets migrated before the tokens existed still carry hand-copied literals, and they are not swept until #143. PENDING_SWEEP names them.

The list is asserted to be exactly the failing set, so it cannot rot in either direction — dropping a name without sweeping the file fails, and sweeping a file without dropping its name fails too. Verified both ways. It reaches empty in #143 and is deleted there along with the assertion. The README says the same, so nobody adds to it.

This is the cost of the split and the only thing in these three PRs that would not exist without it. If you'd rather not carry it, the alternative is landing #150 and #143 together.

No CSS @import, and how the file gets loaded

build.bash rsyncs CSS 1:1 with no bundler, so an @import would depend on each consumer's resolver, and a stylesheet does not drag theme.css in by itself. The component that imports the stylesheet imports the token file alongside it.

Nothing does that yet on this branch, correctly: no stylesheet reads a token until #143 sweeps one, so the tokens are defined and unused. Rather than write the imports early, the rule is enforced — tokens.spec.ts fails when a stylesheet reads a token and the module importing it does not import theme.css. Verified it fires by making Loader.css read one. The per-file assertion is vacuous on this branch by construction and says so; the helper under it is tested on synthetic input.

Imports are read from the module's ImportDeclaration nodes via the TypeScript parser, not matched in the source. A regex also sees // import '../theme/theme.css';, which fails the wrong way round for this check — it reports the token file present when it is absent, so deleting a real import beside a commented-out one would pass.

The export map also carried a real bug, found in review: "./*" rewrote every subpath to *.js, so @openstax/ui-components/theme/theme.css resolved to theme.css.js and threw. A ./*.css pattern now sits ahead of it, verified with node's own resolver against a built dist — dist/cjs under require, dist/esm under import, JS subpaths unaffected. That would have outlived the split: without it a consumer could not load the tokens directly even after #143.

Verification

• 726 tests / 41 suites / 114 snapshots pass; typecheck, lint and build:clean clean.
• Both dist trees carry the token file, and it resolves as a package subpath from both.
• The theme-side files are byte-identical to the reviewed CORE-2720: Sweep the migrated CSS onto the theme tokens #143 head apart from the PENDING_SWEEP scaffolding.

Provenance

Roy's cbf780d (rename the button variant colors) is preserved as his own commit, theme side. The Button.css/DropdownMenu.css half moves to #143 — it edits token references inside already-swept CSS, so it has nothing to apply to until that lands. theme.css is regenerated there rather than hand-edited.

Earlier review rounds on #143 (build integration, the raw-data-file alternative, the as string casts, the dead tokenised flag, parseHex grammar, the property-context gate) are all carried across — see the CORE-2720 ticket for the full record.

🤖 Generated with Claude Code

[Copilot]

🔵 Needs a closer look

The unknown-token check can overlook valid non-ASCII custom-property names by truncating them to existing tokens.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

src/theme/tokens.spec.ts:183

• This character class truncates valid non-ASCII custom-property names. For example, var(--ox-color-redé) is captured as --ox-color-red; because that token exists, the undefined --ox-color-redé reference passes the check. Capture the full CSS identifier so the lookup sees the actual referenced name, and add this as a regression case.

• Files reviewed: 9/9 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[RoyEJohnson]

See Copilot's latest comment. It may fall under 'do it later with the tokenizer'.

[OpenStaxClaude]

@RoyEJohnson — I split it, and the two halves fall on opposite sides of your line.

Fixed here (1e9e3646), because it is a boundary rather than a spelling. The name was matched with [\w-]+, which stops at the first character outside ASCII; CSS name code points include everything at U+0080 and above, so var(--ox-color-redé) was looked up as --ox-color-red, found, and passed. An undefined reference reported as fine — the one answer this check must never give, sitting in the thing that is meant to be the safety net. One character class, and regression cases for a combining accent, an astral character (surrogate pair), a non-ASCII character mid-name, and the prefix it used to truncate to, which still passes. The first three return [] against the old class; checked before committing.

Deferred to CORE-2885, exactly as you suggested: escaped spellings. var(--ox-color-r\65 d) is var(--ox-color-red) to a browser, and this reads it as --ox-color-r and reports it undefined. That needs the same escape decoding as findings 1–3 on that ticket, so patching it here would be the fifth version of the same mistake. Added it as a sixth finding with an acceptance criterion, flagged as one of the claims to put through the browser harness first rather than trust.

It also errs in the safer direction — a false positive fails CI on valid CSS, which gets noticed, where the non-ASCII one passed silently. That asymmetry is why I did not hold both for the ticket.

726 tests / 41 suites / 114 snapshots pass; typecheck, lint and build:clean clean.

[Copilot]

🟡 Changes recommended

Two moderate review findings in src/theme/tokens.spec.ts remain unresolved.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (3)

src/theme/tokens.spec.ts:132

• The allowlist is checked before the theme lookup, so promoting an allowlisted value into palette.ts leaves every existing #ccc/#ddd literal silently exempt: it never reaches duplicates and PENDING_SWEEP cannot require the migration. Since the README explicitly supports moving an allowlisted color into the palette, only honor this exemption when the channels are still absent from themeValues (and add a regression case for that transition).

    if (KNOWN_OFF_PALETTE.has(key)) { continue; }

src/theme/tokens.spec.ts:195

• The regex is not bounded to the var function name, so it also matches the var( suffix of a different function such as myvar(--ox-color-palee). That is a valid token stream in a custom-property value and does not read a CSS variable, but this check reports an unknown token. Add an identifier boundary (and a regression case); apply the same boundary to readsThemeToken below.

    [...stripNoise(css).matchAll(/var\(\s*(--ox-(?:[\w-]|[^\x00-\x7f])+)/gi)]

src/theme/tokens.spec.ts:507

• This has the same unbounded var( match: myvar(--ox-color-pale) makes the import rule believe the stylesheet reads a theme token even though it does not. A component using such a custom-property value would be forced to import theme.css unnecessarily; use the same CSS identifier boundary as the token-reference scan.

const readsThemeToken = (css: string) => /var\(\s*--ox-/i.test(stripNoise(css));

• Files reviewed: 9/9 changed files
• Comments generated: 1
• Review effort level: Lite