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-04-01 — FuneralFinder V4, HomePage V3/V4, Footer restyle

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

Work completed:

• FuneralFinder V4 (new organism): Based on V2 with major changes:
  • 3 numbered steps only (lookingTo, planningFor, funeralType) — location is ungated, no step number
  • No heading/subheading — compact widget for embedding in heroes
  • Refined step indicators: 48px circles matching input height, outline-to-fill + tick animation, no connector lines
  • Labels above, circle + input on same row centred
  • Location field full-width, disabled until step 3 complete
  • "Search" CTA, inline copper error messages per field (D034)
  • Archived in Storybook under Archive/FuneralFinder V4
• FuneralFinder V3 updates:
  • Removed default subheading (now optional)
  • Heading font weight bumped from 400 → 600 (semibold) for more presence
  • Heading copy: "Find your local providers"
  • CTA: "Search Local Providers"
• HomePage V1 archived: Original split-hero layout moved to Archive/HomePage V1
• HomePage V2 archived: Full-bleed hero version broken out as Archive/HomePage V2
• HomePage V3 (new, archived): Based on V2 with:
  • hero-3.png background image
  • Updated hero copy + bullet-point subheading ("Transparent pricing · No hidden fees · Arrange 24/7")
  • Real venue photos in discover section provider cards
  • Map placeholder image from brandassets
  • Scrolling partner logo bar (9 transparent logos, greyscale, edge-to-edge, continuous loop)
  • CTA section: warm gradient bg, text button, no dividers, wider container
  • Increased section spacing throughout (~25% more breathing room)
  • Hero top padding increased 40%
• HomePage V4 (new, archived): Same as V3 but uses FuneralFinder V4 via finderSlot prop. Wider container (620px) for stepped form.
• HomePage component updates:
  • Added finderSlot prop — allows swapping the finder widget without changing the component
  • Increased spacing: hero heading/subtext gap, finder-to-discover gap, all section padding
  • Map container: absolute positioning for dynamic height matching card stack
  • CTA section: gradient bg (brand.100 → surface.warm), text button, no dividers
  • Partner logos: lighter treatment (40% opacity, brightness lift), 48→55px height, 96px gap, no hover interaction
• Footer restyle: Changed from dark espresso (brand.950) to light grey (surface.subtle) matching the header. All text colours flipped to dark-on-light. Logo no longer needs inverse filter.

Decisions made:

• FuneralFinder V4 step indicators use 48px circles (same height as inputs) for visual alignment
• Location field in V4 is gated behind step 3 completion but not numbered
• Inline error messages replace single bottom error — each field shows its own copper-coloured message
• Footer matches header bg colour (surface.subtle) for visual consistency
• Partner logos: only transparent PNGs/WebPs used, opaque logos excluded
• finderSlot prop added to HomePage for widget flexibility without component duplication

Open questions:

• HomePage V4 finder width may need further adjustment — looked narrow in Storybook preview panel (620px container, may need 680-720px)
• Which HomePage version (V3 with FuneralFinderV3 or V4 with FuneralFinderV4) will be the production version?
• FuneralFinder V4 step indicator design — user liked the direction but may want further iteration

Next steps:

• Resolve HomePage V4 finder width — test at wider viewport or increase container
• Decide on production HomePage + FuneralFinder version
• Build next components/pages as needed
• Phase 4 remaining: /typeset sample, /preflight full codebase

---

Session 2026-03-31d — Filters, control bars, UnverifiedProviderStep, HomePage V2

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

Work completed:

• Phase 4 /adapt reviews: Ran responsive adaptation audits on Navigation, Footer, ProviderCard, VenueCard. Fixed P0/P1 touch target issues in Navigation (hamburger + drawer items minHeight 44px) and Footer (all links minHeight 44px, tagline responsive maxWidth). ProviderCard/VenueCard skipped — meta rows aren't interactive, card itself is the touch target.
• ProvidersStep structured filters: Replaced generic ProviderFilter[] chip array with ProviderFilterValues interface containing 5 filter controls inside FilterPanel/DialogShell:
  • Location: Autocomplete multiple + freeSolo with chip-in-input pattern (real estate site UX — chip sits inside the search field with X to clear)
  • Service tradition: Autocomplete with type-to-search, 21 options ('None' first, then alphabetical traditions)
  • Funeral type: Chip multi-select with wrapping layout (6 types from spec)
  • Verified providers / Online arrangements: Switch toggles
  • Price range: Dual-knob slider + compact editable inputs (matching CoffinsStep)
• FilterPanel molecule updates: "Done" → "Apply", "Clear all" moved to footer as "Reset filters" text button
• DialogShell padding: px 3 → 5 (12px → 20px) for breathing room
• Filter panel UX iterations (3 rounds):
  • Section headings: labelLg + fontWeight: 600 for visual hierarchy
  • Price inputs: compact fontSize: 0.875rem + tighter padding
  • Funeral type chips: wrap layout (not horizontal scroll) — stays within bounds
  • Price slider: px: 2.5 accommodates MUI thumb radius, no overflow
  • Active filter count includes location search; reset clears search too
• VenueStep structured filters: Same FilterPanel pattern as ProvidersStep with venue-specific controls:
  • Location (chip-in-input), Venue type (7 chips: Chapel, Church, Cathedral, Outdoor Venue, Hall/Room, Mosque, Temple), Additional services (Video Streaming + Photo Display switches), Service tradition (autocomplete)
• Control bar (both pages): Below search, single line:
  • [Filters] left, [↕ Recommended] right (compact menu button with dropdown)
  • Sort options: Recommended, Nearest, Price: Low to High, Price: High to Low
  • Results count on own line below with breathing room
• List/Map view toggle: Floating overlay in top-left of map panel (paper bg + shadow). Text-labelled: "List" / "Map" with icons. Follows Airbnb/Domain pattern — contextually placed where the map lives.
• New types: ProviderSortBy, VenueSortBy, ListViewMode, VenueFilterValues, VenueTypeOption
• UnverifiedProviderStep (new page): list-detail layout for scraped provider listings. Left: ProviderCardCompact + "Listing" badge + available info + verified recommendations. Right: warm header band + enquiry CTA. 4 story variants (Default, MinimalData, NoData, NoRecommendations). Graceful degradation when data missing.
• HomePage V2: Full-bleed hero with parsonshero.png, FuneralFinder inside hero (overlaps into white below), "See what you'll discover" map+ProviderCardCompact section, stripped features (no cards/circles — just icons+text), editorial alternating testimonials, minimal FAQ accordion, simplified CTA. Multiple iteration rounds on hero positioning.
• New types: TrustStat, FeaturedProvider, ProviderDetail, RecommendedProvider

Decisions made:

• "Service tradition" as the label for religion/faith filter — neutral, user-centric, covers religious and non-religious
• 'None' as first tradition option
• Location uses Autocomplete chip-in-input pattern (Domain/realestate.com.au style)
• Funeral type chips wrap (stack) rather than horizontal scroll — clearer at dialog width
• DialogShell px: 5 is a global change — all dialogs get more breathing room
• FilterPanel footer: "Reset filters" + "Apply" replaces header "Clear all" + footer "Done"
• List/Map toggle lives on the map panel (floating overlay), not in the control bar — frees space, contextually placed
• Sort uses compact menu button (not TextField select) — same visual weight as Filters button
• Unverified providers use list-detail layout (same as PackagesStep) for consistency
• Unverified CTA is "Make an Enquiry" (not "Make an Arrangement") — honest framing
• HomePage V2 hero: text top-aligned, FuneralFinder inside hero with negative mb overlap
• Features section: no cards/circles — just icons + text for authentic feel
• Hero gradient: 55% opacity at top for readability on bright sky

Open questions:

• HomePage V2 still a first pass — may iterate further on discover section, testimonials, etc.
• UnverifiedProviderStep paused — may revisit for enquiry form fields

Next steps:

• Continue user feedback on remaining pages
• Phase 4 remaining: /typeset sample, /preflight full codebase
• Add progress bar + cart stories to more page stories
• Update component-registry.md with UnverifiedProviderStep

---

Session 2026-03-31c — PaymentStep/ConfirmationStep review + progress bar + CartButton

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

Work completed:

• Organism normalize pass (Phase 3): Scanned all 6 organisms. Fixed FuneralFinderV3 transition timing (200ms → 150ms ease-in-out), added autodocs tag to V3 stories. Navigation audit 18/20, ServiceSelector 20/20.
• Navigation P1 fix: Logo wrapper changed from div[role=link] to proper <a> tag for keyboard accessibility.
• PaymentStep feedback (5 items): Divider under subheading, lock icon alignment, ToggleButtonGroup align + direction props (centre-aligned payment options, vertical payment method stack), checkbox alignment fix.
• ToggleButtonGroup atom enhanced: New align (start/center) and direction (row/column) props. Description text bumped from text.secondary to text.primary.
• SummaryStep: Save button → text variant (matches other pages), centred.
• Cross-page heading spacing: All wizard pages mb: 1 → mb: 2 on display3 heading.
• ConfirmationStep redesign: Animated SVG tick (circle draws then checkmark), "What happens next" warm card with bullet points, contact phone as prop, link-based secondary actions.
• VenueStep + ProvidersStep: Sticky search bar padding fix, off-white bg behind card lists.
• IntroStep, CemeteryStep, CrematoriumStep, DateTimeStep: Dividers under subheadings.
• CoffinsStep: h4 heading (matches list layouts), sidebar headings h5 → h6.
• CartButton molecule (new): Outlined pill trigger with receipt icon + "Your Plan" + formatted total in brand colour. Click opens DialogShell with items grouped by section via LineItem, total row, empty state. Mobile collapses to icon + price.
• WizardLayout: Removed STEPPER_VARIANTS whitelist — stepper bar now renders on all variants when props provided. Stepper centred at 700px max-width, cart hugs right.
• StepIndicator: Desktop label fontSize bumped to 0.875rem for readability.
• Prop threading: progressStepper + runningTotal added to DateTimeStep, VenueStep, SummaryStep, PaymentStep.
• Style Dictionary: Auto-generate tokens.d.ts on build, fixed TS unused imports.

Decisions made:

• ToggleButtonGroup align and direction are opt-in props — existing usages unchanged
• ConfirmationStep contact phone is now a prop (default 1800 987 888), no more hardcoded placeholder
• WizardLayout stepper bar shows on ANY variant when props provided (StepperBar returns null when empty)
• CartButton is a molecule (not organism) — self-contained trigger + dialog, same pattern as FilterPanel
• Stepper bar layout: stepper centred at maxWidth 700px, cart hugs right edge

Open questions:

• PaymentStep CTA is right-aligned — all other pages use full-width. Should it match?
• Progress bar stories should be added to more page stories (currently only DateTimeStep has them)

Next steps:

• Continue user feedback/edits on remaining pages
• Add progress bar + cart to remaining page stories
• Retroactive review Phase 3 organisms: Navigation P2s still pending (hardcoded fontSize, drawer width)
• Update component-registry.md with CartButton

---

Session 2026-03-31b — CoffinDetailsStep rewrite + AdditionalServicesStep split

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

Work completed:

• CoffinDetailsStep rewrite — two-panel detail-toggles layout with gallery + specs (left), name + description + colour swatches + allowance-aware pricing + CTA (right). Colour selection doesn't affect price. Allowance logic: fully covered / partially covered / no allowance.
• SummaryStep rewrite — visual cart layout replacing accordion text lists:
  • Arrangement details section at top (arranger, deceased, tradition, dates, times)
  • Compact image cards for provider, venue, crematorium, coffin with location pins
  • Allowance display: "Included in your package" (fully covered) vs price/allowance/remaining breakdown
  • Checklist for included services, priced list for extras (consistent tick logic)
  • Share dialog: "Share this plan" opens DialogShell with multi-email input + confirmation
  • Full-width CTA, deposit deferred to PaymentStep
• AdditionalServicesStep split into two pages:
  • IncludedServicesStep (new) — services included in the package at no cost. Dressing, viewing (with same-venue sub-option inside card), prayers/vigil, funeral announcement.
  • ExtrasStep (new) — optional paid extras for lead generation. Catering, music (flat inline live musician toggle + musician type), coffin bearing (toggle + bearer preference radio), newspaper notice. POA support via priceLabel. Tally of priced selections.
• AddOnOption molecule enhanced:
  • children prop — sub-options render inside the card boundary (below divider) when checked, eliminating nested card "Russian doll" pattern
  • priceLabel prop — custom text like "Price on application" in brand copper italic
• AdditionalServicesStep removed — replaced by the two new pages
• All quality checks passing (TypeScript, ESLint, Prettier)
• Playwright visual verification of all key scenarios

Decisions made:

• Split AdditionalServicesStep into two pages for clearer UX distinction between free inclusions and paid extras
• Sub-options render inside parent card (flat hierarchy) instead of nested cards
• Coffin bearing changed from always-visible radio to toggle + sub-options (consistent with other items)
• bearing field split into bearing: boolean + bearerType for toggle pattern
• Extras page is lead-gen: signals interest, not firm commitment. Director follows up.
• POA items show "Price on application" in brand copper italic
• Copy refined through brand lens — no transactional language ("toggle on"), warm professional tone

Open questions:

• None

Next steps:

• Continue page feedback: PaymentStep, ConfirmationStep
• Retroactive review Phase 3 (organisms) still pending
• Batch a11y fix (aria-describedby + aria-invalid) deferred

---

Session 2026-03-31b — CoffinDetailsStep rewrite: product detail layout

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

Work completed:

• CoffinDetailsStep complete rewrite — transformed to match VenueDetailStep two-panel pattern:
  • Left panel: ImageGallery (hero + thumbnails), product details as semantic dl list (bold label above value)
  • Right panel (sticky): coffin name (h1), description, colour swatch picker, price with allowance-aware display, CTA, save-and-exit
  • Colour picker: circular swatches (36px), aria-pressed, controlled via selectedColourId/onColourChange, does not affect price
  • Allowance pricing logic: fully covered (allowance >= price) → "Included in your package allowance — no change to your plan total." / partially covered → shows "$X package allowance applied" + "+$Y to your plan total" in brand colour / no allowance → price only with extra spacing to CTA
  • Removed: info bubble (redundant with allowance impact text), priceNote prop, termsText prop, old horizontal specs grid, CoffinAllowance type
  • Added: CoffinColour type, allowanceAmount prop, onAddCoffin callback (replaces onContinue)
  • A11y: fixed heading hierarchy (price as <p> not <h5>, Product details as <h2>) — 0 violations
• Stories: FullyCovered, PartiallyCovered, NoAllowance, NoColours, Minimal, PrePlanning, Loading
• Playwright visual verification of all key scenarios
• All quality checks passing (TypeScript, ESLint, Prettier)

Decisions made:

• Allowance impact is computed from allowanceAmount vs coffin.price — no remaining balance tracking (out of scope)
• Info bubble removed from detail page (redundant) — kept on CoffinsStep browsing page
• Product details as single-column stacked dl (label above value) — more readable than grid

Open questions:

• None

Next steps:

• Continue page feedback: AdditionalServicesStep, SummaryStep, PaymentStep, ConfirmationStep
• Retroactive review Phase 3 (organisms) still pending
• Batch a11y fix (aria-describedby + aria-invalid) deferred

---

Session 2026-03-31a — CoffinsStep rewrite: grid-sidebar ecommerce layout

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

Work completed:

• CoffinsStep complete rewrite — transformed from wide-form card grid into a two-column ecommerce layout matching the live site pattern:
  • Layout: grid-sidebar with viewport-locked independent scrolling (sidebar scrollbar on hover, grid always scrollable)
  • Sidebar: heading, conditional allowance info bubble, category menu with expandable subcategories (Collapse animation, chevron rotation), dual-knob price range slider with editable text inputs (commit on blur/Enter), sort by dropdown (popularity, price asc/desc), clear all filters link, save-and-exit link at bottom
  • Grid: 3-col coffin card grid with CoffinCard internal component — thumbnail hover preview (hover swaps main image, leave reverts), equal-height cards via flex layout, subtle background for white-bg product photos, "Most Popular" badge, colour count text
  • Navigation: card click fires onSelectCoffin(id) to navigate to CoffinDetailsStep — no Continue button
  • Pagination: 20 coffins per page max (pageSize prop, enforced via slice)
• WizardLayout grid-sidebar update — wider sidebar (28%), overflowX: hidden (no horizontal scroll), overflowY: auto at all breakpoints, responsive viewport-lock (desktop only)
• Removed: selectedCoffinId, CoffinsStepErrors, CoffinPriceRange, onContinue, loading props
• Added: onSelectCoffin, CoffinSortBy, pageSize, minPrice/maxPrice, thumbnails/colourCount on Coffin, children on CoffinCategory

Decisions made:

• Card click navigates directly to details (no selection + continue pattern) — matches ecommerce browsing UX
• Categories support one level of subcategories — parent click loads all and expands children, child click refines
• Price slider with editable text inputs — commits on blur/Enter to avoid per-keystroke re-renders
• 20 coffins per page default — enforced in component via slice
• Allowance info bubble is conditional (omit prop = no bubble) — some packages don't have coffin allowances

Open questions:

• None

Next steps:

• Continue page feedback: AdditionalServicesStep, SummaryStep, PaymentStep, ConfirmationStep
• Retroactive review Phase 3 (organisms) still pending
• Batch a11y fix (aria-describedby + aria-invalid) deferred

---

Session 2026-03-30e — Page feedback: VenueServices, Crematorium, Cemetery rewrites

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

Work completed:

• VenueServicesStep (new page): Built step 7c — venue-specific service toggles after VenueDetailStep. Compact venue card at top, availability notices (info cards for unavailable services), AddOnOption toggles with maxDescriptionLines for "Read more" expansion, conditional tally showing total of selected priced services. Flow: VenueStep → VenueDetailStep → VenueServicesStep.
• AddOnOption price colour fix: Changed from text.secondary (grey) to color="primary" (copper) for consistency with all other price displays in the system.
• CrematoriumStep rewrite: Completely rewritten to match live site. Two variants based on funeral type:
  • Service & Cremation: stacked crematorium card (image top, details below) + witness Yes/No/Decide later ToggleButtonGroup
  • Cremation Only: stacked card + "Cremation Only" badge + "Included in Package" info notice, no witness question
  • Removed: multi-card selection grid, priority dropdown, special instructions, crematoriums array prop
  • Card iterated from compact horizontal → more generous horizontal → stacked layout based on user feedback
• CemeteryStep rewrite: Rewritten to match live site:
  • RadioGroups replaced with ToggleButtonGroups (Yes/No/Not sure)
  • Card selection grid replaced with freetext search input (Input atom with search icon)
  • searchSlot prop for parent to inject Google Places or geocoding autocomplete
  • Removed static cemeteries array prop and CemeteryOption type
  • Progressive disclosure preserved: own plot → locate it; no plot → preference? → search

Decisions made:

• Venue services belong on a separate page (not inline on VenueDetailStep or in a dialog) due to content volume per service (long descriptions, future images)
• Crematorium is always pre-selected by provider — no multi-select needed, just confirmation
• "Decide later" / "Not sure" options added as explicit third choice on questions where users may be uncertain — grief-sensitive pattern
• Cemetery search should use real location search (Google Places style), not a static dropdown — we don't maintain a cemetery database
• Stacked card layout (image top) works better than compact horizontal for single confirmation cards with long text

Open questions:

• None

Next steps:

• Continue page feedback: CoffinsStep, AdditionalServicesStep, SummaryStep, PaymentStep, ConfirmationStep
• Retroactive review Phase 3 (organisms) still pending
• Batch a11y fix (aria-describedby + aria-invalid) deferred

---

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

Also completed (continued same session):

• DateTimeStep: Swapped date TextField to Input atom (was missed in session 30b)
• VenueStep rewrite: Simplified to click-to-navigate (like ProvidersStep) — removed Continue, selection state, inline detail, service toggles
• VenueDetailStep (new page): Detail-toggles layout with scrollable left panel (ImageGallery, description, features grid, location map placeholder, address, informational service cards) and right panel (name, meta icons, price + offset note, Add Venue CTA, address, religion chips)
• CoffinDetailsStep: Switched from centered-form to detail-toggles layout (image left, specs/price/CTA right)
• WizardLayout detail-toggles overhaul: Viewport-locked with independent panel scroll, maxWidth 1200px centered, generous padding (px:5), back link inside left panel
• WizardLayout list-map scroll fix: Removed top padding gap between nav and sticky search, heading scrolls away while search/filters stay pinned with divider border
• ImageGallery molecule (new): Hero image + landscape thumbnail strip (4:3 ratio), hover to preview, click to select, keyboard accessible, wired into VenueDetailStep and CoffinDetailsStep
• Checkbox atom (new): FA wrapper with warm gold theming, PaymentStep updated
• Retroactive review Phase 2.2: Audited ServiceOption (13/20), AddOnOption (14/20), ProviderCardCompact (15/20), fixed P0/P1s

Next steps:

• Continue page feedback from user: CrematoriumStep, CemeteryStep, CoffinsStep, AdditionalServicesStep, SummaryStep, PaymentStep, ConfirmationStep
• Venue service selection step (new page — toggles moved from VenueDetailStep)
• Batch a11y fix: aria-describedby + aria-invalid across all wizard steps (deferred per user)
• Retroactive review Phase 3: organisms normalize + audit
• Update component registry with new components (ImageGallery, Checkbox, VenueDetailStep)

---

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

---