/notifications-and-recovery

name: notifications-and-recovery
description: When something goes wrong, the user must be able to recover or try again. Toasts, inline errors, banners, and notification patterns each have a specific role. Use when designing error states, success confirmations, async feedback, in-place editing, or any system that communicates state changes to the user.
metadata:
  priority: 8
  pathPatterns:
    - "components/**"
    - "src/components/**"
    - "**/*.tsx"
    - "**/*.jsx"
    - "design-system/**"
    - "ui/**"
  promptSignals:
    phrases:
      - "toast"
      - "notification"
      - "error message"
      - "success message"
      - "in-place editing"
      - "inline error"
      - "alert"
      - "banner"
      - "recovery"
      - "retry"
      - "notification center"
      - "notification preferences"
      - "notification settings"
retrieval:
  aliases:
    - toast notification
    - error recovery
    - inline error
    - notification pattern
    - in-place editing
    - alert banner
    - retry pattern
    - notification center
    - notification preferences
  intents:
    - show a success message
    - handle an error gracefully
    - design a toast notification
    - add retry to a failed action
    - design inline editing feedback
    - design a notification center
    - let users control which notifications they get
  examples:
    - show a toast when the form is saved
    - what happens when the API call fails
    - design the error state for this form
    - add a retry button when network fails
    - design a notification center for this app
    - let users mute or filter notification categories

Notifications and Recovery

When something changes — success, failure, or anything in between — the user must know. And when something goes wrong, they must always have a path forward. A notification without a recovery action is just an apology.

---

Pattern Selection

| Pattern | When to use | Dismissal | |---|---|---| | **Toast** | Transient result of a user action (saved, sent, deleted) | Auto-dismiss 4–6s, manual close | | **Inline error** | Field-level validation, form errors | Clears on correction | | **Alert banner** | Persistent issue affecting the current context | Manual dismiss or resolved state | | **Modal / dialog** | Blocking error requiring a decision before continuing | User action required | | **Empty state** | No data yet — guide the user to the first action | N/A | | **Skeleton / loading** | Async content pending | Replaced by content | | **In-place confirmation** | Inline edit saved, row updated, item toggled | Auto-clears after 2–3s |

---

Toast Notifications

Toasts confirm that a background action completed. They appear without interrupting the user's flow.

**Placement:** bottom-center or bottom-right. Never top-center — it competes with page content and navigation.

**Duration:** 4–6 seconds for information. Errors should persist until dismissed — the user needs time to read and act.

**Anatomy:**

[Icon] Message text                    [Action] [×]

• Icon: colour-coded (green ✓ success, red ✗ error, orange ⚠ warning, blue ℹ info)
• Message: one sentence, plain language
• Action (optional): "Undo", "Retry", "View" — one action maximum
• Close button: always present on errors; optional on success

✓ "Changes saved."
✓ "Message sent.  [Undo]"
✗ "Could not save. Check your connection.  [Retry]"  ← persists until dismissed

**Never:** multiple simultaneous toasts. Queue them; show one at a time.

---

Inline Errors

Inline errors appear adjacent to the element that caused them. They are the most contextual and actionable form of error feedback.

**Form validation:**

• Validate on blur (leaving a field), not on every keystroke — keystroke validation is noisy
• Validate on submit for the complete form
• Show the error message directly below the field, in red, with an icon
• The field border changes to `--color-error`
• Error message is associated via `aria-describedby` for screen readers

<label for="email">Email</label>
<input id="email" aria-describedby="email-error" aria-invalid="true">
<p id="email-error" role="alert">Enter a valid email address.</p>

**In-place editing:**

• When a field is edited inline (table cell, card title), show save/cancel controls adjacent to the field
• On save: brief success indicator ("✓ Saved") that fades after 2s — do not navigate away
• On error: inline error message below the field with a retry option
• On cancel: restore the original value immediately

---

Alert Banners

Banners are persistent — they stay until the condition is resolved or the user dismisses them.

**Use for:**

• Service degradation ("Some features are temporarily unavailable")
• Account issues requiring action ("Your subscription expires in 3 days. [Renew]")
• Ongoing sync errors ("Changes are not saving. [Retry]")
• Important announcements tied to the current page

**Placement:** top of the affected section, not the entire page unless the issue is truly global.

**Anatomy:**

[Icon] [Message — describes the issue and its scope] [Action] [×]

• One banner at a time per region — multiple simultaneous banners create alarm fatigue
• Dismissible unless the condition is blocking
• Colour follows status colour conventions: red (error), orange (warning), blue (info), green (success/resolved)

---

Recovery Patterns

Every error state must have a path forward. Design the recovery action at the same time as the error message.

Retry

For transient failures (network, timeout, rate limit):

"Could not load results."
[Try again]

• Retry button triggers the same action
• After 3 failed retries, escalate: "Still having trouble? [Contact support]"
• Show a spinner during retry — do not let the user click multiple times

Undo

For destructive or irreversible actions (delete, archive, send):

"Message sent.  [Undo]  ×"

• Undo window: 5–10 seconds. Toast persists for this duration.
• After th