feat(design-system): establish Phase 5A.1a foundations

[ericsocrat]

Purpose

Finish Phase 5A.1a, the first of exactly two Design System V2 foundation PRs, while keeping every production route on the byte-compatible V1 visual contract. Living Label and the current mark are provisional working hypotheses; Phase 5A.2 must challenge them before any production redesign begins.

What changes

• Reconciles the deterministic V2 token manifest/generator, scoped CSS and typed artifacts with the canonical motion system: 0/120/180/240/360/500 ms, explicit recipes, and 500 ms reserved for the landing shared-label narrative.
• Preserves the exact V1 light/dark compatibility layer; root production scope remains data-design-system="v1".
• Expands deterministic contrast contracts to 46 named text/UI pairs, including the complete evidence/domain matrix.
• Rebuilds /dev/components as a doubly gated, localized EN/PL/DE foundation catalog using honest V2 specimens rather than rendering V1 components inside V2 scope.
• Defines six theme/locale/accessibility contexts at 390/768/1440: 72 scene PNGs plus 18 contact sheets, exactly 90 candidate PNGs.
• Adds fail-closed candidate provenance and verification: actual checkout SHA/tree, PR-head SHA, worktree classification/digest, exact path matrix, file hashes/counts, symlink/extra-file rejection, and sanitized failure diagnostics.
• Expands the live inventory to 345 governed modules over the complete 450-module production TypeScript graph, with transitive route consumers, runtime boundaries, redesign targets, dispositions, migration/removal gates, V1/V2 status, classified debt, and zero forbidden runtime-boundary imports.
• Keeps visual-debt ratchets shrink-only and prevents regeneration from overwriting a stricter committed baseline.
• Wires verified candidate output into guarded Quality Gate and Nightly lifecycles; candidate upload remains contingent on browser success, safety assertions, fixture cleanup, and no-backup local-runtime shutdown.
• Fixes a PR Gate timeout mismatch exposed during closeout: the Unit Tests job now has eight minutes of total headroom while the Vitest step remains independently fail-closed at six minutes; a static workflow contract locks that relationship.

Future contract documentation only

• Adds the planned, non-production Phase 5A.2 Experience Architecture / Golden Reference Gate.
• Requires up to three original visual directions and three identity options, six interactive reference experiences, static/motion/reduced-motion evidence, content/localization review, two independent fresh-context reviews, a 100-point rubric (88 minimum plus vetoes), and Eric's explicit selection.
• Production redesign now begins in Phase 5A.3+. Every active user-facing route must ultimately migrate to V2 or be explicitly removed; indefinite visual deferral cannot satisfy completion.
• This PR does not create Golden References, choose final branding/type/imagery, redesign production routes, or authorize Phase 5A.1b.

Compatibility and non-scope

• No production route/shell/navigation redesign and no immutable Phase 5A.0d baseline replacement.
• No route-policy, API, database, Supabase migration, PWA/cache, scanner, OG asset, logo, font, Next/Vercel configuration, or hosted-service change.
• No authored dependency or lockfile delta relative to current main; the branch is synchronized with base e8086060b33fe4132bc3c67d7613913e6493dc33.
• The catalog remains on the existing protected route policy and runs through the guarded local-authenticated harness. Its specimens are deterministic and data-independent; hosted Supabase is never a fallback.
• Manrope remains candidate-not-adopted; the system stack remains active and serif adoption remains deferred to the later human art-direction gate.

Authored vs generated artifacts

• Authored source: token manifest/generator, foundation contracts, catalog scenes/copy/styles/gate, capture contract, inventory generator, browser evidence, workflow gates, and governing documentation.
• Generated source-controlled artifacts: frontend/src/design-system/generated/tokens.css, frontend/src/design-system/generated/tokens.ts, docs/assets/design-tokens.json, and docs/phase5/live-route-component-inventory.json.
• Live inventory JSON SHA-256: 014FF7543197D7B5D455E9B00B2221ED53ADD9FFDCA621BDC7DAEDAA2A32B28F.

Local verification

• npm run design-system:check — 7 files / 46 tests passed; generated token artifacts current.
• Complete Vitest suite — 384 files passed, 1 skipped; 6,481 tests passed, 19 skipped.
• npm run type-check, full source lint, explicit tooling/E2E lint, production build, and git diff --check passed.
• The focused workflow contract passed 61/61 after the timeout correction.
• Independent code, CI/provenance, React/Next, security, accessibility, visual, and governing-document reviews found no remaining P0–P2 issue.
• No hosted fallback or safety relaxation was used. Exact-head Linux CI is the authoritative browser/candidate proof.

Accessibility, performance, and visual review

• Whole-page WCAG 2.2 Axe runs with no exclusions; catalog checks also cover document/scene overflow, focus/skip link, theme/system-dark resolution, forced colors, reduced motion, localization, console, and hydration health.
• Minimum deterministic normal-text contrast is 4.716:1 in light and dark; minimum meaningful UI/focus ratios are 3.432:1 light and 3.710:1 dark.
• The first candidate review found forced-color label loss and a compact PL/DE locked-value defect. Both were corrected and re-rendered; every final PNG is byte-identical across the three subsequent exact-head artifacts.
• No runtime dependency or production V2 adoption is introduced. Immutable visual and route-JS gates pass without a production baseline change or threshold regression.
• Lighthouse passes with zero blocking/instability failures. Directional debt remains: median mobile LCP is above 2.5 s on the five measured mobile routes, and authenticated mobile product-detail TBT is 218 ms; desktop lab evidence is green. Lab evidence cannot claim INP or field CWV.
• The 90 PNGs are review candidates, not baselines and not Golden References.

Exact-head acceptance evidence

Final PR head: d23342829931da7815b7121128c8fdaada794d55
Reviewed merge ref: 34a2e315092ec7283f22a5a77b90dee0785beacc
Reviewed tree: 0296dace649b9b3efbb1617d50ad2951de12ad46

• PR Gate 31365081674: passed. The corrected unit job completed all 6,481 tests, timing summary, and artifact upload; timing artifact 9053938535.
• CodeQL 31365081766 and GHAS check 93381875230: passed; zero open alerts.
• Quality Gate 31365081769: passed all public/local lifecycles and 18/18 catalog cases. Candidate artifact 9054003661, ZIP SHA-256 d611ba538c39a081d36f61ea9f7ca158d266eeaa63ebc830c609abc0decde009, manifest SHA-256 27c9662f7fdd8e6f6509279d639fd5b8758fef7238c013290c9c4cf5a65251ff. All 72 scene PNGs and 18 contact sheets were independently verified.
• Immutable visuals 31365081819: passed 5 public + 3 authenticated comparisons; no baseline diff. Manifest checksum 12a00dc37191191b788964d1c599d103aa0fedb1c15fa8cc36ad80d746953716.
• Route JS 31365081706: passed all five fail-if-either guards. Artifact 9054042997, SHA-256 f667a99923887f783e6e18c81ec99f44306cf6aa2fa1fe309d1eb16589122fe2.
• Lighthouse 31365081680, attempt 1: passed 50 measurements, zero blocking failures, and zero instability failures. Artifact 9054220812, SHA-256 dada00e00b7fa5a7581eeb8ab5bc36715f7aaa0e4448007a2c7f0d66b6aaa462; report checksum 9a02c57f60f21b58554e3bfa02ff600a6346c396a6273a02e5afceac558e4829.
• Main Gate 31365492903: sole exact-head dispatch, passed. Sonar job 93384044051 analyzed the exact revision: reliability/security/maintainability A, 91.2% new coverage, 1.4% new duplication, and 100% hotspot review.
• Dependency audit, license compliance, repository hygiene, title checks, Vercel status, fixture teardown, safety assertions, and no-backup local-volume cleanup all passed.

Pending human acceptance — keep draft

• Eric must inspect the SHA-bound contact sheets and explicitly approve or reject the Phase 5A.1a foundation candidates for hierarchy, truthfulness, contrast, responsive reflow, PL/DE expansion, reduced/forced-color behavior, and brand fit.
• This approval is for the direction-resilient foundation only. It does not finalize Living Label, the mark, typography, imagery, Golden References, or production route design.
• Keep this PR draft and do not begin Phase 5A.1b until this PR is approved, merged, the resulting main SHA is verified, and Eric explicitly authorizes the next phase.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
tryvit	Ready	Preview	Aug 10, 2026 7:16am

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d233428299

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Count class tokens inside JSX expressions

The ratchet ignores the common className={...} form because the regex requires a quote or backtick immediately after =. Existing usages such as ProductScoreHero.tsx's className={`card ${band.bgColor} border-0`} are therefore absent from the committed inventory, and future card or input-field debt written this way can increase without failing assertShrinkOnlyVisualDebt, undermining the shrink-only gate.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Give the Subtle chip its own tone

In every locale the seventh chip label is “Subtle,” but its tone repeats neutral, and the stylesheet has no separate subtle selector. Consequently all 18 foundation capture cases present Neutral and Subtle with identical styling, so the 90-image candidate package cannot truthfully support the pending human review of that semantic role; either map it to a distinct subtle treatment or remove the duplicate specimen.

Useful? React with 👍 / 👎.