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>

.claude/skills/build-atom/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: build-atom
+description: Build an atom component (Button, Input, Typography, etc.)
+argument-hint: "[ComponentName]"
+---
+
+Build an atom component for the FA Design System.
+
+Use the component-builder agent to handle this task. The user wants to build the following atom component:
+
+**Component:** $ARGUMENTS
+
+**Instructions for the agent:**
+1. Read all memory files and conventions before starting
+2. Check `docs/memory/component-registry.md` to confirm the component is planned
+3. Create the component in `src/components/atoms/{ComponentName}/`
+4. Include: `{ComponentName}.tsx`, `{ComponentName}.stories.tsx`, `index.ts`
+5. Follow all rules in `docs/conventions/component-conventions.md`
+6. ALL visual values MUST come from the MUI theme — never hardcode
+7. Write comprehensive Storybook stories covering all states
+8. Verify the component renders in Storybook
+9. Update all memory files when done

.claude/skills/build-molecule/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: build-molecule
+description: Build a molecule component (PriceCard, FormField, etc.)
+argument-hint: "[ComponentName]"
+---
+
+Build a molecule component for the FA Design System.
+
+Use the component-builder agent to handle this task. The user wants to build the following molecule component:
+
+**Component:** $ARGUMENTS
+
+**Instructions for the agent:**
+1. Read all memory files and conventions before starting
+2. Check `docs/memory/component-registry.md` to confirm the component is planned and that its constituent atoms are `done`
+3. Create the component in `src/components/molecules/{ComponentName}/`
+4. Include: `{ComponentName}.tsx`, `{ComponentName}.stories.tsx`, `index.ts`
+5. Compose from existing atom components — import from `@atoms/`
+6. Follow all rules in `docs/conventions/component-conventions.md`
+7. ALL visual values MUST come from the MUI theme — never hardcode
+8. Write comprehensive Storybook stories with realistic content
+9. Verify the component renders in Storybook
+10. Update all memory files when done

.claude/skills/build-organism/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: build-organism
+description: Build an organism component (Navigation, PricingTable, etc.)
+argument-hint: "[ComponentName]"
+---
+
+Build an organism component for the FA Design System.
+
+Use the component-builder agent to handle this task. The user wants to build the following organism component:
+
+**Component:** $ARGUMENTS
+
+**Instructions for the agent:**
+1. Read all memory files and conventions before starting
+2. Check `docs/memory/component-registry.md` — confirm the organism is planned
+3. Verify all constituent molecules and atoms are marked `done` in the registry — if any are not, STOP and tell the user which dependencies need to be built first
+4. Create the component in `src/components/organisms/{ComponentName}/`
+5. Include: `{ComponentName}.tsx`, `{ComponentName}.stories.tsx`, `index.ts`
+6. Compose from existing molecule and atom components — import from `@molecules/` and `@atoms/`
+7. Follow all rules in `docs/conventions/component-conventions.md`
+8. ALL visual values MUST come from the MUI theme — never hardcode
+9. Write comprehensive Storybook stories with realistic page-level content
+10. Verify the component renders in Storybook
+11. Update all memory files when done

.claude/skills/create-tokens/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: create-tokens
+description: Create design tokens from brand colours, fonts, and reference material
+argument-hint: "[brand colours, fonts, or Figma URL]"
+---
+
+Create design tokens for the FA Design System.
+
+Use the token-architect agent to handle this task. The user's input follows — it may include brand colours, font choices, reference images, or Figma URLs.
+
+**Instructions for the agent:**
+1. Read all memory files and conventions before starting
+2. If the user provides a Figma URL, use the Figma MCP to extract design context
+3. Create primitive tokens (colour scales, typography, spacing, effects)
+4. Create semantic tokens (map primitives to design intent)
+5. Run `npm run build:tokens` to generate outputs
+6. Update the MUI theme in `src/theme/index.ts` to use generated values
+7. Update all memory files when done
+
+User input: $ARGUMENTS

.claude/skills/review-component/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: review-component
+description: Review a component against design system conventions
+argument-hint: "[ComponentName]"
+---
+
+Review a component against FA Design System conventions and report pass/fail for each check.
+
+**Component to review:** $ARGUMENTS
+
+**Instructions:**
+1. Read `docs/conventions/component-conventions.md` for the rules
+2. Read `docs/conventions/token-conventions.md` for token usage rules
+3. Read the component source file in `src/components/`
+4. Read the component's Storybook stories
+
+**Check each of these and report pass/fail:**
+
+### Code quality
+- [ ] Component uses TypeScript with proper types
+- [ ] Props interface exported with JSDoc on every prop
+- [ ] Uses `React.forwardRef` for interactive elements
+- [ ] Accepts and forwards `sx` prop
+- [ ] Uses `shouldForwardProp` for custom props on styled components
+
+### Theme compliance
+- [ ] NO hardcoded colours — all from `theme.palette.*`
+- [ ] NO hardcoded spacing — all from `theme.spacing()`
+- [ ] NO hardcoded typography — all from `theme.typography.*`
+- [ ] NO hardcoded shadows — all from `theme.shadows`
+- [ ] NO hardcoded border radius — all from `theme.shape.*`
+
+### Accessibility
+- [ ] Minimum 44px touch target on mobile
+- [ ] Visible focus indicator (focus-visible)
+- [ ] Appropriate ARIA attributes
+- [ ] Disabled state uses `aria-disabled`
+- [ ] Colour contrast meets WCAG 2.1 AA
+
+### Storybook coverage
+- [ ] Default story
+- [ ] All variants story
+- [ ] All sizes story (if applicable)
+- [ ] Disabled state
+- [ ] Loading state (if applicable)
+- [ ] Long content / overflow
+- [ ] autodocs tag present
+
+**Report format:** List each check with pass/fail and specific issues found. End with a summary and recommended fixes.

.claude/skills/status/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: status
+description: Report current status of tokens, components, and build health
+---
+
+Report the current status of the FA Design System.
+
+**Instructions:**
+1. Read `docs/memory/session-log.md` — summarise recent work
+2. Read `docs/memory/component-registry.md` — count components by status (planned, in-progress, review, done)
+3. Read `docs/memory/token-registry.md` — summarise token coverage
+4. Read `docs/memory/decisions-log.md` — count decisions logged
+5. Check if Storybook is running (curl http://localhost:6006)
+6. Check if tokens build successfully (`npm run build:tokens`)
+
+**Report format:**
+```
+## FA Design System Status
+
+### Tokens
+- Primitives: [count] defined
+- Semantic: [count] defined
+- Component: [count] defined
+
+### Components
+- Done: [list]
+- In progress: [list]
+- Planned: [list]
+
+### Recent activity
+- [last session summary]
+
+### Next steps
+- [recommended next actions]
+```

.claude/skills/sync-tokens/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: sync-tokens
+description: Rebuild CSS and JS outputs from token JSON sources
+---
+
+Synchronise design tokens — rebuild CSS and JS outputs from token JSON sources.
+
+Use this after token JSON files have been edited manually or after `/create-tokens`. This is a maintenance command — it does NOT create new tokens (use `/create-tokens` for that).
+
+Use the token-architect agent to handle this task.
+
+**Instructions for the agent:**
+1. Read `docs/memory/token-registry.md` to understand current token state
+2. Validate all token JSON files have required fields (`$value`, `$type`, `$description`)
+3. Run `npm run build:tokens` to regenerate:
+   - `src/theme/generated/tokens.css` (CSS custom properties)
+   - `src/theme/generated/tokens.js` (JS ES6 module)
+   - `tokens/export/tokens-flat.json` (flat JSON export)
+4. Check that `src/theme/index.ts` is consuming the generated tokens correctly
+5. If any tokens were added/changed since the theme was last updated, update `src/theme/index.ts`
+6. Report what was generated and any issues found
+7. Update `docs/memory/token-registry.md` if it's out of date

.claude/skills/write-stories/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: write-stories
+description: Write or update Storybook stories for a component
+argument-hint: "[ComponentName]"
+---
+
+Write or update Storybook stories for an existing component.
+
+Use the story-writer agent to handle this task. The component to document:
+
+**Component:** $ARGUMENTS
+
+**Instructions for the agent:**
+1. Read `docs/conventions/component-conventions.md` for story standards
+2. Read the component source file at `src/components/` (check atoms/, molecules/, organisms/)
+3. Create or update `{ComponentName}.stories.tsx` in the component's folder
+4. Cover ALL items in the story coverage checklist:
+   - [ ] 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 (icons, badges, etc.)
+5. Every story meta MUST include `tags: ['autodocs']`
+6. Verify the component renders correctly in Storybook at http://localhost:6006
+7. Update `docs/memory/session-log.md` when done