root
148 lines
7.9 KiB
Markdown
148 lines
7.9 KiB
Markdown
# 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:
|
||
|
||
1. `DECISION_LOG_v9.0.md`
|
||
2. `09_DEVELOPER_HANDOFF_v1.0.md`
|
||
3. component, localization, interaction, token, and QA contracts in this package
|
||
4. 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`.
|