HTTP status pages

A status page replaces the whole main content, so use it only when the whole route can't render: nothing at this URL, no permission, a server error, offline when the page opens. When only part of a page fails, report it in that part and keep the rest usable.

The title says what happened in plain words (“Page not found”); the description says why, when known, and what people can do next. The code sits in the small line above the title for anyone reporting the problem, and is never the only text on the page.

Don't blame the user, don't joke when they just lost what they were doing, don't print a stack trace. An error ID (7f3a-91c2) is plain text people can select and copy.

Each page has exactly one main action; the secondary action is a safe way out, such as Home or Switch account.

The mark in the corner changes with the state: one petal missing when the page isn't found, all fallen when it was removed, still a bud when you need to sign in or ask for access, the ink broken on a server error, faded on a timeout, only a trace when offline. On 429 and 503 the brush stroke fills with the wait; when time is up the blossom opens as Retry turns on.

Kanji style: the code runs down the edge like the loading screen, read digit by digit (四〇四); states without a code use words: 圏外 (out of range) when offline, 新版 for a new version. Latin style, for products that don't use kanji: the code sits horizontally in a light weight in the top corner; states without a code leave that corner empty.

Temporary states should clear themselves: count down from Retry-After and then enable the button, listen for the online event to retry, and offer a reload when a JS file fails to load after a deploy. After sign-in (401), take people back to the page they were opening.

// 429 / 503: take the wait from the header, don't guess
const wait = Number(response.headers.get("Retry-After")) || 30;

// Offline: retry when the browser reports a connection
window.addEventListener("online", retry, { once: true });

// New version: the route's JS file is gone after a deploy
const Settings = lazy(() => import("./pages/Settings").catch(() => ({ default: NewVersionPage })));

A 404 page should return a real 404 status and noindex, so search engines don't index a page that looks normal. Static hosts (GitHub Pages) can only serve 404.html; there, 500 and 503 come from the app itself.

The title is an h1 naming the state; on client-side navigation, move focus to the h1 and update document.title. The vertical code is decorative (aria-hidden); the readable code is in the line above the title.

Announce countdowns through a polite live region at intervals (10 seconds), not every second. Never reload on your own without saying so first. With reduced motion, the brush stroke is already drawn and the petals already lie on the ground.