Merge pull request #40 from programmerShinobi/feat/landing-page

feat: Home landing page + genuinely-mobile experience (prototype match)

Author: programmerShinobi

CHANGELOG.md

@@ -9,6 +9,46 @@ The decision **model** carries its own version, recorded in the
 
 ## [Unreleased]
 
+### Added (Genuinely-mobile experience — 2026-07-14)
+
+- **A real mobile UI for the whole app** (plan: [mobile-experience-plan.md](docs/03-blueprint/mobile-experience-plan.md),
+  written *before* implementation) — not a shrunk desktop layout. On phones (≤640px):
+  - **Fixed bottom tab bar** (`MobileChrome`) — **Home · Advisor · Insights · More** (thumb-zone
+    navigation); the desktop top-nav hides.
+  - **Settings sheet** (slides up from "More") with **Theme · Language · Reading mode** as
+    first-class segmented controls — so all three product toggles are reachable on mobile (the header
+    cluster is hidden there). `useTheme` is lifted to `App` and shared, so header + sheet never
+    desync.
+  - **Sticky bottom primary action** on the Advisor (`AdvisorMobileBar`) — a contextual
+    **"Get your plan" → "Save & share"** button (the "primary button at the bottom" pattern) that
+    scrolls the one-page flow forward via an `IntersectionObserver`. It's navigation sugar; the flow,
+    steps, and model are unchanged.
+  - Decluttered mobile header (brand + Guide); safe-area insets (`viewport-fit=cover`,
+    `env(safe-area-inset-bottom)`); content padding clears the fixed bars.
+  - Desktop (≥641px) is unchanged. Both themes verified. e2e updated for the mobile chrome; budget
+    total JS 193.2/200 kB, CSS 22.9/25 kB.
+
+### Added (Home landing page — 2026-07-13)
+
+- **A proper Home landing page** (`LandingView` + `HeroRadar`), now the **default view**, mirroring
+  the composition of the approved [`prototype-v2/preview-modern.html`](docs/03-blueprint/prototype-v2/preview-modern.html)
+  — closing the gap between the prototype's *layout* and the app (the Aurora reskin had applied the
+  prototype's *style* but kept the tool-first structure).
+  - **Hero:** gradient headline, eyebrow badge, lede, primary/secondary CTAs, hero-meta stats, and
+    the decorative 5-dimension **radar motif** with floating chips (static brand art, distinct from
+    the Advisor's functional radar).
+  - **Pattern Library bento:** four **real** architectures from the frozen model (Event-driven,
+    Modular Monolith, Serverless, CQRS — names from `dimensions.ts`, blurbs bilingual in the dict),
+    each **deep-linking into its Insights Catalog page**.
+  - **How it works:** the three real Advisor steps.
+  - Fully **bilingual** (EN/ID via the dict), **responsive** (radar-first on mobile, bento reflows),
+    reveal-on-scroll (reduced-motion safe), and pointer-glow cards — all reusing the Aurora tokens.
+  - Top nav is now **Home · Advisor · Insights** (Home default). A shared `#s=…` link still opens the
+    Advisor directly. CTAs drive the Advisor; "All architectures" opens Insights.
+  - Kept light: the landing uses `DIMENSIONS` + dict strings (no `readerContent` pulled into the
+    initial bundle); initial JS+CSS 134.1 kB, total JS 191.9 kB — within budget. +3 unit tests
+    (`LandingView.test.tsx`); e2e updated for the new default view. All gates green.
+
 ### Added (PWA resilience polish — 2026-07-13)
 
 - **Stale-chunk auto-recovery.** A tab left open across a deploy could 404 on an old lazy chunk

DECISIONS.md

@@ -196,6 +196,16 @@ Appendix A). Direction chosen with the maintainer: **client-rendered first, Wave
   SPA): the vanilla rewrite, the multi-file `@layer`/`js/` split + `ROOT` depth helper + per-page
   anti-FOUC script, cross-document View Transitions, a hand-rolled service worker/manifest, and the
   `.card`/`.nav` class rename. PWA remains an optional future follow-up.
+- **The prototype's *layout* now ships too — as a Home landing (2026-07-13, FR-SHELL-11).** The
+  reskin first applied only the prototype's *style*; a follow-up added a real **Home landing view**
+  (`LandingView` + `HeroRadar`) mirroring the prototype's composition (hero + Pattern Library +
+  how-it-works). It is the **default** view (top nav Home · Advisor · Insights). Reconciliations vs
+  the prototype (a marketing mockup): the Pattern Library features **real** model architectures
+  (deep-linking into Insights), copy is **bilingual** via the dict, and the decorative hero radar is
+  a *separate* static motif — **not** the Advisor's functional 12-attribute radar (M13 discipline:
+  one radar visual system, two uses). The landing deliberately avoids importing `readerContent`
+  (uses `DIMENSIONS` + dict strings) so the now-default view doesn't pull the content layer into the
+  initial-JS budget. A shared `#s=…` link sets `aa.main=advisor` pre-render so it opens the Advisor.
 
 ## PWA — installable + offline (2026-07)
 

docs/02-requirement-analysis/software-requirements-specification.md

@@ -32,6 +32,7 @@
 | 1.3 | 2026-07-06 | **Insights holistic coverage + English-first**: FR-LEARN-6 extended to all four sections (Catalog/Playbook/Review/Library) with distinct structured lenses and a per-page lens navigation (the Catalog → Playbook → Review → Library knowledge journey) for every one of the 21 architectures; FR-SHELL-2 default language flipped to **EN** (toggle unchanged); FR-LEARN-2 content gate now requires **at least the `en` version**. See [DECISIONS.md](../../DECISIONS.md). No requirements removed |
 | 1.4 | 2026-07-06 | **Insights Wave C + SEO**: added FR-LEARN-8 (Roadmap — guided learning paths), FR-LEARN-9 (Academy — client-side quiz modules), FR-LEARN-10 (Lab — hypothesis experiments that load prepared scenarios into the live engine), and FR-SEO-1 (build-time sitemap/robots/JSON-LD + static crawlable article snapshots; SSG-lite — the SPA architecture is unchanged, superseding "SSG deferred" for discoverability). §3.10 updated to seven sections. No requirements removed |
 | 1.5 | 2026-07-06 | **Wave C holistic parity**: FR-LEARN-8/9/10 strengthened — the Roadmap, Academy, and Lab must each cover **all 21 architectures** (every architecture in ≥1 learning path, reviewed by ≥1 quiz question, and in play in ≥1 experiment), matching the four lenses' 21×4 parity so Wave C can never mismatch the lens coverage; enforced by per-section unit tests. No requirements removed |
+| 1.6 | 2026-07-13 | **Home landing page** (FR-SHELL-11): added a default Home view mirroring the approved prototype composition (hero + real Pattern Library + how-it-works), bilingual/responsive, CTAs into the Advisor and deep-links into Insights; top nav becomes Home · Advisor · Insights. Part of the "Aurora Slate" visual programme (ADR-009). No requirements removed |
 
 ---
 
@@ -216,6 +217,7 @@ v1.0:
 | FR-SHELL-8 | Provide a **command palette and keyboard shortcuts** covering all core actions. | Should | UI/UX Playbook Task 2 | T |
 | FR-SHELL-9 | Provide an in-app **Manual / Guide** that explains the tool end to end — including the full scoring calculation — with a **live worked example** computed from the user's current inputs. | Should | v1.1 enhancement | D |
 | FR-SHELL-10 | Extend the in-app **Manual / Guide** into a genuine deep-dive that, alongside the scoring walkthrough, **explains every architecture the Advisor evaluates** (see §3.9). The Manual is **lazy-loaded** on demand. | Should | v1.1 enhancement | T |
+| FR-SHELL-11 | Provide a **Home landing view** — the **default** top-nav destination (Home · Advisor · Insights) — that mirrors the approved prototype composition: a hero (headline, CTAs, key stats, decorative radar motif), a **Pattern Library** featuring **real** architectures from the frozen model (each deep-linking into its Insights Catalog), and a **how-it-works** summary of the Advisor flow. Bilingual, responsive, and reveal-on-scroll (reduced-motion safe). CTAs open the Advisor; a shared `#s=…` link bypasses Home and opens the Advisor directly. | Should | 2026-07 landing | T |
 
 ### 3.2 Step 1 — Project Factors
 

docs/03-blueprint/design-specification.md

@@ -28,6 +28,8 @@
 | 0.9 | 2026-07-04 | **Responsive UI redesign**: added the `--aa-*` token layer + base classes (§6.1 — fluid spacing/type, soft elevation, 44 px touch targets, global focus ring, canonical breakpoints ≤640/641–1024/≥1025). Supersedes prototype-exact *look* (copy/features/model unchanged — see DECISIONS.md); Advisor & Insights views restyled responsive/card-based. No logic or data changes |
 | 1.0 | 2026-07-12 | **"Aurora Slate" visual direction (ADR-009)** — approved reskin *in place* of the existing React app (aurora palette + accent gradient + Space Grotesk display face, two signatures: aurora background + the existing radar restyled). The blueprint's proposed vanilla/MPA rewrite is **rejected** (ADR-003/004 stand — engine, model, seven-section Insights, and 99 tests preserved). Visual source of truth committed to [`prototype-v2/preview-modern.html`](prototype-v2/preview-modern.html). Implementation is token-value remapping, not a rewrite |
 | 1.1 | 2026-07-13 | **PWA — installable + offline (ADR-010)** via `vite-plugin-pwa` (Workbox `generateSW`, `autoUpdate`); manifest + generated service worker, app shell precached / fonts runtime-cached / SEO snapshots excluded, subpath-safe scope. No app-logic or model changes |
+| 1.2 | 2026-07-13 | **Home landing page (FR-SHELL-11)** — new default view (`LandingView` + `HeroRadar`) mirroring the prototype composition (hero + real Pattern Library + how-it-works); top nav Home · Advisor · Insights; CTAs → Advisor, pattern cards deep-link → Insights Catalog. Part of ADR-009 (Aurora Slate). Landing kept out of `readerContent` to protect the initial-JS budget. No model changes |
+| 1.3 | 2026-07-14 | **Genuinely-mobile experience** ([mobile-experience-plan.md](mobile-experience-plan.md)) — phone-tier bottom tab bar (`MobileChrome`) + settings sheet (theme/language/reading-mode) + Advisor sticky bottom primary action (`AdvisorMobileBar`); `useTheme` lifted to `App` and shared; desktop unchanged. Presentation/navigation only — no flow or model change |
 
 ---
 
@@ -121,7 +123,7 @@ src/
 ├── lib/            scoring · sensitivity · antiPatternEngine · adr · report
 │                   c4 · urlState · customConfig · content · frontmatter · markdown
 ├── hooks/          usePersistedState · useUrlSyncedState
-└── components/     Header · ManualBook (Guide + architecture explanations, lazy) · Disclaimer · ModeToggle · PresetBar · FactorGroup …
+└── components/     Header · LandingView + HeroRadar (Home landing, default) · AuroraBackground · ManualBook (Guide, lazy) · Disclaimer · ModeToggle · PresetBar · FactorGroup …
                     QaWeightChart · DimensionResults · RadarTradeoff · ContributionTable
                     ComparisonMode · SensitivityCard · RiskRegister · AntiPatternAlerts
                     FitnessFunctions · MigrationPath · MethodologyPanel · ReportPreview …

docs/03-blueprint/mobile-experience-plan.md

@@ -0,0 +1,101 @@
+# Mobile Experience Plan — Architecture Advisor
+
+**Status:** **Implemented** 2026-07-14 (written 2026-07-13, before implementation, per the maintainer's docs-first rule)
+**Owner:** Faqih Pratama Muhti · **Relates to:** ADR-009 (Aurora Slate), FR-SHELL-1/2/3/11, design-spec §6.1, [`prototype-v2/preview-modern.html`](prototype-v2/preview-modern.html)
+
+## 1. Goal
+
+Make the **core Advisor and Insights** (and the Home landing) feel like a **genuinely mobile app** on
+phones — not a desktop layout squeezed small — while keeping the exact decision-model flow and all
+logic unchanged. Concretely, on phones (≤640px):
+
+- A **fixed bottom tab bar** for primary navigation (thumb-zone), the mobile convention — replacing
+  the top tab row that currently wraps.
+- A **sticky bottom primary action** on the Advisor (the "main button at the bottom" pattern) that
+  drives the process flow (factors → priorities → plan → save).
+- **First-class, reachable controls** for the three product toggles — **theme (light/dark)**,
+  **language (EN/ID)**, and **Guided/Expert** — surfaced in a mobile **settings sheet** (the header
+  control cluster is cramped on phones).
+- Mobile-native spacing/typography/hit-targets and safe-area handling.
+
+Desktop (≥641px) is unchanged (top nav + header controls as today).
+
+## 2. Non-negotiables
+
+- **No change to the flow or the model.** Same four steps, same scoring, same content — only the
+  *presentation/navigation* changes on phones. All model/content guards and the 102 unit + 14 e2e
+  tests stay green (e2e updated for the new mobile chrome where needed).
+- **No new runtime dependency.** Token-based (`--color-*`, `--aa-*`), `aa-`/`lp-` class conventions,
+  no `!important`, reuse the existing `<dialog>`-based sheet pattern if present or a small one.
+- **Accessibility:** bottom-nav items ≥44px, `aria-current` on the active tab, `env(safe-area-inset-*)`,
+  visible focus, `prefers-reduced-motion` respected, WCAG AA in both themes (axe-gated).
+- **Budget:** stay within the initial-JS/CSS and total-JS budgets (mobile chrome is small CSS + a
+  little JS).
+
+## 3. Components & changes (planned)
+
+| Area | Change |
+|---|---|
+| **`MobileTabBar`** (new) | Fixed bottom bar, phone-only (`aa-only-phone`), 3 tabs **Home · Advisor · Insights** (icon + label), `aria-current`, safe-area padding. Drives the same `mainView` state. The top tab row gets `aa-hide-phone`. |
+| **`MobileSettingsSheet`** (new) | A bottom sheet (slide-up) holding **Theme**, **Language**, **Guided/Expert** as large, labelled controls. Opened from a compact header button (gear) shown on phones. Closes on backdrop/Esc; focus-trapped. |
+| **Header** | On phones, collapse the control cluster (⌘K/?/save already hidden via `aa-hide-phone`); keep brand + theme quick-toggle + the settings (gear) button. Desktop unchanged. |
+| **`AdvisorMobileBar`** (new) | Phone-only sticky bottom action bar (above the tab bar): a **contextual primary button** that advances the flow — *See what matters* → *Get your plan* → *Save & share* — by scrolling to that section (the Advisor stays one page; the bar is the mobile "next"). Uses the existing StepTracker sections as anchors. |
+| **Advisor layout** | Content gets bottom padding = `tabbar + actionbar + safe-area` so nothing hides behind the fixed chrome. Cards/inputs already responsive; verify one-column, comfortable tap targets. |
+| **Insights layout** | Already card-based/stacks; ensure bottom padding for the tab bar and that section/detail navigation is thumb-reachable. |
+| **Landing** | Already responsive (radar-first, reflowing bento); add bottom padding for the tab bar; CTAs unaffected. |
+| **CSS** | New `aa-only-phone` / `aa-hide-phone` usage; `.aa-tabbar`, `.aa-mobile-actionbar`, `.aa-sheet` under the ≤640 breakpoint; all token-based. |
+
+## 4. Interaction / flow (unchanged semantics)
+
+- **Navigation:** bottom tab bar switches `mainView` exactly like the top tabs (Home/Advisor/Insights);
+  a shared `#s=…` link still opens the Advisor.
+- **Advisor bottom action (contextual):**
+  1. On the Factors area → primary button **"See what matters"** scrolls to Priorities.
+  2. Past Priorities → **"Get your plan"** scrolls to the Recommendation.
+  3. At the plan → **"Save & share"** opens the export/share.
+  The determination is by scroll position / which section is in view — no state-machine change; the
+  single-page flow is preserved (this is navigation sugar, not a wizard rewrite).
+- **Toggles:** the settings sheet mutates the same `theme` / `lang` / `mode` state used everywhere;
+  changes apply instantly and persist (localStorage), identical to the header controls.
+
+## 5. Breakpoint & tokens
+
+- Phone tier: **≤640px** (canonical, design-spec §6.1). Bottom nav + action bar + settings sheet are
+  phone-only; ≥641px keeps the current top-nav desktop layout.
+- Safe area: `padding-bottom: env(safe-area-inset-bottom)` on the fixed bars; the viewport already
+  uses `viewport-fit=cover`? (verify/set in index.html).
+
+## 6. Testing (planned)
+
+- **Unit:** a small render test for `MobileSettingsSheet` (toggles call the right setters) and that
+  the bottom tab bar switches views.
+- **e2e (`responsive.spec.ts`):** at the 360px viewport, assert the bottom tab bar is visible and
+  switches Home/Advisor/Insights; the settings sheet opens and toggles theme/lang/mode; no horizontal
+  scroll; the Advisor bottom action advances the flow. Desktop specs unchanged.
+- **a11y:** axe on the mobile chrome (both themes); bottom-nav roles/`aria-current`; focus trap in the
+  sheet.
+
+## 7. Rollout
+
+Incremental, each step gate-green: (1) bottom tab bar + hide top nav on phones; (2) settings sheet +
+header gear; (3) Advisor sticky bottom action; (4) padding/polish for Insights & Landing; (5) e2e +
+a11y + screenshots (both themes), docs, PR. Documented in CHANGELOG + design-spec on completion; this
+plan is the pre-implementation record.
+
+## 8. Implementation notes (as built, 2026-07-14)
+
+- **`MobileChrome`** renders the bottom tab bar (**Home · Advisor · Insights · More**) and the
+  settings sheet; the "More" tab opens the sheet with **Theme · Language · Reading mode** as
+  segmented controls. `useTheme` was **lifted to `App`** and passed to both the header and
+  `MobileChrome` (they share one theme state — `usePersistedState` does not sync across instances).
+- **`AdvisorMobileBar`** is the phone-only sticky primary action; an `IntersectionObserver` on
+  `#adv-plan` flips it from **Get your plan** → **Save & share** as the recommendation reaches the
+  viewport's middle band. Anchors `#adv-plan` / `#adv-save` added to the Advisor sections.
+- The desktop **top nav** and the header **theme/language/mode cluster** move to CSS classes
+  (`.aa-topnav`, `.aa-desktop-controls`) that hide ≤640px — avoiding the inline-`display` footgun
+  that beats `aa-hide-phone` (DECISIONS.md). Content clears the fixed bars via `.aa-page` /
+  `.aa-page.has-actionbar` bottom padding + `env(safe-area-inset-bottom)`; `index.html` gained
+  `viewport-fit=cover`.
+- **Tests:** e2e `responsive.spec.ts` updated to assert the bottom bar + settings sheet on phones;
+  the two App-level a11y unit tests select the first nav match (top nav + bottom bar both render
+  under `css:false`). Desktop specs unchanged. All gates green; budget total JS 193.2/200 kB.

e2e/a11y.spec.ts

@@ -25,6 +25,7 @@ test('no WCAG A/AA violations incl. color-contrast (Guided, dark theme)', async
 test('no WCAG A/AA violations incl. color-contrast (Expert mode + light theme)', async ({ page }) => {
   await page.goto(APP);
   await page.getByRole('button', { name: 'EN', exact: true }).click();
+  await page.getByRole('button', { name: 'Advisor', exact: true }).click(); // default view is now Home
   await page.getByRole('button', { name: 'Expert', exact: true }).click();
   await page.getByRole('button', { name: 'Toggle theme' }).click(); // → light
   await page.getByRole('button', { name: /Adjust weights/ }).click(); // mount the override panel
@@ -78,5 +79,6 @@ test('controls are keyboard-operable', async ({ page }) => {
   // which renames the Indonesian preset chips to their English labels)
   await page.getByRole('button', { name: 'EN', exact: true }).focus();
   await page.keyboard.press('Enter');
+  await page.getByRole('button', { name: 'Advisor', exact: true }).click(); // default view is now Home
   await expect(page.getByRole('button', { name: 'Busy online shop' })).toBeVisible();
 });