# Empty, loading, and error states

Collection and panel states should preserve context and give the user a clear next step.

## Empty-state variants

### First use

Use when no records have ever been created. Hide search and filter controls because there is nothing to query. Include a concise title, one sentence of explanation, and an optional primary creation action.

Use equal vertical padding above and below the empty-state message so the content remains centered within its card.

### No matching results

Use when search or filters remove all visible records. Keep the search and filter controls visible, name the condition, and offer a clear-search or clear-filters action. Do not suggest creating a duplicate record.

### Empty subsection

Use inside a detail card when related data is optional. A single neutral sentence is usually enough; avoid decorative illustrations.

## Loading

- Keep known headings, toolbars, and container dimensions in place.
- Use a compact spinner for actions and short local waits.
- Use neutral skeleton rows only when the shape of incoming content is known.
- Set `aria-busy="true"` on the affected region and provide a polite status message for longer operations.
- Avoid replacing the entire page with a spinner after initial navigation.

## Error

- Place recoverable errors inside the region that failed.
- State what could not be loaded and provide a Retry action when useful.
- Preserve the user's search, filters, input, and surrounding context.
- Use a notification banner only when the failure affects the page rather than one region.