./project-documentation/02-design/
├── design-system/
│   ├── README.md                    # Design system overview
│   ├── style-guide.md               # Complete style guide
│   ├── components/
│   │   ├── README.md                # Component library overview
│   │   ├── buttons.md               # Button specifications
│   │   ├── forms.md                 # Form elements
│   │   ├── navigation.md            # Navigation components
│   │   ├── cards.md                 # Card components
│   │   ├── modals.md                # Modal/dialog specs
│   │   ├── feedback.md              # Toasts, alerts, etc.
│   │   └── data-display.md          # Tables, lists, etc.
│   ├── tokens/
│   │   ├── README.md                # Design tokens overview
│   │   ├── colors.md                # Colour system
│   │   ├── typography.md            # Type system
│   │   ├── spacing.md               # Spacing scale
│   │   └── animations.md            # Motion system
│   └── patterns/
│       ├── README.md                # Pattern overview
│       ├── layouts.md               # Page layouts
│       ├── forms.md                 # Form patterns
│       └── navigation.md            # Navigation patterns
│
└── features/
    └── [feature-name]/
        ├── README.md                # Feature design overview
        ├── user-journey.md          # User flow analysis
        ├── screen-states.md         # All screen states
        └── implementation.md        # Developer handoff

---
title: Colour System
last-updated: [date]
status: approved
---

# Colour System

OKLCH provides perceptually uniform colours with predictable lightness and chroma.
Format: `oklch(L% C H)` where L=lightness (0-100%), C=chroma (0-0.4), H=hue (0-360°).

## Brand Colours

### Primary Palette

| Token | OKLCH | Usage |
|-------|-------|-------|
| primary-50 | oklch(97% 0.02 250) | Subtle backgrounds |
| primary-100 | oklch(93% 0.04 250) | Hover backgrounds |
| primary-200 | oklch(87% 0.08 250) | Light accents |
| primary-300 | oklch(77% 0.12 250) | Borders |
| primary-400 | oklch(67% 0.18 250) | Icons |
| primary-500 | oklch(55% 0.22 250) | **Primary actions** |
| primary-600 | oklch(48% 0.22 250) | Hover states |
| primary-700 | oklch(42% 0.20 250) | Active states |
| primary-800 | oklch(35% 0.16 250) | Dark accents |
| primary-900 | oklch(28% 0.12 250) | Text on light |

### Neutral Palette

| Token | OKLCH | Usage |
|-------|-------|-------|
| neutral-50 | oklch(98% 0.005 250) | Backgrounds |
| neutral-100 | oklch(96% 0.005 250) | Subtle backgrounds |
| neutral-200 | oklch(92% 0.01 250) | Borders, dividers |
| neutral-300 | oklch(87% 0.01 250) | Disabled backgrounds |
| neutral-400 | oklch(70% 0.01 250) | Placeholder text |
| neutral-500 | oklch(55% 0.01 250) | Secondary text |
| neutral-600 | oklch(45% 0.015 250) | Body text |
| neutral-700 | oklch(35% 0.015 250) | Headings |
| neutral-800 | oklch(25% 0.02 250) | High emphasis text |
| neutral-900 | oklch(15% 0.02 250) | Maximum contrast |

[Repeat for secondary palette with different hue]

## Semantic Colours

| Token | Light Mode | Dark Mode | Usage |
|-------|------------|-----------|-------|
| success | oklch(55% 0.18 145) | oklch(70% 0.18 145) | Positive actions, confirmations |
| warning | oklch(70% 0.16 85) | oklch(80% 0.14 85) | Caution states, alerts |
| error | oklch(55% 0.20 25) | oklch(70% 0.18 25) | Errors, destructive actions |
| info | oklch(55% 0.18 250) | oklch(70% 0.16 250) | Informational messages |

## Accessibility Matrix

OKLCH lightness makes contrast checking straightforward:
- For WCAG AA (4.5:1): Ensure ΔL ≥ 50% between text and background
- For WCAG AAA (7:1): Ensure ΔL ≥ 60% between text and background

| Combination | Lightness Delta | WCAG Level |
|-------------|-----------------|------------|
| primary-500 on neutral-50 | 43% | AA ✓ |
| neutral-800 on neutral-50 | 73% | AAA ✓ |
| neutral-50 on primary-700 | 56% | AA ✓ |
| [continue for all combinations] |

## Implementation

### Tailwind Config
```javascript
const oklch = (l, c, h) => `oklch(${l}% ${c} ${h})`;

colors: {
  primary: {
    50: oklch(97, 0.02, 250),
    100: oklch(93, 0.04, 250),
    200: oklch(87, 0.08, 250),
    300: oklch(77, 0.12, 250),
    400: oklch(67, 0.18, 250),
    500: oklch(55, 0.22, 250),
    600: oklch(48, 0.22, 250),
    700: oklch(42, 0.20, 250),
    800: oklch(35, 0.16, 250),
    900: oklch(28, 0.12, 250),
  },
  // ... continue for all palettes
}

:root {
  --color-primary-500: oklch(55% 0.22 250);
  --color-primary-600: oklch(48% 0.22 250);
  /* ... */
  
  /* Semantic tokens referencing primitives */
  --color-text-primary: var(--color-neutral-800);
  --color-bg-primary: var(--color-neutral-50);
}

/* Dark mode overrides */
@media (prefers-color-scheme: dark) {
  :root {
    --color-text-primary: var(--color-neutral-100);
    --color-bg-primary: var(--color-neutral-900);
  }
}

Create `tokens/typography.md`:

```markdown
---
title: Typography System
last-updated: [date]
status: approved
---

# Typography System

## Font Stack

### Primary (Sans-serif)
```css
font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;

font-family: 'JetBrains Mono', 'Fira Code', Consolas, monospace;

fontSize: {
  'display-xl': ['3.75rem', { lineHeight: '1.1', letterSpacing: '-0.02em' }],
  // ...
}

### Phase 2: Component Specifications

For each component, create comprehensive documentation:

`components/buttons.md`:

```markdown
---
title: Button Components
last-updated: [date]
status: approved
related:
  - ./forms.md
  - ../tokens/colors.md
---

# Button Components

## Overview

Buttons trigger actions. Use the appropriate variant based on the action's importance.

## Variants

### Primary Button

**When to use**: Main CTA, primary action on a page/form.

| State | Background | Text | Border | Shadow |
|-------|------------|------|--------|--------|
| Default | primary-500 | white | none | sm |
| Hover | primary-600 | white | none | md |
| Active | primary-700 | white | none | none |
| Focus | primary-500 | white | 2px primary-300 | sm |
| Disabled | neutral-200 | neutral-400 | none | none |
| Loading | primary-500 (50%) | — | none | sm |

**Specifications**:
- Border radius: 8px (md)
- Font: body-sm, weight 500
- Transition: 150ms ease-out (background, shadow)

### Secondary Button

**When to use**: Secondary actions, alternatives to primary.

| State | Background | Text | Border | Shadow |
|-------|------------|------|--------|--------|
| Default | transparent | primary-600 | 1px primary-300 | none |
| Hover | primary-50 | primary-700 | 1px primary-400 | none |
| Active | primary-100 | primary-800 | 1px primary-500 | none |
| Focus | transparent | primary-600 | 2px primary-300 | none |
| Disabled | transparent | neutral-300 | 1px neutral-200 | none |

[Continue for Ghost, Destructive variants]

## Sizes

| Size | Height | Padding (x) | Font Size | Icon Size |
|------|--------|-------------|-----------|-----------|
| sm | 32px | 12px | 14px | 16px |
| md | 40px | 16px | 14px | 18px |
| lg | 48px | 24px | 16px | 20px |
| xl | 56px | 32px | 18px | 24px |

## With Icons

- Icon-only: Square button, icon centered
- Icon + text: 8px gap between icon and text
- Icon position: Leading (left) for actions, trailing (right) for navigation

## Button Groups

- Use 1px gap or connected (no gap, shared borders)
- First button: border-radius left only
- Last button: border-radius right only
- Middle buttons: no border-radius

## Loading State

- Replace text with spinner (same size as icon)
- Maintain button width (prevent layout shift)
- Disable all interactions
- Reduce opacity to 70%

## Accessibility

- Minimum touch target: 44x44px (use padding if button is smaller)
- Focus visible: 2px offset ring
- Disabled buttons: Use `aria-disabled="true"`, keep in tab order for discoverability
- Loading: Add `aria-busy="true"` and visually hidden loading text

## Do's and Don'ts

✅ **Do**:
- Use one primary button per view
- Keep button text concise (2-4 words)
- Use verbs for actions ("Save", "Delete", "Continue")

❌ **Don't**:
- Use multiple primary buttons
- Use vague labels ("Click here", "Submit")
- Disable without explanation

## Implementation Reference

```tsx
// Example usage
<Button variant="primary" size="md" loading={isLoading}>
  Save Changes
</Button>

### Phase 3: Feature-Specific Design

For each major feature, create dedicated documentation:

`features/[feature-name]/README.md`:

```markdown
---
title: [Feature Name] Design
feature: [feature-slug]
last-updated: [date]
status: approved
related:
  - ../../design-system/components/buttons.md
  - ../../design-system/components/forms.md
---

# [Feature Name] Design

## Overview

**Purpose**: [What this feature enables users to do]
**Primary Persona**: [From PM docs]
**Priority**: [MUST/SHOULD/COULD]

## User Journey

### Entry Points
- [How users discover/access this feature]

### Core Flow

### Exit Points
- [Where users go after completing]
- [Where users go if they abandon]

## Screen States

### State: Default
[Detailed layout and component specifications]

### State: Loading
[Loading state specifications]

### State: Empty
[Empty state design]

### State: Error
[Error handling design]

### State: Success
[Success state design]

## Responsive Behaviour

### Desktop (1024px+)
[Layout description]

### Tablet (768-1023px)
[Adaptations]

### Mobile (<768px)
[Mobile-specific design]

## Animations

| Element | Trigger | Animation | Duration | Easing |
|---------|---------|-----------|----------|--------|
| [element] | [trigger] | [description] | [ms] | [easing] |

## Accessibility Notes

- [Feature-specific accessibility considerations]
- [Keyboard shortcuts if applicable]
- [Screen reader announcements]

✅ Design System complete for [Project Name]

**Created**:
- Design system with [X] design tokens
- [X] component specifications
- [X] feature design documents
- Full accessibility documentation

**For Frontend Engineer**:
- Start with design-system/README.md for overview
- Reference tokens/* for all styling values
- Reference components/* for component implementation
- Reference features/* for feature-specific layouts
- Use /mnt/skills/public/frontend-design/SKILL.md for patterns

**Ready for**:
- Phase 2b: Architect (can proceed in parallel)
- Gate #1: Approval (once Architecture complete)