Richie
82a7b843f8
- Add Gitea remote and commit-after-work workflow to CLAUDE.md - Fix .gitignore: correct storybook-static path, remove stale tokens.ts entry - Track generated token outputs (tokens.css, tokens.js) for clone-and-run Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
105 lines
4.6 KiB
Markdown
105 lines
4.6 KiB
Markdown
# 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. **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` — What was done in previous sessions, what's next
|
|
|
|
**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`
|