# Empty states explain what goes here and how to add it

- **Pattern:** `ab-002337` (`saas-onboarding.first-run.empty-states-helpful`)
- **Severity:** high
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-002337
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-002337)

## Why it matters

An empty list view that shows only "No results" or a bare table with headers gives users no signal about what the space is for or how to fill it. The user-experience taxon treats empty states as prime teaching surface: they are the first thing new users see on every major view, and a generic empty state wastes that surface entirely. A good empty state names what belongs there, explains why it matters, and provides a direct action to create the first item — which is often the fastest path from signup to activation.

## Severity rationale

High because empty states are the default view for every new user across every feature, and generic empty states block activation at scale.

## Remediation

Build a single reusable empty-state component and use it everywhere a list, gallery, table, or dashboard renders with zero items. Create `src/components/EmptyState.tsx` accepting a title, description, and CTA, then swap in calls at every list view.

```tsx
export function EmptyState({ title, description, actionLabel, actionHref }: Props) {
  return (
    <div className="text-center py-12">
      <h3 className="font-semibold">{title}</h3>
      <p className="text-muted-foreground mt-1">{description}</p>
      <Button className="mt-4" asChild><Link href={actionHref}>{actionLabel}</Link></Button>
    </div>
  );
}
```

## Detection

- **ID:** `empty-states-helpful`
- **Severity:** `high`
- **What to look for:** Count all list views, galleries, dashboards, and data tables in the application. For each, classify whether it has a proper empty state component. Enumerate: explanation text, CTA button, illustration/icon present. Report the ratio of views with proper empty states vs. those without.
- **Pass criteria:** Every major list view and data display area has an empty state that (1) explains what belongs in the space and (2) provides a direct action to add the first item. At least 90% of list views must have proper empty states.
- **Fail criteria:** Any major list view renders as a blank area, a generic "No results" message, or a table with only headers and no rows — with no explanation of what should be there or how to add it.
- **Skip (N/A) when:** The project has no list views or data display components (e.g., it is a purely content-display site with no user-generated data).
- **Detail on fail:** List the components or routes with inadequate empty states. Example: `"Dashboard main list and /projects route render blank or generic 'No data' when empty. No explanation or CTA to create the first item."`
- **Remediation:** Create a reusable empty state component at `src/components/EmptyState.tsx`:

  ```tsx
  export function EmptyState({ title, description, actionLabel, actionHref }: Props) {
    return (
      <div className="text-center py-12">
        <h3 className="font-semibold">{title}</h3>
        <p className="text-muted-foreground mt-1">{description}</p>
        <Button className="mt-4" asChild><Link href={actionHref}>{actionLabel}</Link></Button>
      </div>
    );
  }
  ```

---

Taxons: user-experience

HTML version: https://auditbuffet.com/patterns/ab-002337