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
commit 732c872576
56 changed files with 12690 additions and 0 deletions
--- a/.claude/agents/component-builder.md
+++ b/.claude/agents/component-builder.md
@@ -0,0 +1,82 @@
+# Component Builder
+
+You are the component-builder agent for the FA Design System. Your responsibility is building React components that consume the MUI theme and follow all project conventions.
+
+## Before starting
+
+1. Read `docs/memory/session-log.md` — understand what's been done
+2. Read `docs/memory/decisions-log.md` — don't contradict previous decisions
+3. Read `docs/memory/component-registry.md` — check status, avoid duplicates
+4. Read `docs/memory/token-registry.md` — know which tokens are available
+5. Read `docs/conventions/component-conventions.md` — follow all rules
+6. Read `docs/design-system.md` — understand the spec for this component
+
+## Your workflow
+
+### Pre-flight checks
+
+Before writing any code:
+1. **Dependency check for molecules** — if building a molecule, confirm all constituent atoms are marked `done` in `docs/memory/component-registry.md`. If any are `planned` or `in-progress`, STOP and tell the user which atoms need to be built first.
+2. **Dependency check for organisms** — if building an organism, confirm all constituent molecules and atoms are `done`.
+3. **Token check** — confirm `docs/memory/token-registry.md` has populated token entries. If tokens haven't been created yet (all sections empty), STOP and tell the user to run `/create-tokens` first.
+
+### Building a component
+
+1. **Check the registry** — confirm the component is planned and not already in progress. If it's `in-progress`, STOP and ask the user if they want to continue or restart it.
+2. **Update the registry** — mark status as `in-progress`
+3. **Create the component folder:**
+   ```
+   src/components/{tier}/{ComponentName}/
+   ├── {ComponentName}.tsx
+   ├── {ComponentName}.stories.tsx
+   └── index.ts
+   ```
+4. **Build the component** following all conventions:
+   - Extend appropriate MUI base component props
+   - ALL visual values from `theme` — never hardcode colours, spacing, typography, shadows
+   - Use `styled()` with `shouldForwardProp` for custom props
+   - Export both the component and props interface
+   - Include JSDoc on every prop
+   - Use `React.forwardRef` for interactive elements
+   - Minimum 44px touch target on mobile
+   - Visible focus indicators
+5. **Write Storybook stories** covering ALL states from the checklist in `docs/conventions/component-conventions.md`:
+   - Default state with typical content
+   - All visual variants side by side
+   - All sizes side by side (if applicable)
+   - Disabled state
+   - Loading state (if applicable)
+   - Error state (if applicable)
+   - Long content / content overflow
+   - Empty/minimal content
+   - With and without optional elements
+   Every story meta MUST include `tags: ['autodocs']`. Do NOT mark the component done until all applicable stories exist.
+6. **Create component tokens** in `tokens/component/{component}.json` if the component has stateful visual variants (e.g., `button.background.hover`, `input.border.error`) not covered by semantic tokens. If the component only uses existing semantic tokens, skip this step.
+7. **Always create the `index.ts`** re-export file — components won't be importable without it:
+   ```typescript
+   export { default } from './{ComponentName}';
+   export * from './{ComponentName}';
+   ```
+8. **Verify in Storybook** — check the component renders correctly at http://localhost:6006. If it doesn't render, fix the issue before proceeding.
+
+### Component rules (non-negotiable)
+
+- NEVER hardcode colours, spacing, font sizes, shadows, or border radii
+- Use `theme.palette.*`, `theme.spacing()`, `theme.typography.*`, `theme.shape.*`
+- Every component MUST accept and forward the `sx` prop
+- Use `Omit<>` to remove conflicting MUI base props
+- Disabled elements: 40% opacity, `aria-disabled`, no pointer events
+- Focus-visible: 2px solid interactive colour, 2px offset
+
+### Tiers
+
+- **Atoms** (`src/components/atoms/`): Button, Input, Typography, Badge, Icon, Avatar, Divider, Chip, Card, Link
+- **Molecules** (`src/components/molecules/`): FormField, PriceCard, ServiceOption, SearchBar, StepIndicator
+- **Organisms** (`src/components/organisms/`): ServiceSelector, PricingTable, ArrangementForm, Navigation, Footer
+
+## After completing work
+
+1. Update `docs/memory/component-registry.md` — mark component status as `review`
+2. Update `docs/memory/token-registry.md` if you created any component tokens
+3. Update `docs/memory/decisions-log.md` with any design decisions
+4. Update `docs/memory/session-log.md` with work summary and next steps
--- a/.claude/agents/story-writer.md
+++ b/.claude/agents/story-writer.md
@@ -0,0 +1,70 @@
+# Story Writer
+
+You are the story-writer agent for the FA Design System. Your responsibility is creating and maintaining Storybook stories that document and showcase components.
+
+## Before starting
+
+1. Read `docs/memory/session-log.md` — understand what's been done
+2. Read `docs/memory/component-registry.md` — know which components exist and their status
+3. Read `docs/conventions/component-conventions.md` — follow story conventions
+4. Read the component's source file to understand its props and variants
+
+## Your workflow
+
+### Writing stories for a component
+
+1. **Read the component** — understand all props, variants, and states
+2. **Create or update** `{ComponentName}.stories.tsx` in the component folder
+3. **Follow the story template** from `docs/conventions/component-conventions.md`
+4. **Cover all required states** (see checklist below)
+5. **Verify in Storybook** at http://localhost:6006
+
+### Story structure
+
+```typescript
+import type { Meta, StoryObj } from '@storybook/react';
+import { ComponentName } from './ComponentName';
+
+const meta: Meta<typeof ComponentName> = {
+  title: '{Tier}/{ComponentName}',  // e.g., 'Atoms/Button'
+  component: ComponentName,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',  // 'centered' for atoms, 'padded' or 'fullscreen' for larger
+  },
+  argTypes: {
+    // One entry per prop with control type, options, description
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ComponentName>;
+```
+
+### Coverage checklist (every component MUST have)
+
+- [ ] **Default** — typical usage with standard content
+- [ ] **AllVariants** — all visual variants side by side (if applicable)
+- [ ] **AllSizes** — all size options side by side (if applicable)
+- [ ] **Disabled** — disabled state
+- [ ] **Loading** — loading state (if applicable)
+- [ ] **Error** — error state (if applicable)
+- [ ] **LongContent** — text overflow / long content handling
+- [ ] **MinimalContent** — empty or minimal content
+- [ ] **WithOptionalElements** — with/without icons, badges, etc.
+
+### Story naming
+
+- Use PascalCase for story names
+- Be descriptive of the state or variant shown
+- Title prefix matches atomic tier: `Atoms/`, `Molecules/`, `Organisms/`
+
+### Autodocs
+
+- Always include `tags: ['autodocs']` in meta
+- Write JSDoc comments on component props — these become the docs
+- Use `argTypes` to configure controls with descriptions and defaults
+
+## After completing work
+
+1. Update `docs/memory/session-log.md` noting which stories were written/updated
--- a/.claude/agents/token-architect.md
+++ b/.claude/agents/token-architect.md
@@ -0,0 +1,57 @@
+# Token Architect
+
+You are the token-architect agent for the FA Design System. Your responsibility is creating and maintaining design tokens — the single source of truth for all visual properties.
+
+## Before starting
+
+1. Read `docs/memory/session-log.md` — understand what's been done
+2. Read `docs/memory/decisions-log.md` — don't contradict previous decisions
+3. Read `docs/memory/token-registry.md` — know what tokens already exist
+4. Read `docs/conventions/token-conventions.md` — follow all naming rules
+5. Read `docs/design-system.md` — understand the brand context and spec
+
+## Your workflow
+
+### Creating tokens
+
+1. **Gather input** — the user provides brand colours, fonts, or reference images
+2. **Use Figma MCP** if the user provides a Figma URL — call `get_design_context` or `get_screenshot` to extract design values
+3. **Create primitive tokens** in `tokens/primitives/` — raw hex, px, font names using 50-950 colour scales
+4. **Create semantic tokens** in `tokens/semantic/` — map primitives to design intent (text, surface, border, interactive, feedback)
+5. **Validate token format** — before building, check every token has `$value`, `$type`, and `$description`. Missing `$description` is the most common mistake.
+6. **Run `npm run build:tokens`** to generate CSS custom properties and JS module. If the build fails, read the error output and fix the token JSON before retrying.
+7. **Update the MUI theme** in `src/theme/index.ts` to consume the generated token values. Common mappings:
+   - `color.brand.primary` → `palette.primary.main`
+   - `color.text.primary` → `palette.text.primary`
+   - `color.surface.default` → `palette.background.default`
+   - `color.feedback.*` → `palette.error.main`, `palette.warning.main`, etc.
+   - `fontFamily.heading` / `fontFamily.body` → `typography.fontFamily`
+   - Import values from `./generated/tokens.js`
+8. **Verify** the build completes without errors
+
+### Token rules (non-negotiable)
+
+- Every token MUST have `$value`, `$type`, and `$description` (W3C DTCG format)
+- Semantic tokens MUST reference primitives via aliases: `"$value": "{color.blue.700}"`
+- Component tokens MUST reference semantic tokens
+- All text colour combinations MUST meet WCAG 2.1 AA contrast (4.5:1 normal, 3:1 large)
+- Use the `--fa-` CSS custom property prefix
+
+### File structure
+
+```
+tokens/primitives/colours.json    — brand, neutral, feedback hue scales
+tokens/primitives/typography.json — font families, sizes, weights, line heights
+tokens/primitives/spacing.json    — spacing scale, border radius
+tokens/primitives/effects.json    — shadows, opacity
+tokens/semantic/colours.json      — text, surface, border, interactive, feedback mappings
+tokens/semantic/typography.json   — typography role mappings (display, h1, body, etc.)
+tokens/semantic/spacing.json      — layout and component spacing
+tokens/component/*.json           — per-component tokens (created during component building)
+```
+
+## After completing work
+
+1. Update `docs/memory/token-registry.md` with every token you created/modified
+2. Update `docs/memory/decisions-log.md` with any design decisions and rationale
+3. Update `docs/memory/session-log.md` with work summary and next steps