mkdir -p docs/design/references
touch docs/design/references/.gitkeep

docs/design/
├── STYLE_GUIDE.md
├── UI_DESIGN_SYSTEM.md
├── UX_PRINCIPLES.md
├── REFERENCES.md
├── COMPONENT_SPEC.md
├── ANIMATION_GUIDE.md
├── RESPONSIVE_STRATEGY.md
└── references/
    └── .gitkeep

# Style Guide: {Project Name}

## Brand Identity

### Color Palette

#### Primary Colors
| Name | Hex | RGB | Usage |
|------|-----|-----|-------|
| {name} | #{hex} | rgb(r,g,b) | {when to use} |

#### Secondary Colors
| Name | Hex | RGB | Usage |
|------|-----|-----|-------|
| {name} | #{hex} | rgb(r,g,b) | {when to use} |

#### Semantic Colors
| Name | Hex | Usage |
|------|-----|-------|
| Success | #{hex} | Positive actions, confirmations |
| Warning | #{hex} | Caution states |
| Error | #{hex} | Errors, destructive actions |
| Info | #{hex} | Informational messages |

### CSS Variables

```css
:root {
  /* Primary */
  --color-primary: #{hex};
  --color-primary-hover: #{hex};
  --color-primary-active: #{hex};

  /* Secondary */
  --color-secondary: #{hex};

  /* Neutrals */
  --color-background: #{hex};
  --color-surface: #{hex};
  --color-text: #{hex};
  --color-text-muted: #{hex};

  /* Semantic */
  --color-success: #{hex};
  --color-warning: #{hex};
  --color-error: #{hex};
  --color-info: #{hex};
}

@import url('https://fonts.googleapis.com/css2?family={Font}:wght@400;500;600;700&display=swap');

:root {
  --space-xs: 0.25rem;
  --space-sm: 0.5rem;
  --space-md: 1rem;
  --space-lg: 1.5rem;
  --space-xl: 2rem;
  --space-2xl: 3rem;
}

### UI_DESIGN_SYSTEM.md Template

```markdown
# UI Design System: {Project Name}

## Component Catalog

### Buttons

#### Variants
| Variant | Usage | Example |
|---------|-------|---------|
| Primary | Main actions | Save, Submit |
| Secondary | Alternative actions | Cancel, Back |
| Ghost | Subtle actions | Learn more |
| Destructive | Dangerous actions | Delete |

#### States
- Default, Hover, Active, Focus, Disabled, Loading

#### Sizes
- Small (32px), Medium (40px), Large (48px)

### Form Inputs

#### Text Input
- Label above, placeholder hint, helper text below
- Error state with red border and message
- Focus ring with primary color

#### Select / Dropdown
- Custom styled, accessible
- Search for long lists

#### Checkbox / Radio
- Custom styled, clear hit area
- Group labels for related options

### Cards

#### Standard Card
- Surface background, shadow-md
- Padding: space-lg
- Radius: radius-md

#### Interactive Card
- Hover state with shadow-lg transition
- Optional click action

### Modals

- Centered, backdrop blur
- Max-width: 500px (sm), 700px (md), 900px (lg)
- Close button top-right
- Focus trap

### Navigation

#### Top Nav
- Logo left, nav items center/right
- Sticky on scroll
- Mobile: hamburger menu

#### Sidebar
- Collapsible
- Active state indicator
- Icons + labels

### Data Display

#### Tables
- Sticky header
- Zebra stripes optional
- Sortable columns
- Responsive: horizontal scroll or card view

#### Lists
- Clear item separation
- Icon/avatar left, actions right

## Layout Patterns

### Container Widths
| Size | Max Width | Usage |
|------|-----------|-------|
| sm | 640px | Narrow content |
| md | 768px | Default |
| lg | 1024px | Wide content |
| xl | 1280px | Full layouts |

### Grid System
- 12-column grid
- Gap: space-md (desktop), space-sm (mobile)

---
_Created: {YYYY-MM-DD}_ | _Version: 1.0_

# UX Principles: {Project Name}

## Core Principles

### 1. {Principle Name}
{Description of principle and why it matters}

**Do:** {Positive example}
**Don't:** {Anti-pattern}

### 2. {Principle Name}
{Description}

## Interaction Patterns

### Feedback

| Action | Feedback | Timing |
|--------|----------|--------|
| Button click | Visual press state | Immediate |
| Form submit | Loading → Success/Error | During operation |
| Data load | Skeleton → Content | While loading |

### Error Handling

| Error Type | Display | Action |
|------------|---------|--------|
| Validation | Inline below field | Immediate |
| Server | Toast notification | After response |
| Critical | Full-page message | Blocking |

### Loading States

| Context | Pattern |
|---------|---------|
| Initial page | Full skeleton |
| Data refresh | Subtle spinner + stale data |
| Button action | Spinner inside button |

## Accessibility (WCAG 2.1 AA)

### Color Contrast
- Text: 4.5:1 minimum
- Large text: 3:1 minimum
- UI components: 3:1 minimum

### Keyboard Navigation
- All interactive elements focusable
- Visible focus indicators
- Logical tab order
- Escape closes modals

### Screen Readers
- Semantic HTML
- ARIA labels for icons/images
- Live regions for dynamic content

## User Flows

### {Flow Name}
```mermaid
flowchart LR
  A[Start] --> B[Step 1]
  B --> C{Decision}
  C -->|Yes| D[Path A]
  C -->|No| E[Path B]

### REFERENCES.md Template

```markdown
# Design References: {Project Name}

## Inspiration Sources

### Websites

| URL | What to Take | Notes |
|-----|--------------|-------|
| {url} | {specific elements} | {notes} |

### Screenshots

| File | Source | Inspiration |
|------|--------|-------------|
| `references/{filename}` | {where from} | {what we like} |

### Mood Board

{Description of overall aesthetic direction}

## Design Decisions Log

| Decision | Rationale | Date |
|----------|-----------|------|
| {decision} | {why} | {date} |

---
_Created: {YYYY-MM-DD}_ | _Version: 1.0_

# Component Specifications: {Project Name}

## Component: {ComponentName}

### Purpose
{What this component does}

### Props / API

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| {prop} | {type} | {default} | {yes/no} | {description} |

### Variants

| Variant | Description |
|---------|-------------|
| {variant} | {when to use} |

### States

| State | Visual Change |
|-------|---------------|
| default | {description} |
| hover | {description} |
| active | {description} |
| disabled | {description} |

### Slots / Children

| Slot | Purpose |
|------|---------|
| {slot} | {what goes here} |

### Usage Example

```tsx
<ComponentName
  prop="value"
  variant="primary"
/>

### ANIMATION_GUIDE.md Template

```markdown
# Animation Guide: {Project Name}

## Motion Principles

### 1. Purposeful
Every animation should serve a purpose: guide attention, provide feedback, or establish spatial relationships.

### 2. Quick
Animations should feel snappy. Most under 300ms.

### 3. Natural
Use easing curves that feel organic.

## Timing

| Duration | Usage |
|----------|-------|
| 100ms | Micro-interactions (hover, toggle) |
| 200ms | Standard transitions |
| 300ms | Complex transitions |
| 500ms+ | Emphasis, page transitions |

## Easing Curves

| Name | CSS | Usage |
|------|-----|-------|
| ease-out | cubic-bezier(0, 0, 0.2, 1) | Enter animations |
| ease-in | cubic-bezier(0.4, 0, 1, 1) | Exit animations |
| ease-in-out | cubic-bezier(0.4, 0, 0.2, 1) | Move/resize |
| spring | {custom} | Playful bounce |

### CSS Variables

```css
:root {
  --duration-fast: 100ms;
  --duration-normal: 200ms;
  --duration-slow: 300ms;

  --ease-out: cubic-bezier(0, 0, 0.2, 1);
  --ease-in: cubic-bezier(0.4, 0, 1, 1);
  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
}

@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

### RESPONSIVE_STRATEGY.md Template

```markdown
# Responsive Strategy: {Project Name}

## Approach

**Mobile-first** / **Desktop-first** (choose one)

{Rationale for chosen approach}

## Breakpoints

| Name | Width | Target |
|------|-------|--------|
| sm | 640px | Large phones |
| md | 768px | Tablets |
| lg | 1024px | Laptops |
| xl | 1280px | Desktops |
| 2xl | 1536px | Large screens |

### CSS Variables

```css
/* Tailwind-compatible */
--screen-sm: 640px;
--screen-md: 768px;
--screen-lg: 1024px;
--screen-xl: 1280px;
--screen-2xl: 1536px;

/* Mobile-first */
@media (min-width: 640px) { /* sm */ }
@media (min-width: 768px) { /* md */ }
@media (min-width: 1024px) { /* lg */ }
@media (min-width: 1280px) { /* xl */ }

/* Desktop-first */
@media (max-width: 1279px) { /* below xl */ }
@media (max-width: 1023px) { /* below lg */ }
@media (max-width: 767px) { /* below md */ }
@media (max-width: 639px) { /* below sm */ }

---

# IMPLEMENTATION MODE

## Trigger

`executing-plans` skill reads TASK.md and finds `specialist: frontend-design`

## Process

### Step 1: Load Design Context

Read design docs as constraints:

Extract CSS variables, component patterns, and design tokens.

### Step 2: Understand the Task

Read TASK.md for:
- Objective
- Acceptance criteria
- Technical context
- Files to create/modify

### Step 3: Design Thinking

Before coding, establish:

| Aspect | Question |
|--------|----------|
| **Purpose** | What problem does this UI solve? |
| **Tone** | What emotion should it evoke? (within design system) |
| **Constraints** | Technical requirements, accessibility |
| **Differentiation** | What makes this memorable? |

### Step 4: Implement

Create production-grade code that:

- Uses design tokens from STYLE_GUIDE.md (colors, fonts, spacing)
- Follows component patterns from UI_DESIGN_SYSTEM.md
- Applies animations from ANIMATION_GUIDE.md
- Respects breakpoints from RESPONSIVE_STRATEGY.md
- Is visually striking while staying within design system

### Step 5: Verify

| Check | Action |
|-------|--------|
| Design tokens | Verify CSS variables match STYLE_GUIDE |
| Accessibility | Check contrast, keyboard nav, ARIA |
| Responsiveness | Test all breakpoints |
| Animation | Verify reduced motion support |

## Frontend Aesthetics Guidelines

Even within design system constraints, apply these principles:

- **Typography**: Use the defined fonts with intention. Create hierarchy.
- **Color**: Use defined palette boldly. Don't be timid with the design system.
- **Motion**: Apply animations purposefully per ANIMATION_GUIDE.
- **Composition**: Create visual interest within the grid system.
- **Details**: Shadows, borders, spacing - precision matters.

**NEVER** produce generic output. The design system provides constraints, not excuses for mediocrity.

---

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Ignoring design docs in implementation mode | Always read STYLE_GUIDE first |
| Asking too many questions in docs mode | Just three questions, then research |
| Generic output | Make bold choices within constraints |
| Skipping references folder | Always create it for screenshots |
| Not using CSS variables | Extract and use tokens from STYLE_GUIDE |

## Remember

**Docs Mode:**
- Read inception + vision docs first
- Ask only three questions
- Research trends autonomously
- Generate all seven documents + references folder

**Implementation Mode:**
- Load design docs as constraints
- Apply design system strictly
- Still create memorable, distinctive UI
- Verify against design tokens