Files

T

CI / test (push) Failing after 28s

Details

chore: fix prettier formatting, regenerate phase9 manifest, add missing config files (.env.example, .node-version, .nvmrc, CI workflow)

2026-06-25 20:12:15 -04:00

8.2 KiB

Raw Permalink Blame History

Phase 9: Developer Handoff

1. Scope

This handoff converts the approved homePageCar design system and Phase 8 prototype into implementation contracts for a multilingual rental-car SaaS marketing website. It covers the homepage, demo-booking flow, guided product tour, responsive navigation, theme selection, locale routing, SEO language relationships, analytics boundaries, accessibility, assets, validation, and release gates.

It does not approve unverified capabilities, customer evidence, integrations, certifications, service levels, prices, legal language, CRM behavior, or usability acceptance.

2. Implementation authority

Use this precedence when files disagree:

DECISION_LOG_v9.0.md
09_DEVELOPER_HANDOFF_v1.0.md
component, localization, interaction, token, and QA contracts in this package
Phase 8 prototype as behavioral reference only

The prototype is not production source code. Its inline rendering, simulated submission, local research logging, illustrative product UI, and placeholder contact destination must not be copied blindly.

3. Required architecture properties

The implementation must:

render public pages server-side or statically with correct lang, dir, canonical, and reciprocal hreflang before hydration;
use strict TypeScript for application code;
consume semantic CSS custom properties, never component-local brand hex values;
use one component tree for LTR and RTL;
use locale-prefixed routes and stable route IDs;
persist explicit theme preference in a first-party cookie and mirror it in local storage;
run the pre-paint theme bootstrap before blocking styles;
keep all public strings outside component source except documented proper names and immutable technical identifiers;
use native semantic controls unless a documented accessibility review approves a replacement;
provide deterministic state URLs or test fixtures for every visual-regression state;
gate production analytics behind approved consent rules and exclude form values and free text.

4. Breakpoints and layout modes

Breakpoints are layout decisions, not device labels.

Mode	CSS range	Reference frames	Required behavior
Compact	0–767 px	320, 390	One-column sections; mobile drawer; stacked CTAs; product preview simplified; no horizontal page scroll
Medium	768–1119 px	768, 1024	Two-column where specified; mobile drawer remains; 4-column workflow allowed; balanced content widths
Wide	1120 px and above	1280, 1440	Desktop navigation and controls; 12-column composition; hero 7/5 split; max container 1280 px

Do not infer new behavior between breakpoints. Follow components/RESPONSIVE_BEHAVIOR_MATRIX_v1.0.csv.

5. Theme contract

Supported preferences are exactly light, dark, and system. Preference and resolved theme are separate values.

Cookie: hpc-theme, value light|dark|system, Path=/, SameSite=Lax, one-year max age, Secure in production.
Local storage mirror: hpc.theme.preference.
Root attributes: data-theme-preference and resolved data-theme (light|dark).
Cookie wins if cookie and local storage disagree.
Default with no stored preference: system.
System updates live on prefers-color-scheme changes.
Theme application has no global transition.
Set color-scheme to the resolved theme.
The bootstrap must run in <head> before blocking CSS and use a CSP nonce or approved hash.

See interaction/theme-bootstrap_v1.0.js and implementation/theme-config_v1.0.ts.

6. Localization and routing contract

Public routes are locale-prefixed: /en, /fr, /ar. English is source/default/fallback, but missing translations fail CI.

Root / may redirect using explicit cookie, then Accept-Language, then English.
Explicit locale URLs are never overridden automatically.
Arabic renders <html lang="ar" dir="rtl">; English and French render dir="ltr".
Locale switching maps by stable route ID, preserves query parameters approved in the route manifest, and preserves valid section hashes.
Atomic LTR values inside Arabic use <bdi dir="ltr"> or an equivalent isolation primitive.
Language does not determine currency, country, timezone, tax, or phone formatting.
Reciprocal hreflang entries include en, fr, ar, plus x-default pointing to /en.

See the localization directory for exact rules and generated resources.

7. Component implementation

Every public component must implement:

semantic anatomy and heading rules;
props and state enums from implementation/component-contracts_v1.0.ts;
explicit compact/medium/wide behavior;
light/dark behavior via tokens;
LTR/RTL behavior via logical CSS and selective icon mirroring;
keyboard and focus behavior;
visible-copy keys and content bounds;
stable test IDs only where semantic selectors are insufficient.

No component may introduce a fixed height for translated text, validation messages, cards, buttons, or headings.

8. Demo form production contract

Required fields: full name, work email, company, fleet-size range. Optional fields: market/country, preferred language, message.

Submission state machine:

idle → validating → submitting → success | recoverable_error | terminal_error

Rules:

preserve entered data on recoverable service failure;
focus the first invalid field after summary announcement;
show inline errors and a form-level summary;
do not use a toast as the only error record;
disable duplicate submission while a request is in flight;
attach an idempotency key to each intentional submission;
do not log names, emails, company names, messages, or raw server responses;
render final consent only after Legal approval;
provide an alternate contact path only after Sales approves a real destination;
success copy must accurately describe what the backend actually did.

The CRM endpoint, consent language, routing, retries, spam controls, and duplicate policy are release blockers in the issue register.

9. Motion and overlays

Drawer opens from inline-start: left in LTR, right in RTL.
Drawer and dialogs trap focus, make background inert, support Escape, and return focus to the trigger.
Backdrop dismissal is allowed for non-destructive dialogs; pending form submission blocks accidental dismissal.
Animations are 160–220 ms and use opacity/transform only.
prefers-reduced-motion: reduce removes smooth scrolling, transforms, shimmer, and non-essential progress animation.
No information, success, or error state may depend on animation.

10. Assets and evidence

Only assets in assets/ASSET_MANIFEST_v1.0.csv with status approved may ship. The current product preview is illustrative and must either receive written approval or be replaced by an evidence-governed product capture before launch.

Product captures require metadata for locale, direction, theme, capture date, product version, approval owner, and expiry/review date. Never mirror, recolor, or invert captures.

11. Quality gates

A production candidate must pass:

locale key parity and linguistic review;
all listed browser and viewport scenarios;
keyboard, screen-reader, zoom, reflow, forced-colors, and reduced-motion checks;
light/dark/system and LTR/RTL visual regression;
form validation, network failure, duplicate, retry, consent, and CRM integration tests;
performance budgets in qa/PERFORMANCE_BUDGETS_v1.0.json;
zero open Critical or High issues;
approved evidence and legal content only;
the complete definition of done.

12. Explicitly unresolved

The final framework, browser policy owner, analytics vendor, CRM, consent implementation, spam protection, product-tour media, market assumptions, multi-location claim, pricing, integrations, security evidence, legal documents, and participant acceptance are not approved. The package supplies a vendor-neutral implementation and a default technical profile, but each unresolved item remains visible and owned in OPEN_ISSUE_REGISTER_v1.0.csv.

8.2 KiB Raw Permalink Blame History Unescape Escape