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 · 4.0.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.

Markup

<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.

Markup

<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.

Markup

<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.

Markup

<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.

Markup

<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.

Markup

<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@4.0.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@4.0.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

Specimen density

Specimen profile

Alert `alert`

Family: Feedback and overlays
Maturity: stable
Priority: R1
Since: 0.1.0
Native control: native landmark-free block; role=alert for danger, role=status for every other status; an optional native close button — APG pattern
specified
demonstrated

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

Report an issue with this component

Tokens

Focus a role to inspect its values; follow its link for persistent usage and source details.

Part	Role	Value	Use
`danger.bg`	`color.status.danger.tint`observeduse	`#2b0e0d`	Danger background tint.
`danger.border`	`color.status.danger.border`observeduse	`#e53935`	Danger border, 2px on invalid inputs.
`danger.text`	`color.status.danger.text`observeduse	`#f07178`	D-041 readable error text on neutral surfaces and native warning tints.
`warning.bg`	`color.status.warning.tint`approveduse	`#1f1a0c`	Warning background tint.
`warning.border`	`color.status.warning.border`approveduse	`#e5c07b`	D-041 status.warning.border: color.primitive.modern.amber.
`warning.text`	`color.status.warning.text`approveduse	`#e5c07b`	D-041 status.warning.text: color.primitive.modern.amber.
`success.bg`	`color.status.success.tint`approveduse	`#0f1a0e`	Success background tint.
`success.border`	`color.status.success.border`approveduse	`#82d9a0`	D-041 status.success.border: color.primitive.modern.green.
`success.text`	`color.status.success.text`approveduse	`#82d9a0`	D-041 status.success.text: color.primitive.modern.green.
`info.bg`	`color.status.info.tint`approveduse	`#0f141c`	Info background tint.
`info.border`	`color.status.info.border`approveduse	`#82b4ff`	D-041 status.info.border: color.primitive.modern.blue.
`info.text`	`color.status.info.text`approveduse	`#82b4ff`	D-041 status.info.text: color.primitive.modern.blue.
`neutral.bg`	`color.status.neutral.tint`approveduse	`#140b0b`	D-041 status.neutral.tint: color.primitive.modern.raised.
`neutral.border`	`color.status.neutral.border`approveduse	`#986f72`	D-041 status.neutral.border: color.primitive.modern.control.
`neutral.text`	`color.status.neutral.text`approveduse	`#d4868b`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`body.text`	`color.text.default`approveduse	`#e99499`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`close.text`	`color.action.tertiary.text`approveduse	`#e99499`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`close.bg-hover`	`color.action.tertiary.hover-bg`observeduse	`#1c0a09`	Ghost and icon button hover.
`close.ring`	`color.interaction.focus.ring`observeduse	`#e53935`	1px dashed focus ring on controls and rows.

State matrix

Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).

State	Danger	Warning	Success	Info	Neutral	Dismissible
`default`	Build failed Two token references do not resolve in the default profile.	Unsaved changes The draft is kept locally until you publish.	Saved The settings apply to new windows.	Fonts The reference font is not distributed; a metric-compatible fallback is used.	Read only This profile is approved; open a decision to change it.	New version 0.2.0 adds the extended overlay.
`hover`
`focus-visible`

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

Parts as listed in the anatomy. Each of the five statuses uses its own tint, border and text roles.

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 → `color.action.tertiary.hover-bg`; the alert itself does not react	cursor: pointer on the button only
focus-visible	1px dashed `color.interaction.focus.ring` ring at −2px on the close button	the ring

No disabled, selected or loading state: a message that is no longer true is removed, not greyed.

Keyboard

As in the key table. Escape does nothing so a page-level Escape handler is never swallowed.

Accessibility

Danger is role="alert" (assertive) because it needs attention now; the other four are role="status" (polite). The container exists before its text is set so the live region fires; never inject text 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 the glyph alone. The close button is at least 24×24 CSS pixels. Text meets 4.5:1 on every tint; borders 3:1.

Portability

The glyph is a text character, not an icon font. A toolkit with a native info bar maps its type to the five statuses and keeps the glyph in the text; one without a tint draws the border only and records 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. role="alert" for success. A close icon with no accessible name. Fixed-position alerts covering content.

Contrast report

20 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 0 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.

Pair	State	Kind	Foreground	Background	Ratio	Min	Result
alert default text	default	text	`color.status.danger.text` `#f07178`	`color.status.danger.tint` `#2b0e0d`	6.27	4.5	pass
alert default border	default	ui	`color.status.danger.border` `#e53935`	`color.status.danger.tint` `#2b0e0d`	4.24	3	pass
alert hover text	hover	text	`color.action.tertiary.text` `#e99499`	`color.action.tertiary.hover-bg` `#1c0a09`	8.35	4.5	pass
alert focus-visible text	focus-visible	text	`color.action.tertiary.text` `#e99499`	`color.status.info.tint` `#0f141c`	8.06	4.5	pass
alert focus-visible outline	focus-visible	ui	`color.interaction.focus.ring` `#e53935`	`color.status.info.tint` `#0f141c`	4.37	3	pass
body text on the danger tint	—	text	`color.text.default` `#e99499`	`color.status.danger.tint` `#2b0e0d`	7.82	4.5	pass
warning glyph and title on the warning tint	—	text	`color.status.warning.text` `#e5c07b`	`color.status.warning.tint` `#1f1a0c`	10.04	4.5	pass
warning border on the warning tint	—	ui	`color.status.warning.border` `#e5c07b`	`color.status.warning.tint` `#1f1a0c`	10.04	3	pass
body text on the warning tint	—	text	`color.text.default` `#e99499`	`color.status.warning.tint` `#1f1a0c`	7.56	4.5	pass
success glyph and title on the success tint	—	text	`color.status.success.text` `#82d9a0`	`color.status.success.tint` `#0f1a0e`	10.54	4.5	pass
success border on the success tint	—	ui	`color.status.success.border` `#82d9a0`	`color.status.success.tint` `#0f1a0e`	10.54	3	pass
body text on the success tint	—	text	`color.text.default` `#e99499`	`color.status.success.tint` `#0f1a0e`	7.80	4.5	pass
info glyph and title on the info tint	—	text	`color.status.info.text` `#82b4ff`	`color.status.info.tint` `#0f141c`	8.73	4.5	pass
info border on the info tint	—	ui	`color.status.info.border` `#82b4ff`	`color.status.info.tint` `#0f141c`	8.73	3	pass
body text on the info tint	—	text	`color.text.default` `#e99499`	`color.status.info.tint` `#0f141c`	8.06	4.5	pass
neutral glyph and title on the neutral tint	—	text	`color.status.neutral.text` `#d4868b`	`color.status.neutral.tint` `#140b0b`	7.01	4.5	pass
neutral border on the neutral tint	—	ui	`color.status.neutral.border` `#986f72`	`color.status.neutral.tint` `#140b0b`	4.48	3	pass
body text on the neutral tint	—	text	`color.text.default` `#e99499`	`color.status.neutral.tint` `#140b0b`	8.46	4.5	pass
close button on the info tint	—	text	`color.action.tertiary.text` `#e99499`	`color.status.info.tint` `#0f141c`	8.06	4.5	pass
ring on the info tint	focus-visible	ui	`color.interaction.focus.ring` `#e53935`	`color.status.info.tint` `#0f141c`	4.37	3	pass

Keys

Key	Action
`Tab`	Reaches the close button when present; the alert itself is never focusable.
`Enter / Space`	Dismisses; focus returns to the element that had it, or to the next focusable element after the alert.
`Escape`	Nothing; alerts are not dialogs.

For agents

Component JSON ·Implementation brief ·Build a task kit ·

Stress fixtures: FX-LONG FX-320 FX-ZOOM-200 FX-I18N FX-RTL FX-RM FX-HC FX-STATE-MATRIX

j3w1 / theme

j3w1 / command

Alert

Live variants

danger

warning

success

info

neutral

dismissible

Install and register

Copy the complete implementation

Public API

attributes

properties

methods

events

Dependencies and verification

Canonical specification

Alert `alert`

Tokens

State matrix

Purpose

Anatomy

States

Keyboard

Accessibility

Portability

Non-examples

Contrast report

Keys

For agents

Live variants

danger

warning

success

info

neutral

dismissible

Install and register

Copy the complete implementation

Public API

attributes

properties

methods

events

Dependencies and verification

Canonical specification

Alert alert

Tokens

State matrix

Purpose

Anatomy

States

Keyboard

Accessibility

Portability

Non-examples

Contrast report

Keys

For agents

Alert `alert`