Update Alert role

[huyenltnguyen]

Description

The Alert component always has the alert role:

ui/src/alert/alert.tsx

Line 36 in 46150e7

<div className={classes} role="alert" {...props}>

However, the alert role is quite disruptive to non-sighted users. The role is equivalent to setting aria-live="assertive", which interrupts the user's current task and announces the message immediately. For this reason, the role should only be used for time-sensitive messages, typically error messages.

I'd propose that we change the component's role as follows:

• role is alert if the variant is danger
• role is status if the variant is info, success, or warning

---

Additionally, we should consider creating a separate component for callout boxes:

Screenshots

Variant	Screenshot
Info
Danger

We're using Alert for those messages (to achieve consistent styles), but I think the content of those boxes should be read as part of the page content, rather than as a notification / alert.

The new callout component can have the same set of variants that Alert has, but renders its content in a plain div, without any roles.

References

• https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role
• https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role

[ahmaxed]

I am not familiar with the CallOut component. It does not seem to be a common pattern in other component libraries. Would it be possible to just adjust the role for info, success, or warning if necessary instead of creating a new component?

[huyenltnguyen]

In my mind, I'm differentiating Alert and Callout like this:

• Alert
  • Belongs to the system messaging component set.
    • Dialog also belongs to this group, but it's more intrusive because it's a popup and blocks user's flow
  • Used when we want to communicate the status of an action (theme changed successfully, profile edited successfully, etc.)
  • Because of the importance of the messages, Alert needs to have a role so that screen readers can announce to users accordingly
• Callout
  • Is just a box of text that has different styles than the rest of the page content
  • Used to highlight information that is related to the page content
  • Does not convey important information that requires screen readers to pick up immediately
• Callout is borrowing Alert styles, so they are currently looking alike
• I think the split is necessary because of the differences in the components' purposes

The Alert/Callout split was also inspired by the following design systems:

• Twilio
  • Alert: https://paste.twilio.design/components/alert
  • Callout: https://paste.twilio.design/components/callout
  • Also see https://paste.twilio.design/components/callout#alert-vs-callout-vs-toast-vs-help-text
• New South Wales Gov
  • Global alert: https://digitalnsw.github.io/nsw-design-system/components/global-alert/index.html
  • Callout: https://digitalnsw.github.io/nsw-design-system/components/callout/index.html
• Alberta Gov
  • Notification banner (equivalent to our Alert) https://design.alberta.ca/components/notification-banner
  • Callout: https://design.alberta.ca/components/callout#tab-0
• Shopify
  • Banner (equivalent to our Alert): https://polaris.shopify.com/components/feedback-indicators/banner
  • Callout card (equivalent to our Callout, the use case here is similar to the donation box that we show on /learn): https://polaris.shopify.com/components/layout-and-structure/callout-card
• Duetds
  • Alert: https://www.duetds.com/components/alert/
  • Callout: https://www.duetds.com/components/callout/

I initially went with Notes for the name of this callout/message box component. But one use case of this component is the donation box on /learn, so "Notes" doesn't cover all of its potential use cases. I decided to use Callout as it is more commonly used in design systems.

---

It is possible to reuse Alert and let the consumers specify the role. However, this adds an overhead to the consumers as well as shifting the a11y responsibility to them (whether or not to add a role, and which role should be used). And unfortunately, accessibility is an area that's often overlooked, so I doubt that the consumers would use the role prop at all, let alone using the correct role.

Also, if we make role optional, the component name, "Alert", will no longer be accurate as an alert is supposed to... make some noise, while without role it will just be a silent div.

We have a similar situation with the Button component, where the component is a little too smart and has the ability to render as both an <a> and a <button>. That ends up with some confusion as the name "Button" doesn't imply that it can render as a link, and we even had accessibility issues because the props interface is too flexible (to account for both link and button) that incorrect usages can sneak in.

In summary, I think of freecodecamp/ui as a design system rather than just a reusable component library, so I believe it should have certain usage rules. The components should be implemented in ways that guide (or even force) its consumers to follow those rules, and one way of doing that is making the components fool-proof.