search

freeCodeCamp / ui

freeCodeCamp's UI Component Library
BSD 3-Clause "New" or "Revised" License
12 stars 14 forks source link

Update Alert `role` #132

Open huyenltnguyen opened 4 months ago

huyenltnguyen commented 4 months ago

Description

The Alert component always has the alert role:

https://github.com/freeCodeCamp/ui/blob/46150e76c8eaea15570f26001463d192f586b67a/src/alert/alert.tsx#L36

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:

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

Screenshots | Variant | Screenshot | | --- | --- | | Info | Screenshot 2024-05-15 at 14 23 32 | | Danger | Screenshot 2024-05-15 at 14 26 03 |

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

ahmaxed commented 1 month ago

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 commented 1 month ago

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

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

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.