test: cover the CSS custom-property resolution contract (tests/css-variables.test.mjs)

[hivecommons-hive]

Test Improvement

Adds tests/css-variables.test.mjs — the only file this PR touches. No
production change, no new dependency.

Nothing in the test suite reads a CSS custom-property name. An unresolved
var(--x) is not an error anywhere in the pipeline: the browser drops the
declaration, the property falls back to its initial/inherited value,
docusaurus build succeeds, and the element renders unstyled. A typo in a
token name ships green.

Under src/ today: 10 stylesheets, 15 declared custom properties, 15 var()
references, 1 property declared from a JS inline style, 0 references carrying
a fallback. All of it currently resolves — this is a guard for a clean
invariant, not a bug report.

What it asserts

1. Non-vacuity — stylesheets, declarations and references are all
   non-empty, so a regression in the extractors cannot silently pass the rest.
2. Forward — every var(--x) resolves to a CSS declaration under src/,
   a JS inline-style declaration, or the Infima/Docusaurus vendor namespace.
3. Bounded allowlist — the --ifm-* / --docusaurus-* exemption may
   never swallow a project-owned --cncf-* token.
4. Reverse — every declared --cncf-* token is read by at least one
   var() (orphan detection).
5. Theme parity — every --cncf-* token themed on :root is redeclared
   under [data-theme='dark'], so a new brand token cannot be added
   light-only and silently inherit the wrong value in dark mode.

Two repo-specific details the scan handles, both of which break a naive
implementation:

• --bar-width is declared in JavaScript, not CSS —
  src/components/MetricsDashboard/index.js:52 sets it as a style-object key
  and MetricsDashboard/styles.module.css:16 reads it. A stylesheet-only scan
  reports a false positive.
• Assertion 5 matches :root by substring because the selector in
  src/css/custom.css carries a :not(#\#):not(#\#) specificity hack.

Verification

Mutation-tested; each mutation is caught by the intended assertion, and no
assertion is redundant:

mutation	caught by
typo var(--cncf-button-text) -> --cncf-button-txt	2, 3, 4
delete --cncf-button-text from the [data-theme='dark'] block	5
inline a var(--cncf-button-background-hover) to its hex literal	4
rename the '--bar-width' inline-style key in MetricsDashboard/index.js	2, 3

npm run test:unit -> 60 tests, 60 pass (55 before this PR).
prettier --check clean.

Scope and disjointness

Claimed ground: tests/css-variables.test.mjs only; the invariant is CSS
custom-property (var(--x)) name resolution across src/**/*.css plus
inline-style declarations in src/**/*.{js,jsx,ts,tsx}.

No open PR reads CSS custom properties. #289 covers /img asset paths, #343
covers JSX href/src hygiene, #229 and #268 cover React modules, #253 /
#260 / #287 cover data/*.json, and #185 / #197 / #208 / #214 / #216 / #221 /
#231 cover scripts/. Issues #317 (url() refs against static/fonts/) and
#319 (*.module.css class names) are adjacent but neither is a custom
property and neither has a PR; their proposed test files are
tests/css-assets.test.mjs and tests/css-modules.test.mjs, so there is no
file collision either.

Related Issue

Closes #346 — merging this lands the sole deliverable that issue tracks
(tests/css-variables.test.mjs), leaving nothing for it to track.

---

Filed by quality agent (hold-gated mode). Human review required.

— hive: agent=quality backend=copilot model=claude-opus-5

[hivecommons-hive]

Important

Held for human review by the hive's ACMM level gate.

This PR was opened by the "quality" agent while Hive policy required a human checkpoint for that agent. Non-outreach agents are held at ACMM L3–L5; the outreach agent is always held because it publishes project-facing communication.

Hive will automatically remove the hold label once current policy no longer requires a level hold for "quality". If this is an outreach PR, a human must review it and remove the label.