# Design System - Loading States

## Overview

Loading state components for indicating progress and system activity. All loaders use the signature Orange→Pink→Blue color palette and maintain visual consistency with the design system.

---

## Design Principles

| Principle | Implementation |
|-----------|----------------|
| **Brand Colors** | Orange (#FB923C) → Pink (#F472B6) → Blue (#93C5FD) |
| **Smooth Motion** | 3s duration cycles, ease timing |
| **Accessibility** | Include aria-labels, respect reduced-motion |
| **Contextual Sizing** | Small (inline), Medium (buttons), Large (page) |

---

## Loading Components

### 1. 3D Box Loader (Primary)

Full-page or section loading indicator with 3D animated boxes.

| Property | Value |
|----------|-------|
| Size | 200px × 320px (default) |
| Duration | 3s cycle |
| Use Case | Initial page load, major data fetching |
| Colors | Orange cubes with pink/blue shadows |

### 2. Ripple Spinner

Circular spinner with ripple wave effect.

| Property | Value |
|----------|-------|
| Sizes | sm (20px), md (32px), lg (48px), xl (64px) |
| Duration | 1.5s cycle |
| Use Case | Buttons, inline loading, cards |
| Colors | Orange → Pink → Blue gradient |

### 3. Dot Pulse

Three dots pulsing in sequence.

| Property | Value |
|----------|-------|
| Sizes | sm (6px dots), md (8px dots), lg (10px dots) |
| Duration | 1.4s cycle |
| Use Case | Chat typing indicator, inline status |
| Colors | Orange, Pink, Blue dots |

### 4. Wave Loader

Bars animating in wave pattern.

| Property | Value |
|----------|-------|
| Sizes | sm (16px height), md (24px), lg (32px) |
| Duration | 1.2s cycle |
| Use Case | Audio/processing indicator |
| Colors | Orange → Pink → Blue bars |

### 5. Skeleton Loader

Placeholder shapes for content loading.

| Property | Value |
|----------|-------|
| Animation | Shimmer sweep |
| Duration | 1.5s cycle |
| Use Case | Cards, lists, content placeholders |
| Colors | Gray (#E5E5E5) with light shimmer |

### 6. Progress Bar

Linear progress indicator.

| Property | Value |
|----------|-------|
| Height | 4px (thin), 8px (default) |
| Animation | Gradient flow or determinate fill |
| Use Case | File uploads, step progress |
| Colors | Orange → Pink → Blue gradient |

---

## Size Scale

| Size | Dimension | Use Case |
|------|-----------|----------|
| `xs` | 16px | Inline text loading |
| `sm` | 24px | Button loading state |
| `md` | 32px | Card loading |
| `lg` | 48px | Section loading |
| `xl` | 64px | Page loading |
| `full` | 200×320px | Full 3D loader |

---

## Color Tokens

```css
:root {
  /* Loading Primary Colors */
  --loader-orange: #FB923C;
  --loader-pink: #F472B6;
  --loader-blue: #93C5FD;

  /* Loading Secondary */
  --loader-orange-light: #FDBA74;
  --loader-pink-light: #F9A8D4;
  --loader-blue-light: #BFDBFE;

  /* Skeleton Colors */
  --skeleton-base: #E5E5E5;
  --skeleton-shimmer: #F5F5F5;

  /* Timing */
  --loader-duration-fast: 1s;
  --loader-duration-normal: 1.5s;
  --loader-duration-slow: 3s;
}
```

---

## HTML Structure

### 3D Box Loader

```html
<div class="loader-3d" aria-label="Loading" role="status">
  <div class="loader-ground"><div></div></div>
  <div class="loader-box box0"><div></div></div>
  <div class="loader-box box1"><div></div></div>
  <div class="loader-box box2"><div></div></div>
  <div class="loader-box box3"><div></div></div>
  <div class="loader-box box4"><div></div></div>
  <div class="loader-box box5"><div></div></div>
  <div class="loader-box box6"><div></div></div>
  <div class="loader-box box7"><div></div></div>
</div>
```

### Ripple Spinner

```html
<div class="spinner spinner-md" aria-label="Loading" role="status">
  <div class="spinner-ring"></div>
  <div class="spinner-ring"></div>
  <div class="spinner-ring"></div>
</div>
```

### Dot Pulse

```html
<div class="dots dots-md" aria-label="Loading" role="status">
  <span class="dot"></span>
  <span class="dot"></span>
  <span class="dot"></span>
</div>
```

### Wave Loader

```html
<div class="wave wave-md" aria-label="Loading" role="status">
  <span class="bar"></span>
  <span class="bar"></span>
  <span class="bar"></span>
  <span class="bar"></span>
  <span class="bar"></span>
</div>
```

### Skeleton

```html
<!-- Text skeleton -->
<div class="skeleton skeleton-text"></div>

<!-- Circle skeleton (avatar) -->
<div class="skeleton skeleton-circle"></div>

<!-- Card skeleton -->
<div class="skeleton-card">
  <div class="skeleton skeleton-image"></div>
  <div class="skeleton skeleton-text"></div>
  <div class="skeleton skeleton-text short"></div>
</div>
```

### Progress Bar

```html
<!-- Indeterminate -->
<div class="progress" aria-label="Loading" role="progressbar">
  <div class="progress-bar indeterminate"></div>
</div>

<!-- Determinate -->
<div class="progress" aria-label="75% complete" role="progressbar" aria-valuenow="75">
  <div class="progress-bar" style="width: 75%"></div>
</div>
```

---

## Usage Context

### Button Loading

```html
<button class="btn btn-primary loading" disabled>
  <span class="spinner spinner-sm"></span>
  <span>Creating...</span>
</button>
```

### Card Loading

```html
<div class="card loading">
  <div class="skeleton skeleton-image"></div>
  <div class="card-body">
    <div class="skeleton skeleton-text"></div>
    <div class="skeleton skeleton-text short"></div>
  </div>
</div>
```

### Full Page Loading

```html
<div class="page-loader">
  <div class="loader-3d"></div>
  <p class="loader-text">Loading your strategies...</p>
</div>
```

---

## Accessibility

- Always include `role="status"` and `aria-label="Loading"`
- Use `aria-valuenow` for determinate progress
- Respect `prefers-reduced-motion` media query
- Provide text alternative for screen readers

```css
@media (prefers-reduced-motion: reduce) {
  .spinner,
  .dots,
  .wave,
  .loader-3d,
  .skeleton {
    animation: none;
  }

  .skeleton {
    background: var(--skeleton-base);
  }
}
```

---

## Integration Examples

### Loading State in Chat

```html
<div class="chat-typing">
  <div class="dots dots-sm">
    <span class="dot"></span>
    <span class="dot"></span>
    <span class="dot"></span>
  </div>
  <span>AI is thinking...</span>
</div>
```

### Loading State in Strategy Card

```html
<div class="strategy-card loading">
  <div class="skeleton-card">
    <div class="skeleton skeleton-circle avatar"></div>
    <div class="skeleton skeleton-text title"></div>
    <div class="skeleton skeleton-text"></div>
    <div class="skeleton skeleton-text short"></div>
  </div>
</div>
```

---

## Prototype

`loading-prototype/index.html`