Parsons/CLAUDE.md

FA 2.0 Design System

Project overview

Rebuilding the Funeral Arranger (funeralarranger.com.au) design system using a code-first approach. Parsons (H.Parsons Funeral Directors) is the client. FA is an Australian funeral planning platform — the design language must be warm, professional, trustworthy, and calm. Users are often in distress.

Tech stack

• React 18 + TypeScript
• Material UI (MUI) v5
• Storybook 8+ with autodocs
• Style Dictionary for token transformation
• W3C DTCG token format (2025.10 stable spec)
• Chromatic for Storybook hosting (later)

Architecture

Source of truth: Token JSON files in tokens/ (DTCG format) Flow: Token JSON → Style Dictionary → MUI theme + CSS vars → React components → Storybook

Token tiers

1. Primitives (tokens/primitives/): Raw values — hex, px, font names, scales
2. Semantic (tokens/semantic/): Design intent — color.text.primary, color.surface.default
3. Component (tokens/component/): Per-component — button.background.default

Component tiers (atomic design)

1. Atoms (src/components/atoms/): Button, Input, Typography, Badge, Icon, Avatar, Divider, Chip, Card, Link
2. Molecules (src/components/molecules/): SearchBar, PriceCard, ServiceOption, FormField
3. Organisms (src/components/organisms/): ServiceSelector, PricingTable, ArrangementForm, Navigation

Critical rules

1. Every component MUST consume the MUI theme — never hardcode colours, spacing, typography, or shadows
2. Every token MUST have a $description — this is how agents maintain context about design intent
3. Always read docs/design-system.md before creating or modifying anything
4. Always check docs/memory/ before starting work — these files contain decisions and state from previous sessions
5. Always update docs/memory/ after completing work — log what was done, decisions made, and open questions
6. Run npm run build:tokens after any token JSON change
7. Verify in Storybook before marking any component done
8. Follow the component lifecycle — see docs/reference/component-lifecycle.md for the full quality gate sequence (build → QA → polish → present → iterate → normalize → preflight → commit)
9. Commit and push after completing each unit of work — see Git workflow below

Git workflow

Remote: Gitea at http://192.168.50.211:3000/richie/ParsonsFA.git (credentials stored via git credential helper)

After completing each unit of work (a component, a token change, a bug fix, etc.):

1. Stage the changed files (git add — prefer naming specific files over git add -A)
2. Commit with a clear message describing what was done
3. Push to origin (git push)

This is not optional — the user relies on the git history for rollback safety. Each commit should represent a coherent, working state (Storybook builds, TypeScript compiles). Do not batch multiple unrelated changes into a single commit.

Commit message format:

Short summary (imperative mood, <70 chars)

- Bullet points with detail if needed
- Reference decision IDs (D001, D002...) when relevant

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Branch strategy: All work on main for now. Feature branches when the project grows.

Memory system

This project uses structured markdown files for cross-session memory.

Before starting any work, read these files:

• docs/memory/decisions-log.md — All design decisions with rationale
• docs/memory/component-registry.md — Status of every component (planned/in-progress/done)
• docs/memory/token-registry.md — All tokens with their current values and usage notes
• docs/memory/session-log.md — Recent sessions (last 2-3); older sessions in docs/memory/archive/

After completing work, update:

• The relevant memory files with what changed
• docs/memory/session-log.md with a summary of what was accomplished and next steps

MCP servers

• Figma remote MCP (figma-remote-mcp): Read FA 1.0 designs, extract design context
• Storybook MCP (storybook): Query component library for available components and props

Setup instructions in docs/reference/mcp-setup.md.

File conventions

• Component folders: PascalCase (Button/, PriceCard/)
• Token files: camelCase (colours.json, typography.json)
• Each component folder contains: ComponentName.tsx, ComponentName.stories.tsx, index.ts
• CSS custom properties prefix: --fa- (e.g., --fa-color-brand-primary)
• MUI theme paths: follow MUI conventions (palette.primary.main)

Naming conventions for tokens

See docs/conventions/token-conventions.md for the full specification.

Quick reference:

• Primitives: color.blue.500, spacing.4, fontSize.base
• Semantic: color.text.primary, color.surface.default, color.interactive.default
• Component: button.background.default, button.background.hover