---
title: "Alert escalation"
description: "Moving a message from ambient to interruptive only as far as it has earned, with a budget per screen and an announced de-escalation"
url: "https://opsinjs.pensievelabs.org/docs/patterns/alert-escalation"
source: "https://opsinjs.pensievelabs.org/docs/patterns/alert-escalation.md"
section: "Patterns"
kind: "pattern"
aliases: ["escalation ladder", "interruptive alerts", "alert budget", "when to interrupt"]
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> Nothing is missing from this page. The data simply does not live in
> the prose.

The unit of design is the ladder rather than the alert. It has four surfaces of rising cost, and rules for which one a message may occupy. opsinjs never decides that something is urgent. A clinical rule your product owns assigns the level.

## When to use it [#when-to-use-it]

Use it when the product says something the reader did not ask for and several things could claim their attention. Use something else for:

* a result that is the whole screen's purpose: [Result disclosure](./result-disclosure.mdx);
* an emergency, which is never a banner: [High-stakes moments](../health/high-stakes-moments.mdx);
* information with nothing to do, or a system fault: a [Callout](../components/callout.mdx), off the status axis;
* a commercial prompt, which belongs on no rung.

## How it works [#how-it-works]

A message enters at the lowest rung that can do its job and climbs only on a written trigger, such as "three days and the section is still unopened".

1. **Ambient.** A [StatusPill](../components/status-pill.mdx) on the [MetricTile](../components/metric-tile.mdx). Most status belongs here.
2. **In-context.** An [AlertBanner](../components/alert-banner.mdx) above the content it concerns, in normal flow, covering nothing.
3. **Top of screen.** A persistent [CareCard](../components/care-card.mdx) above the fold, with a named action and owner.
4. **Interruptive.** A [Dialog](../components/dialog.mdx) or [Sheet](../components/sheet.mdx) that must be answered, only for information whose absence would cause harm before the next likely session.

The assigned level caps the rung. `steady` and `watch` stay ambient. `attention` reaches a banner with the action inside it. `urgent` adds a CareCard with the action and its timing, and interrupts only where a documented rule requires it.

### The budget [#the-budget]

* One urgent surface per screen, and at most two banners. A second urgent message is merged with the first, demoted or moved to its own screen, never stacked.
* Interruption is metered per session, not per event.
* Two messages at one rung are ranked by clinical consequence, never by recency.
* Repetition is suppressed by identity and state, never by count. No rung is a toast.

### Dismissal and clearing [#dismissal-and-clearing]

* An alert at `attention` or above carries one specific primary action, listed first: "Call your clinic", never "Learn more". Without one, it is information.
* Decide per rung whether dismissal lasts for the session, until the value changes, or for good. Dismissing never resolves the underlying state, and an interruptive surface closes only on an answer.
* Say when a condition clears. An alert that silently disappears teaches the reader that alerts were never real.
* Stale data degrades an alert to [Offline and stale data](./offline-and-stale-data.mdx) rather than letting it assert a current fact.

<NotBuiltYet />

## Components [#components]

* [StatusPill](../components/status-pill.mdx): rung 1.
* [AlertBanner](../components/alert-banner.mdx): rung 2, with no category colour and no transition.
* [CareCard](../components/care-card.mdx): rung 3.
* [Dialog](../components/dialog.mdx) and [Sheet](../components/sheet.mdx): rung 4. On Dialog, `severity="alert"` removes the close control and stops <Kbd>Escape</Kbd> and the scrim from closing it.
* [Callout](../components/callout.mdx): information, off the ladder.

## Escalate in stages [#escalate-in-stages]

```tsx
import { AlertBanner } from "@/components/ui/alert-banner"

<AlertBanner
  status="urgent"
  heading="Your example measurement needs someone to look at it today"
  detectedAt="2026-03-14T10:55:00+00:00"
  dismissible
  onAcknowledge={() => setAcknowledged(true)}
  dismissLabel="I have read this"
  actions={[{ label: "Call your clinic", href: "#example-clinic" }]}
>
  Call your clinic today. This reading is outside the range they asked
  us to tell you about. Your clinic has not been contacted for you.
</AlertBanner>
```

`dismissible` needs `onAcknowledge`, which at `urgent` is your record of who saw the banner and when. Removing the banner drops focus to `<body>`, which the product must recover. To clear an alert, render a `steady` banner that says so.

## Content [#content]

State the fact in the reader's words, then the action and its timing, then the boundary if your rule requires one. The higher the rung, the shorter the sentence and the more specific the action. Never carry severity with capitals, exclamation marks or emoji.

## Accessibility [#accessibility]

* A new alert on the current screen is a status message (WCAG 2.2 SC 4.1.3). Rungs 1 to 3 announce politely and never move focus.
* Rung 4 takes and traps focus. If <Kbd>Escape</Kbd> is disabled, announce why.
* AlertBanner mounts no live region at `steady` or `watch`, so announcing a de-escalation is yours.
* Nothing pulses or flashes, and every rung reads in greyscale by position, icon and wording.
