Notification Modal

Overview

Style

Accessibility

Description

What it does

Notification Modal surfaces a system-level message that requires explicit user acknowledgement before they can continue. It is a modal overlay, not an inline component.

Where it appears

Session expiry warnings, terms of service updates, critical system status changes, or mandatory onboarding notices that must be seen before a user proceeds.

Why it exists

Some messages cannot be passively received — they need deliberate acknowledgement. Notification Modal creates that moment without requiring a full page navigation.

Notification Modal vs Modal

	Notification Modal	Modal
Trigger	System-initiated — the system decides when to show it, not a user action	User-initiated — triggered by a user action (clicking Delete, Edit, etc.)
Icon	Always present — reinforces the type and urgency of the message	Optional — the status variants (Danger, Warning, Success, Info) add one
Actions	Typically one action (OK / Acknowledge) or a choice (Accept / Decline)	Two actions (primary + cancel/secondary)
Dismissal	Often non-dismissible — the message must be acknowledged	Always has a close button and backdrop dismiss
Content	System message — neutral tone, describes a state or change	Task-focused — directly related to what the user was doing

Notification Modal vs Alert

	Notification Modal	Alert
Interrupts flow	Yes — page interaction is blocked until acknowledged	No — appears inline, user can continue
Requires action	Yes — must be dismissed explicitly	No — may be informational only
Urgency	High — used when the message cannot be missed	Variable — success to critical error

Anatomy

Part	Required?	Notes
Backdrop	Required	Semi-transparent overlay. Unlike Modal, clicking it does not dismiss the Notification Modal.
Icon	Required	Sits in the header to the left of the title and reinforces the type of notification — info, warning, success or error. Never decorative-only; always meaningful.
Title	Required	A clear, direct headline in the header, beside the icon. Referenced by `aria-labelledby`.
Close button	Conditional	The Figma variants include the × in the header. Remove it when the message must be acknowledged with the action button.
Message	Required	Plain language explanation. State what happened, what it means, and what (if anything) the user needs to do.
Primary action	Required	"OK", "Got it", "Accept", or similar. This is the only required action. Add a secondary action only when a genuine choice exists.

Variants

Show notification

Your response has been submitted and can no longer be edited.

Got it

Success notification

Confirms a system-initiated outcome the user must acknowledge

Confirming a system-initiated outcome the user must acknowledge before continuing.

Show notification

You'll be logged out in 5 minutes due to inactivity. Save your work to avoid losing any changes.

Log out now

Stay logged in

Warning notification

Surfaces a time-sensitive system state with a meaningful choice

A time-sensitive system state the user should act on, with a meaningful choice available.

Show notification

Error notification

Surfaces a critical error that blocks progress and demands urgent attention

A critical error that blocks progress and must be surfaced urgently, via role="alertdialog".

Show notification

An administrator has revoked your access to this workspace. You will be signed out now.

Sign out

Destructive confirmation

Announces a system-initiated, irreversible change to the user's own access or data

A system-initiated, irreversible change to the user's own access or data that they must acknowledge immediately.

Usage guidelines

When to use

A system-level event has occurred that the user must be aware of before continuing.
Legal, terms, or policy changes that require explicit acknowledgement.
A session is about to expire or has already expired.
A critical integration or dependency has changed that affects the user's current work.

When not to use

For feedback after a user action — use Alert.
For decisions the user initiates — use Modal.
For marketing or promotional messages — do not use an interrupting modal for non-essential content.
More than once per session for the same type of message — repeated interruptions cause users to dismiss without reading.

Do / Don't

Write messages in plain language. "Your session will expire in 5 minutes. Save your work to avoid losing changes." Not "Session timeout warning".

Don't

Don't use Notification Modal for anything that can be shown inline. The interruption cost is high — only use it when missing the message would have real consequences.

Give the user agency where possible. "Renew session" and "Log out now" is better than a single "OK" when a meaningful choice exists.

Don't

Don't stack Notification Modals. If multiple system events fire simultaneously, queue them or consolidate into a single notification.

Layout & Spacing

Notification Modal is the Modal with a status variant (Danger, Warning, Success or Info; Brand and Neutral also exist). A status icon sits to the left of the title, and the confirm button takes the status colour. It is centred in the viewport like any modal and shares the Modal's sizes, spacing and type.

Element	Spec
Width	480 / 640 / 800px (S / M / L), 90vw on small screens. `--orbit-modal-size-*-width`
Status icon	Left of the title, 8px gap, colour per variant. `--orbit-modal-{variant}-icon`, `-status-icon-size`
Header, body and footer padding	As Modal: 24px, with 12px at the top of the header
Confirm button	Button accent in the variant colour (Danger, Warning, Success, Info or Brand)
Title	20px heading font (Lora), medium weight
Border radius	12px. `--orbit-modal-radius`

Component tokens

Notification Modal uses the shared --orbit-modal-* tokens: surface, radius, shadow, spacing and type, plus a status icon colour per variant (--orbit-modal-danger-icon, -warning-icon, -success-icon, -info-icon) and --orbit-modal-status-icon-size. See the Modal page for the full list.

Element	Token
Background	`--orbit-modal-background`
Backdrop	`--orbit-modal-scrim`
Title text	`--orbit-modal-title-color`
Body text	`--orbit-modal-body-color`
Info icon	`--orbit-modal-info-icon`
Success icon	`--orbit-modal-success-icon`
Warning icon	`--orbit-modal-warning-icon`
Error icon	`--orbit-modal-danger-icon`
Brand icon	`--orbit-modal-brand-icon`

Engineering notes

Use role="alertdialog" when the notification describes a critical error — this causes screen readers to announce the message more urgently than role="dialog".
When acknowledgement is mandatory, do not add backdrop click dismissal. The user must engage with the action button.
Always move focus into the modal on open — system-initiated modals can appear while the user is anywhere on the page.

Keyboard interaction

Key	Action
`Tab`	Moves focus between action buttons. Focus is trapped within the modal.
`Enter or Space`	Activates the focused button.
`Escape`	Closes the modal only if a close path is available. When acknowledgement is mandatory, Escape does nothing.

Why it matters

Notification Modals are system-initiated — the user didn't ask for them. This makes focus management especially important: when the modal opens, focus must move immediately into it, and the first thing announced must clearly explain what has happened. A screen reader user who opens a page and suddenly hears nothing — because the modal appeared but focus stayed on the page — receives no information about a potentially critical system event.

ARIA — dialog vs alertdialog

Role	When to use	Announcement behaviour
`role="dialog"`	Standard notifications: session expiry, terms updates, feature announcements	Polite — announces after the current reading context finishes
`role="alertdialog"`	Critical errors that require immediate action: data loss risk, authentication failure, sync errors	Assertive — interrupts reading immediately

Watch out

Don't use role="alertdialog" for routine notifications. Assertive interruption is disruptive for screen reader users — reserve it for situations where the user genuinely needs to act immediately to prevent harm or data loss.

Things to avoid

Don't auto-open Notification Modals on page load unless the event is genuinely critical. Let the page settle before interrupting.
Don't allow the backdrop to be clicked when acknowledgement is mandatory. The user must engage with the content.
Don't omit the icon's colour and shape variation just to keep design clean — these signals are critical for users with visual impairments who can distinguish shapes but not colours.
Don't use role="alertdialog" without also ensuring focus moves into the modal on open — an assertive live region that doesn't receive focus still loses context on some screen readers.

Web Awesome implementation

Notification Modal uses the same wa-dialog component as Modal, without a close button when acknowledgement is mandatory. Set light-dismiss=“false” so backdrop clicks can’t dismiss the message, and add role=“alertdialog” for critical errors so screen readers announce it more urgently.

Standard notification (requires acknowledgement)

<wa-dialog
  id="session-warning"
  label="Your session is about to expire"
  light-dismiss="false"
  without-header
>
  <wa-icon slot="icon" name="triangle-exclamation" variant="warning"></wa-icon>
  <p>You'll be logged out in 5 minutes due to inactivity. Save your work to avoid losing any changes.</p>
  <wa-button slot="footer" appearance="plain" data-style="secondary">Log out now</wa-button>
  <wa-button slot="footer" variant="neutral" appearance="accent">Stay logged in</wa-button>
</wa-dialog>

Critical error notification (alertdialog)

<wa-dialog
  id="sync-error"
  role="alertdialog"
  label="Sync failed"
  light-dismiss="false"
  without-header
>
  <wa-icon slot="icon" name="circle-xmark" variant="danger"></wa-icon>
  <p>Your changes could not be saved due to a connection error. Download a copy of your work before continuing.</p>
  <wa-button slot="footer" variant="neutral" appearance="accent">Download backup</wa-button>
</wa-dialog>

HTML pattern

Notification Modal uses the same <dialog> element as Modal but omits the close button when acknowledgement is mandatory. Use role=“alertdialog” when the notification describes a critical error — this causes screen readers to announce the message more urgently.

Standard notification (requires acknowledgement)

<dialog
  id="session-warning"
  aria-labelledby="notif-title"
  aria-describedby="notif-desc"
>
  <div class="notif-modal">
    <div class="notif-modal__icon notif-modal__icon--warning" aria-hidden="true">
      <!-- warning icon -->
    </div>
    <h2 id="notif-title" class="notif-modal__title">Your session is about to expire</h2>
    <p id="notif-desc" class="notif-modal__message">
      You'll be logged out in 5 minutes due to inactivity. Save your work to avoid losing any changes.
    </p>
    <div class="notif-modal__actions">
      <button class="btn btn--secondary" onclick="document.getElementById('session-warning').close()">
        Log out now
      </button>
      <button class="btn btn--primary" onclick="renewSession()">
        Stay logged in
      </button>
    </div>
  </div>
</dialog>

Critical error notification (alertdialog)

<dialog
  id="sync-error"
  role="alertdialog"
  aria-labelledby="error-title"
  aria-describedby="error-desc"
>
  <div class="notif-modal">
    <div class="notif-modal__icon notif-modal__icon--error" aria-hidden="true">
      <!-- error icon -->
    </div>
    <h2 id="error-title" class="notif-modal__title">Sync failed</h2>
    <p id="error-desc" class="notif-modal__message">
      Your changes could not be saved due to a connection error. Download a copy of your work before continuing.
    </p>
    <button class="btn btn--primary" onclick="document.getElementById('sync-error').close()">
      Download backup
    </button>
  </div>
</dialog>