Resilient UI States
A view with data has (at minimum) four states, and treating any of them as
optional is where the incident starts: the loading state that never resolves
because there's no timeout, the empty state that doesn't exist so the user
sees a blank screen and assumes the app is broken, the error that's caught
three components up and takes the whole page down with it.
Composes with the library:
- honest-degradation — this skill's error/empty states are the frontend
instance of that skill's PASS/WARN/FAIL discipline: never render a
best-effort or partial result as if it were the complete one
- validate-at-the-boundary — the error state produced by a rejected input
is this skill's territory (how it's surfaced); the rejection logic itself
is that skill's
- frontend-accessibility-by-construction — an error/loading state that
isn't announced to assistive tech doesn't exist for a screen-reader user;
see that skill for
aria-live/role="alert" mechanics
The four mandatory states (methodological decision)
Every component that depends on async data has exactly these states, and
MUST render something intentional for each — never assume one "won't
happen":
| State |
MUST render |
Common failure when skipped |
| Loading |
A distinct, bounded-time indicator (skeleton or spinner) |
Blank screen read as broken; or spinner with no timeout, spins forever on a hung request |
| Success |
The actual data |
(rarely skipped — this is the state everyone builds for) |
| Empty |
A state distinct from both loading and error, explaining why it's empty and what to do next |
Renders as an empty loading skeleton or an empty error — user can't tell "no results" from "still loading" from "broken" |
| Error |
A specific, actionable message tied to what actually failed |
Generic "Something went wrong", or the loading spinner just... stops, with no explanation |
MUST distinguish empty from error from still-loading in the rendered
output — these are three different facts and collapsing any two of them is a
comprehension failure, not just a polish gap.
Error boundaries: scope the blast radius
Source: Next.js error handling docs (framework-level convention); general React error boundary pattern.
SHOULD place error boundaries per independent feature/section, not one
global boundary at the app root. Applies when a page has multiple
independently-useful sections (e.g. a dashboard with several widgets) — one
widget's fetch failure should not blank the whole page. Does not apply
when the failing section's data is load-bearing for everything else on the
page (e.g. auth state) — in that case a page-level boundary is correct,
because partial rendering would be actively misleading.
Form validation timing and structure
Source: TetraLogical, form validation and error messages.
- SHOULD validate on blur, not on every keystroke — validating on
keystroke punishes the user mid-typing for an incomplete value that isn't
wrong yet, it's just unfinished.
- MUST associate the error with its field via
aria-invalid="true" and
aria-describedby pointing at the error text — a red border with no
programmatic link is invisible to a screen reader.
- SHOULD render a summary of all errors at the top of the form on submit,
in addition to inline errors, for forms with more than a couple of fields —
a submit that silently scrolls to the first error loses everyone who tabs
or uses a screen reader.
- MUST use
role="alert" or an aria-live region for the error summary
so it's announced without requiring the user to find it visually.
Failure modes / anti-patterns
- Infinite spinner: no timeout or retry-with-backoff on a hung request —
the loading state has no maximum duration, so a stalled network call is
indistinguishable from a working one.
- Generic error message: "Something went wrong" / "Error" with no
specifics and no next action — technically correct, operationally useless.
- Empty-as-loading: an empty result set renders the same skeleton as the
loading state, so the user waits for data that will never arrive.
- One error boundary to rule them all: a single unhandled rejection in
one widget blanks the entire page instead of just that widget.
- Optimistic UI with no rollback path: a mutation is rendered as
succeeded before the server confirms, with no visible correction if it
actually fails — the user acts on a state that silently reverts.
- Validation on keystroke: the field turns red while the user is still
typing a valid value, before they've finished.
- Form reset on error: a failed submission clears fields the user already
filled in, forcing them to redo work — see
non-overwhelming-ux for why
this is a cognitive-load failure, not just an annoyance.
Verifiable checks
1---2name: resilient-ui-states3description: Design every view that fetches or mutates data around its full state machine — loading, success, empty, and error are all mandatory, none optional — with error handling that fails at the right boundary and produces a specific, actionable message. Use whenever building or reviewing a component that does async data fetching, mutation, or submission. Trigger on "loading state", "error state", "empty state", "skeleton", "error boundary", "form validation", "what happens if this fails", "spinner forever", "blank screen", "something went wrong". Not about visual polish of these states — about which states are required to exist and where failure is caught.4metadata:5 source: https://skillmd.com/skills/annatchijova/resilient-ui-states6---78# Resilient UI States910A view with data has (at minimum) four states, and treating any of them as11optional is where the incident starts: the loading state that never resolves12because there's no timeout, the empty state that doesn't exist so the user13sees a blank screen and assumes the app is broken, the error that's caught14three components up and takes the whole page down with it.1516Composes with the library:1718- **honest-degradation** — this skill's error/empty states are the frontend19 instance of that skill's PASS/WARN/FAIL discipline: never render a20 best-effort or partial result as if it were the complete one21- **validate-at-the-boundary** — the error state produced by a rejected input22 is this skill's territory (how it's surfaced); the rejection logic itself23 is that skill's24- **frontend-accessibility-by-construction** — an error/loading state that25 isn't announced to assistive tech doesn't exist for a screen-reader user;26 see that skill for `aria-live`/`role="alert"` mechanics2728---2930## The four mandatory states (methodological decision)3132Every component that depends on async data has exactly these states, and33**MUST** render something intentional for each — never assume one "won't34happen":3536| State | MUST render | Common failure when skipped |37|---|---|---|38| Loading | A distinct, bounded-time indicator (skeleton or spinner) | Blank screen read as broken; or spinner with no timeout, spins forever on a hung request |39| Success | The actual data | (rarely skipped — this is the state everyone builds for) |40| Empty | A state distinct from both loading and error, explaining *why* it's empty and what to do next | Renders as an empty loading skeleton or an empty error — user can't tell "no results" from "still loading" from "broken" |41| Error | A specific, actionable message tied to what actually failed | Generic "Something went wrong", or the loading spinner just... stops, with no explanation |4243**MUST** distinguish empty from error from still-loading in the rendered44output — these are three different facts and collapsing any two of them is a45comprehension failure, not just a polish gap.4647## Error boundaries: scope the blast radius4849Source: [Next.js error handling docs](https://nextjs.org/docs/app/getting-started/error-handling) (framework-level convention); general React error boundary pattern.5051**SHOULD** place error boundaries per independent feature/section, not one52global boundary at the app root. **Applies when** a page has multiple53independently-useful sections (e.g. a dashboard with several widgets) — one54widget's fetch failure should not blank the whole page. **Does not apply**55when the failing section's data is load-bearing for everything else on the56page (e.g. auth state) — in that case a page-level boundary is correct,57because partial rendering would be actively misleading.5859## Form validation timing and structure6061Source: [TetraLogical, form validation and error messages](https://tetralogical.com/blog/2024/10/21/foundations-form-validation-and-error-messages/).6263- **SHOULD** validate on blur, not on every keystroke — validating on64 keystroke punishes the user mid-typing for an incomplete value that isn't65 wrong yet, it's just unfinished.66- **MUST** associate the error with its field via `aria-invalid="true"` and67 `aria-describedby` pointing at the error text — a red border with no68 programmatic link is invisible to a screen reader.69- **SHOULD** render a summary of all errors at the top of the form on submit,70 in addition to inline errors, for forms with more than a couple of fields —71 a submit that silently scrolls to the first error loses everyone who tabs72 or uses a screen reader.73- **MUST** use `role="alert"` or an `aria-live` region for the error summary74 so it's announced without requiring the user to find it visually.7576## Failure modes / anti-patterns7778- **Infinite spinner**: no timeout or retry-with-backoff on a hung request —79 the loading state has no maximum duration, so a stalled network call is80 indistinguishable from a working one.81- **Generic error message**: "Something went wrong" / "Error" with no82 specifics and no next action — technically correct, operationally useless.83- **Empty-as-loading**: an empty result set renders the same skeleton as the84 loading state, so the user waits for data that will never arrive.85- **One error boundary to rule them all**: a single unhandled rejection in86 one widget blanks the entire page instead of just that widget.87- **Optimistic UI with no rollback path**: a mutation is rendered as88 succeeded before the server confirms, with no visible correction if it89 actually fails — the user acts on a state that silently reverts.90- **Validation on keystroke**: the field turns red while the user is still91 typing a valid value, before they've finished.92- **Form reset on error**: a failed submission clears fields the user already93 filled in, forcing them to redo work — see `non-overwhelming-ux` for why94 this is a cognitive-load failure, not just an annoyance.9596## Verifiable checks9798- [ ] Every component with async data has distinguishable loading, success,99 empty, and error renders (test: force each state and screenshot/diff).100- [ ] The loading state has a maximum duration (timeout) with a defined101 fallback, or is provably bounded by the request itself.102- [ ] The empty state names *why* it's empty when the reason is knowable103 (no results for this filter vs. nothing created yet) and offers a next104 action.105- [ ] Every error message is specific to the failure (network vs. validation106 vs. permission vs. server error) — grep for generic strings like107 "Something went wrong" and confirm each one has a fallback only, not a108 primary use.109- [ ] Error boundaries are scoped to independent sections, not a single110 app-root boundary, unless the failing section is load-bearing for the111 rest of the page.112- [ ] Form errors are both inline (per field, with `aria-invalid` +113 `aria-describedby`) and summarized (`role="alert"` region) on submit114 for forms beyond 1-2 fields.115- [ ] A failed submission preserves user-entered data — nothing is cleared on116 error.