Feedback
ErrorState
A page that could not be shown.
Usage
import { ErrorState } from '@misoto22/design'Notes
A page that could not be shown.
The code is set at the top of the type ladder and marked aria-hidden — read aloud, "404" before the sentence explaining it is noise, and the heading immediately after says the same thing in words.
Anatomy
| Element | Description |
|---|---|
| Screenrequired | A section at least one viewport tall, painting its own --paper ground and holding 96px of clearance for a header. It is a page, not a block. |
| Coderequired | code at the top of the type ladder, aria-hidden. The largest thing on the screen and the one thing a screen reader is never told. |
| Headingrequired | heading through Heading at --fs-heading, and the first thing said aloud. level defaults to 1 because this replaces the page; the size is fixed, so an error state demoted to an h2 is the same size it was. |
| Messagerequired | message at --measure-record, which is where the explanation of what happened goes. |
| Actionrequired | The way back. Required rather than optional, and the only focusable thing on the screen. |
Best practices
Do
- Render it instead of the page, not inside it. It is a full viewport with its own ground and its own top clearance, so nested in a layout that already has a header it adds a second screen of blank below the fold.
- Announce it or move focus into it on a client-side failure. There is no role and no live region here, so a route that swaps the whole screen for this one changes everything a sighted reader can see and says nothing at all.
- Point action at a real destination rather than at history. A reader often arrives at an error page cold or from a link, so going back returns them to the page that just failed, or to nothing.
Don’t
- Do not leave level at 1 inside an app shell that already has an h1. Two h1s on one document leave a heading list that no longer says which one is the page — pass level={2} for a state rendered into a shell rather than instead of one.
- Do not put a request id, a trace or a sentence into code. It is set at --fs-title with leading-none and it is aria-hidden, so anything long becomes the biggest object on the page and is simultaneously invisible to the reader most likely to have to quote it.
- Do not use it when one panel failed and the rest of the page still works. Replacing the whole screen throws away the navigation the reader needed to get out; an Alert inside the panel keeps both the error and the way past it.
Examples
not found
The page that could not be shown. Render it instead of the page rather than inside it: it is a full viewport with its own ground and its own top clearance, so nested in a layout that already has a header it adds a second screen of blank below the fold — the examples here pass min-h-0 to fit the canvas, and level={2} because this page's own h1 sits above them. code sits at the top of the type ladder and is aria-hidden, so the heading immediately after has to say the same thing in words. There is no live region either, so a route that swaps the whole screen for this changes everything a sighted reader can see and says nothing at all.
a way back
action is required rather than optional, because it is the only focusable thing on the screen — and it has to point at a real destination rather than at history. A reader arrives at an error page cold or from someone else's link at least as often as they arrive from the app, so going back returns them to the page that just failed, or to nothing. Two links are about the most this should carry: the way home, and the page that says whether it is only them.
Something went wrong at our end
The request reached us and failed while it was being handled. Nothing you sent was lost.
the trace id
Where the reference goes: in the message, never in code. code is set at --fs-title with leading-none and it is aria-hidden, so a request id put there becomes the largest object on the page and is at the same time invisible to the reader most likely to have to quote it down a phone line. Three characters is what that slot is sized for; the id belongs in the sentence, where it is selectable, copyable and read out with the rest of the explanation.
We could not load this deploy
The build service timed out. Quote req_8f31c0 if you report it — it identifies this request.
Re-exports
ERROR_ACTION_CLASS = 'text-sm text-(--ink) underline decoration-(--rule-2) underline-offset-4 transition-colors duration-(--duration-fast) hover:decoration-(--ink)'The recovery affordance's look, exported so every error page offers the same one rather than each inventing a link style.
Accessibility
- The big status code is aria-hidden; the heading immediately after says the same thing in words.