Skip to content
opsinjs
Edit this page

Patterns

Alert escalation

Moving a message from ambient to interruptive only as far as it has earned, with a budget per screen and an announced de-escalation

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

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;
  • an emergency, which is never a banner: High-stakes moments;
  • information with nothing to do, or a system fault: a Callout, off the status axis;
  • a commercial prompt, which belongs on no rung.

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 on the MetricTile. Most status belongs here.
  2. In-context. An AlertBanner above the content it concerns, in normal flow, covering nothing.
  3. Top of screen. A persistent CareCard above the fold, with a named action and owner.
  4. Interruptive. A Dialog or Sheet 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

  • 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

  • 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 rather than letting it assert a current fact.

NOT IMPLEMENTED. This component does not exist in any released version of opsinjs. There is no package to install, no module to import and no props interface to generate code against. Everything on this page is a specification of intended behaviour and may change without notice. Do not write code against it.

This component is not built yet

There is nothing to render because there is nothing to install. What you can read on this page is the specification the implementation will have to satisfy.

PlannedRoadmapWhat “planned” means

Components

  • StatusPill: rung 1.
  • AlertBanner: rung 2, with no category colour and no transition.
  • CareCard: rung 3.
  • Dialog and Sheet: rung 4. On Dialog, severity="alert" removes the close control and stops Escape and the scrim from closing it.
  • Callout: information, off the ladder.

Escalate in stages

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

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

  • 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 Escape 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.