---
name: toasts
user-invocable: true
description: >-
  How to do toasts in an Adom app: the transient, non-blocking confirmation that tells the user what
  just happened. Covers position (bottom center), the three types (success green, error red, info
  teal), durations (about 4s for a confirmation, sticky for errors, pause on hover), stacking newest
  on top with a cap, dismiss, carrying an action (above all Undo for destructive actions), ARIA, and
  the POST /ui/toast hook. In Adom a toast does double duty: it is also how the AI, which is driving
  the front-end, narrates to the user live during a test or demo ("file downloaded", "running test
  3 of 8"). Read BEFORE adding any confirmation, snackbar, or status popup. Trigger words: toast,
  toasts, snackbar, notification popup, confirmation message, status toast, ui toast, POST /ui/toast,
  show a toast, undo toast, success message, error toast, ai narration, file downloaded toast.
---

# Toasts

A toast is a short, non-blocking message that appears, says what just happened, and goes away. It is
the default answer to "every action answers back": a click that produces no visible change reads as
broken, and a toast is the cheapest way to confirm it worked.

## Rules

- **Position:** bottom center, consistent across the app. One stack, one place to look.
- **Three types,** each with a clear icon and color:
  - success: green `#3fb950`
  - error: red `#f85149`
  - info / neutral: teal `#00b8b0`
- **Duration:** about **4 seconds** for a confirmation, **sticky** for an error the user must read
  and dismiss. **Pause the timer on hover** so it does not vanish while being read.
- **Stack newest on top, cap the visible count** (3 to 4), and collapse or drop the oldest beyond
  the cap. Each toast is individually dismissable.
- **Carry an action when one exists,** above all **Undo** for anything destructive. A delete that
  shows "Deleted. Undo" is forgiving; a silent delete is not.
- **Never block.** A toast never traps focus or stops the user. If a choice is required, that is a
  modal, not a toast.
- **It sits at `--z-toast: 400`** in the z-index ladder (below modals and tooltips, above HUDs).
- **Accessible:** `role="status"` and `aria-live="polite"` for info and success, `role="alert"` and
  `aria-live="assertive"` for errors, so screen readers announce them.

```css
.toast {
  display: flex; align-items: center; gap: 12px;
  background: #161b22; border: 1px solid #30363d; border-radius: 12px;
  padding: 14px 18px; box-shadow: 0 18px 50px rgba(0,0,0,.5);
  border-left: 3px solid var(--toast-accent);   /* green / red / teal by type */
}
.toast .action { margin-left: auto; color: #58a6ff; font-weight: 600; cursor: pointer; }
```

## The `POST /ui/toast` hook: feedback AND AI narration

Build a server endpoint that raises a toast, from day one. It serves two callers with one
mechanism:

1. **The user**, getting feedback on their own actions.
2. **The AI**, which is driving the front-end (see `ai-driven-apps`). Because the AI controls the
   app, a toast is the natural place for it to narrate live, on top of the running app, during a
   test or a demo: "running test 3 of 8", "file downloaded", "loaded LM358, re-routing". That status
   belongs over the app, not buried in chat.

```
POST /ui/toast  { "type": "success", "message": "File downloaded", "action": null, "ttl": 4000 }
```
The CLI wraps it: `mytool ui toast "file downloaded"`. The same command the AI uses to drive
everything else also lets it talk to the user.

## Related skills

`tooltips` (the z-index ladder, the sibling transient element), `ai-driven-apps` (the AI raising
toasts while driving), `human-ui-patterns` (the broader feedback rules), and `adom-ui-design` (the
hub).