---
name: empty-state-audit
description: Find screens that render blank, broken, or misleading with zero data, and draft an empty state for each. Use after building list, dashboard, inbox, or search screens - anywhere a first-run account, a cleared view, or a failed load can leave the user staring at nothing.
---

# Empty State Audit

## When to use

- A screen shows a list, table, feed, chart, or search results
- The product is about to get new users who start with zero data

Do NOT use to redesign states that already exist and work. If a screen
handles empty well, say so and move on.

## Inventory: find every emptiable surface

1. List the screens that render collections or fetched data.
2. For each, force the four empty conditions - they fail differently:
   - **First run**: account created, nothing added yet
   - **Cleared**: data existed, user removed all of it
   - **No results**: filters or search exclude everything
   - **Failed load**: the request errored, nothing to show
   - **Permission-denied**: data exists but this user may not see it.
     This is NOT an empty state - say access is missing; never draft
     "create your first item" copy for something the user cannot create
3. Screenshot or describe what actually renders for each condition.
   A spinner that never resolves and a stack trace both count as
   findings.

## Draft each empty state

Every empty state answers three questions in this order:

1. **What is this?** One line naming what will live here.
2. **Why is it empty?** First run, cleared, no results, or error -
   say which, honestly.
3. **What next?** One primary action: create the first item, clear
   the filter, retry the load. Never more than one primary action.

Rules per condition: first-run states teach and invite; cleared
states confirm and offer undo if possible; no-results states name the
filter that hid everything; error states say what failed and offer
retry - they never pretend to be an empty list.

## Output format

Per screen: the condition, what renders today, the drafted copy
(headline, one supporting line, one action label), and any data the
state needs that the screen does not currently have.

## Hard boundaries

- Never show fake rows, skeletons that never resolve, or dummy data
  to fill an empty screen.
- Never blame the user ("you have no friends yet") - frame empty as
  the starting point, not a failure.
- An error state must not look like a successful empty list.
