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-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

Open questions:

• PreviewStep + AuthGateStep: deprecate/remove once ArrangementDialog fully replaces them in the flow

Next steps:

• Wire ArrangementDialog into PackagesStep flow (replace standalone preview + auth)
• Remaining copy/spacing polish across steps
• Component registry updates

---

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

---