# Toast

> Give a short receipt for an action, with enough time to dismiss it or undo it.

Source: https://kwark.space/designSystem/components/toast

## Usage

### Choose the tone
| Tone | Example | Status |
|---|---|---|
| Neutral | Notes copied. | Ready for Kwark |
| Success | Call sheet issued · Revision 2 | App |
| Info | Scene 12 opened in view-only mode. | App |
| Warning | Saved on this device. | App |
| Error | Could not copy the call-sheet link. | App |
| Undo | Scene 12 moved to Act 2. Undo | App |
| Measured progress | Exporting the screenplay · 48 of 112 pages | Ready for Kwark |

Use a persistent [banner](https://kwark.space/designSystem/components/banner.md) for offline or read-only status that still affects the page. The warning toast can acknowledge a specific action taken in that state. A failed export that requires a retry belongs beside the export control. The app provider stacks short messages and uses four seconds for a receipt and eight seconds when it carries an action.

## Style

### Anatomy

A surface-coloured rectangle with a tone border, a leading Lucide glyph, and readable text. An optional text action precedes the dismiss target. The app displays a lower-right stack. Keep the stack clear of phone navigation and the floating pen.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-ok` | #2c6e49 | #6cc08a |
| `--k-info` | #255799 | #7db4f0 |
| `--k-warn` | #8a5a00 | #d8a44a |
| `--k-danger` | #b4382c | #e0685c |
| `--k-radius-card` | 10px |  |
| `--k-shadow-pop` | 0 1px 2px rgba(15, 23, 42, .06), 0 12px 32px rgba(15, 23, 42, .12) | 0 2px 6px rgba(0, 0, 0, .2), 0 16px 36px rgba(0, 0, 0, .55) |

## Code

### React

In the Kwark app: `import { useToast } from '@/components/ui/Toast'`.

```tsx
const { showToast } = useToast();
showToast('Scene 12 moved to Act 2.', 'info', { label: 'Undo', onClick: restoreScene });
```

| Prop | Type | Notes |
|---|---|---|
| `message` | `string` | Announce the outcome once. |
| `type` | `'success' \| 'error' \| 'info' \| 'warning'` | Defaults to info. Neutral and progress are standalone proposals. |
| `action` | `{ label: string; onClick: () => void }` | One reversible action. |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-toast-stack" aria-label="Example notifications">
  <div class="kw-toast" role="status"><span>Copied the prompt</span><button class="kw-icon-button" type="button" aria-label="Dismiss notification"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg></button></div>
  <div class="kw-toast kw-toast--success" role="status"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21.8 10A10 10 0 1 1 17 3.3"/><path d="m9 11 3 3L22 4"/></svg><span>Call sheet issued as Rev 2</span><button class="kw-icon-button" type="button" aria-label="Dismiss notification"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg></button></div>
  <div class="kw-toast kw-toast--info" role="status"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><path d="M12 16v-4M12 8h.01"/></svg><span>Project moved to trash</span><button class="kw-text-button" type="button">Undo</button><button class="kw-icon-button" type="button" aria-label="Dismiss notification"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg></button></div>
  <div class="kw-toast kw-toast--warning" role="status"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m21.7 18-8-14a2 2 0 0 0-3.5 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.7-3M12 9v4M12 17h.01"/></svg><span>Kept on this device; it will sync when you are back online.</span><button class="kw-icon-button" type="button" aria-label="Dismiss notification"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg></button></div>
  <div class="kw-toast kw-toast--error" role="alert"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><path d="M12 8v4M12 16h.01"/></svg><span>That picture could not be saved. Try a smaller image.</span><button class="kw-icon-button" type="button" aria-label="Dismiss notification"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg></button></div>
</div>
```

## Accessibility

Publish routine receipts to one polite live region. Announce an urgent error only once. Never move focus into a new toast. Pause dismissal while a pointer or focus is inside, and keep a recoverable alternative if Undo times out. Progress needs a label, unit and total. Treat repeated updates as one task.

## For agents

### Rules

- **Must** name the action outcome in words.
- **Must** preserve the underlying work when a command cannot complete.
- **Always** offer Undo for a reversible removal or move.
- **Never** use a fleeting toast as the only place someone can recover.

### AI readiness test

**Task:** Show a save receipt, a temporary offline warning, and Undo for a scene move.

**Give the agent:** Decision 0013, Toast and Saving and sync.

**Constraint:** The scene move is reversible and the draft may be offline.

**A reliable answer:**
- Distinguishes neutral, success and warning
- Uses the actual persistence state
- Keeps Undo reachable
- Avoids duplicate screen-reader announcements
