How-to

Run the Web validation gate

Use this procedure after a Web change is implemented. A passing build alone is insufficient: source contracts, browsers, accessibility, and committed visual baselines are separate parts of the gate.

Run deterministic non-browser checks

Nushell · non-browser gate

cd web
^npm run tokens:check
^npm run typecheck
^npm run test:unit
^npm run build
^npm run check:build

These checks verify generated design-token adapters, TypeScript, architecture/content contracts, static output, discovery metadata, and bundle budgets.

Run browser and accessibility checks

Nushell · browser gate

^npm run test:browser

The configured matrix covers Chromium desktop/mobile, Firefox, and WebKit, including navigation behaviour, route integrity, no-overflow checks, keyboard interaction, and blocking axe findings.

On RHEL, run the browser step inside the Playwright image matching the lockfile version. For the current Web package that means Playwright 1.62.1 and the corresponding mcr.microsoft.com/playwright:v1.62.1-noble image rather than host-installed Ubuntu browser binaries.

Verify visual baselines

Nushell · visual gate

^npm run test:visual

Do not update snapshots merely to make CI green. Generate new baselines only when the visual change is intentional, inspect the resulting images or GitHub Actions artefact, and commit the reviewed corpus as an explicit change.

Treat CI as evidence, not as the whole review

A pull request is ready only when the required checks pass on its current head, expected visual artefacts exist, stale or cancelled runs have been diagnosed, and the public claims still match implementation maturity. See Review and release gates for the full contract.