# FA 2.0 Design System

## Project

Funeral Arranger (funeralarranger.com.au) design system rebuild. Client: Parsons
(H.Parsons Funeral Directors). Users are often in distress — the design language
must be warm, professional, trustworthy, and calm.

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

## 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: primitives (`tokens/primitives/`) → semantic (`tokens/semantic/`) → component (`tokens/component/`)
Component tiers: atoms → molecules → organisms → templates → pages (in `src/components/`)

## Commands

- `npm run build:tokens` — regenerate CSS/JS from token JSON (run after any token change)
- `npm run storybook` — dev server on localhost:6006
- `npm run type-check` — TypeScript compilation check
- `npm run lint` / `npm run lint:fix` — ESLint
- `npm run format` / `npm run format:check` — Prettier
- `npm run test` — Vitest

## Rules (always)

1. Consume the MUI theme for all visual values — `theme.palette.*`, `theme.spacing()`, `theme.typography.*`
2. Every token has `$value`, `$type`, and `$description` (DTCG format)
3. Error styling uses copper (#B0610F) not red — grief-sensitive context
4. Read `docs/memory/` before starting work (decisions-log, component-registry, token-registry, session-log)
5. Update `docs/memory/` after completing work
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 in `docs/reference/component-lifecycle.md`
9. Commit and push after each coherent unit of work

## Rules (never)

- Use raw hex values in component source files — map to semantic tokens
- Mix token access methods — semantic via `theme.*`, component via `var(--fa-*)`
- Skip the barrel export (`index.ts`) for any component
- Edit files owned by another agent without coordinating (see File ownership)

## Git workflow

Remote: Gitea at `http://192.168.50.211:3000/richie/ParsonsFA.git`
Branch: all work on `main` for now.

Stage specific files (not `git add -A`). Commit message format:
```
Short summary (imperative mood, <70 chars)

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

## File conventions

- Component folders: PascalCase — `Button/`, `PriceCard/`
- Token files: camelCase — `colours.json`, `typography.json`
- Each component folder: `ComponentName.tsx`, `ComponentName.stories.tsx`, `index.ts`
- CSS custom properties prefix: `--fa-`
- Semantic tokens via theme, component tokens via CSS vars — see `docs/conventions/token-conventions.md`
- Component structure and props: see `docs/conventions/component-conventions.md`

## Key references

- Design spec: `docs/design-system.md`
- Component lifecycle: `docs/reference/component-lifecycle.md`
- Flow architecture (wizard steps, branching, fields): `documentation/flow-definition.yaml`
- Redesigned flow spec: `documentation/steps/flow-definition.yaml` + `documentation/steps/flow-spec.md`
- Cross-tool workflow: `docs/reference/cross-tool-workflow.md`

## File ownership

One file, one owner at a time. Check `docs/memory/session-log.md` before starting.

- **Component source, tokens, theme, memory files:** Claude Code owns writes
- **Visual QA, browser verification, screenshots:** Antigravity owns
- **Shared read:** all documentation, all source files, AGENTS.md
- **When backend agent starts:** backend owns `src/payload/`, `src/api/`; frontend agents never touch those. `documentation/flow-definition.yaml` is the shared contract.