ADR-0002: Phase 11 Foundation Architecture

Status: Accepted for implementation; browser evidence pending
Date: 2026-06-25
Scope: Design tokens, theme, localization, routing, metadata, application shell, and global states
Supersedes: No Phase 9 or Phase 10 product decision

Context

Phase 11 must extend the Phase 10 repository without mutating the immutable Phase 9 contract, weakening CSP, inventing unresolved destinations, or creating a second styling, routing, or localization authority.

Decisions

Token pipeline

Keep Phase 9 raw and semantic token files unchanged. Add src/styles/component-tokens.css as an additive component-facing layer. Application CSS may not consume raw palette tokens or literal colors.

Theme persistence and bootstrap

Keep hpc-theme as the server-readable canonical preference and hpc.theme.preference as a client continuity copy. Preference remains distinct from resolved theme. The nonce-bearing head bootstrap resolves before paint. A CSS media-query fallback gives readable system-dark behavior when JavaScript is delayed or unavailable. Same-window theme selectors synchronize through a custom event; cross-tab selectors synchronize through the storage event.

Locale routing and negotiation

The route path remains the active locale authority. Root negotiation uses the locale cookie, then Accept-Language, then English. Locale switching resolves the current semantic route ID, preserves only allowlisted campaign parameters, and preserves only hashes approved for that route.

Translation loading

Server components load typed catalogs through getMessages. Interaction-only global states use a small client shell-catalog map. Missing-key and type parity remain CI failures. No runtime fallback silently substitutes English for French or Arabic.

Formatting

Centralized Intl formatters require an explicit locale and, where relevant, time zone or currency. Language never implies market, country, currency, or jurisdiction. Gregorian dates and Latin digits remain the inherited baseline until product research approves alternatives.

Font loading

Use the pinned local Fontsource variable packages for Inter and Noto Sans Arabic. Arabic receives its own line-height and does not inherit forced Latin metrics.

Application shell composition

The locale layout owns document attributes, theme bootstrap, skip navigation, header, footer, and theme controller. The header is server-rendered except for route-aware navigation, selectors, and the native modal mobile drawer. The drawer uses <dialog> for modal semantics, Escape behavior, background interaction blocking, and focus containment, with explicit focus return.

Unresolved destinations

Authoritative route-manifest paths are generated for login and legal routes, but those pages render localized noindex pending shells. Demo, contact, and login actions do not receive invented production integrations. They remain visibly disabled or lead to an explicit pending route.

Metadata

A single server helper generates canonical URLs, reciprocal hreflang, Open Graph locale data, social summary metadata, and release-safe robots behavior from route IDs. No structured organization, review, rating, pricing, or contact data is emitted.

CSS organization

tokens.css: immutable Phase 9 tokens
component-tokens.css: Phase 11 component-facing roles
globals.css: reset, typography, focus, selection, accessibility utilities
CSS Modules: component and page layout

Visual regression

Playwright Chromium is the canonical snapshot engine. Functional projects remain Chromium, Firefox, WebKit, mobile Chromium, and mobile WebKit. Snapshot generation and approval are blocked until the pinned browser environment can execute.

Consequences

The application foundation is traceable and does not encode unresolved product decisions. The cost is an explicit set of pending route shells and disabled conversion destinations until owners close the inherited gates. Full acceptance still requires Node 24.17.0 CI, Playwright execution, and reviewed visual snapshots.

4.1 KiB Raw Blame History