richie/Parsons
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: FA 2.0 Design System foundation

Browse Source 
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>
This commit is contained in:
Richie
2026-03-25 15:08:15 +11:00
commit 732c872576
56 changed files with 12690 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
.claude/agents/component-builder.md Normal file
View File

@@ -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

70
.claude/agents/story-writer.md Normal file
View File

@@ -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

57
.claude/agents/token-architect.md Normal file
View File

@@ -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

22
.claude/skills/build-atom/SKILL.md Normal file
View File

@@ -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

23
.claude/skills/build-molecule/SKILL.md Normal file
View File

@@ -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

24
.claude/skills/build-organism/SKILL.md Normal file
View File

@@ -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

20
.claude/skills/create-tokens/SKILL.md Normal file
View File

@@ -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

49
.claude/skills/review-component/SKILL.md Normal file
View File

@@ -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.

35
.claude/skills/status/SKILL.md Normal file
View File

@@ -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]
```

22
.claude/skills/sync-tokens/SKILL.md Normal file
View File

@@ -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

29
.claude/skills/write-stories/SKILL.md Normal file
View File

@@ -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