┌─────────────────────────────────────────────────────────┐
│                    DESIGN PYRAMID                       │
├─────────────────────────────────────────────────────────┤
│  ✨ Delight        → "Wow" moments, micro-interactions  │
│  🎯 Usability      → Easy to use, error prevention     │
│  📐 Functionality  → Solves the problem                │
│  🔍 Reliability    → Works consistently                │
└─────────────────────────────────────────────────────────┘

❌ NEVER create these experiences:
- Dark patterns that manipulate user choices
- Infinite scroll without escape
- Fake urgency or scarcity
- Hidden costs or terms
- Impossible-to-find cancel options
- Cookie-cutter templates without customization
- Beauty over function (pretty but unusable)
- Accessibility as an afterthought

✅ ALWAYS:
- Design for edge cases
- Make actions reversible
- Provide clear feedback
- Respect user attention
- Design for everyone

         Discover          Define          Deliver          Develop
            ▲                ▲                ▲                ▲
    ┌──────────┐      ┌──────────┐      ┌──────────┐      ┌──────────┐
    │ Research │      │ Synthesis│      │ Prototype│      │  Launch  │
    │  Empathize│     │   Focus  │      │  Test    │      │ Iterate  │
    └──────────┘      └──────────┘      └──────────┘      └──────────┘
         Diverge          Converge         Diverge          Converge

The 5 Whys Technique:
Problem: Users drop off at checkout
1. Why? → They abandon at shipping form
2. Why? → Shipping cost appears late
3. Why? → Cost shown after address entry
4. Why? → Current flow separates cost calc
5. Why? → Legacy system limitation

Root Cause: Users feel "tricked" by surprise shipping cost
Solution: Show shipping cost early, before form entry

# Persona: [Name]

## Demographics
- Age: [range]
- Location: [region]
- Tech Savviness: [level]
- Occupation: [role]

## Goals
- [Primary goal]
- [Secondary goal]
- [Latent need]

## Pain Points
- [Frustration 1]
- [Frustration 2]
- [Workaround they use]

## Behaviors
- "I usually [behavior] when [situation]"
- "I wish I could [desire]"
- "I hate it when [pet peeve]"

## Quote
"[Real or synthesized user quote]"

## Scenario
[Context: When, where, how they use the product]

[User] needs [need] because [insight],
but [current barrier] prevents them from [desired outcome].

Example:
"Busy parents need quick meal planning because they're time-poor,
but complex recipe apps prevent them from getting dinner on the table fast."

┌─────────────────────────────────────────────────────────┐
│                    LOW-FIDELITY                         │
│  • Paper sketches, whiteboard                           │
│  • Focus: Layout, flow, structure                      │
│  • Speed: Fastest (minutes)                            │
│  • Best for: Early ideation, team alignment            │
├─────────────────────────────────────────────────────────┤
│                   MID-FIDELITY                          │
│  • Digital wireframes, grayscale                        │
│  • Focus: Interaction, content hierarchy               │
│  • Speed: Fast (hours)                                 │
│  • Best for: User testing, stakeholder review          │
├─────────────────────────────────────────────────────────┤
│                   HIGH-FIDELITY                         │
│  • Visual design, colors, animations                    │
│  • Focus: Aesthetics, micro-interactions               │
│  • Speed: Slower (days)                                │
│  • Best for: Stakeholder buy-in, development handoff   │
└─────────────────────────────────────────────────────────┘

Always design components before pages:

1. Atoms   → Buttons, inputs, labels
2. Molecules → Search bar, form groups
3. Organisms → Navigation, cards, forms
4. Templates → Page layouts with components
5. Pages    → Complete, populated interface

Benefits:
- Consistent design language
- Faster iteration
- Easier maintenance
- Scalable system

F-Pattern (Text-heavy content):
┌────────────────────────────────┐
│ Eye starts here →              │
│                    →           │
│                    →           │
│                                │
│ Eye scans ↓ here               │
│                    →           │
│                    →           │
│                                │
│ Eye scans ↓ here               │
│                    →           │
└────────────────────────────────┘

Z-Pattern (Minimal content):
┌────────────────────────────────┐
│ Eye starts here → → → → → → → →│
│                              ↓ │
│                              ↓ │
│← ← ← ← ← ← ← ← ← ← ← ← ← ←  ↓ │
│                              ↓ │
│→ → → → → → → → → → → → → → → →│
└────────────────────────────────┘

/* Visual Hierarchy through Scale */
:root {
  /* Headings - Decreasing importance */
  --text-h1: clamp(2.5rem, 5vw, 4rem);    /* 40-64px */
  --text-h2: clamp(2rem, 4vw, 3rem);      /* 32-48px */
  --text-h3: clamp(1.5rem, 3vw, 2rem);    /* 24-32px */
  --text-h4: clamp(1.25rem, 2vw, 1.5rem); /* 20-24px */

  /* Body - Readable range */
  --text-body: clamp(1rem, 1.5vw, 1.125rem); /* 16-18px */
  --text-small: clamp(0.875rem, 1.2vw, 1rem); /* 14-16px */

  /* Weights for hierarchy */
  --font-light: 300;
  --font-regular: 400;
  --font-medium: 500;
  --font-semibold: 600;
  --font-bold: 700;
}

/* Visual priority classes */
.priority-critical {
  font-size: var(--text-h1);
  font-weight: var(--font-bold);
  color: var(--color-primary);
}

.priority-important {
  font-size: var(--text-h2);
  font-weight: var(--font-semibold);
}

.priority-secondary {
  font-size: var(--text-body);
  font-weight: var(--font-regular);
  color: var(--color-text-muted);
}

/* White Space as Design Element */
:root {
  /* Micro space - element spacing */
  --space-xs: 0.25rem;   /* 4px */
  --space-sm: 0.5rem;    /* 8px */
  --space-md: 1rem;      /* 16px */

  /* Macro space - section spacing */
  --space-lg: 2rem;      /* 32px */
  --space-xl: 4rem;      /* 64px */
  --space-2xl: 8rem;     /* 128px */
}

/* Breathing room for readability */
.container {
  max-width: 65ch; /* Optimal line length */
  padding: var(--space-xl);
}

.section {
  padding-block: var(--space-2xl); /* Generous vertical spacing */
}

/* Negative space creates focus */
.hero {
  min-height: 80vh; /* Dominant viewport share */
  display: grid;
  place-items: center;
}

┌─────────────────────────────────────────────────────────┐
│              WCAG AA COMPLIANCE                         │
├─────────────────────────────────────────────────────────┤
│  Normal Text (< 18pt / 24px):                           │
│    • Contrast ratio: 4.5:1 minimum                      │
│    • Example: #1a1a1a on #ffffff = 15.7:1 ✅           │
│    • Example: #666666 on #ffffff = 5.7:1 ✅            │
│                                                         │
│  Large Text (≥ 18pt / 24px or bold 14pt/18.6px):       │
│    • Contrast ratio: 3:1 minimum                        │
│    • Example: #767676 on #ffffff = 3.1:1 ✅            │
│                                                         │
│  Interactive Elements:                                  │
│    • Visual focus indicator: 3:1 minimum               │
│    • Focus not visible: 3:1 against background         │
└─────────────────────────────────────────────────────────┘

def contrast_ratio(hex1: str, hex2: str) -> float:
    """Calculate WCAG contrast ratio between two hex colors."""
    def relative_luminance(hex_color: str) -> float:
        r, g, b = hex_to_rgb(hex_color)
        # Normalize to 0-1
        r, g, b = [x / 255 for x in (r, g, b)]
        # Apply gamma correction
        def channel(c: float) -> float:
            return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
        r, g, b = map(channel, (r, g, b))
        return 0.2126 * r + 0.7152 * g + 0.0722 * b

    l1 = relative_luminance(hex1)
    l2 = relative_luminance(hex2)
    lighter = max(l1, l2)
    darker = min(l1, l2)
    return (lighter + 0.05) / (darker + 0.05)

/* Typography Scale - Major Third (1.250) */
:root {
  /* Type Scale */
  --scale-1: 1rem;      /* 16px - Base */
  --scale-2: 1.25rem;   /* 20px */
  --scale-3: 1.563rem;  /* 25px */
  --scale-4: 1.953rem;  /* 31px */
  --scale-5: 2.441rem;  /* 39px */
  --scale-6: 3.052rem;  /* 49px */

  /* Line Height for readability */
  --leading-tight: 1.25;   /* Headings */
  --leading-normal: 1.5;   /* Body text */
  --leading-relaxed: 1.75; /* Long-form content */

  /* Letter spacing for readability */
  --tracking-tight: -0.02em;   /* Large display */
  --tracking-normal: 0;        /* Body */
  --tracking-wide: 0.05em;     /* Small text, uppercase */
}

/* Applied typography */
.display {
  font-size: var(--scale-6);
  line-height: var(--leading-tight);
  letter-spacing: var(--tracking-tight);
}

.body {
  font-size: var(--scale-1);
  line-height: var(--leading-normal);
  letter-spacing: var(--tracking-normal);
}

.label {
  font-size: 0.875rem;
  line-height: var(--leading-normal);
  letter-spacing: var(--tracking-wide);
  text-transform: uppercase;
}

┌─────────────────────────────────────────────────────────┐
│                   DESIGN SYSTEM                         │
├─────────────────────────────────────────────────────────┤
│  TOKENS          │  COMPONENTS    │  PATTERNS          │
│  • Colors        │  • Buttons     │  • Forms           │
│  • Typography    │  • Inputs      │  • Navigation      │
│  • Spacing       │  • Cards       │  • Feedback        │
│  • Shadows       │  • Modals      │  • Data display    │
│  • Border Radius │  • Lists       │                    │
├─────────────────────────────────────────────────────────┤
│  DOCS            │  CODE          │  ASSETS            │
│  • Guidelines    │  • CSS/Sass    │  • Icons           │
│  • Examples      │  • React/Vue   │  • Illustrations   │
│  • Best practices│  • Tokens      │  • Photos          │
└─────────────────────────────────────────────────────────┘

{
  "color": {
    "primary": {
      "50": "#f0f9ff",
      "100": "#e0f2fe",
      "200": "#bae6fd",
      "300": "#7dd3fc",
      "400": "#38bdf8",
      "500": "#0ea5e9",
      "600": "#0284c7",
      "700": "#0369a1",
      "800": "#075985",
      "900": "#0c4a6e"
    },
    "semantic": {
      "bg-primary": "var(--color-gray-50)",
      "bg-secondary": "var(--color-gray-100)",
      "text-primary": "var(--color-gray-900)",
      "text-secondary": "var(--color-gray-600)",
      "border-default": "var(--color-gray-200)",
      "border-focus": "var(--color-primary-500)"
    }
  },
  "typography": {
    "fontFamily": {
      "sans": ["Inter", "system-ui", "sans-serif"],
      "mono": ["JetBrains Mono", "monospace"]
    },
    "fontSize": {
      "xs": ["0.75rem", "1rem"],
      "sm": ["0.875rem", "1.25rem"],
      "base": ["1rem", "1.5rem"],
      "lg": ["1.125rem", "1.75rem"]
    }
  },
  "spacing": {
    "0": "0",
    "1": "0.25rem",
    "2": "0.5rem",
    "3": "0.75rem",
    "4": "1rem",
    "5": "1.25rem",
    "6": "1.5rem",
    "8": "2rem",
    "10": "2.5rem",
    "12": "3rem",
    "16": "4rem"
  }
}

# Component Name

## Description
Brief description of what this component does and when to use it.

## Anatomy
[Visual breakdown of component parts]

## States
| State | Description | Visual |
|-------|-------------|--------|
| Default | Initial state | [Image] |
| Hover | User hovers | [Image] |
| Active | User activates | [Image] |
| Disabled | Cannot interact | [Image] |
| Error | Validation error | [Image] |

## Usage
```jsx
<PrimaryButton onClick={handleClick}>
  Save Changes
</PrimaryButton>

---

# Interaction Design

## Micro-interactions

```css
/* Button Micro-interaction */
.button {
  position: relative;
  padding: 0.75rem 1.5rem;
  font-weight: 600;
  transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
}

/* Hover - Immediate feedback */
.button:hover {
  transform: translateY(-2px);
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}

/* Active - Physical feel */
.button:active {
  transform: translateY(0);
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}

/* Focus - Visible for keyboard */
.button:focus-visible {
  outline: 3px solid var(--color-primary-500);
  outline-offset: 2px;
}

/* Loading - State indication */
.button:has(.spinner) {
  color: transparent;
  pointer-events: none;
}

/* Ripple Effect - Material Design style */
.button::after {
  content: '';
  position: absolute;
  inset: 0;
  background: radial-gradient(circle, rgba(255,255,255,0.3) 0%, transparent 70%);
  transform: scale(0);
  opacity: 0;
}

.button:active::after {
  transform: scale(2);
  opacity: 1;
  transition: transform 0.5s, opacity 0.3s;
}

┌─────────────────────────────────────────────────────────┐
│              LOADING STATE PATTERNS                     │
├─────────────────────────────────────────────────────────┤
│  SPINNER         • For actions < 3s                    │
│  SKELETON        • For content loading                 │
│  PROGRESS BAR    • For known duration                  │
│  PULSING         • Subtle, non-blocking                │
│  PARTIAL CONTENT • Show data as it arrives             │
└─────────────────────────────────────────────────────────┘

Rules:
- < 0.1s: No indicator (feels instant)
- 0.1-1s: Optional indicator
- 1-5s: Show progress
- > 5s: Show progress + allow cancel

/* Success Feedback */
.toast-success {
  background: #dcfce7;
  color: #166534;
  border-left: 4px solid #22c55e;
  animation: slide-in 0.3s ease-out;
}

/* Error Feedback */
.toast-error {
  background: #fee2e2;
  color: #991b1b;
  border-left: 4px solid #ef4444;
  animation: shake 0.4s ease-out;
}

@keyframes shake {
  0%, 100% { transform: translateX(0); }
  25% { transform: translateX(-8px); }
  75% { transform: translateX(8px); }
}

/* Warning Feedback */
.toast-warning {
  background: #fef3c7;
  color: #92400e;
  border-left: 4px solid #f59e0b;
  animation: fade-in 0.3s ease-out;
}

┌─────────────────────────────────────────────────────────┐
│              P.O.U.R. FRAMEWORK                         │
├─────────────────────────────────────────────────────────┤
│  P - Perceivable                                         │
│     • Text alternatives for non-text content            │
│     • Captions for multimedia                           │
│     • Adaptable content                                 │
│     • Distinguishable content                           │
│                                                         │
│  O - Operable                                           │
│     • Keyboard accessible                               │
│     • Enough time                                       │
│     • No seizures (≤ 3 flashes/second)                  │
│     • Navigable                                         │
│                                                         │
│  U - Understandable                                     │
│     • Readable                                          │
│     • Predictable                                       │
│     • Input assistance                                  │
│                                                         │
│  R - Robust                                             │
│     • Compatible with assistive technologies            │
│     • Valid HTML                                        │
└─────────────────────────────────────────────────────────┘

// Focus trap in modal
function trapFocus(element) {
  const focusable = element.querySelectorAll(
    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
  );
  const first = focusable[0];
  const last = focusable[focusable.length - 1];

  element.addEventListener('keydown', (e) => {
    if (e.key === 'Tab') {
      if (e.shiftKey && document.activeElement === first) {
        e.preventDefault();
        last.focus();
      } else if (!e.shiftKey && document.activeElement === last) {
        e.preventDefault();
        first.focus();
      }
    }
  });
}

// Restore focus after modal closes
let previousFocus = null;
function openModal(modal) {
  previousFocus = document.activeElement;
  modal.querySelector('button').focus();
}

function closeModal(modal) {
  modal.close();
  previousFocus?.focus();
}

<!-- Dialog Pattern -->
<div
  role="dialog"
  aria-modal="true"
  aria-labelledby="dialog-title"
  aria-describedby="dialog-description"
>
  <h2 id="dialog-title">Delete Account</h2>
  <p id="dialog-description">
    This action cannot be undone.
  </p>
  <button id="confirm-delete">Delete</button>
  <button id="cancel-delete">Cancel</button>
</div>

<!-- Toggle Button -->
<button
  aria-pressed="false"
  aria-label="Toggle notifications"
>
  <span aria-hidden="true">🔔</span>
</button>

<!-- Form Validation -->
<input
  aria-invalid="true"
  aria-describedby="error-message"
/>
<span id="error-message" role="alert">
  Please enter a valid email
</span>

/* Mobile-first approach */
:root {
  /* Breakpoints */
  --bp-sm: 640px;   /* Large phones */
  --bp-md: 768px;   /* Tablets */
  --bp-lg: 1024px;  /* Laptops */
  --bp-xl: 1280px;  /* Desktops */
  --bp-2xl: 1536px; /* Large screens */
}

/* Base styles - Mobile (0-639px) */
.container {
  padding: 1rem;
  font-size: 1rem;
}

/* Large phones */
@media (min-width: 640px) {
  .container {
    padding: 1.5rem;
  }
}

/* Tablets */
@media (min-width: 768px) {
  .container {
    padding: 2rem;
    display: grid;
    grid-template-columns: 1fr 1fr;
  }
}

/* Laptops+ */
@media (min-width: 1024px) {
  .container {
    grid-template-columns: repeat(4, 1fr);
  }
}

/* Minimum touch target: 44x44px (iOS), 48x48px (Android) */
.button {
  min-height: 48px;
  min-width: 48px;
  padding: 12px 24px;
}

/* For small icons, expand hit area */
.icon-button {
  width: 24px;
  height: 24px;
  padding: 12px; /* Expands touch area to 48x48 */
  margin: -12px;
}

# Usability Test Script

## Introduction (2 min)
"Hi [name], thank you for joining. I'm [your name] from [company].
I'm testing [product], not you. There are no wrong answers.
Think aloud as you complete tasks. Your feedback helps us improve."

## Warm-up Task (2 min)
Simple task to get comfortable with the interface.

## Core Tasks (15-20 min)
1. [Task 1 - Primary user goal]
2. [Task 2 - Secondary user goal]
3. [Task 3 - Edge case or complex flow]

## Debrief (5 min)
- What was easiest?
- What was most frustrating?
- What would you improve?