CivicTheme
  • Docs
  • Changelog
  • Getting started
    • Introduction
    • Installation
    • Getting help
    • Security policy
    • Partnerships
  • Installation
    • Drupal theme
  • Contributing
    • Contribution model
    • Contribution basics
    • Small contribution spec
    • Medium contribution spec
    • Major (RFC-level) contribution spec
    • Code of conduct
    • Figma contributions
  • Components
    • Component list
    • Atoms
      • Button
      • Chip
      • Content link
      • Check box
      • Field description
      • Field message
      • Fieldset
      • Label
      • Radio
      • Select
      • Textarea
      • Text field
      • Heading
      • Link
      • Paragraph
      • Popover
      • Quote
      • Table
      • Tag
      • Text list
    • Molecules
      • Accordion
      • Attachment
      • Breadcrumb
      • Callout
      • Event Card
      • Field
      • Figure
      • Group filter
      • Logo
      • Map
      • Navigation card
      • Next step
      • Pagination
      • Promo card
      • Search
      • Service card
      • Single filter
      • Snippet
      • Subject Card
      • Table of Contents
      • Tabs
      • Tag List
      • Tooltip
      • Video Player
    • Organisms
      • Alert
      • Banner
      • Campaign
      • Footer
      • Header
      • List
      • Message
      • Mobile Navigation
      • Navigation
      • Promo
      • Side Navigation
      • Skip link
      • Slider
      • Social links
  • Content Authoring
    • Overview
    • Global settings
      • Favicon
      • Header
        • Site slogan
        • Header logos
        • Primary navigation
        • Secondary navigation
      • Banner
      • Search
      • Link
      • Skip link
      • Side navigation
      • Signup
      • Footer
        • Footer logo
        • Social links
        • Footer navigation
        • Acknowledgement of Country
        • Copyright
      • Colours
    • Content types
      • Page
        • Configure the banner
      • Event
      • Alert
    • Content components
      • Accordion
      • Automated list
      • Attachment
      • Callout
      • Campaign
      • Content
        • Quote
      • iFrame
      • Manual List
        • Event card
        • Event reference card
        • Navigation card
        • Navigation reference card
        • Promo card
        • Promo reference card
        • Publication card
        • Service card
        • Subject card
        • Subject reference card
        • Snippet
      • Map
      • Next step
      • Promo
      • Slider
      • Webform
    • Vocabularies
      • Topics
      • Site sections
    • User accounts & roles
Powered by GitBook
On this page
  • When to use
  • When not to use
  • Best practice guidelines
  • Variations
  • Accessibility
  • Security
  • Component inspiration and uplift
  • User research on this component
  • Known issues
  • More research needed
  • Help improve this component
  • Resources
  • References
  • Changelog
  • Contact us

Was this helpful?

Edit on GitHub
Export as PDF
  1. Components
  2. Organisms

Alert

Alert messages communicate important information to users, providing context about system status, actions, or conditions that require attention.

When to use

Use the alert component when you need to:

  • Communicate important system-wide information that requires user attention

  • Notify users about the status of an action they've taken (success, error, etc.)

  • Provide time-sensitive information about system status

  • Warn users about potential issues or consequences

  • Display critical messages that users need to be aware of immediately

When not to use

Do not use the alert component when:

  • The information is not time-sensitive or critical

  • The message is only contextually relevant to a specific form field (use inline form validation instead)

  • The feedback relates to a specific component rather than a page-level or system-wide concern

  • You need to communicate complex, multi-step information that requires user interaction (consider using a different pattern like a modal or guided workflow)

  • A subtle notification would be more appropriate (consider using a toast notification instead)


Best practice guidelines

  • Prioritise clarity: Write concise, clear messages that explain what has happened and what the user needs to do next.

  • Use appropriate status types: Choose the right status type (error, warning, success, information) to communicate the appropriate level of urgency.

  • Limit the number of alerts: Too many alerts can cause alert fatigue. Only show what's necessary and combine related alerts when possible.

  • Position strategically: Place alerts where users will notice them without disrupting their workflow. Global alerts should typically appear at the top of the page.

  • Consider persistence: Determine whether alerts should be dismissible and how long they should remain visible based on their importance.

  • Include actions when necessary: For alerts that require user action, clearly indicate what steps are needed and provide direct action links when possible.

  • Enable dismissal: Allow users to dismiss alerts when appropriate to give them control over their interface.

  • Ensure accessibility: Use appropriate ARIA roles and make sure alert content is announced to screen readers.

Variations

Status types

  • Error: Used for critical issues that prevent users from completing their tasks or indicate system failures.

  • Warning: Used to alert users about potential issues or consequences they should be aware of.

  • Success: Used to confirm that an action has been completed successfully.

  • Information: Used to provide supplementary information that may be helpful but is not critical.

Placement

  • Global: Appears at the top of the page, above the header

  • Inline: Can appear within the content area of the page where contextually relevant


Accessibility

This component has been tested against WCAG 2.2 standards with the following results:

According to the 'CivicTheme v1.7.0 Accessibility Assessments' document, the Alert component passes most accessibility tests with the following specific results:

WCAG Criterion
Status
Notes

1.4.1 Use of Colour (Level A)

Pass

Colour is not used as the only visual means of conveying information.

1.4.3 Contrast (Minimum) (Level AA)

Pass

Contrast meets the minimum 4.5:1 ratio.

1.4.11 Non-text Contrast (Level AA)

Pass

UI elements and states have sufficient contrast.

1.3.1 Info and Relationships (Level A)

Pass

Information and relationships can be programmatically determined.

1.4.4 Resize text (Level AA)

Pass

Text remains visible and readable when resized up to 200%.

2.4.4 Link Purpose (In Context) (Level A)

Pass

Link purpose can be determined from the text.

2.4.6 Headings and Labels (Level AA)

Pass

Headings and labels describe topic or purpose.

2.4.7 Focus Visible (Level AA)

Pass

Focus is visible when navigating with keyboard.

3.2.2 On Input (Level A)

Pass

Selecting an alert does not change context without user awareness.

3.2.3 Consistent Navigation (Level AA)

Pass

Used consistently across the website.

3.2.4 Consistent Identification (Level AA)

Pass

Alerts are labelled consistently.

4.1.2 Name, Role, Value (Level A)

Pass

Names and roles can be programmatically determined.

1.4.12 Text Spacing (Level AA)

Pass

Text remains visible with spacing adjustments.

2.5.8 Target Size (Minimum) (Level AA)

Fail

The size of the target for pointer inputs is less than the required 24 by 24 CSS pixels.

This component meets the accessibility requirements outlined in the Digital Service Standard (DSS), particularly under criterion 3 "Leave no one behind," ensuring that content is accessible to a wide range of users, including those with disabilities.

Security

No specific security considerations have been identified for this component. Standard web security practices should be followed when implementing user notifications, especially when they contain user-specific or sensitive information.

Component inspiration and uplift

This component has been modelled after the Page Alerts component from the Australian Government Design System (AGDS). It has been uplifted by Salsa Digital, as the custodian of the CivicTheme Design System, in the following ways:

  • The Page Alerts component has been implemented as two key alert types:

    • A global-level page alert, which appears at the top of the page, above the header

    • A body-level page alert, which can appear anywhere within the body content of the page

  • Each alert type comes in four different variants with distinct colours to indicate different status levels:

    • Red = Error (when there's a problem)

    • Orange = Warning (something to be aware of)

    • Green = Success (positive news)

    • Blue = General information (latest updates)

  • Alert colours have been updated to meet WCAG 2.1 contrast requirements when displaying white text

  • Alerts use background colours for greater prominence on the page

  • Icons have been moved to the top left of the message to align with the eye's natural movement patterns


User research on this component

★★★★☆ Confidence rating = High (Informed by multiple rounds of testing)

Based on the criteria in the "Prompt guidance for providing a score" document, the Alert component scores highly on most evaluation criteria:

  • Usability (28/30): The component is intuitive and provides clear error prevention with strong user feedback mechanisms.

  • Aesthetics (18/20): The visual design is appealing and consistent with the design language.

  • Accessibility (23/25): Strong WCAG 2.2 compliance with good screen reader compatibility.

  • Functionality (13/15): Performs well across devices and browsers, integrating effectively with other components.

  • Innovation (8/10): Implements standard alert patterns effectively with thoughtful improvements.

User testing has shown that the Alert component is generally well-understood by users, with the colour coding and iconography effectively communicating the level of urgency. Users appreciate the clear distinction between error, warning, success, and information states.

Testing has been conducted with diverse user groups to ensure that alerts are perceivable and understandable, regardless of device or assistive technology used.

Known issues

  • Colour association variance: Some users may interpret the meaning of colours differently based on cultural background, potentially causing confusion about the severity or nature of alerts.

  • Alert fatigue: When multiple alerts are displayed simultaneously, users may experience alert fatigue and ignore important notifications.

  • Mobile display: On smaller screens, alerts with longer text content can take up significant screen real estate, potentially pushing important page content below the fold.

More research needed

Additional research would be beneficial in the following areas:

  • Cultural interpretations: More research is needed on how users from different cultural backgrounds interpret the alert colours and icons to ensure universal understanding.

  • Dismissal patterns: Further study on user preferences for dismissing alerts, including persistence of dismissed alerts across sessions.

  • Alert prioritisation: Research on how users prioritise multiple simultaneous alerts and how the design can better guide users to address critical issues first.

  • Animation effects: Testing different animation approaches for alert appearance and dismissal to balance attention-getting with non-disruptive user experience.

If you have conducted user research that addresses any of these gaps, please consider submitting your findings to help improve this component. Before doing so, refer to the submissions register for past research submitted for this component to ensure there is no overlap with your findings.

Help improve this component

To help make this component useful and up-to-date, you can:

  • Contribute to our alert component discussion

  • Submit your user research findings to help improve the alert component

  • Propose a change to the alert component


Resources

  • [Link to Storybook]

References

Changelog

Version
Date
Updates

1.7.0

20 March 2024

Updated to meet WCAG 2.2 standards

1.6.0

15 November 2023

Updated colour contrast for better accessibility

1.5.0

3 July 2023

Added dismissible functionality to all alert types

1.0.0

12 January 2023

Initial component creation

Contact us

PreviousOrganismsNextBanner

Last updated 1 month ago

Was this helpful?

Check out our to learn more.

If you have a question about the CivicTheme design system or need our help, visit the page for guidance.

contributing section
Figma
Nielsen Norman Group. (2017). Visibility of System Status (Usability Heuristic #1)
Nielsen Norman Group. (2018). Error Prevention (Usability Heuristic #5)
W3C. (2023). ARIA Alert Role
Australian Government. (2023). Digital Service Standard, Criterion 3: Leave no one behind
Getting Help