Files

Richie 732c872576 Initial commit: FA 2.0 Design System foundation

Token pipeline (Style Dictionary v4, DTCG format):
- Primitive tokens: colour palettes (brand, sage, neutral, feedback),
  typography (3 font families, 21-variant type scale), spacing (4px grid),
  border radius, shadows, opacity
- Semantic tokens: text, surface, border, interactive, feedback colours;
  typography roles; layout spacing
- Component tokens: Button (4 sizes), Input (2 sizes)
- Generated outputs: CSS custom properties, JS ES6 module, flat JSON

Atoms (3 components):
- Button: contained/soft/outlined/text × primary/secondary, 4 sizes,
  loading state, underline for text variant
- Typography: 21 variants across display/heading/body/label/caption/overline,
  maxLines truncation
- Input: external label, helper text, error/success validation,
  start/end icons, required indicator, 2 sizes, multiline support

Infrastructure:
- MUI v5 theme with full token mapping
- Storybook 8 with autodocs
- Claude Code agents and skills for token/component workflows
- Design system documentation and cross-session memory

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

2026-03-25 15:08:15 +11:00

3.6 KiB

Raw Blame History

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

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

Component tiers (atomic design)

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

Critical rules

Every component MUST consume the MUI theme — never hardcode colours, spacing, typography, or shadows
Every token MUST have a $description — this is how agents maintain context about design intent
Always read docs/design-system.md before creating or modifying anything
Always check docs/memory/ before starting work — these files contain decisions and state from previous sessions
Always update docs/memory/ after completing work — log what was done, decisions made, and open questions
Run npm run build:tokens after any token JSON change
Verify in Storybook before marking any component done

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

3.6 KiB Raw Blame History