# Empty States

Empty states are onboarding moments, not wallpaper.

## The three-part formula

1. **Acknowledge** the state briefly.
2. **Explain the value** of filling it.
3. **Provide a clear action**.

## Templates

| Surface | Empty | Filled |
|---|---|---|
| Project list | "No projects yet. Create your first to start tracking work." + [Create project] | List of projects |
| Inbox | "Inbox zero. Anything new will land here." | Messages |
| Search | "Nothing matches '[query]'. Try a broader term." + [Clear search] | Results |
| Trash | "Trash is empty." | Deleted items |
| First-run dashboard | "Welcome. Connect your first data source to see metrics." + [Connect source] | Charts |

## Types of empty

Not all empty states are the same — match the copy to the cause:

| Type | Tone | Example |
|---|---|---|
| **First use** | Welcoming, instructive | "No projects yet. Create your first to start." |
| **Cleared** | Neutral, factual | "All caught up." |
| **Filtered out** | Neutral with action | "Nothing matches these filters. [Clear filters]" |
| **Permission-blocked** | Explanatory | "You don't have access. Ask your admin to invite you." |
| **Error-induced** | Apologetic, recoverable | "Couldn't load. [Retry]" |

## Avoid

- "No items" / "No results" / "Nothing here" — wallpaper, no value.
- Decorative illustrations without functional copy — pretty empty is still empty.
- CTAs that don't work without prerequisites (e.g., "Create project" when the user can't because billing isn't set up).
- Humor when the user is stuck.

## Empty states for AI features

Increasingly relevant. When an AI feature returns nothing:
- Explain *why* (no relevant context, low confidence, blocked).
- Offer a fallback (manual entry, escalation, reformulation).
- Don't fake content to fill the space.