Parsons/AGENTS.md

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.