# Alert

A message let into the surface, with an annunciator: a small lit legend (Note, Done, Check, Fault) beside the words that say what happened.

Kit part · Free · https://tactileui.dev/parts/alert

- Element: `<div role="alert">`
- Needs: `kit.css` and `kit.mjs` ([how to install the kit](https://tactileui.dev/docs/installation#the-kit))
- Categories: Alerts, Notifications
- Finishes: Aluminium, Graphite, Oak, Walnut, Porcelain, Black, Daylight, Night, Paper, Phosphor, E-paper, AMOLED
- Volumes: Tactile, Quiet

## Variants

### Fault · with a key

```html
<div style="width:240px"><div class="tui-alert tui-alert--stacked" data-alert="error"><span class="tui-alert__legend">Fault</span><p class="tui-alert__text"><b>Backup failed.</b> The disk is full.</p><div class="tui-alert__actions"><button class="tui-key tui-key--sm">Free space</button></div></div></div>
```

### Check · dismissable

```html
<div style="width:240px"><div class="tui-alert" data-alert="warning"><span class="tui-alert__legend">Check</span><p class="tui-alert__text"><b>Disk 82% full.</b></p><button class="tui-key tui-key--flat tui-key--icon tui-key--sm tui-alert__dismiss" type="button" aria-label="Dismiss" data-tip="Dismiss" data-alert-dismiss><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4.5 4.5l7 7M11.5 4.5l-7 7"/></svg></button></div></div>
```

### Done

```html
<div style="width:240px"><div class="tui-alert" data-alert="success"><span class="tui-alert__legend">Done</span><p class="tui-alert__text"><b>Backup finished</b> at 02:14.</p></div></div>
```

### Note · words only

```html
<div style="width:240px"><div class="tui-alert" data-alert="info"><span class="tui-alert__legend">Note</span><p class="tui-alert__text">Backups run nightly at 02:00.</p></div></div>
```

### Fault that needs you now · blinking

```html
<div style="width:240px"><div class="tui-alert" data-alert="error"><span class="tui-alert__legend" data-blink>Fault</span><p class="tui-alert__text"><b>Smoke in the loft.</b></p></div></div>
```

## Every state

- Note
- Done
- Check
- Fault

Hover, pressed and focus are forced with `.is-hover`, `.is-down` and `.is-focus`; checked and disabled are real.

## API

| Name | Kind | Values | What it does |
| - | - | - | - |
| .tui-alert | class | on | The message window: a recess in the surface, 9px corners. |
| data-alert | attribute | "info" · "success" · "warning" · "error" | Lights the legend: display white, green, amber or red. Nothing else takes colour. |
| .tui-alert__legend | class | one word | The annunciator: dark glass, the word lit behind it. Note, Done, Check, Fault, or your own single word. |
| data-blink | attribute | on the legend | For a fault that needs someone now. Reduced motion holds it lit. |
| .tui-alert__text | class | on | What happened, then what it means. Put the first sentence in . |
| .tui-alert__actions | class | on | One or two keys: the fix, and perhaps a flat key. |
| .tui-alert--stacked | class | — | Puts the keys on their own line under the words, for narrow places. |
| .tui-alert__dismiss · data-alert-dismiss | class · attribute | on a flat icon key | The × key. Needs aria-label and data-tip. |
| role | attribute | "alert" · "status" | “alert” for a fault that appears while someone works; “status” for the rest. None for messages already there on load. |
| --lit | CSS property | set by data-alert | The legend’s light. Read it; data-alert writes it. |
| dismissAlert(alert) | function | kit.mjs | Lets a message go from a script: fade, hide, event, focus onward. |
| tui-alert-dismiss | event | bubbles | Fired on the alert once it is hidden. |
| Enter · Space | keyboard | on × | Dismisses; focus moves to the next focusable thing after the alert. |

## Markup

```html
<div class="tui-alert" data-alert="error" role="alert">
  <span class="tui-alert__legend">Fault</span>
  <p class="tui-alert__text"><b>The inverter stopped answering at 14:02.</b>
    The house is on the grid until it restarts.</p>
  <div class="tui-alert__actions">
    <button class="tui-key tui-key--sm">Restart inverter</button>
  </div>
  <button class="tui-key tui-key--flat tui-key--icon tui-key--sm tui-alert__dismiss"
          aria-label="Dismiss" data-tip="Dismiss" data-alert-dismiss>…×…</button>
</div>
```

```js
import '/kit/kit.mjs';   // wires every [data-alert-dismiss]

document.addEventListener('tui-alert-dismiss', (e) => remember(e.target.id));
// From a script:
import { dismissAlert } from '/kit/kit.mjs';
dismissAlert(document.querySelector('#inverter-fault'));
```

The demo on the page:

```html
<div style="display:grid;gap:12px;width:min(100%,600px)">
  <div class="tui-alert" data-alert="error" role="alert"><span class="tui-alert__legend">Fault</span><p class="tui-alert__text"><b>The inverter stopped answering at 14:02.</b> The house is on the grid until it restarts.</p><div class="tui-alert__actions"><button class="tui-key tui-key--sm" data-toast="Restarting the inverter. It takes about a minute." data-lamp="amber">Restart inverter</button></div><button class="tui-key tui-key--flat tui-key--icon tui-key--sm tui-alert__dismiss" type="button" aria-label="Dismiss" data-tip="Dismiss" data-alert-dismiss><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4.5 4.5l7 7M11.5 4.5l-7 7"/></svg></button></div>
  <div class="tui-alert" data-alert="warning" role="status"><span class="tui-alert__legend">Check</span><p class="tui-alert__text"><b>The export limit is 3.68 kW.</b> Above it the inverter throttles the panels.</p><div class="tui-alert__actions"><button class="tui-key tui-key--flat tui-key--sm" data-toast="Opened the export settings.">Change the limit</button></div><button class="tui-key tui-key--flat tui-key--icon tui-key--sm tui-alert__dismiss" type="button" aria-label="Dismiss" data-tip="Dismiss" data-alert-dismiss><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4.5 4.5l7 7M11.5 4.5l-7 7"/></svg></button></div>
  <div class="tui-alert" data-alert="success" role="status"><span class="tui-alert__legend">Done</span><p class="tui-alert__text"><b>Firmware 4.2 installed.</b> The hub restarted at 02:04 and kept every schedule.</p><button class="tui-key tui-key--flat tui-key--icon tui-key--sm tui-alert__dismiss" type="button" aria-label="Dismiss" data-tip="Dismiss" data-alert-dismiss><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4.5 4.5l7 7M11.5 4.5l-7 7"/></svg></button></div>
  <div class="tui-alert" data-alert="info" role="status"><span class="tui-alert__legend">Note</span><p class="tui-alert__text">Readings are kept for 13 months, then summed into monthly totals.</p></div>
</div>
```

## Usage notes

Every kind at once. The keys work; the × lets a message go and moves focus on to the next thing.

## Accessibility

- Colour is never alone: the legend is a word, and the text says what happened. The red legend is lifted toward white to read at 4.5:1 on its glass.
- Use `role="alert"` only for a fault that appears while someone is working, so it interrupts; `role="status"` is read politely.
- After a dismiss, focus moves to the next focusable element on the page, never to the top of the document.
- The × key has an `aria-label`; the tip repeats it for pointer and keyboard users.

## How it’s built

The window is the kit’s recess. The annunciator is a 24px strip of display glass (the VFD background, an inset shadow, a faint glare) with the word in Geist Mono lit by `--lit` and a two-step glow; a radial wash of the same light sits behind it, the way a lamp shows through printed film. `data-alert` only sets `--lit`. The dismiss is fifteen lines in `alert.mjs`, delegated from the document, so alerts added later work too.

## Rules

The legend lights; the words carry the meaning. A fault says what to do about it, and an alert that needs action never leaves by itself.

The full rules are in `alert.rules.md` in the brain, which ships with the Kit.

## Related parts

- [Toast](https://tactileui.dev/parts/toast): A confirmation after an action: a small plate with a lamp and one factual sentence, read out politely, gone in 3.6 seconds.
- [Lamp](https://tactileui.dev/parts/lamp): The only colour in the kit: a lamp that is on. Green is on, amber is waiting, red is recording or failing, blue is linked, white is standing by. Always next to words.
- [Dialog](https://tactileui.dev/parts/dialog): A decision that must be made now: a native dialog with a question, one sentence of consequence, a way back and the act.
