# Design System - Empty States

## Overview

Empty states communicate when there's no content to display. They guide users on what to do next and maintain engagement during empty or error scenarios. All empty states use the brand color palette (Orange→Pink→Blue) for illustrations.

---

## Empty State Types

| Type | When Used | Tone |
|------|-----------|------|
| **First Use** | User hasn't created anything yet | Encouraging, welcoming |
| **No Results** | Search/filter returns nothing | Helpful, suggestive |
| **No Data** | List or section is empty | Informative, actionable |
| **Error** | Something went wrong | Apologetic, solution-focused |
| **No Access** | User lacks permissions | Clear, directive |
| **Offline** | No internet connection | Patient, reassuring |

---

## Anatomy

```
┌─────────────────────────────────────┐
│                                     │
│         [Illustration]              │  ← Brand-colored SVG
│                                     │
│           Headline                  │  ← Bold, concise
│                                     │
│     Supporting description          │  ← Explains context
│     text that helps user            │
│                                     │
│        [ Primary Action ]           │  ← Main CTA
│          Secondary link             │  ← Optional alternative
│                                     │
└─────────────────────────────────────┘
```

---

## Specifications

| Element | Specification |
|---------|---------------|
| **Illustration** | 120×120px default, SVG format |
| **Headline** | 18px, font-weight 600, #383737 |
| **Description** | 14px, font-weight 400, #9A9A9A |
| **Max Width** | 320px for text content |
| **Spacing** | 16px between elements |
| **Alignment** | Center aligned |

---

## Color Usage

Illustrations use the brand gradient colors:

| Color | Hex | Usage |
|-------|-----|-------|
| Orange | #FB923C | Primary shapes, accents |
| Pink | #F472B6 | Secondary shapes, shadows |
| Blue | #93C5FD | Background shapes, highlights |
| Gray | #E5E5E5 | Neutral elements, outlines |

---

## Empty State Patterns

### First Use / Welcome

**Use when:** User is new and hasn't created content yet.

```html
<div class="empty-state">
  <div class="empty-illustration">
    <!-- Welcome illustration -->
  </div>
  <h3 class="empty-title">Create your first strategy</h3>
  <p class="empty-description">
    Get started by creating a strategy. We'll guide you through the process.
  </p>
  <button class="btn btn-primary">Create Strategy</button>
</div>
```

### No Search Results

**Use when:** Search or filter returns no matches.

```html
<div class="empty-state">
  <div class="empty-illustration">
    <!-- Search illustration -->
  </div>
  <h3 class="empty-title">No results found</h3>
  <p class="empty-description">
    We couldn't find anything matching "{{query}}". Try adjusting your search.
  </p>
  <button class="btn btn-secondary">Clear filters</button>
</div>
```

### Empty List

**Use when:** A list or collection has no items.

```html
<div class="empty-state">
  <div class="empty-illustration">
    <!-- Empty box illustration -->
  </div>
  <h3 class="empty-title">No strategies yet</h3>
  <p class="empty-description">
    Strategies you create will appear here.
  </p>
  <button class="btn btn-primary">Create Strategy</button>
</div>
```

### Error State

**Use when:** Something went wrong loading content.

```html
<div class="empty-state empty-error">
  <div class="empty-illustration">
    <!-- Error illustration -->
  </div>
  <h3 class="empty-title">Something went wrong</h3>
  <p class="empty-description">
    We couldn't load your strategies. Please try again.
  </p>
  <button class="btn btn-primary">Retry</button>
  <a href="#" class="empty-link">Contact support</a>
</div>
```

### No Access

**Use when:** User doesn't have permission to view content.

```html
<div class="empty-state">
  <div class="empty-illustration">
    <!-- Lock illustration -->
  </div>
  <h3 class="empty-title">Access restricted</h3>
  <p class="empty-description">
    You don't have permission to view this content.
  </p>
  <a href="#" class="empty-link">Request access</a>
</div>
```

### Offline

**Use when:** No internet connection.

```html
<div class="empty-state">
  <div class="empty-illustration">
    <!-- Offline illustration -->
  </div>
  <h3 class="empty-title">You're offline</h3>
  <p class="empty-description">
    Check your internet connection and try again.
  </p>
  <button class="btn btn-secondary">Retry</button>
</div>
```

---

## CSS Implementation

```css
.empty-state {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  text-align: center;
  padding: 48px 24px;
  max-width: 400px;
  margin: 0 auto;
}

.empty-illustration {
  width: 120px;
  height: 120px;
  margin-bottom: 24px;
}

.empty-illustration svg {
  width: 100%;
  height: 100%;
}

.empty-title {
  font-family: 'Space Grotesk', sans-serif;
  font-size: 18px;
  font-weight: 600;
  color: #383737;
  margin-bottom: 8px;
}

.empty-description {
  font-family: 'Space Grotesk', sans-serif;
  font-size: 14px;
  color: #9A9A9A;
  margin-bottom: 24px;
  max-width: 320px;
  line-height: 1.5;
}

.empty-state .btn {
  margin-bottom: 12px;
}

.empty-link {
  font-size: 14px;
  color: #FB923C;
  text-decoration: none;
}

.empty-link:hover {
  text-decoration: underline;
}
```

---

## Size Variants

| Size | Illustration | Title | Use Case |
|------|--------------|-------|----------|
| **Small** | 80px | 16px | Inline, cards |
| **Medium** | 120px | 18px | Sections, panels |
| **Large** | 160px | 20px | Full page |

```css
.empty-state.small .empty-illustration { width: 80px; height: 80px; }
.empty-state.small .empty-title { font-size: 16px; }

.empty-state.large .empty-illustration { width: 160px; height: 160px; }
.empty-state.large .empty-title { font-size: 20px; }
```

---

## Writing Guidelines

### Headlines
- Keep under 6 words
- Be specific about what's empty
- Use sentence case

### Descriptions
- Explain why it's empty
- Suggest what to do next
- Keep under 2 sentences
- Be encouraging, not blaming

### Actions
- Primary: Main action to resolve empty state
- Secondary: Alternative option (optional)

### Examples

| Bad | Good |
|-----|------|
| "Nothing here" | "No strategies yet" |
| "Error occurred" | "Couldn't load strategies" |
| "Empty" | "Create your first strategy" |
| "No permission" | "Request access to view" |

---

## Contextual Usage

### In Cards
```html
<div class="card">
  <div class="empty-state small">
    <div class="empty-illustration">...</div>
    <p class="empty-description">No items</p>
  </div>
</div>
```

### In Tables
```html
<table>
  <tbody>
    <tr>
      <td colspan="4">
        <div class="empty-state small">
          <p class="empty-description">No data to display</p>
        </div>
      </td>
    </tr>
  </tbody>
</table>
```

### Full Page
```html
<main class="page-content">
  <div class="empty-state large">
    <div class="empty-illustration">...</div>
    <h3 class="empty-title">Welcome to Pinnlo</h3>
    <p class="empty-description">
      Create your first strategy to get started.
    </p>
    <button class="btn btn-primary">Get Started</button>
  </div>
</main>
```

---

## Accessibility

- Illustrations should have `aria-hidden="true"` (decorative)
- Empty states should be announced to screen readers
- Action buttons must be keyboard accessible
- Color should not be the only indicator

```html
<div class="empty-state" role="status" aria-live="polite">
  <div class="empty-illustration" aria-hidden="true">...</div>
  <h3 class="empty-title">No results found</h3>
  <p class="empty-description">...</p>
</div>
```

---

## Prototype

`empty-states-prototype/index.html`