States

Work-in-progress feedback. For unknown waits, a spinner or progress; for content shapes you can predict, a skeleton. The job is to say “something is happening,” not to entertain.

Use when

A request will take long enough that a blank screen would read as broken.

Confused with

Skeleton — a skeleton is a kind of loading state shaped like the eventual content.

Say it precisely“Show a loader.”“Show a determinate progress bar if duration is known; otherwise a spinner after a 300ms delay to avoid flicker.”

A zero-content state — no results, nothing created yet. A good empty state explains why it's empty and offers the single next action, instead of leaving a void.

Use when

A list, search, or freshly created space has nothing to show.

Confused with

Error — empty is expected and calm; error means something went wrong.

Say it precisely“Handle no data.”“Render an empty state with a one-line reason and a primary action — not a blank container.”

Failure feedback that says what went wrong and how to recover. Place it next to its cause, keep the tone plain, and always offer a way forward — retry, undo, or a fix.

Use when

An action failed or input is invalid and the user must do something about it.

Confused with

Toast — a toast is transient; a blocking error stays until resolved.

Say it precisely“Show an error.”“Show an inline error beside the field: what failed, why, and a retry — never a generic ‘something went wrong’.”

A control that's temporarily unavailable — visibly present but inert. The hard part is telling the user why, so the disabled state never becomes a dead end.

Use when

An action isn't possible yet, and you can explain the precondition to unlock it.

Don't use when

You can't say why it's disabled — then hide it or show an error on attempt instead.

Say it precisely“Grey it out.”“Disable the button with aria-disabled and a tooltip stating the unmet condition; re-enable when met.”

Placeholder shapes that mirror the eventual layout while it loads. Because the structure stays put, content swaps in without a jarring reflow — calmer than a spinner for known shapes.

Use when

You know the shape of what's coming — cards, rows, an article — and want zero layout shift.

Confused with

Spinner — a spinner says “wait”; a skeleton previews the structure of the result.

Say it precisely“Add shimmer placeholders.”“Show skeleton blocks matching the final card layout; cross-fade to content on load, no reflow.”