# FA 2.0 Design System — Antigravity Rules

## Project context

Funeral Arranger (funeralarranger.com.au) design system rebuild. Parsons is the
client. 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+ (running on localhost:6006)
- Style Dictionary for token transformation
- W3C DTCG token format

## Hard rules

1. **Never hardcode colours, spacing, typography, or shadows** — always consume the MUI theme (`theme.palette.*`, `theme.spacing()`, `theme.typography.*`) or CSS custom properties (`var(--fa-*)`)
2. **Never use raw hex values in components** — map to semantic tokens
3. **Follow atomic design tiers:** atoms → molecules → organisms → templates → pages
4. **Component folders:** PascalCase, each contains `ComponentName.tsx`, `ComponentName.stories.tsx`, `index.ts`
5. **Token files:** camelCase in `tokens/` directory (primitives → semantic → component tiers)
6. **CSS custom properties prefix:** `--fa-`
7. **Error styling uses copper (#B0610F)** not red — this is intentional for grief-sensitive context
8. **Copy tone:** warm but not gushy. Understated empathy. Let UI structure be the empathy.

## Token access convention

- Semantic tokens: `theme.palette.*`, `theme.typography.*`, `theme.spacing()`
- Component tokens: `var(--fa-component-property-state)`
- Never mix — semantic via theme, component via CSS vars

## Storybook

Dev server runs on `localhost:6006`. When verifying components visually, navigate
to the specific story URL. Story IDs follow the pattern:
`/story/{tier}-{componentname}--{variantname}`

## File structure

```
src/components/atoms/       — Button, Input, Typography, Card, etc.
src/components/molecules/   — SearchBar, PriceCard, ServiceOption, etc.
src/components/organisms/   — Navigation, Footer, ArrangementDialog, etc.
src/components/templates/   — WizardLayout
src/components/pages/       — IntroStep, ProvidersStep, etc. (wizard steps)
tokens/primitives/          — Raw values (hex, px, font names)
tokens/semantic/            — Design intent (color.text.primary)
tokens/component/           — Per-component tokens
```

## When making visual changes

1. Make the code change
2. Open the Storybook story in the browser to verify
3. Screenshot and check spacing, alignment, visual weight
4. Self-correct if something looks off before presenting