Parsons/docs/memory/session-log.md

# Session log

This file tracks work completed across Claude Code sessions. Every agent MUST
read this file before starting work and update it after completing work.

> Earlier sessions (2026-03-24 through 2026-03-26d) archived in
> `docs/memory/archive/sessions-through-2026-03-26.md`

## Format

Each entry follows this structure:
```
### Session [date] — [brief description]
**Agent(s):** [which agents were active]
**Work completed:**
- [bullet points of what was done]
**Decisions made:**
- [any design/architecture decisions with brief rationale]
**Open questions:**
- [anything unresolved that needs human input]
**Next steps:**
- [what should happen next]
```

---

## Sessions

### Session 2026-03-30d — Steps 8-15 consistency pass

**Agent(s):** Claude Opus 4.6 (1M context)

**Work completed:**
- **Consistency pass across Steps 8-15** — aligned all remaining wizard steps with the conventions established during the Steps 1-6 feedback iteration:
  - **Subheading variant:** CrematoriumStep, CoffinDetailsStep changed from `body2` → `body1` (match IntroStep/DateTimeStep centered-form convention)
  - **Subheading spacing:** CrematoriumStep, CemeteryStep, CoffinDetailsStep, AdditionalServicesStep, SummaryStep, PaymentStep all changed from `mb: 4` → `mb: 5`
  - **Section dividers:** CrematoriumStep gained 3 `<Divider>` between question sections (crematorium → witness, conditional priority, special instructions)
  - **Link atom:** PaymentStep terms links and ConfirmationStep phone number changed from `Box component="a"` → `Link` atom
  - **CoffinsStep:** No changes needed (wide-form layout has its own spacing convention)
- **Audited CrematoriumStep (15/20) and PaymentStep (16/20)** — findings are pre-existing, not introduced by the pass
- **Visual verification:** Playwright screenshots of CrematoriumStep, PaymentStep, ConfirmationStep, AdditionalServicesStep, SummaryStep — all pass

**Decisions made:**
- Centered-form heading convention now formally: `display3` → `body1` subheading → `mb: 5` gap (documented via consistent implementation across all 10+ centered-form steps)
- Wide-form layout (CoffinsStep) keeps its own tighter spacing convention (`body2` + `caption`, `mb: 3`)

**Open questions:**
- **Checkbox atom:** PaymentStep uses MUI Checkbox directly — only form control without an FA atom wrapper. Create Checkbox atom?
- **aria-describedby/aria-invalid:** All wizard steps lack error field association. Batch normalize fix recommended.
- **Retroactive review Phase 2.2** still pending (audit priority molecules: ServiceOption, AddOnOption, ProviderCardCompact)

**Also completed (same session):**
- **Checkbox atom created:** New FA wrapper (forwardRef, displayName, stories: Default/States/TermsAgreement/Checklist). MuiCheckbox theme overrides (warm gold checked, focus ring, disabled muted). PaymentStep updated to import from atom.
- **Retroactive review Phase 2.2 complete:** Audited ServiceOption (13/20), AddOnOption (14/20), ProviderCardCompact (15/20). Fixed:
  - AddOnOption: added `aria-disabled` when disabled (P1)
  - ProviderCardCompact: added `maxLines={1}` on name (P2)
  - ServiceOption: price uses `labelLg` variant instead of h6 + hardcoded fontWeight (P1)
- Note: audit agents flagged false P0s (AddOnOption "double handler", ServiceOption "role collision") — verified both are correctly handled by existing `stopPropagation` and prop spread order in Card atom

**Next steps:**
- User has step page feedback to provide — iterate when ready
- Batch a11y fix: add aria-describedby + aria-invalid to error fields across all wizard steps (deferred per user)
- Retroactive review Phase 3: organisms normalize + audit (Navigation, ServiceSelector, FuneralFinderV3)

---

### Session 2026-03-30c — HomePage build + Chromatic + Story to Design setup

**Agent(s):** Claude Opus 4.6 (1M context)

**Work completed:**
- **Story to Design agent:** Helped user install and run the story.to.design agent on Arch Linux (extracted from .deb, installed webkit2gtk dependency). Agent connects Storybook to Figma plugin.
- **Chromatic setup:** Installed chromatic, published Storybook to Chromatic CDN. Set visibility to public for shareable links. Updated `package.json` chromatic script with `--build-script-name=build:storybook`.
- **HomePage component built:** Full marketing landing page at `src/components/pages/HomePage/`
  - 7 sections: Hero, FuneralFinder widget (overlapping card), Partner Logos carousel, Features (4-card grid), Reviews/Testimonials, CTA Banner, FAQ accordion
  - Composes FuneralFinderV3 organism, Navigation + Footer via props
  - CSS-only infinite scroll logo carousel with prefers-reduced-motion
  - Feature cards with warm circular icon backgrounds
  - Full a11y: section landmarks, aria-labelledby, heading hierarchy
  - Grief-sensitive copy (quieter pass applied)
- **Quality gates run:** /critique (32/40), /audit (16/20), /quieter (all pass)
- **Design iteration:** Multiple rounds of visual refinement using Playwright screenshots
  - Reduced oversized typography (display1 → display3 for hero, display2 → h2 for sections)
  - Reserved serif fonts for hero + CTA only, sans-serif for all other section headings
  - Tightened spacing, reduced section padding
  - Feature cards: compact padding, warm circular icon backgrounds
  - Fixed unicode rendering bugs in copy

**Decisions made:**
- Serif display fonts reserved for hero heading and CTA banner only — all other section headings use Montserrat (h2/h3)
- Feature card icons wrapped in warm circular backgrounds (brand.50 bg, 56px diameter)
- HomePage is a page component (not a template) — does not use WizardLayout
- Chromatic published URL is the shareable Storybook link for stakeholders

**Open questions:**
- Homepage is first-pass only — user will return to iterate later
- Partner logo placeholder images need real assets
- Hero image slot needs real photography
- CTA banner click destination needs clarification (scroll to widget vs wizard entry)

**Next steps:**
- Resume arrangement wizard page feedback from VenueStep (Step 7) onwards — Steps 1-6 done in previous session
- Remaining pages: VenueStep, CrematoriumStep, CemeteryStep, CoffinsStep, CoffinDetailsStep, AdditionalServicesStep, SummaryStep, PaymentStep, ConfirmationStep

---

### Session 2026-03-30b — Page feedback iteration (Steps 1-6) + DialogShell

**Agent(s):** Claude Opus 4.6 (1M context)

**Work completed:**
- **IntroStep (Step 1):** Static subheading (removed dynamic text change on selection), ToggleButtonGroup top-left alignment fix
- **ProvidersStep (Step 2):** Heading reduced to h4 "Find a funeral director", SearchBar → location TextField with pin icon, FilterPanel moved below search right-aligned, map fill fix (height:100% → flex:1), hover scrollbar on left panel
- **VenueStep (Step 7):** Same consistency fixes as ProvidersStep (h4, location icon, filter layout, map fill, results count format)
- **PackagesStep (Step 3):** Removed budget filter + "Most Popular" badge + mobile Continue button. Added grouped packages pattern ("Matching your preferences" / "Other packages from [Provider]" with brand accent bars). `onArrange` replaces `onContinue`. Clickable provider card (`onProviderClick`). Heading to h4.
- **DateTimeStep (Step 6):** display3 heading (centered-form consistency). Name fields swapped from MUI TextField to Input atom (external label, no clipping). Multiple preferred dates (up to 3, progressive disclosure). Removed service tradition/religion field. Dividers between question sections.
- **DialogShell atom:** New shared dialog container (header + optional back + close, scrollable body, optional footer). Audited 17→19/20, P1s fixed (focus management, sx pattern).
- **FilterPanel refactored:** Popover → DialogShell (centered Dialog with backdrop)
- **ArrangementDialog refactored:** Now composes DialogShell for consistent chrome
- **PreviewStep + AuthGateStep removed:** Consolidated into ArrangementDialog (D-E)
- **WizardLayout:** ListMapLayout left panel gets thin scrollbar visible on hover

**Decisions made:**
- Heading convention: display3 for centered-form pages, h4 for narrow panels (list-map, list-detail)
- DialogShell is the standard popup container — all site dialogs compose it
- Service tradition removed from DateTimeStep — flows from provider/package selection, confirmed on summary
- "Service tradition" is the preferred terminology (not "religion" or "religious style")
- Package grouping pattern: matched vs other, with brand accent bar section labels
- FilterPanel uses Dialog (not Popover) for filter controls

**Open questions:**
- Provider profile popup contents — user will provide details later
- Heading convention (display3 vs h4) should be documented as a decision

**Next steps:**
- **Resume page feedback from VenueStep (Step 7) onwards** — Steps 1-6 are done
- Remaining pages to review: VenueStep, CrematoriumStep, CemeteryStep, CoffinsStep, CoffinDetailsStep, AdditionalServicesStep, SummaryStep, PaymentStep, ConfirmationStep
- Homepage layout work (user priority — separate task)
- Input atom clipping: audit remaining pages for MUI TextField → Input atom swap where labels clip

---

### Session 2026-03-30a — Tooling upgrades + workflow evaluation

**Agent(s):** Claude Opus 4.6 (1M context)

**Work completed:**
- **Storybook addons:** Added `@storybook/addon-storysource` (story source code panel) and `@storybook/addon-a11y` (real-time axe-core accessibility checks)
- **Playwright MCP:** Installed `@playwright/mcp` and registered as MCP server. Enables Claude Code to take screenshots of Storybook for visual verification. Available from next session.
- **Workflow evaluation:** Comprehensive analysis of current capabilities, identified core gap (Claude Code cannot see visual output), researched solutions
- **Antigravity research:** Investigated Google Antigravity IDE for visual polish workflow. Installed on system. Created `GEMINI.md` project rules file. User decided to pause on Antigravity for now and continue with Claude Code + Playwright MCP approach.
- **GEMINI.md:** Created project rules file for Antigravity IDE, mirroring key conventions from CLAUDE.md (token access, atomic tiers, no hardcoded values)

**Decisions made:**
- Playwright MCP is the primary solution for visual verification gap — enables Claude Code to screenshot Storybook stories and self-correct visual issues
- Antigravity available as secondary tool for visual tweaks but not primary workflow
- Claude Code remains the primary tool for architectural/structural work due to custom skills, memory system, and accumulated project context

**Open questions:**
- User has refinement feedback from previous session that was partially overlooked — to be addressed next session
- Some items from the user's original feedback across 15 steps were missed when compressed into D-A through D-H decisions

**Next steps:**
- Restart session to activate Playwright MCP
- User to provide refinement feedback
- Use Playwright MCP to visually verify changes as they're made
- Address remaining P1s from previous session (radiogroup keyboard nav, dialog mobile fullscreen)

---

### Session 2026-03-29e — Feedback iteration Batches 1 & 2

**Agent(s):** Claude Opus 4.6 (1M context)

**Work completed:**
- **Batch 1: Atom + Template Foundation**
  - ToggleButtonGroup: label-to-options spacing `mb: 1→2`, top-align content `flex-start`, fixed selected border CSS specificity (added `&.Mui-selected` in grouped selector)
  - Heading standardisation: all 6 split-layout steps changed from `h4` → `display3` (ProvidersStep, PackagesStep, PreviewStep, VenueStep, CoffinsStep, CoffinDetailsStep) per D-A
  - DateTimeStep: normalised section gaps (scheduling fieldset `mb: 3→4`)
  - CrematoriumStep: added subheading for consistency, normalised witness section `mb: 3→4`
  - PackagesStep + DateTimeStep: fixed input label clipping (`pt: 0.5` on TextField containers)
- **Batch 2: List-Map Layout Rework (D-B)**
  - WizardLayout ListMapLayout: 420px fixed left column, `flex: 1` right panel
  - Back link rendered inside left panel (not above split) — eliminates gap above map
  - LAYOUT_MAP type updated to accept `backLink` prop for list-map variant
  - ProvidersStep + VenueStep: sticky header (heading + search + filters pinned at top of scrollable left panel)
- **Batch 3: FilterPanel molecule + integration (D-C, D-F)**
  - New FilterPanel molecule: Popover trigger with active count badge, Clear all, Done actions
  - ProvidersStep: inline chips → FilterPanel Popover alongside search bar
  - VenueStep: same pattern, filter chips in Popover
  - CoffinsStep (D-F): grid-sidebar → wide-form (full-width 4-col grid), filters in Popover
  - WizardLayout: added `wide-form` variant (maxWidth lg, single column) for card grids
  - FilterPanel stories: Default, WithActiveFilters, SelectFilters, CustomLabel
- **Batch 4: Step Simplifications (D-D, D-G)**
  - ProvidersStep (D-D): removed selection state, Continue button, radiogroup pattern. Clicking a provider card triggers navigation directly. Stories updated.
  - CoffinDetailsStep (D-G): removed all customisation (handles, lining, nameplate, OptionSection, ProductOption/CoffinDetailsStepValues types). Simplified to coffin profile + Continue CTA. Changed from detail-toggles to centered-form layout. Stories simplified.
  - Updated CoffinDetailsStep index.ts re-exports
- **Batch 5: ArrangementDialog organism (D-E)**
  - New ArrangementDialog organism: MUI Dialog with two internal steps
  - Step 1 (preview): ProviderCardCompact, package summary with sections/items/total, "What happens next" checklist
  - Step 2 (auth): SSO buttons, email, progressive disclosure for details, verification code, terms
  - Parent controls step state + auth form values; dialog has back arrow and close button
  - Stories: Default (full flow), AuthStep, AuthDetails, PrePlanning
  - PreviewStep + AuthGateStep kept for now, to be deprecated once dialog is wired in

**Decisions made:**
- All 8 iteration decisions now implemented: D-A through D-H

**Quality passes:**
- Ran 3 parallel audits (FilterPanel, ArrangementDialog, all reworked steps)
- FilterPanel: 4 P0 + 2 P1 fixed (forwardRef, useId, aria-controls, dialog role, label prop, scroll)
- ArrangementDialog: 3 P0 + 2 P1 fixed (forwardRef, focus management, aria-live, semantic tokens, Link atom)
- Sticky headers: responsive padding match + top breathing room (pt: 2)
- ProvidersStep: role="list", semantic map token
- VenueStep: aria-label on search, semantic map token
- CoffinDetailsStep: form wrapper added

**Remaining P1/P2 (for next session):**
- VenueStep/CoffinsStep radiogroup arrow-key navigation (P1)
- ArrangementDialog step number badge hardcoded font size/weight (P1)
- ArrangementDialog mobile fullscreen treatment (P1)
- CoffinDetailsStep centered-form width may be tight for coffin images (P2)
- CTA alignment inconsistency VenueStep vs CoffinsStep/CoffinDetailsStep (P2)
- ArrangementDialog missing story variants: verify, loading, errors, overflow (P2)

**Open questions:**
- PreviewStep + AuthGateStep: deprecate/remove once ArrangementDialog fully replaces them in the flow
- User to review all steps in Storybook and report any visual issues still present

**Next steps:**
- User review in Storybook — note any remaining visual issues
- Fix remaining P1s (radiogroup keyboard nav, dialog mobile fullscreen)
- Wire ArrangementDialog into PackagesStep flow
- Component registry updates for FilterPanel + ArrangementDialog

---

### Session 2026-03-29c — Grooming pass: critique/harden/polish all 15 steps

**Agent(s):** Claude Opus 4.6 (1M context)

**Work completed:**
- **Full grooming pass across all 15 wizard steps** — applied critique (UX design review), harden (edge cases/error states), and polish (visual alignment/copy/code) frameworks.
- **[P0] CrematoriumStep bug fix:** `<option>` elements replaced with `<MenuItem>` — the MUI `<TextField select>` requires MenuItem children, not native option elements. The priority dropdown was non-functional.
- **[P1] Double-submit prevention:** Added `if (!loading) onContinue()` guard to all form `onSubmit` handlers across steps 1, 5, 6, 7, 8, 9, 10, 11, 12, 14 (10 steps with forms). Prevents keyboard Enter re-submission during async loading.
- **[P1] Accessibility — aria-busy:** Added `aria-busy={loading}` to all form elements so screen readers announce processing state.
- **[P1] Error colour normalisation:** Replaced `color="error"` (red #BC2F2F) with `var(--fa-color-text-brand)` (copper #B0610F) across 7 steps (ProvidersStep, PackagesStep, VenueStep, CrematoriumStep, CemeteryStep, CoffinsStep, PaymentStep). Per D024, FA uses warm copper for errors rather than aggressive red.
- **[P2] Grief-sensitive copy:** "Has the person died?" → "Has this person passed away?" (IntroStep). "About the person who died" → "About the person who has passed" (DateTimeStep).
- **[P2] Results count copy:** "Showing results from X providers" → "X providers found" (ProvidersStep).
- **[P2] Empty state guidance:** Added actionable guidance text to empty states in ProvidersStep, PackagesStep, VenueStep, CoffinsStep ("Try adjusting..." copy).
- **Steps that passed with no issues:** PreviewStep (4), SummaryStep (13), ConfirmationStep (15) — all clean.
- **IntroStep critique score: 35/40 (Good)** — full heuristic scoring completed as reference.
- **D034 implemented:** Form error styling unified to copper end-to-end. MuiOutlinedInput error border/ring, MuiFormHelperText error text, MuiFormLabel error state (neutral per D024), ToggleButtonGroup error border — all now use copper (#B0610F). `palette.error.main` remains red for non-form uses.
- **Tagged `v0.1-wizard-groomed`** — safe rollback point before user review checkpoint.
- **Roadmap documented** in persistent memory (`project_roadmap.md`) with 9 phases, checkpoint gates, and guiding principles.

**Decisions made:**
- D034: Form error styling uses copper across theme (MuiOutlinedInput, MuiFormHelperText, MuiFormLabel, ToggleButtonGroup). `palette.error.main` stays red for destructive buttons/system alerts.
- User review checkpoint required before integration — tagged `v0.1-wizard-groomed` as rollback point.

**Open questions:**
- None

**Next steps:**
- Feedback iteration Batch 1 (next session)

---

### Session 2026-03-29d — User review checkpoint + iteration planning

**Agent(s):** Claude Opus 4.6 (1M context)

**Work completed:**
- **D034 implemented:** Form error copper styling unified across theme (MuiOutlinedInput, MuiFormHelperText, MuiFormLabel, ToggleButtonGroup).
- **Tagged `v0.1-wizard-groomed`** — safe rollback point before feedback iteration.
- **Roadmap documented** in persistent memory (`project_roadmap.md`).
- **User review checkpoint completed.** User reviewed all 15 steps in Storybook and provided detailed feedback across every step.
- **Iteration plan created** at `.claude/plans/zany-jingling-lynx.md` — 7 batches, ~6-8 sessions estimated.
- **All 8 design decisions resolved** (D-A through D-H): display3 headings everywhere, 420px fixed left column, Popover filters, click-to-navigate (no Continue buttons on selection steps), two-step modal for preview+auth, full-width coffin grid, remove coffin customisation for now, defer map pins.

**Key feedback themes:**
- ToggleButtonGroup: spacing tight, content misaligned, selected border not showing (CSS specificity bug)
- List-map layout: needs fixed-width left column, scrollable list with fixed header, no gap above map
- New FilterPanel component needed (reusable across providers, venues, coffins)
- PreviewStep + AuthGateStep consolidation into two-step modal
- CoffinDetailsStep: remove customisation, simplify to details + CTA
- Several copy and spacing issues across steps

**Decisions made:**
- D-A: `display3` heading everywhere (brand warmth)
- D-B: 420px fixed left column in list-map layout
- D-C: FilterPanel uses Popover (MVP), Drawer for mobile later
- D-D: Click-to-navigate on ProvidersStep (remove selection state + Continue)
- D-E: Remove standalone PreviewStep + AuthGateStep, use two-step ArrangementDialog
- D-F: CoffinsStep full-width grid with FilterPanel button
- D-G: Remove coffin customisation, note as future enhancement
- D-H: Map pins deferred

**Open questions:**
- None

**Next steps:**
- Start Batch 1: Atom + Template Foundation (ToggleButtonGroup fixes, heading standardisation, spacing normalisation)
- Plan file: `.claude/plans/zany-jingling-lynx.md`

---

### Session 2026-03-29b — Wizard steps 5-15 (complete flow)

**Agent(s):** Claude Opus 4.6 (1M context)

**Work completed:**
- **Step 5 — AuthGateStep:** Centered-form, 3 progressive sub-steps (SSO/email → details → verify). Phone optional when email-only. Benefit framing ("Save your plan"). Audit 18/20, P1 fixed (responsive name fields).
- **Step 6 — DateTimeStep:** Centered-form, two fieldset sections (name + scheduling). Grief-sensitive labels ("Their first name"). Date/time radios + Autocomplete for religion (22 options). Save-and-exit CTA.
- **Step 7 — VenueStep:** Venue card grid (1-2 col) with search/filters. Inline venue detail (Collapse) with features + religions. Service toggles (photo, streaming, recording) via AddOnOption. VenueCard extended with selected + ARIA passthrough props.
- **Step 8 — CrematoriumStep:** Single crematorium confirmation card (most common) or multi-card grid. Witness question personalised with deceased name. Special instructions via progressive disclosure textarea.
- **Step 9 — CemeteryStep:** Triple progressive disclosure (have plot? → choose cemetery? → card grid). Dependent field resets. "Provider can arrange this" shortcut.
- **Step 10 — CoffinsStep:** 3-col card grid with category/price filters. "Most Popular" badge (Rec #10). Pagination support. Australian terminology ("coffin").
- **Step 11 — CoffinDetailsStep:** Coffin profile (image + specs grid) + 3 product option RadioGroups (handles, lining, nameplate) with branded selected state. Price: "Included" or "+$X".
- **Step 12 — AdditionalServicesStep:** Merged from optionals + extras (Rec #2). Section 1: complimentary (dressing, viewing, prayers, announcement). Section 2: paid (catering, music, bearing, newspaper). Multi-level progressive disclosure.
- **Step 13 — SummaryStep:** Accordion sections with edit buttons, dl/dt/dd definition lists, total bar (aria-live), share button. Pre-planning: "Save your plan" / at-need: "Confirm".
- **Step 14 — PaymentStep:** ToggleButtonGroup for plan (full/deposit) + method (card/bank). PayWay iframe slot. Bank transfer details display. Terms checkbox. Security reassurance.
- **Step 15 — ConfirmationStep:** Terminal page, no back/progress. At-need: "submitted" + callback info. Pre-planning: "saved" + return-anytime. Muted success icon, next-steps links.

**Approach:** Same as previous session — first pass build + quick audit + P0/P1 fixes only. Grooming pass comes later.

- **Layout fixes:** Corrected 3 steps that had wrong WizardLayout variants:
  - VenueStep: centered-form → **list-map** (venue cards left, map slot right — matches ProvidersStep)
  - CoffinsStep: centered-form → **grid-sidebar** (filter sidebar left, card grid right)
  - CoffinDetailsStep: centered-form → **detail-toggles** (coffin profile left, option selectors right)

**Decisions made:**
- VenueCard extended with selected/ARIA props (same pattern as ProviderCard from step 2)
- CoffinDetailsStep uses OptionSection helper component for DRY RadioGroup rendering
- SummaryStep uses Accordion not Paper for sections (per spec's collapsible requirement)
- PaymentStep uses slot pattern for PayWay iframe (cardFormSlot prop)

**Open questions:**
- None

**Next steps:**
- All 15 wizard steps are now first-pass complete (steps 1-15) with correct layouts
- Grooming pass: /critique, /harden, /polish, /normalize across all steps
- Retroactive review backlog still pending
- Integration: routing, state management, GraphQL queries

---

### Session 2026-03-29 — Wizard Phase 0 through Phase 4 (foundation + steps 1-4)

**Agent(s):** Claude Opus 4.6 (1M context)

**Work completed:**
- **Phase 0 — Foundation components:**
  - WizardLayout template: 5 layout variants, nav slot, sticky help bar, back link, progress stepper + running total, `<main>` landmark
  - Collapse atom: thin MUI Collapse wrapper with unmountOnExit
  - ToggleButtonGroup atom: exclusive single-select with fieldset/legend a11y, FA brand styling
- **Phase 1 — IntroStep (step 1):**
  - Centered-form layout, forWhom + hasPassedAway with progressive disclosure
  - Auto-sets hasPassedAway="no" for "Myself", grief-sensitive copy adapts
  - Audit 18→20/20 after fixes (`<main>` landmark, `<form>` wrapper)
- **Phase 2 — ProvidersStep (step 2):**
  - List-map split: provider cards w/ radiogroup + search + filter chips (left), map slot (right)
  - ProviderCard extended with selected prop + HTML/ARIA passthrough
  - Audit 18/20, P1 fixed (radio on focusable Card)
- **Phase 3 — PackagesStep (step 3):**
  - List-detail split: ProviderCardCompact + budget filter + ServiceOption list (left), PackageDetail (right)
  - "Most Popular" badge, mobile Continue button
- **Phase 4 — PreviewStep (step 4):**
  - Informational review, "What happens next" numbered checklist
  - Pre-planning variant shows "Explore other options" tertiary CTA

**Approach:** First pass of all steps (build + quick audit + P0/P1 fixes only), then grooming pass (critique/harden/polish/normalize) across the full flow.

**Decisions made:**
- Templates at `src/components/templates/`, Pages at `src/components/pages/`
- ProviderCard/ServiceOption: ARIA passthrough for radiogroup patterns
- First-pass approach: build all steps, then groom — user confirmed

**Open questions:**
- None

**Next steps:**
- Step 5 (Auth Gate) — centered-form layout, account creation/login
- Continue through remaining steps (6-18)
- Retroactive review backlog still pending

---

### Session 2026-03-27b — Retroactive review Phase 1 + 2.1, wizard planning

**Agent(s):** Claude Opus 4.6 (1M context)

**Work completed:**
- **Retroactive review (morning housekeeping):**
  - Phase 1.1: Atoms normalize — 3 fixes (Input spacing, Card focus token, unused import)
  - Phase 1.2: Atom audits — Button 20/20, Input 20/20, Card 18→20/20 (2 P1 fixes: keyboard activation + responsive padding)
  - Phase 2.1: Molecules normalize — 7 fixes (StepIndicator timing/spacing/font, ProviderCardCompact star colour + icon size)
- **Wizard flow documentation review:**
  - Read flow-spec.md (854 lines), flow-definition.yaml (616 lines), 3 representative step YAMLs
  - Saved reference memories for flow documentation structure and project context
- **Layout analysis:**
  - Analysed 5 layout reference images in /documentation/layouts/
  - Identified 5 layout variants: Centered Form, List+Map, List+Detail, Grid+Sidebar, Detail+Toggles
  - Mapped each layout to specific wizard steps
  - Saved layout reference to memory
- **Implementation plan:**
  - Created comprehensive plan at .claude/plans/validated-brewing-matsumoto.md
  - Phase 0 (foundation): WizardLayout template, Collapse atom, ToggleButtonGroup atom
  - Phases 1–7: Steps in build order with component dependencies
  - ~11 new components, ~16 sessions estimated
  - Plan approved by user, updated with layout variants

**Decisions made:**
- Step pages live at `src/components/pages/` (new atomic tier)
- CardSelectionGrid extracted after step 3 (not upfront)
- Build from specs, Figma for structural shape only
- Steps are pure presentation (props in, callbacks out) — no routing/state/GraphQL yet

**Open questions:**
- Hardcoded fontWeight on price typography varies across molecules — still unresolved from normalize

**Next steps:**
- Start Phase 0: Build WizardLayout template (5 variants), Collapse atom, ToggleButtonGroup atom
- Then Phase 1: Step 1 (Intro) — first wizard step

---

### Session 2026-03-27b (earlier) — Retroactive review Phase 1 + 2.1

**Agent(s):** Claude Opus 4.6 (1M context)

**Work completed:**
- **Phase 1.1 — Atoms normalize:** Scanned all 11 atoms across 7 dimensions. Fixed 3 issues: Input raw px spacing → MUI units, Card focus-visible token → CSS var, removed unused Theme import.
- **Phase 1.2 — Atom audits (high priority):** Button 20/20, Input 20/20, Card 18/20 → fixed 2 P1s → 20/20.
  - Card P1 fix: Added Enter/Space keyboard activation for interactive cards (WCAG 2.1.1)
  - Card P1 fix: Responsive padding — 16px mobile / 24px desktop (convention alignment)
- **Phase 2.1 — Molecules normalize:** Scanned all 8 molecules across 7 dimensions. Fixed 7 issues:
  - StepIndicator: transition 300ms → 150ms, raw px → MUI spacing, borderRadius → token, mobile font 10px → 11px (D020 floor)
  - ProviderCardCompact: star colour → warning.main (match ProviderCard), meta icon 16px → 14px (match tier)

**Decisions made:**
- None (all fixes are convention enforcement, no new decisions)

**Open questions:**
- Hardcoded fontWeight on price typography varies across molecules (500 vs 600) — intentional design variation or normalize?
- Remaining atom audits (Typography, Badge, Chip, Switch, Radio, IconButton, Divider, Link) — all low/medium priority wrappers, likely 20/20. Run if time permits.

**Next steps:**
- Phase 2.2: Audit priority molecules (ServiceOption, AddOnOption, ProviderCardCompact)
- Phase 3: Organisms normalize + audit (Navigation, ServiceSelector, FuneralFinderV3)
- Phase 4: Cross-cutting (adapt, typeset, preflight)
- New component work as user directs

---

### Session 2026-03-27a — Workflow improvement (5-phase infrastructure upgrade)

**Agent(s):** Claude Opus 4.6 (1M context)

**Work completed:**
- **Phase 1A:** Archived session log — moved 25 old sessions to `docs/memory/archive/sessions-through-2026-03-26.md`, trimmed active log from 1096 to 91 lines
- **Phase 1B:** Documented token access convention as D031 — `theme.palette.*` for semantic tokens, `var(--fa-*)` for component tokens. Fixed Badge.tsx colour map inconsistency (unified to CSS vars). Updated component-conventions.md.
- **Phase 2:** Added ESLint v9 (flat config) + Prettier. Installed `eslint`, `@eslint/js`, `typescript-eslint`, `eslint-plugin-react`, `eslint-plugin-react-hooks`, `eslint-plugin-jsx-a11y`, `eslint-config-prettier`, `prettier`. Ran initial format pass across all 54 .tsx files. Fixed 5 empty interface warnings (Switch, Radio, Divider, IconButton, Link). Added `lint`, `lint:fix`, `format`, `format:check` scripts.
- **Phase 3:** Created 7 new impeccable-adapted skills: `/polish`, `/harden`, `/normalize`, `/clarify`, `/typeset`, `/quieter`, `/adapt`. Downloaded Vercel reference docs (web-design-guidelines, react-best-practices). Updated `/audit` and `/review-component` with optional Vercel references. Total skills: 19.
- **Phase 4:** Added Husky v9 + lint-staged for pre-commit automation. ESLint + Prettier auto-run on staged files. Updated `/preflight` skill with ESLint and Prettier checks (now 8 checks total).
- **Phase 5:** Added Vitest v4 + jsdom + @testing-library/react. Created `vitest.config.ts` and test setup. Created `/write-tests` skill for test generation guidance. Added `test` and `test:watch` scripts. Note: `@storybook/test-runner` deferred — requires Storybook 10+ (we have 8).

**Decisions made:**
- D031: Token access convention — theme accessors for semantic, CSS vars for component (see decisions-log)
- ESLint story files exempt from `react-hooks/rules-of-hooks` and `no-console` (Storybook render pattern)
- Empty `interface extends` changed to `type =` for ESLint compliance (5 wrapper atoms)
- Storybook test-runner deferred until Storybook upgrade to v10
- Prettier printWidth set to 100 (matching observed code style)

**Also completed:**
- Created `docs/reference/component-lifecycle.md` — 10-stage quality gate sequence (build → QA → polish → present → iterate → normalize → preflight → commit)
- Created `docs/reference/retroactive-review-plan.md` — plan to review 30+ existing components (~3.5 sessions)
- Updated `/build-atom`, `/build-molecule`, `/build-organism` to include internal QA stages automatically
- Added lifecycle reference as CLAUDE.md critical rule #8

**Open questions:**
- Storybook upgrade to v10 — would unlock `@storybook/test-runner` for CI test execution
- FuneralFinder version decision (v1/v2/v3) — needed before retroactive review of organisms
- Review depth — P0/P1 only (faster) or include P2?

**Next steps (pick up in next session):**
- Start retroactive review: `/normalize atoms` → `/audit` high-priority atoms
- Interleave with new component work if preferred
- Use `/write-tests` on interactive components as time permits

---

### Session 2026-03-26f — FuneralFinder v3 build + polish

**Agent(s):** Claude Opus 4.6 (1M context)

**Work completed:**
- Created FuneralFinderV3 — clean vertical form based on user's Figma layout (5919:29445), restyled to FA design system
- Two side-by-side StatusCards (Immediate Need default-selected / Pre-planning), stack on mobile
- Standard card container (surface.raised, card shadow) — initially built with glassmorphism, user redirected to standard palette
- Overline section labels (text.secondary) for "How Can We Help", "Funeral Type", "Location"
- Standard outlined fields (white bg, neutral border, brand border on focus, no focus ring per user request)
- Location input with LocationOnOutlined pin icon
- CTA "Find Funeral Directors →" always active — validates on click, scrolls to first missing field
- Dividers after header and before CTA for visual rhythm
- Funeral type options: same as V2 + "Show all options"
- WAI-ARIA roving tabindex on radiogroup, aria-labelledby via React.useId()
- Semantic tokens throughout (border-brand, surface-warm, text-brand, interactive-focus, text-disabled)
- Error messages conditionally rendered in aria-live regions (brand copper tone — gentle validation)
- First pass scored Critique 33/40, Audit 13/20 → iterated on all findings → re-audit 18/20
- Polish pass: revised copy, fixed spacing, defaults, label rename

**Decisions made:**
- Status cards replace V2's step-circle + dropdown — simpler, more visual, side-by-side on desktop
- Standard design system styling (user clarified Figma was for structure only, not colour scheme)
- "Immediate Need" selected by default — most common use case, status error essentially unreachable
- Section renamed from "Current Status" (programmatic) to "How Can We Help" (warm, human)
- Copy: "A recent loss or one expected soon" — "expected soon" differentiates from pre-planning gently
- Copy: "Planning ahead for yourself or a loved one" — "planning ahead" reinforces non-urgency
- No sequential unlock — all fields accessible immediately
- CTA always active — validates on click, scrolls to missing field
- Form simplified to 3 fields (status, funeral type, location) vs V2's 4
- Focus ring suppressed on Select/Input per user requirement — status cards retain focus-visible
- Error colour uses text.brand (copper) not feedback.error (red) — intentional for funeral context

**Open questions:**
- Location autocomplete integration still pending across all versions
- Decision: V1 vs V2 vs V3 for production

**Next steps:**
- User to review final V3 in Storybook
- If V3 chosen: location autocomplete, possible further refinements

---

### Session 2026-03-26e — FuneralFinder v2 polish + consistency fixes

**Agent(s):** Claude Opus 4.6 (1M context)

**Work completed:**
- Fixed location input styling to match select fields (border color, hover, disabled, error states)
- Added `active` prop to StepCircle — step 1 uses brand-500 primary fill by default
- Aligned Input with full selectSx overrides (bgcolor, disabled opacity+dashed, error border)
- Investigated systemic Input vs Select visual differences — confirmed issue is component-local overrides, not theme

**Decisions made:**
- Custom field styling kept within FuneralFinderV2 (intentional divergence from theme for this component's design)
- Step 1 circle uses primary fill since it's always active — visual "start here" signal

**Next steps:**
- v2 is feature-complete and polished — ready for user review in Storybook
- Decision pending: v1 vs v2 for production
- If v2 chosen: add location autocomplete, write flow logic reference doc

---