J3W1 / DESIGN SYSTEM

Error state

A specific failure explanation with an explicit recovery request.

stable · LIGHT DOM · 1.1.0

Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.

Standalone example ↗Copy file manifest Canonical JSON Vue gallery ↗Prepare an agent kit →

Live variants

default

✕ Project list unavailable

The demonstration request failed. Retry to load the local example records.

<j3w1-error-state id="example-error-state-default"><section class="error-state" aria-labelledby="example-error-state-default-error-title"><h3 id="example-error-state-default-error-title">✕ Project list unavailable</h3><p>The demonstration request failed. Retry to load the local example records.</p><button class="error-state-control" type="button" data-retry="" data-demo-focus-target="">Retry loading</button></section></j3w1-error-state>

Install and register

Use the exact version. If npm publication is pending, install the release tarball from the installation guide.

npm install --save-exact @j3w1/ui@1.1.0

import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/error-state.css';
import '@j3w1/ui/register/error-state';

Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.

Vue SFC, React, Astro and plain HTML integration →

Copy the complete implementation

npx --package=@j3w1/ui@1.1.0 j3w1-ui copy error-state --out ./vendor/j3w1/error-state

The CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.

Public API

attributes

Name	Type / signature	Meaning
`disabled`	`CustomEvent`	Disable the native controls owned by this instance.
`loading`	`CustomEvent`	Mark the primary control busy and prevent duplicate activation.

properties

Name	Type / signature	Meaning
`disabled`	`boolean`	Delegates disabled state to native children.
`name`	`string`	Native control name; application form keys remain explicit.

methods

Name	Type / signature	Meaning
`refresh`	`(): void`	Reconnect behavior after replacing native child structure.
`focus`	`(options?: FocusOptions): void`	Focus the first usable native control.
`dismiss`	`(id?: string): void`	Dismiss a message; focused actions move to the next available control.

events

Name	Type / signature	Meaning
`j3w1-dismiss`	`CustomEvent`	Cancelable message dismissal.
`j3w1-retry`	`CustomEvent`	Request recovery; the host owns the result.
`j3w1-action`	`CustomEvent`	An explicit message action.

Dependencies and verification

Registered components: none. Style dependencies: none.

Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.

Full implementation manifest, API and token dependency closure

Canonical specification

Purpose

Explain a failed operation and offer a bounded recovery action. Retrying emits a request; the component does not claim that a service recovered. The host updates content when the actual operation completes.

Anatomy

message: Heading, explanation and text error glyph.
recovery: Native retry action, disabled while the host request is pending.

States

State	Presentation	Non-colour channel
default	Danger border and text heading.	Specific written explanation and error glyph.
error	Same explicit failure treatment.	Failure text remains available.
loading	Busy status accompanies the existing explanation.	aria-busy and host-provided pending text.
disabled	Disabled roles at full opacity.	Native retry button is disabled.
focus-visible	Dashed ring.	Native keyboard focus.

Keyboard

Tab / Shift+Tab: Reach the recovery action.
Enter / Space: Request a retry without moving focus.

Accessibility

Do not rely only on color or a glyph. Give the retry action a specific name. Announce a newly occurring error in an appropriate host status region, without repeatedly interrupting reading. Keep focus unless recovery requires an explicit next step.

Portability

Wrap labels and actions without changing source order. Use logical spacing in RTL. Preserve native target sizes at both densities; only bounded data regions may scroll horizontally. Use equivalent native semantics and approved roles; record any unsupported behavior as a mapping deviation. The host owns application data, persistence, permissions and services.

Non-examples

Unlabelled controls, color-only status, drag-only operations, hidden required instructions, stolen focus or an invented service success.