# Notification banners

Notification banners communicate page-level feedback that must remain visible long enough to understand or act on. They reconcile Kantoku's application banner and Superviso's flash alerts into one muted semantic pattern.

## Tones

| Tone | Use | Token pair |
| --- | --- | --- |
| Success | A completed operation or saved change | `--status-success-surface` / `--status-success-text` |
| Information | Neutral progress, availability, or contextual information | `--status-info-surface` / `--status-info-text` |
| Warning | A recoverable issue or condition that needs attention | `--status-warning-surface` / `--status-warning-text` |
| Danger | A failed operation, blocked task, or urgent problem | `--status-danger-surface` / `--status-danger-text` |

Application payloads named `error` map to the danger tone. Accent colors do not create additional banner meanings.

## Anatomy

- A tone-specific icon is required and is decorative when the title already communicates the meaning.
- A concise title is recommended when the message needs hierarchy; the description is always required.
- One short inline action may follow the description. Use a text link rather than a competing primary button.
- A dismiss control is optional. Give it an explicit accessible name such as `Dismiss warning notification`.

## Placement

Place a banner below the page header and above the affected page region. A global account or system notice may sit below the application navigation when it genuinely applies to every page.

Avoid floating banners over content. Use field messages for validation errors and status badges for record state.

## Toast boundary

A toast is appropriate only for brief, non-blocking confirmation that does not need to remain in the reading order. Superviso actively uses bottom-right PrimeVue toasts for operation and flash feedback, generally with a five-second lifetime. Kantoku includes PrimeVue toast styling but has no active toast runtime usage in its Vue application; it currently relies on banners and local action messages.

Toast notifications remain a candidate pattern until adoption converges:

- place the stack at the bottom-right, respecting a 16px viewport inset;
- use the same success, information, warning, and danger meanings as banners;
- include a visible dismiss control and pause expiration while hovered or focused;
- announce routine messages politely and avoid moving focus;
- do not include required actions, validation errors, or critical guidance;
- avoid stacking more than three messages and collapse repeated events.

Prefer a banner when the message affects the current page, blocks a task, requires an action, or must survive longer than a few seconds.

## Behavior

1. Do not automatically dismiss warning or danger banners.
2. Allow dismissal only when the message remains recoverable elsewhere or no longer blocks the current task.
3. Consolidate related feedback rather than stacking several banners.
4. Preserve the banner during an Inertia visit when the underlying condition still exists.
5. If an action retries a request, keep its label stable and show a local loading state.

## Accessibility

Use `role="status"` or a polite live region for routine success and information updates. Use `role="alert"` only for urgent failures that require immediate announcement; do not apply it to static guidance rendered with the page.

Tone never carries meaning alone. Keep the visible icon, title or message, and semantic role aligned. Move focus only when the banner contains the next required interaction or when the user's action cannot continue without addressing it.

## Migration notes

- Replace Kantoku's saturated indigo success strip with the shared muted success treatment.
- Replace Superviso's raw Tailwind green, blue, yellow, and red alert palettes with the corresponding semantic status tokens.
- Preserve each application's flash payload and lifecycle behavior while aligning presentation and accessibility.