# Core/Alert - Design

Alerts are used to communicate important information to the user.

## Usage

Use an Alert to surface contextual feedback in the page: the outcome of an action (success or failure), a condition that needs attention before the user continues, or information that should stay visible while they keep working in the same view.

Keep alerts scoped to the page or region they refer to. Prefer one alert per region so the message stays easy to scan; when several conditions apply at once, combine them into a single alert when it makes sense.

## Properties

### Appearances

### Info

General information like recommend actions to accelerate a user's workflow, helpful information, or tips.

### Error

Problems that must be resolved before the user can complete a task, such as an error on a form.

### Warning

Notify users of cautionary/temporary information affecting the user's workflow, but does not block a user from
completing the action or workflow.

### Success

Brings special attention to the user that an action has been completed, or a status has been updated.

### Layout

### Section

Section notifications communicate the status of a section to the user.

### Inline

Inline notifications are low-priority messages about a single element, like a tile or row item.

### Additional properties

### Title

A title is recommended, but optional. Use a title to quickly summarize the purpose of the notification. Keep titles
short, no more than 60 characters, and avoid repeating the body text.

### Body

The body text is required for all notifications. If the notification is actionable, the text should inform the user
of the next step.

### Action

Actionable notifications are recommended to help the user resolve the issue.

### Dismiss

Alert banners can include a dismiss button that removes the notice from the page layout. Error banners can not be
dismissed.

## Layout and spacing

* Alerts span the full width of their container.

## Behavior

* Alerts are static by default; they do not auto-dismiss.
* If the user triggers an action that resolves the alert condition, remove the alert programmatically.
* When an alert is injected into the DOM, announce it to screen readers via `aria-live`.

## Content

* Title: sentence case, no trailing punctuation, max 60 characters.
* Body: one to two sentences. State the problem and the resolution path. Use punctuation.
* Action label: verb-first, 1-3 words (e.g., "Retry", "View details").
* Avoid technical jargon in user-facing alert text.

## Best Practices

Do:

* Do use `appearance="danger"` for blocking error states.
* Do provide an action when the user has a clear path to resolution.

Don't:

* Don't use Alert for transient, auto-dismissing notifications — use Toast.
* Don't use Alert for individual form field validation errors — use the field's error state.
* Don't use Alert when the message isn't tied to the current page or task context.
* Don't stack Alerts in the same region.
* Don't make `appearance="danger"` Alerts dismissable — the component prevents this automatically.

## Accessibility

* Use `role="alert"` for errors and warnings so they are announced immediately by screen readers.
* Use `role="status"` for informational and success alerts, which are announced at a lower priority.
* Don't rely solely on color to convey alert type — the icon and/or title must distinguish the appearance.
* Ensure the dismiss button has an accessible label (e.g., `aria-label="Dismiss alert"`).

### Keyboard interaction

* Alerts exist in the page's natural tab sequence, their actions reachable via `tab` and `shift`+`tab` keys.

## Related components

* [Toast](?path=/docs/core-toast--design) — For non-blocking, auto-dismissing notifications.
* [Pill](?path=/docs/core-pill--design) — For inline semantic status indicators without body copy.
* [Modal](?path=/docs/core-modal--design) — When the error or warning requires an immediate blocking decision.