J3W1 / DESIGN SYSTEM

Alert

An inline status message with a mandatory glyph on the status tint behind a 1px status border; role alert for danger, status otherwise.

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

danger

Build failed

Two token references do not resolve in the default profile.

<j3w1-alert id="example-alert-danger"><div class="alert alert-danger" role="alert">
  <span class="alert-glyph" aria-hidden="true">✕</span>
  <div class="alert-body">
    <strong class="alert-title">Build failed</strong>
    <p class="alert-text">Two token references do not resolve in the default profile.</p>
  </div>
</div></j3w1-alert>

warning

Unsaved changes

The draft is kept locally until you publish.

<j3w1-alert id="example-alert-warning"><div class="alert alert-warning" role="status">
  <span class="alert-glyph" aria-hidden="true">!</span>
  <div class="alert-body">
    <strong class="alert-title">Unsaved changes</strong>
    <p class="alert-text">The draft is kept locally until you publish.</p>
  </div>
</div></j3w1-alert>

success

Saved

The settings apply to new windows.

<j3w1-alert id="example-alert-success"><div class="alert alert-success" role="status">
  <span class="alert-glyph" aria-hidden="true">✓</span>
  <div class="alert-body">
    <strong class="alert-title">Saved</strong>
    <p class="alert-text">The settings apply to new windows.</p>
  </div>
</div></j3w1-alert>

info

Fonts

The reference font is not distributed; a metric-compatible fallback is used.

<j3w1-alert id="example-alert-info"><div class="alert alert-info" role="status">
  <span class="alert-glyph" aria-hidden="true">i</span>
  <div class="alert-body">
    <strong class="alert-title">Fonts</strong>
    <p class="alert-text">The reference font is not distributed; a metric-compatible fallback is used.</p>
  </div>
</div></j3w1-alert>

neutral

Read only

This profile is approved; open a decision to change it.

<j3w1-alert id="example-alert-neutral"><div class="alert alert-neutral" role="status">
  <span class="alert-glyph" aria-hidden="true">·</span>
  <div class="alert-body">
    <strong class="alert-title">Read only</strong>
    <p class="alert-text">This profile is approved; open a decision to change it.</p>
  </div>
</div></j3w1-alert>

dismissible

New version

Example notification. Dismiss removes this local message.

<j3w1-alert id="example-alert-dismissible"><div class="alert alert-info" role="status">
  <span class="alert-glyph" aria-hidden="true">i</span>
  <div class="alert-body">
    <strong class="alert-title">New version</strong>
    <p class="alert-text">Example notification. Dismiss removes this local message.</p>
  </div>
  <button class="alert-close" type="button" aria-label="Dismiss">✕</button>
</div></j3w1-alert>

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/alert.css';
import '@j3w1/ui/register/alert';

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 alert --out ./vendor/j3w1/alert

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

A status message that belongs to the page or form around it: a failed submit, a saved draft, a deprecation notice. It stays in flow, is never timed, and is announced once when it appears. Transient confirmations are toasts; blocking questions are dialogs.

Anatomy

The block on the status tint behind a 1px status border; the glyph in the status text colour; the title in the same colour and the message in color.text.default; an optional close button at the end. The five statuses use their own tint, border and text roles: color.status.danger.tint, color.status.warning.tint, color.status.success.tint, color.status.info.tint and color.status.neutral.tint behind color.status.danger.border, color.status.warning.border, color.status.success.border, color.status.info.border and color.status.neutral.border.

States

State	Visual	Non-colour channel
default	status tint, 1px status border, glyph and title in the status text colour	the glyph ✕ ! ✓ i ·
hover	close button background → `color.action.tertiary.hover-bg`; the alert itself does not react	cursor: pointer on the button only
focus-visible	ring 1px dashed `color.interaction.focus.ring` at −2px on the close button	the ring

The alert has no disabled, selected or loading state; a message that is no longer true is removed, not greyed.

Keyboard

Only the close button is in the tab order. Enter or Space dismisses and returns focus to where it was, or to the next focusable element after the alert when that element is gone. Escape does nothing, so a page-level Escape handler is never swallowed.

Accessibility

Danger uses role="alert" (assertive) because it needs attention now; the other four use role="status" (polite). The container exists before its text is set, so the live region fires; text is never injected together with the container. The glyph is aria-hidden and the title states the status in words (“Build failed”, “Saved”), so nothing depends on colour or on the glyph alone. The close button is aria-label="Dismiss" and at least 24×24 CSS pixels. Contrast: status text on its tint from 4.88:1 (danger) to 6.59:1 (warning, info); body text at least 7.56:1 on every tint; borders from 4.07:1 (neutral) to 6.59:1.

Portability

Everything is a tint, a 1px border and text; the glyph is a text character, not an icon font. Toolkits with a native info bar map its type to the five statuses and keep the glyph in the text; toolkits without a tint draw the border only and record the deviation.

Non-examples

A coloured left stripe with no border. A rounded, shadowed card. A banner that slides in or auto-dismisses. Colour-only status without the glyph and a worded title. Using role="alert" for success messages. A close button that is an icon with no accessible name. Fixed-position alerts covering content.