# EmptyState

> Tells people why a surface is empty and what to do first.

- **Level**: molecule · **Status**: stable · **Role**: feedback
- **Import**: `import { EmptyState } from "@rrios-forge/ui/molecules/empty-state";`
- **Source**: `packages/ui/src/molecules/empty-state`

Centred title + description + actions explaining a zero / blocked state and the next move. Title is required; vague copy ('Nothing here') is documented as an anti-pattern. Patterns consulted: Patterns/Feedback · LoadingFeedback, Patterns/Page Shells · EmptyPage, Patterns/Information Architecture · BasicHierarchy.

## Use it for

- Empty / loading state → `EmptyState` / `LoadingState` or `Skeleton`

## Axes

| Axis | Part | Values | Default | Meaning |
|---|---|---|---|---|
| `size` | — | `sm` `md` `lg` | `md` | Ergonomic scale, in three families (control, text, container). |
| `tone` | — | `neutral` `info` `success` `warning` `danger` | `neutral` | Which semantic colour family the element speaks in. |

## Stories

- [Playground](/?path=/story/components-molecules-emptystate--playground) · frame: `/iframe.html?id=components-molecules-emptystate--playground&viewMode=story`
- [Tones](/?path=/story/components-molecules-emptystate--tones) · frame: `/iframe.html?id=components-molecules-emptystate--tones&viewMode=story`
- [Sizes](/?path=/story/components-molecules-emptystate--sizes) · frame: `/iframe.html?id=components-molecules-emptystate--sizes&viewMode=story`
- [Search empty](/?path=/story/components-molecules-emptystate--search-empty) · frame: `/iframe.html?id=components-molecules-emptystate--search-empty&viewMode=story`
- [Permission empty](/?path=/story/components-molecules-emptystate--permission-empty) · frame: `/iframe.html?id=components-molecules-emptystate--permission-empty&viewMode=story`
- [Error empty](/?path=/story/components-molecules-emptystate--error-empty) · frame: `/iframe.html?id=components-molecules-emptystate--error-empty&viewMode=story`
- [With actions](/?path=/story/components-molecules-emptystate--with-actions) · frame: `/iframe.html?id=components-molecules-emptystate--with-actions&viewMode=story`

## Decisions that name it

- ADR-030 — Axis vocabulary: one name, one meaning

## Always

- Tokens only (R04); variants are semantic axes, never appearance (R02).
- Typography and actions are Poesía atoms, never raw HTML with utilities.
- Vibrant panes need a ground and never nest (ADR-027).