
### Session 2026-03-26d — FuneralFinder v2 build

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

**Work completed:**
- Built FuneralFinderV2 from scratch — completely different approach from v1 (quick-form vs stepped wizard)
- 4-step vertical form with 48px numbered circles (brand-200 default → brand-500 completed) and 3px connector lines
- Steps: (1) Intent (3 options), (2) Planning for (conditional auto-set for arrange-now), (3) Funeral type (5 options), (4) Location
- Sequential unlock logic: each step enables only when the previous is filled
- Labels use brand-700 copper when active, text.disabled when locked
- Selects match Input medium height (48px) via py: 14px
- Display serif heading + body2 subheading with full-width divider
- Default contained CTA (copper), disabled until location has 3+ chars
- Trust signal "Free to use · No obligation" below CTA
- Focus rings suppressed (subtle brand-400 border only)
- Full accessibility: role="search", aria-required, aria-label on all fields
- Multiple iteration rounds incorporating user feedback on sizing, alignment, colours, spacing, and layout
- Ran /critique (33/40 Good) and /audit (18/20 Excellent) — fixed all P0/P1 issues

**Decisions made:**
- v2 keeps v1 alongside — both exported from index.ts for comparison
- Step circles use brand-200 warm fill (not neutral grey) for palette cohesion
- "Plan a funeral for someone expected to pass soon" softened to "Plan ahead for someone who is unwell"
- Connector lines use ::after on each StepCircle rather than container ::before (starts from circle bottom, not above)
- Location input uses no icon, matches select styling (py: 14px, fontSize: 0.875rem)

**Open questions:**
- Which version (v1 or v2) to proceed with for production? May keep both and A/B test
- Connector line height (60px) is a magic number — works for single-line labels but would need adjustment if labels wrap

**Next steps:**
- User to review in Storybook and decide on v1 vs v2 direction
- If v2 chosen: add location autocomplete, consider progress summary state
- Update docs/reference/ with v2 flow logic doc (similar to funeral-finder-logic.md for v1)

---

### Session 2026-03-26c — FuneralFinder v1 refinement and completion

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

**Work completed:**
- Redesigned FuneralFinder from a "dump everything in step 3" pattern to a full stepped conversational flow
- Every decision is now its own step with CompletedRow collapse (intent → planning-for → type+preferences → service → location+CTA)
- CTA ("Find funeral providers") and location input are always visible at the bottom — not gated behind steps
- Implemented smart defaults: minimum search requirements are intent + location; type/service/themes default to "show all"
- Added funeral type options: Cremation, Burial, Water Burial (QLD only), Explore All (as a proper TypeCard)
- Added service preference step (conditional): With a service / No service / I'm flexible
- Added theme preferences (eco-friendly, budget-friendly, religious specialisation) as optional sub-option within type step
- Created StepHeading sub-component (bodyLg, centered) for clear hierarchy vs card labels (body1/body2)
- Added loading prop for CTA button, location validation (3+ chars with error state)
- Added Divider under subheading, h2 display heading, generous CompletedRow spacing (py: 1.5)
- Fixed accessibility: aria-label on Change links, role="alert" on intent prompt, 44px touch targets on all chips
- Removed "Take your time" empathetic message per user preference
- Renamed "ceremony" → "service" throughout, "Without (direct)" → "No service"
- Removed TypeCard descriptions for standard types (Cremation, Burial don't need them)
- Multiple audit/critique cycles: final scores Audit 14/20 (Good), Critique 29/40 (Good)

**Decisions made:**
- CTA always visible with smart defaults — users can skip optional steps and search with just intent + location
- Stepped flow continues through ALL decisions (not just steps 1-2 like the previous version)
- Theme preferences belong in the type step as a sub-option, not in the location step
- "Where are you looking?" (not "located") to allow searching outside own area
- Step headings use bodyLg centered for visual hierarchy distinct from card labels

**Open questions:**
- Progress indicator (Step X of Y) — flagged by critique as P2, deferred. Variable step count makes implementation non-trivial.
- Roving tabindex for radiogroups — flagged by audit as P0, deferred. Requires arrow-key handler + tabindex management.
- Location autocomplete — flagged by critique as P2, deferred. Would need suburb/postcode API integration.
- CSS var vs MUI theme accessor consistency — flagged by audit, deferred. Architectural choice to address system-wide.

**Next steps:**
- FuneralFinder v1 is complete and approved
- Consider building the homepage hero composition as a standalone organism or page template
- ArrangementForm organism is next planned organism (multi-step wizard with StepIndicator)

### Session 2026-03-24 — Project scaffold setup and hygiene

**Agent(s):** Manual (no agents invoked — setup phase)

**Work completed:**
- Fixed missing `.storybook/` directory (main.ts + preview.tsx with MUI ThemeProvider)
- Created `.gitignore` (was missing entirely)
- Created `.mcp.json` with Figma remote MCP config
- Removed malformed `{.claude/agents,.claude/...}` directory tree (bash brace expansion bug)
- Created 3 agent definitions: token-architect, component-builder, story-writer
- Created 8 slash commands: create-tokens, build-atom, build-molecule, build-organism, write-stories, sync-tokens, status, review-component
- Migrated commands from `.claude/commands/` to `.claude/skills/<name>/SKILL.md` format with YAML frontmatter
- Fixed **critical** Style Dictionary v4 config: converted from CommonJS to ESM (`StyleDictionary` class API)
- Changed `build:tokens` script from `style-dictionary build --config ...` to `node style-dictionary/config.js`
- Added `"type": "module"` to package.json for ESM support
- Changed SD output from `tokens.ts` to `tokens.js` (Style Dictionary v4 generates JS, not TS)
- Registered `@storybook/addon-designs` in `.storybook/main.ts` (was installed but not configured)
- Added CSS token import to `.storybook/preview.tsx`
- Added Card and Link to CLAUDE.md atom list (were missing)
- Fixed broken Penpot/Storybook MCP references in `docs/reference/mcp-setup.md`
- Improved agent instructions with pre-flight dependency checks, story checklist enforcement, token validation steps, and MUI theme mapping guide
- Created `src/components/{atoms,molecules,organisms}/` directories
- Fixed `bootstrap.sh` to check for `.storybook/` dir instead of `node_modules/@storybook`
- Verified `npm run build:tokens` runs successfully (empty output expected — no tokens yet)
- Verified Storybook runs at http://localhost:6006

**Decisions made:**
- Skills use `.claude/skills/<name>/SKILL.md` format (not `.claude/commands/`)
- Style Dictionary v4 config is a standalone ESM script run via `node`, not CLI
- British spelling for filenames (`colours.json`), standard `color` namespace for token paths

**Open questions:**
- Slash commands `/create-tokens` etc. showing "Unknown skill" — may need Claude Code restart to discover newly created skills. User should test after restarting.

**Next steps:**
- ~~Verify slash commands work after Claude Code restart~~ ✓ Skills working
- ~~Begin Step 1: `/create-tokens` with brand colours, fonts, and reference material~~ ✓ Done

### Session 2025-03-25 — Token creation (Step 1)

**Agent(s):** token-architect (via /create-tokens skill)

**Work completed:**
- Extracted brand colours from user-provided swatch image (12 colours across 3 palettes)
- Reviewed 5 Parsons FA 1.0 Figma screens for colour application context
- Reviewed 2 FA 2.0 Design System Template screens (buttons + inputs)
- Created complete primitive tokens:
  - Colour scales (50-950): brand (warm gold), sage (cool grey-green), neutral, red, amber, green, blue + white/black
  - Typography: 3 font families (Montserrat, Noto Serif SC, JetBrains Mono), font size scale (xs-4xl + mobile), weights, line heights, letter spacing
  - Spacing: 4px-based scale (2px-80px), border radius scale
  - Effects: 4 shadow levels, 3 opacity values
- Created complete semantic tokens:
  - Colour mappings: text (9 variants), surface (6), border (6), interactive (7), feedback (8)
  - Typography roles: display, h1-h4, bodyLarge, body, bodySmall, caption, label, overline — each with font family, size, weight, line height, letter spacing + mobile size overrides
  - Spacing: component (xs-lg), layout (gutter, section, page, padding) with mobile/desktop variants
- Fixed Style Dictionary v4.4.0 CSS output: added `usesDtcg: true` flag (required for DTCG format CSS generation)
- Generated outputs:
  - CSS: 245 custom properties in `src/theme/generated/tokens.css` with `var()` references for semantic tokens
  - JS: 258 named exports in `src/theme/generated/tokens.js`
  - JSON: flat export in `tokens/export/tokens-flat.json`
- Updated MUI theme (`src/theme/index.ts`):
  - All palette colours mapped from token imports
  - All typography variants mapped (h1-h6, body1, body2, subtitle1/2, caption, overline, button)
  - 3 custom typography variants added: display, bodyLarge, label (with TS module declarations)
  - Responsive font sizes via @media queries for display, h1, h2, h3
  - Component overrides for Button and Card border radius
- Updated docs/design-system.md with actual brand colours, palettes, and font stacks
- Updated docs/memory/decisions-log.md with 8 design decisions (D001-D008)
- Updated docs/memory/token-registry.md with complete token reference

**Decisions made:**
- D001: Primary brand colour is #BA834E (warm gold from swatch)
- D002: Primary text colour is #2C2E35 (charcoal, not pure black)
- D003: Brand link colour uses #B0610F (copper, meets WCAG AA)
- D004: Sage palette as secondary (calming contrast to warm primary)
- D005: Noto Serif SC for display/H1-H2, Montserrat for H3+ and body
- D006: Warning text uses amber.700 for AA compliance
- D007: Style Dictionary requires usesDtcg: true for CSS output
- D008: Responsive typography via explicit @media queries in MUI theme

**Open questions:**
- Font name confirmation: user wrote "Not Serif SC" — interpreted as "Noto Serif SC" (Google Font). Needs confirmation.
- brand.500 (#BA834E) has 3.7:1 contrast on white — AA for large text only. Primary buttons use white text on this background, which works for button-sized text. Should we darken the primary CTA colour for better accessibility, or is the current value acceptable?
- Token collision warning: benign collision on `$type: "color"` set in both primitives and semantic colour files. Doesn't affect output.

**Next steps:**
- ~~Confirm display font name (Noto Serif SC vs something else)~~
- ~~Begin Step 2: Build first atom component (Button recommended as it exercises the most tokens)~~ ✓ Done
- Consider adding Google Fonts import for Montserrat and Noto Serif SC to index.html or Storybook preview

### Session 2026-03-25 — Button atom (Step 2)

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Reviewed 3 Figma component sets: Icons (29:54), Button (28:50), Text Button (32:1361)
- Created button component tokens (`tokens/component/button.json`): height, paddingX, paddingY, fontSize, iconSize, iconGap, borderRadius for xs/sm/md/lg sizes
- Rebuilt token pipeline — 25 new button tokens generated across CSS/JS/JSON outputs
- Updated MUI theme (`src/theme/index.ts`) with comprehensive MuiButton overrides:
  - 4 sizes: xs (28px), small (32px), medium (40px), large (48px)
  - Contained, outlined, text variants for primary and secondary colours
  - Hover backgrounds using brand.100 and sage.100 for outlined/text variants
  - Focus-visible outline (2px solid interactive.focus, 2px offset)
  - Disabled elevation via `disableElevation: true` default prop
  - Custom `xs` size via MUI variant system + module augmentation
- Created Button component (`src/components/atoms/Button/Button.tsx`):
  - Wraps MUI Button with React.forwardRef
  - Custom props: `loading` (spinner + disabled), `underline` (text-decoration for text variant)
  - Accepts all MUI ButtonProps (variant, color, size, startIcon, endIcon, fullWidth, etc.)
- Created barrel export (`src/components/atoms/Button/index.ts`)
- Created comprehensive Storybook stories (`Button.stories.tsx`): 16 stories covering Default, Variants (primary/secondary), AllSizes, Icons, Disabled, Loading, TextWithUnderline, FullWidth, LongContent, CompleteMatrix
- Storybook builds successfully with Button stories

**Decisions made:**
- D009: Merge Text Button into Button atom — text buttons are `variant="text"` with optional `underline` prop, not a separate component
- D010: Button sizes adjusted for touch targets — xs: 28px, sm: 32px, md: 40px, lg: 48px (lg meets 44px minimum)
- D011: Use `@mui/icons-material` over Font Awesome — native MUI integration, no adapter needed, tree-shakeable
- D012: Responsive sizing is a composition concern — Button size is an explicit prop, not responsive by default. Layouts choose the right size per breakpoint.

**Open questions:**
- primary.main maps to brand.600 (copper #B0610F) for AA compliance, but Figma designs show brand.500 (warm gold #BA834E) as primary button fill. Should we adjust? Current mapping prioritises accessibility.
- Google Fonts import still needed for Montserrat and Noto Serif SC in Storybook
- Icon approach confirmed as @mui/icons-material — should we create any custom SvgIcon components for FA-specific icons?

**Next steps:**
- ~~User to review Button in Storybook and provide feedback on colours/sizing~~ ✓ Feedback received
- Build Typography atom
- Add Google Fonts to Storybook preview
- ~~Log D009-D012 in decisions-log.md~~ ✓ Done

### Session 2026-03-25b — Button refinements from user review

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Fetched Figma Secondary/Brand and Secondary/Grey button details — discovered they are **soft-filled** (tonal) buttons, not outlined
- Added custom `variant="soft"` to MUI Button — tonal/muted fill treatment
  - Primary soft: brand.200 bg (#EBDAC8), brand.700 text (#8B4E0D), brand.300 hover
  - Secondary soft: neutral.200 bg (#E8E8E8), neutral.700 text (#404040), neutral.300 hover
- Changed MUI secondary palette from sage to neutral grey (neutral.600 main, neutral.700 dark, neutral.300 light)
- Updated all secondary button overrides (outlined, text) from sage to neutral
- Moved loading spinner from left to right side of button text
- Updated stories: added FigmaMapping story, soft variant stories, LoadingToSuccess pattern story
- Logged D013-D015 in decisions log

**Decisions made:**
- D013: Added `soft` variant for tonal buttons — maps to Figma Secondary/Brand and Secondary/Grey
- D014: Secondary palette changed from sage to neutral grey
- D015: Loading spinner positioned on right

**Open questions:**
- primary.main maps to brand.600 (copper #B0610F) for AA compliance, but Figma designs show brand.500 (warm gold #BA834E) as primary button fill. Should we adjust?
- Google Fonts import still needed for Montserrat and Noto Serif SC in Storybook
- Icon approach confirmed as @mui/icons-material — should we create any custom SvgIcon components for FA-specific icons?
- Sage palette no longer used for buttons — consider if it should be re-introduced as a custom colour later

**Next steps:**
- ~~User to re-review Button in Storybook~~ ✓ Approved as good baseline
- ~~Build Typography atom~~ ✓ Done
- ~~Add Google Fonts to Storybook preview~~ ✓ Done

### Session 2026-03-25c — Typography atom + housekeeping

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Added Google Fonts loading: Montserrat (400/500/600/700) + Noto Serif SC (600/700) in `.storybook/preview-head.html` and `index.html`
- Created Typography component (`src/components/atoms/Typography/Typography.tsx`):
  - Thin wrapper around MUI Typography with React.forwardRef
  - Custom prop: `maxLines` for CSS line-clamp truncation
  - All MUI Typography props passed through (variant, color, align, component, gutterBottom, etc.)
- Created barrel export (`src/components/atoms/Typography/index.ts`)
- Created comprehensive Storybook stories (9 stories): Default, HeadingHierarchy, BodyVariants, UIText, Colours, SemanticHTML, MaxLines, RealisticContent, FontFamilies
- Added "Future enhancements" tracking table to component-registry.md — deferred items (IconButton, destructive colours, link-as-button) tracked with triggers for when to address them
- Logged D016 (primary colour confirmed as copper brand.600) in decisions-log.md
- Storybook builds successfully

**Decisions made:**
- D016: Primary button colour confirmed as copper (brand.600) — user approved
- Typography atom is a thin wrapper + maxLines — no over-engineering

**Open questions:**
- Icon approach confirmed as @mui/icons-material — should we create any custom SvgIcon components for FA-specific icons?
- Sage palette no longer used for buttons — consider if it should be re-introduced as a custom colour later

**Next steps:**
- User to review Typography in Storybook
- Build next atom (Input or Card recommended — Input for forms, Card for service listings)
- Consider building FormField molecule next if Input is done (label + input + helper text)

### Session 2026-03-25d — Typography expansion (21 variants)

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Reviewed user's FA 2.0 Figma type scale (node 23:30) — 21 variants across 6 categories, 3 responsive breakpoints
- Expanded primitive typography tokens: added fontSize.2xs (11px), fontSize.display.* sub-group (hero 80px through sm 32px), mobile overrides for all display and heading sizes
- Rewrote semantic typography tokens: 21 variants with specific line-heights and letter-spacing per variant
- Rewrote MUI theme typography section: refactored to wildcard import (`import * as t`), added all 21 variants with module augmentations, responsive scaling via @media queries
- Updated Google Fonts: added Noto Serif SC weight 400 (Regular) for display text
- Updated Typography component JSDoc with full variant guide
- Rewrote Typography stories: 10 stories including CompleteScale (all 21 variants matching Figma layout)
- Key font changes: headings now Montserrat Bold (not serif), display now Regular 400 (not Bold), body now Medium 500 (not Regular)

**Decisions made:**
- D017: Headings use Montserrat Bold, not Noto Serif SC (supersedes D005)
- D018: Display weight is Regular 400, not Bold
- D019: Body weight is Medium 500 (user preference, 450 not available)
- D020: 21 typography variants across 6 categories

**Next steps:**
- ~~User to review expanded type scale in Storybook~~ ✓
- Fine-tune heading sizes if they don't match Figma exactly (h2-h6 were estimated)
- ~~Build next atom (Input or Card)~~ ✓ Input done

### Session 2026-03-25e — Input atom

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Reviewed FA 2.0 Figma Input Field design (node 39:713) — 9 states × 4 toggle properties = ~90 variants
- Analysed Figma design and provided feedback: identified 7 improvements (leading icons, size variation, required indicator, select vs input naming, multiline, character count, error icon treatment)
- Created Input component tokens (`tokens/component/input.json`): height (sm/md), paddingX, paddingY (sm/md), fontSize, borderRadius, gap, iconSize — 9 tokens total
- Rebuilt token pipeline — 9 new input tokens generated across CSS/JS/JSON outputs
- Updated MUI theme (`src/theme/index.ts`) with comprehensive MuiOutlinedInput overrides:
  - Border colours per state: neutral.300 default, neutral.400 hover, brand.500 focus, error/success for validation
  - Focus ring: double box-shadow (2px white gap + 4px brand.500) matching Figma's elevation-special/focus-ring effect
  - Error + focus ring: error-coloured ring
  - Disabled background: neutral.100
  - Two sizes via minHeight: medium (48px), small (40px)
  - Icon sizing: 20px via InputAdornment
  - Notch legend hidden for external label pattern
  - Multiline padding normalisation
- Created Input component (`src/components/atoms/Input/Input.tsx`):
  - Composes FormControl + InputLabel + OutlinedInput + FormHelperText
  - External label pattern (InputLabel with position:static, no floating)
  - Custom props: `label`, `helperText`, `success`, `startIcon`, `endIcon`, `fullWidth`
  - Label stays neutral on error/focus/success (per Figma design)
  - Required asterisk on label (via MUI InputLabel)
  - Success state: green border + green helper text (not a native MUI state)
  - Error helper text has `role="alert"` for screen readers
  - `aria-describedby` connection between input and helper text
  - Supports multiline via `multiline` + `rows`/`minRows`/`maxRows`
- Created barrel export (`src/components/atoms/Input/index.ts`)
- Created comprehensive Storybook stories (11 stories): Default, FigmaMapping, AllStates, Required, Sizes, SizeAlignment, WithIcons, PasswordToggle, Multiline, ValidationFlow, ArrangementForm, CompleteMatrix
- Logged D021-D025 in decisions log
- Updated component registry (Input → review)
- Storybook builds successfully

**Decisions made:**
- D021: External label pattern, not MUI floating label
- D022: Two sizes — medium 48px (matches Button large), small 40px (matches Button medium)
- D023: Focus ring uses brand.500 warm gold (Figma spec), not brand.600
- D024: Label stays neutral on error/success (calmer for FA audience)
- D025: Added startIcon/endIcon convenience props and success validation state

**Open questions:**
- Should error+focus ring be error-coloured or brand-coloured? Currently error-coloured (reinforces the validation state during keyboard navigation)
- FormField molecule may now be unnecessary — Input already includes label + helper text. Consider repurposing FormField as a layout/validation wrapper instead.
- Should we add a character count feature? (Useful for textarea fields like special instructions)

**Next steps:**
- ~~User to review Input in Storybook~~ ✓
- ~~Build next atom (Card, Badge, or Chip recommended)~~ ✓ Card done
- Consider whether FormField molecule is still needed given Input's built-in label/helperText

### Session 2026-03-25f — Card atom

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Created card component tokens (`tokens/component/card.json`): borderRadius, padding (default 24px / compact 16px), shadow (default md / hover lg), border, background — 7 tokens total
- Rebuilt token pipeline — 7 new card tokens generated across CSS/JS/JSON outputs
- Updated MUI theme (`src/theme/index.ts`) with MuiCard overrides:
  - Root: card token border radius, background, resting shadow (shadow.md), smooth transition
  - Outlined variant: no shadow, card border colour
- Created Card component (`src/components/atoms/Card/Card.tsx`):
  - Two visual variants: elevated (shadow, default) and outlined (border)
  - `interactive` prop: hover shadow lift (shadow.lg), pointer cursor, focus-visible outline
  - `padding` prop: "default" (24px), "compact" (16px), "none" (raw children for full-bleed)
  - Uses CardContent internally for padded variants; raw children when none
  - Thin wrapper pattern consistent with Button and Typography
- Created barrel export (`src/components/atoms/Card/index.ts`)
- Created 8 Storybook stories: Default, Variants, Interactive, PaddingPresets, PriceCardPreview, ServiceOptionPreview, WithImage, RichContent
- Preflight passed all 5 checks
- Committed and pushed to Gitea

**Decisions made:**
- Card uses MUI spacing units (p: 4/6) for padding presets rather than CSS variables — consistent with MUI-first approach
- Elevation set to 0 on MuiCard; box-shadow applied directly from card tokens for precise control
- Interactive hover uses CSS variable (`var(--fa-card-shadow-hover)`) for shadow.lg
- No new design decisions needed — Card follows existing token/design conventions from design-system.md

**Open questions:**
- Should interactive cards have a subtle border-colour change on hover in addition to shadow lift?
- Should we add a "selected" state for ServiceOption-style cards (e.g., brand border + brand.50 background)?

**Next steps:**
- ~~User to review Card in Storybook~~ ✓ Feedback received — add selected + hover bg

### Session 2026-03-25g — Card selected state + hover background

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Reviewed FA 1.0 Figma designs for card usage patterns:
  - ListItemPurchaseOption (2349:39505): selectable cards with 4 states × 2 viewports
  - ListItemAddItem (2350:40658): toggle/switch pattern — deferred to future Toggle component
- Added `selected` prop: brand border (2px, warm gold #BA834E) + warm background (brand.50 #FEF9F5)
- Added hover background fill: interactive cards now fill with neutral.50 on hover (matching Figma's inactive→hover pattern)
- Hover on selected cards preserves warm background instead of switching to neutral
- Elevated interactive cards still get shadow lift on hover; outlined ones only get bg fill
- Added 3 new card tokens: border.selected, background.hover, background.selected
- Added 4 new stories: Selected, OptionSelect (single-select with radio semantics), MultiSelect (checkbox toggle), OnDifferentBackgrounds (white vs grey surface)
- Replaced ServiceOptionPreview story with the more complete OptionSelect and MultiSelect patterns
- Preflight passed all 5 checks
- Committed and pushed to Gitea

**Decisions made:**
- Selected state uses 2px brand border (not 1.5px from Figma 1.0) — 2px aligns with our focus ring width and sits on the 2px sub-grid
- Selected background uses brand.50 (warm tint) not neutral.50 (grey) — warm tint reinforces the brand connection and distinguishes selected from hovered
- Hover bg fill uses neutral.50 (not brand.50) for unselected cards — keeps hover subtle and neutral
- Toggle/switch pattern from Figma (ListItemAddItem) is a separate component concern, not Card

**Next steps:**
- ~~User to review Card selected/hover states in Storybook~~ ✓ Approved
- ~~Build Badge or Chip atom next~~ ✓ Badge done

### Session 2026-03-25h — Badge atom

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Searched FA 2.0 and Parsons 1.0 Figma files for badge/chip/tag components — none found, designed from conventions
- Created badge component tokens (`tokens/component/badge.json`): height, paddingX, fontSize, iconSize, iconGap, borderRadius for sm/md — 10 tokens total
- Built Badge component (`src/components/atoms/Badge/Badge.tsx`):
  - Pill-shaped, display-only status indicator (not interactive)
  - 6 colour intents: default, brand, success, warning, error, info
  - 2 variants: soft (tonal bg + coloured text, default) and filled (solid bg + white text)
  - 2 sizes: small (22px) and medium (26px)
  - Optional leading `icon` prop for contextual icons
  - All soft colours use CSS variables from token system — no hardcoded hex
  - Warning text uses amber.700 for WCAG AA compliance
- Created 10 Storybook stories including realistic compositions (InPriceCard, ServiceStatus)
- Preflight passed all 5 checks
- Committed and pushed to Gitea

**Decisions made:**
- Badge defaults to soft variant — calmer, more appropriate for FA's sensitive context. Filled variant for high-priority emphasis only.
- Badge uses Box (span) not MUI Chip — keeps it simple, display-only, no interactive baggage
- Pill shape (borderRadius.full) distinguishes badges from rectangular UI elements
- Brand soft colours match Button soft (brand.200 bg, brand.700 text) for visual consistency

**Next steps:**
- ~~User to review Badge in Storybook~~ ✓ Approved (large size added)

### Session 2026-03-25i — Impeccable integration

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Researched pbakaus/impeccable (Apache 2.0) — 21 skills for frontend design quality
- Assessed fit for FA project — identified overlaps/conflicts, recommended selective integration
- Downloaded 14 reference files to `docs/reference/impeccable/`:
  - 7 design guides (typography, colour, spatial, motion, interaction, responsive, ux-writing)
  - 3 critique references (cognitive-load, heuristics-scoring, personas)
  - 4 skill references (audit, critique, polish, frontend-design anti-patterns)
- Created `/audit` skill — technical quality scoring (0-20) across 5 dimensions, adapted for FA
- Created `/critique` skill — UX review using Nielsen's 10 heuristics (0-40), with FA-specific persona checks
- Updated `/review-component` — added interactive states checklist (8 checks) and design anti-patterns checklist (8 checks)
- Updated `/preflight` — added visual QA spot-check section (advisory, non-blocking)
- All changes are skill/docs only — zero code changes to existing components

**Decisions made:**
- Selective integration over wholesale install — only /audit, /critique, reference material, and anti-patterns merged
- Removed impeccable's dependency chain (/frontend-design → /teach-impeccable) — FA already has CLAUDE.md + docs/memory/ for design context
- Replaced impeccable's command recommendations with FA's available skills
- Critique adapted with FA-specific personas (bereaved family member, arrangement planner)
- OKLCH recommendation noted in reference but not adopted — FA uses hex-based DTCG tokens

**Component status at end of session:**
- **Done (5):** Button, Typography, Input, Card, Badge
- **Planned (5 atoms):** IconButton, Icon, Avatar, Divider, Chip, Link
- **Planned (5 molecules):** FormField, PriceCard, ServiceOption, SearchBar, StepIndicator
- **Planned (5 organisms):** ServiceSelector, PricingTable, ArrangementForm, Navigation, Footer

**Next steps:**
- Review Badge in Storybook (large size was added per user request)
- ~~Build Chip atom (interactive tags — clickable, deletable, with icon support)~~ ✓ Done
- Consider running /audit or /critique on completed atoms to establish baseline scores
- Begin PriceCard molecule once Chip is done (depends on Card + Badge + Typography + Button)

### Session 2026-03-25j — Chip atom

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Created chip component tokens (`tokens/component/chip.json`): height, paddingX, fontSize, iconSize, deleteIconSize, iconGap, borderRadius for sm/md — 12 tokens total
- Rebuilt token pipeline — 12 new chip tokens generated across CSS/JS/JSON outputs
- Updated MUI theme (`src/theme/index.ts`) with MuiChip overrides:
  - Pill-shaped borderRadius from token
  - Two sizes: small (28px), medium (32px)
  - Filled variant: neutral.200 bg for default, brand.200 bg for primary (soft/tonal, matching Badge and Button soft)
  - Outlined variant: neutral.300 border for default, brand.400 border for primary
  - Hover states per variant × colour
  - Delete icon hover colour change
  - Focus-visible outline (brand.500, 2px offset)
- Created Chip component (`src/components/atoms/Chip/Chip.tsx`):
  - Wraps MUI Chip with React.forwardRef
  - Custom `selected` prop: promotes colour to primary, outlined selected gets brand border + warm bg
  - Two variants: filled (tonal, default), outlined (border)
  - Two colours: default (neutral), primary (brand)
  - Interactive modes: clickable (via onClick), deletable (via onDelete), both, or static
  - All MUI ChipProps passed through
- Created barrel export (`src/components/atoms/Chip/index.ts`)
- Created 10 Storybook stories: Default, Variants, Sizes, WithIcons, Clickable, Deletable, Selected, FilterChips (interactive toggle demo), RemovableTags (interactive dismiss demo), InServiceOption (realistic card composition), CompleteMatrix
- Preflight passed all 5 checks

**Decisions made:**
- Chip uses MUI Chip wrapper (unlike Badge which uses raw Box) — MUI Chip provides built-in keyboard navigation, delete icon, and click handling that would be complex to reimplement
- Chip defaults to `filled` variant with soft/tonal colours (matching Badge soft and Button soft patterns) — NOT MUI's default opaque fill
- Only `default` and `primary` colours initially — secondary/error/etc. added when needed (YAGNI)
- Selected state auto-promotes to primary colour unless colour is explicitly set — mirrors Card's selected brand treatment
- No new design decision IDs needed — Chip follows established conventions

**Component status at end of session:**
- **Done (5):** Button, Typography, Input, Card, Badge
- **Review (1):** Chip
- **Planned (4 atoms):** IconButton, Icon, Avatar, Divider, Link
- **Planned (5 molecules):** FormField, PriceCard, ServiceOption, SearchBar, StepIndicator
- **Planned (5 organisms):** ServiceSelector, PricingTable, ArrangementForm, Navigation, Footer

**Next steps:**
- ~~User to review Chip in Storybook~~ ✓ Approved
- ~~Consider running /audit or /critique on completed atoms to establish baseline scores~~ ✓ Done
- Begin PriceCard molecule (depends on Card + Badge + Typography + Button + Chip)

### Session 2026-03-25k — Audit, P1 fixes, Switch + Radio atoms

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Ran /audit on all 5 completed atoms (Button, Typography, Input, Card, Badge)
  - Average score: 18/20 (Excellent)
  - 2 P1 issues identified and fixed, 7 P2s documented, 5 P3s noted
- Fixed P1: Button loading state now announces to screen readers (aria-busy + visually-hidden text)
- Fixed P1: Card interactive now has tabIndex={0} and role="button" for keyboard operability
- Fixed P2: Card Record<string, any> → Theme type for type safety
- Reviewed Parsons 1.0 Figma "Toggles" board (node 2322:42538) — identified 4 new atoms: Switch, Radio, ColourToggle, Slider
- Added all 4 to component registry (ColourToggle and Slider deferred)
- Created switch component tokens (`tokens/component/switch.json`): track width/height/borderRadius, thumb size — 4 tokens
- Created radio component tokens (`tokens/component/radio.json`): size, dotSize — 2 tokens
- Updated MUI theme with MuiSwitch overrides: bordered pill track, brand.500 active fill, focus-visible ring
- Updated MUI theme with MuiRadio overrides: neutral.400 unchecked, brand.500 checked, hover states
- Created Switch component — thin MUI wrapper with forwardRef
- Created Radio component — thin MUI wrapper with forwardRef
- Created Switch stories (4): Default, States, ServiceAddOns (interactive add-on toggle demo), WithLabels
- Created Radio stories (5): Default, States, RadioGroup, CardSelection (interactive card + radio demo), PaymentMethod
- Preflight passed all 5 checks

**Decisions made:**
- Switch implements Figma "Style One" (bordered pill) only — other styles deferred as variants if needed
- Switch/Radio are ultra-thin wrappers — all styling via MUI theme overrides, no component-level sx
- ColourToggle and Slider deferred until their consuming organisms are built

**Component status at end of session:**
- **Done (5):** Button, Typography, Input, Card, Badge
- **Review (3):** Chip, Switch, Radio
- **Planned (6 atoms):** IconButton, Icon, Avatar, Divider, ColourToggle, Slider, Link
- **Planned (5 molecules):** FormField, PriceCard, ServiceOption, SearchBar, StepIndicator
- **Planned (5 organisms):** ServiceSelector, PricingTable, ArrangementForm, Navigation, Footer

**Next steps:**
- ~~User to review Switch and Radio in Storybook~~ ✓ Approved
- ~~Begin PriceCard molecule~~ ✓ Replaced with ProviderCard (see below)
- Address P2 audit issues in a future cleanup pass

### Session 2026-03-25l — ProviderCard molecule (first molecule)

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Reviewed 3 Figma designs: Provider Cards (5503:44422), Service Venue (2997:83018), Map Pin Card (5369:140263)
- Captured business context: verified vs unverified providers, Parsons partner strategy, map + list layout
- Replaced generic "PriceCard" in registry with 3 specific molecules: ProviderCard, VenueCard, MapCard
- Saved business context to auto-memory (project_listing_cards.md)
- Created plan via /plan mode — component API, card structure, token plan, story plan
- Created providerCard component tokens (`tokens/component/providerCard.json`): image.height, logo.size, footer.background/paddingX/paddingY, content.padding/gap — 7 tokens
- Built ProviderCard molecule (`src/components/molecules/ProviderCard/ProviderCard.tsx`):
  - Composes Card (interactive, padding="none") + Badge + Typography
  - Verified variant: hero image (CSS bg-image cover), logo overlay (48px circle, absolute positioned, overlaps content), "Trusted Partner" badge (filled brand), capability badge
  - Unverified variant: text-only, same content area + footer
  - Footer bar: warm brand.100 bg, "Packages from $X" + ChevronRight
  - Accessibility: aria-label on reviews, aria-hidden on decorative icons, alt text on logo
  - All values from token CSS variables, no hardcoded hex
- Created 9 Storybook stories: Default, VerifiedProvider, UnverifiedProvider, ListLayout (mixed), CapabilityVariants, EdgeCases, Responsive, OnDifferentBackgrounds, InteractiveDemo
- Preflight passed all 5 checks
- Logged D026-D030 in decisions log

**Decisions made:**
- D026: Molecules compose atoms via sx — no MUI theme overrides
- D027: Image as URL string (CSS bg-image), logo as URL string (<img>)
- D028: Logo 48px (not 75px Figma) for card width proportion
- D029: Footer built in via startingPrice prop, not a slot
- D030: verified is explicit boolean, not derived from imageUrl

**Component status at end of session:**
- **Done (7):** Button, Typography, Input, Card, Badge, Chip, Switch, Radio
- **Review (1 molecule):** ProviderCard
- **Planned (7 atoms):** IconButton, Icon, Avatar, Divider, ColourToggle, Slider, Link
- **Planned (5 molecules):** VenueCard, MapCard, ServiceOption, SearchBar, StepIndicator, FormField
- **Planned (5 organisms):** ServiceSelector, PricingTable, ArrangementForm, Navigation, Footer

**Next steps:**
- ~~User to review ProviderCard in Storybook~~ ✓ Feedback received, iterated in session 25m

### Session 2026-03-25m — ProviderCard v2 refinements from user feedback

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Iterated on ProviderCard based on 5 feedback items from user review
- **Logo**: circle → 64px rounded rectangle (8px radius, `borderRadius.md`). Positioned fully inside image area (absolute, bottom-left) with white border + shadow. Eliminates dead space — name sits directly below image.
- **Footer removed**: "View packages >" bar was redundant (whole card is clickable, price already in content). Removed 3 footer tokens (`footer.background`, `.paddingX`, `.paddingY`).
- **Price typography**: Split into "Packages from" (body2, 14px, secondary) + price (h6, 16px, weight 500, primary). Lighter, streamlined ecommerce feel vs old blocky labelLg/700.
- **Verified badge**: Bumped from `size="small"` to `size="medium"` for visibility.
- **Capability badge**: Bumped to `size="medium"`. Added trailing `InfoOutlinedIcon` and new `capabilityDescription` prop — wraps badge in MUI Tooltip on hover/focus for plain-language definitions of industry jargon.
- **Unverified card differentiation**: 3px `borderTop` (neutral.200) as visual anchor. ListLayout story now on neutral.50 background.
- **Caption weight fix (system-wide)**: Caption and CaptionSm bumped from fontWeight 400 (Regular) → 500 (Medium) in semantic typography tokens. Aligns with D019 — user found Regular too light for Montserrat.
- **Meta row**: Location/reviews dropped from body2 (14px) → caption (12px) with 14px icons for clearer tertiary hierarchy.
- Updated all stories with `capabilityDescription` tooltips for 3 capability types
- Preflight passed all 5 checks

**Decisions made:**
- Logo positioned fully inside image (no overlap into content) — tried flex-row overlap approach first but it "dug into" the photo and pushed the name sideways
- Footer removal: card's interactive hover + price in content are sufficient affordance
- Caption weight 500: extends D019 (body weight = Medium) to all Montserrat text variants. Only display (Noto Serif SC) stays at 400 per D018.
- Info icon for capability badges: trailing position (after label), `cursor: help` when tooltip active

**Token changes:**
- `providerCard.logo.size`: 56px → 64px
- `providerCard.logo.borderRadius`: new, → `{borderRadius.md}` (8px)
- `providerCard.footer.*`: 3 tokens removed (footer eliminated)
- `typography.caption.fontWeight`: `{fontWeight.regular}` → `{fontWeight.medium}`
- `typography.captionSm.fontWeight`: `{fontWeight.regular}` → `{fontWeight.medium}`

**Component status at end of session:**
- **Done (8):** Button, Typography, Input, Card, Badge, Chip, Switch, Radio
- **Review (1 molecule):** ProviderCard (v2, user approved direction)
- **Planned (6 atoms):** IconButton, Icon, Avatar, Divider, ColourToggle, Slider, Link
- **Planned (5 molecules):** VenueCard, MapCard, ServiceOption, SearchBar, StepIndicator, FormField
- **Planned (5 organisms):** ServiceSelector, PricingTable, ArrangementForm, Navigation, Footer

**Next steps:**
- ~~Build VenueCard molecule~~ ✓ Done
- ~~Address P2 audit issues~~ ✓ Done
- ~~Audit ProviderCard v2~~ ✓ Done (17/20, P2s fixed)

### Session 2026-03-25n — VenueCard molecule, P2 fixes, ProviderCard audit

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Reviewed Figma venue card design (node 2997:83018) — photo + name + location + capacity + price
- Created venueCard component tokens (`tokens/component/venueCard.json`): image.height (180px), content.padding (spacing.3), content.gap (spacing.1) — 3 tokens
- Built VenueCard molecule (`src/components/molecules/VenueCard/VenueCard.tsx`):
  - Composes Card (interactive, padding="none") + Typography
  - Hero image with `role="img"` + aria-label for screen readers
  - Meta row: location (pin icon) + capacity with "guests" suffix for clarity
  - Price with "From" qualifier (split typography like ProviderCard)
  - No verification tiers, no logo, no badges — simpler than ProviderCard
- Created 6 Storybook stories: Default, ListLayout, EdgeCases, Responsive, OnDifferentBackgrounds, InteractiveDemo
- Ran /critique on VenueCard: 33/40 (Good). Applied P2 fixes before commit:
  - Capacity: bare number → "X guests" for visible context
  - Price: bare "$900" → "From $900" for transparency
  - Image: added `role="img"` + `aria-label` for screen readers
- Fixed 6 P2 audit issues across atom components:
  - Input: `Record<string, any>` → `Theme` type on boxShadow accessor
  - Button: documented aria-label requirement for icon-only usage
  - Badge: documented aria-label for icon-only badges
  - Switch: strengthened a11y docs with FormControlLabel example
  - Radio: strengthened a11y docs with RadioGroup + FormControlLabel example
  - Chip: documented aria-label for icon-only deletable chips
- Ran /audit on ProviderCard v2: 17/20 (Good). Fixed 3 P2s:
  - Hero image: added `role="img"` + `aria-label` for screen readers
  - Logo shadow: hardcoded rgba → `var(--fa-shadow-sm)`
  - Logo border: hardcoded white → `var(--fa-color-white)`

**Decisions made:**
- VenueCard follows same token structure as ProviderCard (image.height, content.padding, content.gap) for visual consistency in list views
- Capacity shows "X guests" suffix — bare number was confusing in critique
- Price shows "From $X" — matches ProviderCard's "Packages from" pattern for transparency

**Component status at end of session:**
- **Done (8):** Button, Typography, Input, Card, Badge, Chip, Switch, Radio
- **Review (2 molecules):** ProviderCard (v2, audit 17/20), VenueCard (critique 33/40)
- **Planned (6 atoms):** IconButton, Icon, Avatar, Divider, ColourToggle, Slider, Link
- **Planned (4 molecules):** MapCard, ServiceOption, SearchBar, StepIndicator, FormField
- **Planned (5 organisms):** ServiceSelector, PricingTable, ArrangementForm, Navigation, Footer

**Next steps:**
- ~~User to review VenueCard in Storybook~~ ✓ Approved
- ~~Build next atoms (IconButton, Divider, Link)~~ ✓ Done

### Session 2026-03-25n (continued) — IconButton, Divider, Link atoms

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Built IconButton atom — wraps MUI IconButton with FA theme overrides:
  - 3 sizes reusing Button height tokens (sm 32px, md 40px, lg 48px)
  - Rounded rect shape (borderRadius.md), brand hover colours, focus ring
  - 4 colour options: default, primary, secondary, error
  - 5 stories including CommonUseCases (card toolbar, dialog close, nav toggle)
- Built Divider atom — wraps MUI Divider with FA border token:
  - Horizontal/vertical orientation, fullWidth/inset/middle variants
  - Text children support (MUI built-in)
  - 6 stories including InContent and NavigationList patterns
- Built Link atom — wraps MUI Link with FA brand tokens:
  - Copper colour (brand.600, 4.8:1 contrast) by default
  - Underline on hover, focus-visible ring, fontWeight 500
  - 7 stories including Inline (body text), Navigation, FooterLinks
- Added MuiIconButton, MuiDivider, MuiLink overrides to theme

**Decisions made:**
- IconButton uses rounded rect (borderRadius.md) not circle — consistent with Button. Circle can be achieved with sx if needed.
- Link defaults to underline="hover" — always-underlined links feel heavy in FA's clean aesthetic, but the underline is important for discoverability so it appears on hover.
- No new component tokens — IconButton reuses Button tokens, Divider uses palette.divider, Link uses palette colours.

**Component status at end of session:**
- **Done (8):** Button, Typography, Input, Card, Badge, Chip, Switch, Radio
- **Review (3 atoms):** IconButton, Divider, Link
- **Review (2 molecules):** ProviderCard (v2, audit 17/20), VenueCard (critique 33/40)
- **Planned (3 atoms):** Icon, Avatar, ColourToggle, Slider
- **Planned (4 molecules):** MapCard, ServiceOption, SearchBar, StepIndicator, FormField
- **Planned (5 organisms):** ServiceSelector, PricingTable, ArrangementForm, Navigation, Footer

**Next steps:**
- ~~User to review IconButton, Divider, Link in Storybook~~ ✓ Approved
- ~~Build ServiceOption molecule~~ ✓ Done

### Session 2026-03-25n (continued) — ServiceOption molecule

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Reviewed 2 Figma components: ListItemPurchaseOption (2349:39505) and ListItemAddItem (2350:40658)
  - ListItemPurchaseOption: click-to-select card with 4 states (inactive, hover, active, active hover)
  - ListItemAddItem: toggle with Switch — deferred as a future AddOnOption molecule
- Built ServiceOption molecule (`src/components/molecules/ServiceOption/ServiceOption.tsx`):
  - Composes Card (interactive, selected) + Typography
  - Heading row: name (h6) + optional price (h6, brand colour, right-aligned, nowrap)
  - Optional description below (body2, text.secondary)
  - Selected state via Card's built-in brand border + warm bg
  - Disabled state with opacity token (--fa-opacity-disabled) + pointer-events: none
  - role="radio" + aria-checked for proper single-select group semantics
  - Uses card.padding.compact (16px) for content padding
- Created 7 stories: Default, Selected, ServiceTypeSelection (interactive radiogroup),
  CoffinSelection (interactive 4-option), WithoutPrice, Disabled, EdgeCases
- No new tokens — ServiceOption reuses Card tokens (padding.compact, border.selected, etc.)

**Decisions made:**
- ServiceOption uses role="radio" + aria-checked — correct for single-select groups within a radiogroup. Parent wraps in role="radiogroup".
- Price right-aligned in heading row — natural scanning pattern (name on left, cost on right, like a menu)
- No component-specific tokens needed — Card's existing tokens handle all visual states
- AddOnOption (ListItemAddItem with Switch) deferred — will compose Card + Switch when arrangement form organisms are built

**Component status at end of session:**
- **Done (8):** Button, Typography, Input, Card, Badge, Chip, Switch, Radio
- **Review (3 atoms):** IconButton, Divider, Link
- **Review (3 molecules):** ProviderCard, VenueCard, ServiceOption
- **Planned (3 atoms):** Icon, Avatar, ColourToggle, Slider
- **Planned (3 molecules):** MapCard, SearchBar, StepIndicator, FormField
- **Planned (5 organisms):** ServiceSelector, PricingTable, ArrangementForm, Navigation, Footer

**Next steps:**
- ~~Build SearchBar molecule~~ ✓ Done
- ~~Build AddOnOption molecule~~ ✓ Done
- ~~Build StepIndicator molecule~~ ✓ Done
- ~~Build Navigation organism~~ ✓ Done

### Session 2026-03-25o — SearchBar, AddOnOption, StepIndicator molecules + Navigation organism

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Built SearchBar molecule (`src/components/molecules/SearchBar/`):
  - Composes Input (with search icon) + optional Button for provider/venue search
  - Enter-to-submit, progressive clear button (appears when text present), inline loading spinner
  - Guards empty submissions (`value.trim()`), refocuses input after clear
  - `role="search"` landmark, two sizes aligned with Input/Button
  - Critique: 35/40 (Good). P2 fixes applied before commit.
  - 8 stories: Default, WithButton, SmallSize, WithPreloadedValue, Loading, Disabled, ProviderSearch, VenueSearch
- Built AddOnOption molecule (`src/components/molecules/AddOnOption/`):
  - Composes Card (interactive, selected) + Typography + Switch
  - Maps to Figma ListItemAddItem (2350:40658) — toggle for optional extras
  - Heading + optional price + description + Switch right-aligned
  - Click anywhere on card toggles the switch (stopPropagation on switch itself)
  - `aria-labelledby` connects switch to heading text
  - 7 stories: Default, Checked, ServiceAddOns (interactive list with running total), WithoutPrice, WithoutDescription, Disabled, EdgeCases
- Built StepIndicator molecule (`src/components/molecules/StepIndicator/`):
  - Maps to Figma Progress Bar - Steps (2375:47468) — horizontal segmented bar
  - Brand gold for completed/current steps, grey (divider) for upcoming
  - Responsive bar height (10px desktop, 6px mobile), responsive labels
  - Current step label bolded, `role="navigation"` + `aria-current="step"`
  - 7 stories: Default, AllStates, TwoSteps, ManySteps, Interactive (nav demo), Completed, NarrowContainer
- Built Navigation organism (`src/components/organisms/Navigation/`):
  - First organism in the design system
  - Maps to Figma Main Nav (14:108) + Mobile Header (2391:41508)
  - Desktop: sticky AppBar, logo left, nav Link items right, optional CTA Button
  - Mobile: hamburger IconButton + Drawer with nav list, CTA, Divider, help footer with phone
  - Warm surface background (brand.50), border bottom
  - Composes AppBar, Link, IconButton, Button, Divider, Drawer, Typography
  - 6 stories: Default, WithCTA, WithPageContent (sticky scroll demo), Minimal, ExtendedNavigation, MobilePriceTracker
- All 4 components: TypeScript compiles, Storybook builds, committed and pushed

**Decisions made:**
- SearchBar guards empty submissions and disables button when empty — prevents wasted requests
- AddOnOption uses click-anywhere-to-toggle pattern (stopPropagation on Switch to avoid double-toggle)
- StepIndicator uses `palette.divider` for incomplete steps — grey/sage from theme, not hardcoded
- Navigation uses `var(--fa-color-surface-warm)` background — matches Figma's warm grey #F4F3EF
- Navigation nav link colour uses brand.900 (#51301B) — matches Figma "Brown Two" token
- No new component tokens needed for any of the 4 components — all reuse existing tokens

**Component status at end of session:**
- **Done (8):** Button, Typography, Input, Card, Badge, Chip, Switch, Radio
- **Review (3 atoms):** IconButton, Divider, Link
- **Review (6 molecules):** ProviderCard, VenueCard, ServiceOption, SearchBar, AddOnOption, StepIndicator
- **Review (1 organism):** Navigation
- **Planned (3 atoms):** Icon, Avatar, ColourToggle, Slider
- **Planned (2 molecules):** MapCard, FormField
- **Planned (4 organisms):** ServiceSelector, PricingTable, ArrangementForm, Footer

**Post-review fixes (same session):**
- SearchBar: button height aligned via explicit CSS var height, icon-to-text gap tightened (adornment mr: 0.5), focus ring gap increased (gap 6px → 10px)
- AddOnOption: price moved to own row below heading, heading row centre-aligned so short headings (no description) align with switch, heading-to-price margin removed
- AddOnOption + ServiceOption: added optional `maxDescriptionLines` prop with CSS line-clamp + "View more"/"View less" toggle (caption size, text.secondary, weight 400). Omit prop for no limit.

**Next steps:**
- ~~Build Footer organism~~ (next)
- ~~Build ServiceSelector organism~~ (next)
- ~~Consider FormField molecule~~ (next)
- ~~Remaining P3s~~ (next)

### Session 2026-03-25p — Review completion + Navigation fixes

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Completed review of all components — user approved all atoms + molecules with no changes
- Applied 4 Navigation fixes from user feedback:
  1. Added "Provider Portal" to default nav items
  2. Integrated real FA logo SVGs from `brandassets/brandlogo/` (full wordmark desktop, short icon mobile)
  3. Changed nav background from warm (`surface.warm` / brand.50) to grey (`surface.subtle` / neutral.50)
  4. Removed `mobileTrailing` prop and `MobilePriceTracker` story — speculative feature not in design
- Added `staticDirs: ['../brandassets']` to Storybook config for logo serving
- Updated component-registry.md: promoted 11 atoms + 6 molecules + 1 organism from "review" to "done"
- TypeScript compiles, Storybook builds

**Decisions made:**
- Nav background is grey (neutral.50) not warm (brand.50) — per user's Figma reference
- "Log in" label kept as-is — universally understood, user confirmed
- mobileTrailing prop removed entirely — was over-reading Figma's mobile header

**Component status at end of session:**
- **Done (11 atoms):** Button, Typography, Input, Card, Badge, Chip, Switch, Radio, IconButton, Divider, Link
- **Done (6 molecules):** ProviderCard, VenueCard, ServiceOption, SearchBar, AddOnOption, StepIndicator
- **Done (1 organism):** Navigation
- **Planned (3 atoms):** Icon, Avatar, ColourToggle, Slider
- **Planned (2 molecules):** MapCard, FormField
- **Planned (4 organisms):** ServiceSelector, PricingTable, ArrangementForm, Footer

**Next steps:**
- ~~Build Footer organism~~ ✓ Done
- ~~Build ServiceSelector organism~~ ✓ Done
- Consider FormField molecule if Input's built-in label/helperText proves insufficient
- Remaining P3s: InfoOutlinedIcon sizing in ProviderCard, image loading placeholder, accent bar 3px→4px

### Session 2026-03-25p (continued) — Footer + ServiceSelector organisms

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Built Footer organism (`src/components/organisms/Footer/`):
  - Dark espresso (brand.950) surface with inverse white text
  - Logo + tagline + contact info (phone/email with tel:/mailto: links) in left column
  - Configurable link group columns with heading + `<ul>` list
  - Bottom legal bar: copyright + legal links (Privacy, Terms, Accessibility)
  - Semantic HTML: `<footer>`, `<nav aria-label>` per link group, `<ul>` for link lists
  - Responsive: stacks to single column on mobile, side-by-side on desktop
  - 5 stories: Default, Minimal, WithContactOnly, TwoColumns, FullPage (Nav + content + Footer)
  - Critique: 38/40 (Excellent). P2 fixes applied: legal links bumped from 11px → 12px, nav landmarks added
- Built ServiceSelector organism (`src/components/organisms/ServiceSelector/`):
  - Single-select panel composing Typography + ServiceOption × n + Button
  - Heading + optional subheading + radiogroup of ServiceOption cards + optional continue button
  - Continue button auto-disables when nothing selected (overridable via `continueDisabled`)
  - `maxDescriptionLines` pass-through to ServiceOption for truncation
  - 7 stories: Default, PreSelected, Interactive, CoffinSelection, WithTruncatedDescriptions, WithoutContinue, WithDisabledOptions, InArrangementFlow (with StepIndicator)
- No new tokens needed — both organisms reuse existing token system
- TypeScript compiles, Storybook builds

**Decisions made:**
- Footer uses brand.950 (espresso) background — darkest brand tone for maximum contrast with white text, warm but professional
- Footer link groups get individual `<nav aria-label>` landmarks — better screen reader navigation
- ServiceSelector is a controlled component: parent manages `selectedId` + `onSelect`. Keeps state lifting simple for arrangement flow.
- Continue button defaults to disabled when nothing selected — prevents empty submissions without explicit error messages

**Component status at end of session:**
- **Done (11 atoms):** Button, Typography, Input, Card, Badge, Chip, Switch, Radio, IconButton, Divider, Link
- **Done (6 molecules):** ProviderCard, VenueCard, ServiceOption, SearchBar, AddOnOption, StepIndicator
- **Done (1 organism):** Navigation
- **Review (2 organisms):** Footer (critique 38/40), ServiceSelector
- **Planned (3 atoms):** Icon, Avatar, ColourToggle, Slider
- **Planned (2 molecules):** MapCard, FormField
- **Planned (2 organisms):** PricingTable, ArrangementForm

**Next steps:**
- ~~User to review Footer + ServiceSelector~~ ✓ Approved
- ~~Build ArrangementForm~~ Removed — premature, need more building blocks
- ~~Build Package Select page components~~ ✓ Done

### Session 2026-03-26a — Reviews, Navigation fixes, Package Select page components

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- Completed review of all 10 "review" components — all approved to done
- Navigation fixes from user feedback:
  - Added "Provider Portal" to nav items
  - Integrated real FA logo SVGs from `brandassets/brandlogo/`
  - Changed nav background from warm (brand.50) → grey (neutral.50 / surface.subtle)
  - Removed `mobileTrailing` prop and MobilePriceTracker story (speculative)
  - Added `staticDirs` to Storybook for brand asset serving
- Built Footer organism (critique 38/40):
  - Dark espresso bg, logo + tagline + contact + link columns + legal bar
  - P2 fixes: extracted overline sx, used overlineSm variant, bumped legal links to 12px
- Built ServiceSelector organism:
  - Single-select panel with radiogroup, continue button auto-disables
  - WithLineLimit story for description truncation
- Built and removed ArrangementForm organism (premature — user flagged)
- Analysed Package Select page from Figma (5405:181955):
  - Identified gaps: LineItem, ProviderCardCompact, PackageDetail
  - Recommended Chip filter bar for funeral type switching
- Built LineItem molecule (audit 19/20):
  - Name + info tooltip + optional price, allowance asterisk, total variant
  - Font weight 500 (D019), prices text.secondary for readability hierarchy
  - aria-label on info icon for screen readers
- Built ProviderCardCompact molecule:
  - Horizontal layout: image left, name + location + rating right
- Built PackageDetail organism (audit 19/20):
  - Warm header band with "Package" overline, name, price in brand colour
  - sections (before total) + total + extras (after total with subtext)
  - compareLoading prop for Compare button spinner
  - T&C grey footer, responsive button stacking
  - Section headings h6 (16px/600) vs LineItem body2 (14px/500) for hierarchy
  - Full PackageSelectPage story with filter chips, ServiceOption list, sticky detail
- Multiple audit + review iterations with user feedback applied

**Decisions made:**
- Navigation background is grey (surface.subtle), not warm — per user
- "Make Arrangement" is the FA term for selecting/committing to a package
- PackageDetail structure: sections → total → extras. Total separates included content from additional-cost items. Business-critical distinction.
- LineItem prices use text.secondary — name reads first, price supports. Total row stays prominent.
- Chip filter bar for funeral type switching — visible, discoverable, matches existing Chip component
- Always audit before presenting to user — saved as feedback memory

**Component status at end of session:**
- **Done (11 atoms):** Button, Typography, Input, Card, Badge, Chip, Switch, Radio, IconButton, Divider, Link
- **Done (10 molecules):** ProviderCard, VenueCard, ServiceOption, SearchBar, AddOnOption, StepIndicator, LineItem, ProviderCardCompact
- **Done (4 organisms):** Navigation, Footer, ServiceSelector, PackageDetail
- **Planned (3 atoms):** Icon, Avatar, ColourToggle, Slider
- **Planned (2 molecules):** MapCard, FormField
- **Planned (2 organisms):** PricingTable, ArrangementForm

**Next steps:**
- ~~Review next key page (Package Select)~~ ✓ Done
- ~~Build homepage FuneralFinder organism~~ ✓ Done (v2 — conversational redesign)

### Session 2026-03-26b — FuneralFinder organism + further PackageDetail refinements

**Agent(s):** Claude Opus (via conversation)

**Work completed:**
- PackageDetail review refinements from user feedback:
  - Section headings bumped from label (14px) to h6 (16px/600) — now stand out against line items
  - Added Divider + subtext before Extras ("These items can be added at additional cost")
  - T&C line height reduced 1.5 → 1.3
  - Item spacing increased 12px → 16px
  - Warm header band (surface.warm) with "Package" overline, name, price in brand colour
  - Compare button loading state (compareLoading prop)
  - Complimentary items now correctly shown before total
  - Total row padding balanced (top matched to bottom)
  - Audit: 19/20 (Excellent)
- Built FuneralFinder organism — homepage hero search widget:
  - **v1**: Literal translation of marketing reference — numbered steps, uppercase overlines, cramped options. User feedback: "looks like a government form, not gentle guidance"
  - **v2 (current)**: Complete conversational redesign:
    - Warm questions: "How can we help you today?" not "I'M HERE TO"
    - ChoiceCards: generous padding, descriptions, check icon on selection
    - TypePills: pill-shaped buttons for dynamic funeral type list
    - CompletedRow: "I'm here to **Arrange a funeral now** · Change"
    - One question at a time — true progressive disclosure
    - CTA only appears at location step — no disabled button staring at you
    - No step numbers or badges
  - Flow: Intent → Planning For (conditional) → Funeral Type → Location → CTA
  - Audit: 17/20 (Good). P1/P2 fixes applied: aria-labels, radiogroup semantics, edit affordance
  - 5 stories: Default, FewerTypes, CustomHeading, InHeroDesktop, InHeroMobile

**Decisions made:**
- "Make Arrangement" is FA's term for selecting/committing to a package
- PackageDetail structure: sections → total → extras (business-critical distinction)
- LineItem prices use text.secondary for readability hierarchy
- FuneralFinder uses conversational approach, not procedural/form-like
- Funeral types are prop-driven (dynamic from API)
- Pre-plan "for someone else" affects the arrangement journey
- Location needs a reusable Autocomplete atom (future work)
- "Find funeral directors" is the CTA text (not "Find providers")

**Component status at end of session:**
- **Done (11 atoms):** Button, Typography, Input, Card, Badge, Chip, Switch, Radio, IconButton, Divider, Link
- **Done (10 molecules):** ProviderCard, VenueCard, ServiceOption, SearchBar, AddOnOption, StepIndicator, LineItem, ProviderCardCompact
- **Done (4 organisms):** Navigation, Footer, ServiceSelector, PackageDetail
- **Review (1 organism):** FuneralFinder (v2 conversational — user wants further changes)
- **Planned (3 atoms):** Icon, Avatar, ColourToggle, Slider
- **Planned (2 molecules):** MapCard, FormField, Autocomplete
- **Planned (2 organisms):** PricingTable, ArrangementForm

**Next steps:**
- User to continue refining FuneralFinder — further UX changes planned
- Homepage redesign — FuneralFinder is one organism on the page, full homepage composition next
- Build Autocomplete atom for location search (reusable pattern for other areas)
- P3 cleanup: inverse logo SVG, InfoOutlinedIcon sizing in ProviderCard, image placeholder, accent bar 3px→4px
