Alert
Displays a contextual feedback message in response to a user action or system event. Use to communicate success, errors, warnings, or informational updates inline.
Description
What it does
Alert communicates a system state, feedback message, or important notice to the user. It appears inline within page content, not as a modal overlay.
Where it appears
Form feedback, page-level notifications, system status banners, upload results, and confirmation of completed actions. It sits within the document flow, not above it.
Why it exists
Consistent alert treatment means users can quickly identify and interpret feedback without re-learning each screen. The four semantic variants — success, error, warning, info — carry predictable meaning across the product. Brand and Neutral add product and system notices, and Pending, Scheduled and Discovery (Figma only) cover workflow statuses. Each comes in three appearances (accent, filled-outlined, plain) and five sizes.
Dependencies
For messages requiring a user decision, use Modal. For transient messages that appear and disappear automatically, use the toast pattern (separate component). Alert is for persistent or semi-persistent inline messages.
Anatomy
| Part | Required? | Notes |
|---|---|---|
| Icon | Recommended | Sits to the left of the message and scales with the alert size (14, 16, 20, 24 or 32px; 20px at medium). Reinforces the semantic variant. Never the only signal — always pair with colour and text. |
| Title | Optional | Short headline. Use when the message benefits from a scannable label. Omit for brief single-sentence messages. In Figma the title is part of the Callout's content slot (swap the content), not a separate layer. |
| Body text | Required | The message. Plain language. One clear idea per alert. |
| Action link | Optional | A single inline action relevant to the message. Use sparingly. Not a separate layer in the Figma Callout; place it inside the content slot. |
| Dismiss button | Optional | × button for closeable alerts. Only include when dismissal is genuinely appropriate for the context. The Figma Callout does not include one yet, so it is designed per use. |
Variants
Success
Positive outcome
Confirming a completed action: saved, submitted, sent, created. Be specific — tell the user exactly what succeeded.
Danger
Something went wrong
An action failed, a system error occurred, or validation cannot proceed. Explain what went wrong and what the user can do. Never blame the user.
Warning
Potential issue or risk
Something is unusual or may cause a problem, but hasn't yet. Used for time-sensitive situations, impending expiry, or partial failures.
Info
Informational
Contextual information that helps the user but doesn't signal a problem or outcome. "This consultation closes in 3 days."
Brand
Product-branded notice
A notice that highlights something about the product itself, such as a new feature. Not a status signal.
Neutral
System or contextual notice
Passive system information with no urgency or status implication. Use when the message is contextual rather than responsive to a user action.
States
| State | Behaviour |
|---|---|
| Default (open) | Visible in document flow. Announced to screen readers via ARIA live region. |
| Dismissible | Has a close button. On dismiss: removed from DOM or hidden via the hidden attribute. Dismissal can be animated if prefers-reduced-motion allows. |
| Loading | Some system alerts appear while an operation is in progress. Use role="status" for these — not role="alert" (see Accessibility tab). |
Usage guidelines
When to use
- Confirming the result of an action: form submission, file upload, save operation.
- Communicating a system error that the user needs to know about.
- Flagging a condition that may affect the user's next steps.
- Providing context about a page or feature state.
When not to use
- When the message requires a user decision — use a Modal.
- For messages that should disappear automatically — use a toast notification.
- For field-level validation — use inline error messages on the form field instead.
- As a container for complex content or interactive UI — keep alert content short and focused.
Do / Don't
Do
Be specific in success messages: "Consultation saved" rather than "Success". Tell users exactly what happened.
Don't
Don't use alarming language in error messages. "Something went wrong — please try again" is better than "Critical error — operation failed".
Do
Use icon + colour + text together. Colour alone isn't enough — users who can't distinguish red from green still need to understand the message.
Don't
Don't stack multiple alerts of the same type. Consolidate messages into one alert with a list if multiple issues exist.
Do
Use role="alert" for urgent messages (errors) and role="status" for non-urgent ones (success, info). See the Accessibility tab.
Don't
Don't include dismiss buttons on error alerts unless the error has been resolved. Dismissing an unresolved error creates confusion.
Layout & Spacing
Alerts are full-width by default within their container. They stack vertically with --op-space-16 between multiple alerts. The icon and body text are vertically centred when the message is single-line; they align to the top when multi-line.
| Element | Spec |
|---|---|
| Padding (all sides) | 12 / 14 / 16 / 20 / 24px (XS to XL), medium 16px. --orbit-callout-size-*-padding |
| Icon size | 14 / 16 / 20 / 24 / 32px. --orbit-callout-size-*-icon-size |
| Icon gap | Same as the padding. --orbit-callout-size-*-gap |
| Border | 1px outline on the filled-outlined appearance only (accent and plain have none). --orbit-callout-border-width |
| Border radius | 8px. --orbit-callout-radius |
| Body font size | 12 / 14 / 16 / 20 / 24px, regular weight. --orbit-callout-size-*-font-size |
Component tokens
Callout (Alert) is built from framework-neutral CSS variables, so any framework can use it without Web Awesome. Colours follow Light and Dark mode and the product theme, and every token aliases a Semantic token. Nine colour variants: brand, neutral, info, success, warning, danger, pending, scheduled and discovery. Three appearances: accent, filled-outlined and plain.
| Token | What it sets |
|---|---|
--orbit-callout-{variant}-accent-background, -accent-text, -accent-icon |
Solid fill, text and icon for the accent appearance. |
--orbit-callout-{variant}-filled-outlined-background, -filled-outlined-border, -filled-outlined-icon |
Tinted fill, outline and icon colour. |
--orbit-callout-{variant}-plain-icon |
Icon colour for the plain appearance. |
--orbit-callout-text |
Body text for filled-outlined and plain. |
| `--orbit-callout-size-{xs | s |
--orbit-callout-radius, -border-width, -font-family, -font-weight |
Shape and type. |
Tokens per variant
The default filled-outlined appearance uses these tokens. Replace {group} with the colour group.
| Variant | Colour group | Background | Border | Icon | Text |
|---|---|---|---|---|---|
| Success | success |
--orbit-callout-{group}-filled-outlined-background |
--orbit-callout-{group}-filled-outlined-border |
--orbit-callout-{group}-filled-outlined-icon |
--orbit-callout-text |
| Error | danger |
same pattern | same pattern | same pattern | --orbit-callout-text |
| Warning | warning |
same pattern | same pattern | same pattern | --orbit-callout-text |
| Info | info |
same pattern | same pattern | same pattern | --orbit-callout-text |
Brand, Neutral, Pending, Scheduled and Discovery follow the same pattern. The accent appearance swaps the tinted fill for a solid one (--orbit-callout-{group}-accent-background) with its own text and icon tokens.
Engineering notes
- Don't pre-render hidden alerts and show them with CSS — toggling
displayorvisibilitydoes not trigger live region announcements. Inject the element into the DOM, or use thehiddenattribute and remove it. - Don't auto-dismiss error alerts. Users — especially those using screen readers or who read slowly — may not have finished reading the message.
- When auto-dismissing non-error alerts, respect
prefers-reduced-motionand give enough time (minimum 5 seconds) before removing. - After a failed form submission, programmatically move focus to the error alert so keyboard users are immediately aware of it. See the Accessibility tab for the focus pattern.
Keyboard interaction
| Key | Action |
|---|---|
| Tab | Moves focus to the dismiss button (if present) or to interactive elements within the alert (action links). |
| Enter or Space | Activates the focused button or link within the alert. |
| Escape | Dismisses the alert if it has a dismiss button and focus is within the alert. |
Why it matters
Alerts that appear dynamically — like a success message after saving a form — aren't automatically communicated to screen reader users. Without an ARIA live region, a user who can't see the screen has no way of knowing their action succeeded. Getting ARIA roles right on alerts is one of the highest-impact, lowest-effort accessibility improvements you can make in a form-heavy application like Open Point.
Focus
Alert itself is not focusable — it's a notification container, not an interactive element. Interactive elements within it (dismiss button, action links) are focusable and receive standard focus ring treatment.
When an error alert appears after form submission, programmatically move focus to the alert so keyboard and screen reader users are immediately aware of it:
ARIA — role="alert" vs role="status"
This is the most important accessibility decision for the Alert component. Getting it wrong either silently ignores messages or creates a disruptive experience for screen reader users.
| ARIA role | Live region | Interrupts? | When to use |
|---|---|---|---|
role="alert" |
aria-live="assertive" |
Yes — immediately interrupts the screen reader | Error alerts only. When the user must be aware of the message right now because it affects what they're doing. Form errors, system failures, permission denials. |
role="status" |
aria-live="polite" |
No — waits for a pause in reading | Success, info, and warning alerts. The message is important but not urgent. Form saved, consultation published, file uploaded. |
Watch out
The most common mistake is using role="alert" for everything because it feels "more reliable". Assertive live regions interrupt screen readers mid-sentence — if used for routine success messages, they become deeply disruptive to assistive technology users. Reserve role="alert" for genuine errors that require immediate attention. For everything else, role="status" is more respectful of the user's reading flow.
Contrast
All alert variants use --op-color-text-primary on their respective background tokens. All combinations meet the minimum contrast requirement for body text at small sizes. All variants pair icon + colour + text together — users who cannot perceive colour differences still receive the full signal through shape and text.
| Variant | Text token | Background token |
|---|---|---|
| Success | --op-color-text-primary |
--op-color-status-success-bg |
| Error | --op-color-text-primary |
--op-color-status-error-bg |
| Warning | --op-color-text-primary |
--op-color-status-warning-bg |
| Info | --op-color-text-primary |
--op-color-status-info-bg |
Touch targets
The dismiss button within a closeable alert must have a minimum 44×44px interactive hit area. Achieve this with padding on the button element rather than increasing the visible size. The visual × icon can remain small while the tappable area extends around it.