A presentation at React Miami in April 2023 in Miami, FL, USA by Kathleen McMahon
Welcome everyone! I’m Kathleen McMahon and I’m here today to talk about a Design System Carnival! One accessible component, many pretty masks. Before we begin, let’s get some details out of the way.
My presentation will be posted on Notist, that’s https://noti.st/resource11 — including links to resources — after my talk. I’ll also post the full URL on Twitter after my presentation.
You can follow me at resource11 on Twitter, Instagram, and GitHub.
Let’s back up so I can introduce myself better…
So I’m an engineer and a designer and I like to speak about things…
Occasional cyclocross racer. In costume, of course.
Lover of lights
Beach goer.
Sand dollar collector
Lover of my cats Thor
…and Otis.
I’m a Crystal collector
And I try to get good photos but Otis…
…interferes often
…and has…
…none of it. Thanks, Otis
Thor does the same…
He looks pretty satisfied.
Who could resist them, though?
I’m also a Senior Design Systems Engineer at Northwestern Mutual, working on the Luna Design System. I love my team; they are pretty rad.
I love design systems; it’s exciting! Especially if you like…
…herding kittens. Always fun, lots of moving parts.
I think Design Systems are like a Carnival! What do I mean by that?
Well… I visited Venice last fall and was fascinated by the masks. I loved their beauty…
their variety…
And… they’re everywhere.
Everywhere you look in Venice.
In the shops.
…the souvenirs.
I even made my own mask
And I learned the masks have a rich history of providing access. And helping a person blend in…
…to hide their gender, identity, social class…
Some of the well-known masks are the Bauta… This mask was great because it had this big jaw so you could go eat and drink and do the things you want to do and not be noticed.
There’s the Moretta…
The Gagna… meow!
The Harlequin..
…and wearing these masks gave you access to places with more freedom — like this parade of gondolas during Venice’s Carnival Similar to a design system. When well-crafted, masks create consistency of experience.
So, is the experience consistent for everyone though? Let’s talk Accessibility.
From vision hearing, motor skills, cognitive, sensory, language needs, bandwidth, speed, and more. Our users have so many needs, and so often, accessibility is what is handled last. We don’t want to leave our users behind
Now what does this mean in terms of accessible design system components?
Well, there is this report called the WebAIM Million report and it’s been released for the past five years now. If you’ve read the results, they’re a bit concerning. It’s an accessibility analysis of the top 1000 homepages. And I’m going to focus on the amount of ARIA present on the homepage.
There has been up to a 29% increase the past year, and the amount of ARIA attributes has nearly quadrupled since 2019. So that means that our developers are making the web worse in the spirit of best intentions.
There has been up to a 29% increase the past year, and the amount of ARIA attributes has nearly quadrupled since 2019. So that means that our developers are making the web worse in the spirit of best intentions.
There has been up to a 29% increase the past year, and the amount of ARIA attributes has nearly quadrupled since 2019. So that means that our developers are making the web worse in the spirit of best intentions.
There has been up to a 29% increase the past year, and the amount of ARIA attributes has nearly quadrupled since 2019. So that means that our developers are making the web worse in the spirit of best intentions.
There has been up to a 29% increase the past year, and the amount of ARIA attributes has nearly quadrupled since 2019. So that means that our developers are making the web worse in the spirit of best intentions.
So what can we do about this?
This is the W3C’s Web Accessibility Initiative page, and it has some fantastic guidelines for us to follow. Especially for ARIA authoring practices, design patterns, and examples.
Now, I generally with all my talks will give you examples and how-tos on how to make a component accessible, This is not that type of talk. However. I will be providing code examples and resources at the end of the talk. So don’t worry, you will not miss anything. I will have the code examples. I will have the notes. And I always provide notes with my deck so you can sit back, relax, and enjoy the storytelling instead… and the masks.
We have this one pattern in a design system that is the basis for things like popups, toggleTips, toggleSearch, and you can see them used in things like a terms of service widget.
This one pattern has a few uses, and if it’s built correctly, it can have a few uses in your design system. It’s called the Disclosure Widget.
The anatomy of a disclosure widget is…
A button that opens and closes a container And returns focus to the button.
And the WAI site has a documented pattern for this basic disclosure widget
This pattern has three primary keyboard interactions: • Space bar/Enter key — which comes natively when you use a button to open the disclosure — • Mouse clicks, and • And the ESC key, which is part of the extended disclosure pattern
So when you build a disclosure pattern you begin with a button JSX button because..
…you natively get under the hood: mouse clicks, enter keypress and spacebar keypresses by default. This is just built in. Yay HTML. We love HTML. I love HTML.
And… we’ll use just enough ARIA attributes to let screen readers know when the container is being opened and closed — or in the case of if you have many widgets on the page — which container is being opened or closed.
On the button, the three ARIA attributes we’re adding are
Aria-controls to tell assistive technology the id of the associated element the button’s controlling. In this case it would be the name of the container’s id.
[jsx code] aria-controls={ariaControls}
aria-expanded, which conveys whether the widget is expanded or not
[jsx code]
aria-expanded={ariaExpanded}
And aria-label for cases where we need a more accurate button label, especially if we are doing icon buttons
[jsx code]
aria-label={ariaLabel}
We also need state and click handlers to toggle the container open and closed
We’ll use React’s useState hook to define the isOpen state variable and setIsOpen function, initializing isOpen to false.
[jsx code]
const [isOpen, setIsOpen] = useState(false);
Optionally, we could pass in a boolean defaultExpanded prop, for those cases when we need a widget to be open when a view is loaded.
Like a Terms of Service toggle tip, for example.
[jsx code]
const [isOpen, setIsOpen] = useState(defaultExpanded);
We then make a toggleOpen function that uses setIsOpen to toggle the state between true and false
[jsx code]
const toggleOpen = () => { setIsOpen(!isOpen); };
In the Button, we pass the toggleOpen function into the onClick event
[jsx code]
onClick={toggleOpen}
…the isOpen value into the ariaExpanded prop
[jsx code]
aria-expanded={isOpen}
And add isOpen to the children JSX expression so the children only render in the div if isOpen is true
[jsx code]
<div> {isOpen && children} </div>
Focus management. Let’s set our widget up to listen for ESC key presses and return focus to the button when the widget closes
**Focus management is a nice UX enhancement and is an extended disclosure pattern, so you should test this with your users.
We’ll start by creating a buttonRef using React’s useRef hook, initializing to null
[jsx code]
const buttonRef = useRef(null);
…make an onKeyUpHandler function, listening for ESC key presses while the widget isOpen, And if the widget is open, we’ll set IsOpen to false and send focus to the buttonRef
[jsx code]
const onKeyUpHandler = (e) => { if ((e.key === “Escape” || e.keyCode === 27) && isOpen) { setIsOpen(false); buttonRef.current.focus(); } };
Next, we pass in the onKeyUpHandler function to the onKeyUp synthetic event on the DisclosureWidget’s wrapper div, and
[jsx code]
return ( <div onKeyUp={onKeyUpHandler} className=”dwWrapper”> <Button aria-controls={ariaControls} aria-expanded={ariaExpanded} aria-label={ariaLabel} id={buttonId} buttonRef={buttonRef} buttonClasses={buttonClassNames} icon={buttonIcon} iconOnlyBtn={iconOnlyBtn} onClick={toggleOpen} size={buttonSize} > {buttonText} </Button> <div> {isOpen && children} </div>
Pass in the buttonRef to the Button’s buttonRef prop (say that three times fast) Your Widget will now close on ESC keypress and return focus to the Button
This is the extended disclosure pattern. You should test with users
[jsx code]
buttonRef={buttonRef}
CSS focus states. Now that we have focus management done, let’s get our CSS focus states normalized
Since browsers don’t give a consistent look for focus states, we should make it clearly visible for our users when our interactive controls receive focus.
Let’s add some default styling for our :focus pseudo selector throughout our app, and pick a color with at least a 3:1 contrast ratio or greater.
[css code]
*:focus { outline: 0; outline-offset: var(—s-5); box-shadow: 0 0 0 var(—s-5) var(—purple-orchid); }
We can always override focus styles in our individual CSS files to customize them even more, yet it’s always important to show them.
[css code]
.button { font-weight: var(—font-weight-bold); border: 0; border-radius: var(—border-radius); cursor: pointer; display: inline-block; line-height: 1; transition: background-color 0.2s ease;
:hover { background-color: var(—color-primary); border: 1px solid var(—color-primary); }
:focus { outline: 0.1em solid var(—color-primary-reverse); outline-offset: -2px; box-shadow: 0 0 0 0.2rem var(—color-focus); }
:active { outline: 0.1em solid var(—color-aquamarine-500); }
Mouse click management. If you have many widgets on the page, you’ll only want to have one widget open at a time, so let’s set up a handler to make that happen
Like our buttonRef, we’ll create a contentRef with useRef, initializing to null
[jsx code]
const contentRef = useRef(null);
Like our buttonRef, we’ll create a contentRef with useRef, initializing to null
[jsx code]
const contentRef = useRef(null);
Create an onClickOutside event Handler function. This will check if the buttonRef or contentRef contains the event target, keep the widget open, otherwise, set IsOpen to false to close the widget
[jsx code]
const clickOutsideHandler = (e) => { if ( contentRef.current.contains(e.target) || buttonRef.current.contains(e.target) ) { return; } setIsOpen(false); };
Now that we have that clickOutsideHandler set up, we can user React’s useEffect hook and some if statements For example, If isOpen is true, we’ll add some document.addEventListener functions for mouseup and keyup and call the clickOutsideHandler for each.
[jsx code]
if (isOpen) { document.addEventListener(“mouseup”, clickOutsideHandler); document.addEventListener(“keyup”, clickOutsideHandler); }
If isOpen is false, we’ll remove those event listeners.
[jsx code]
} else { document.removeEventListener(“mouseup”, clickOutsideHandler); document.removeEventListener(“keyup”, clickOutsideHandler); };
We’ll also do a cleanup function to remove any stray event listeners from running
[jsx code]
return () => { document.removeEventListener(“mouseup”, clickOutsideHandler); document.removeEventListener(“keyup”, clickOutsideHandler); };
Lastly, we’ll pass in isOpen as the second array argument in our hook to be sure useEffect only runs if the isOpen state changes value
[jsx code]
[isOpen]
Now we can start using this pattern to making many pretty masks… so let’s make a toggle tip.
One important thing to note. A tooltip is NOT a toggle tip, the interactions are different.
A tooltip’s interactivity revolves around hovering over the tool tip and maybe focusing on it with a keyboard.
Toggletips contain interactive content,are supported by touch devices, non-mouse pointers, and eye trackers, where tooltips are not
But technically, what we’ve already built, will support what we need with a little styling, and I know you’re going to go back to your work and do something like this instead
Mmm hmm. OK y’all. Fine! We’ll make a Toggle tip with an icon-only version.
But let’s talk about icons for a minute
Icons can be informative or decorative
Informative icons need to be paired with descriptive text to be perceivable by screen readers.
Decorative icons need to be hidden from screen readers, because they don’t add significant value to your app
Since we want to support icons in our Button component, we’ll add in a new component to the mix
The FontAwesomeIcon React component. What I like about the ReactFontAwesome icon under the hood, it uses an SVG. Their team preps their SVG in a way where they set it to be focusable=false so they hide it as a decorative icon already. So it’s up to you to use the ARIA labels/everything else to make it informative, if you want. It’s a nice way to use a decorative icon, then pair it with children into a span and use CSS for positioning. We’ll gate them behind the icon prop to render them only when we need them.
[jsx code]
{icon && ( <FontAwesomeIcon icon={icon} className={iconOnlyBtn ? iconBtnClasses : iconClasses} size={size !== ButtonSizes.small ? “lg” : “sm”} /> )}
We can pair an icon with visible button text
[jsx code]
<Button icon={buttonIcon}> {buttonText} </Button>
And since we added that aria-label support in earlier, we can pair an icon with an aria-label here and support screen readers
[jsx code]
<Button aria-label={buttonAriaLabel} icon={buttonIcon} iconOnlyBtn={true}
{buttonText} </Button>
And we have a way to add extra CSS to override Button styles in icon-only scenarios
[jsx code]
<Button iconOnlyBtnClasses={styles.btnIcon} > {buttonText} </Button>
Now that we have the button adjusted, we can use our DisclosureWidget and build our ToggleTip
[jsx code]
export default function ToggleTip() { return ( <DisclosureWidget aria-label=“Fruit trivia” buttonClasses={styles.toggleTipButton)} buttonIcon=”apple-alt” iconOnlyBtnClasses={styles.btnIcon} iconOnlyBtn={true} > <div className={styles.floatingContainer)}> <p className={styles.toggleTipContainer}> Hungry for more interesting fruit facts? View a{” “} <a href=”https://google.com”>full list of fruit trivia</a> in at our virtual farm stand. </p> </div> </DisclosureWidget> ); }
First we’ll pass in the buttonIcon, set iconOnlyBtn to true and pass in an aria-label
[jsx code]
<Button aria-label={buttonAriaLabel} icon={buttonIcon} iconOnlyBtn={true}
{buttonText} </Button>
export default function ToggleTip() { return ( <DisclosureWidget aria-label=“Fruit trivia” buttonClasses={styles.toggleTipButton)} buttonIcon=”apple-alt” iconOnlyBtnClasses={styles.btnIcon} iconOnlyBtn={true} > <div className={styles.floatingContainer)}> <p className={styles.toggleTipContainer}> Hungry for more interesting fruit facts? View a{” “} <a href=”https://google.com”>full list of fruit trivia</a> in at our virtual farm stand. </p> </div> </DisclosureWidget> ); } Then, we’ll add some styling to the button and the icon
Then, we’ll pass in a div with a paragraph and a link to our widget.
[jsx code]
<div className={styles.floatingContainer)}> <p className={styles.toggleTipContainer}> Hungry for more interesting fruit facts? View a{” “} <a href=”https://google.com”>full list of fruit trivia</a> in at our virtual farm stand. </p> </div>
Boom. ToggleTip
Let’s make a Disclosure with an embedded search form
First…
[jsx code]
export default function ToggleSearch() { return ( <DisclosureWidget buttonClasses={clsx(styles.searchMenuButton)} buttonText=”Find a fruit” buttonIcon=”search” > <form onSubmit={(e) => e.preventDefault()} > <Input label=”Search” name=”value” type=”search” /> <Button>Go</Button> </form> </DisclosureWidget> ); }
We’ll pass in some buttonText and an icon to our disclosureWidget button For the purposes of this prototype, we’ll pass in a form and prevent the default onSubmit action
[jsx code]
aria-label=“Fruit trivia”
buttonIcon=”apple-alt”
iconOnlyBtn={true}
Add an Input component with a label, name attribute and a input type of search, and a Button component. We don’t need to specify a submit type for the button, since it’s embedded in a form and we get that attribute for free.
[jsx code]
buttonClasses={styles.toggleTipButton)}
iconOnlyBtnClasses={styles.btnIcon}
An embedded search widget is the perfect use case for some enhanced UX… like targeted focus management.
In other words, when we open the widget, we’ll send focus right to the search input.
To do that, we’ll use the useRef hook to create the DOM reference to our input, create a variable called firstItemRef, and assign useRef to null
[jsx code]
const firstItemRef = useRef(null);
We’ll pass firstItemRef into the DisclosureWidget prop …and our Input component’s inputRef prop
[jsx code]
<DisclosureWidget firstItemRef={firstItemRef} buttonClasses={clsx(styles.searchMenuButton)} buttonText=”Find a fruit” buttonIcon=”search”
<form onSubmit={(e) => e.preventDefault()} > <Input inputRef={firstItemRef} label=”Search” name=”value” type=”search” /> <Button>Go</Button> </form> </DisclosureWidget>
In our DisclosureWidget useEffect’s first if statement, we’ll add a nested if statement checking if the firstItemRef is defined,
And if so, send focus to that firstItemref
We’ll also pass in firstItemRef as second argument to the useEffect function array to prevent component re-renders
[jsx code]
if (firstItemRef) { firstItemRef.current.focus(); }
And now we have an embedded search widget. These are some really great patterns based on the enhanced disclosure widget.
This is where it gets tricky, because this is the point where things get tempting for a developer.
What if your designer comes up with this hamburger navigation pattern? Hmm. Looks like a good case for a disclosure pattern, right?
Well, if it’s navigation, those items should look like links not buttons, so we should adjust them…
…to have underlines and less of a button-y look to communicate intent. Because cognitive accessibility is important too. Now let’s get back to the building it.
Let’s add some links in there.
Cool. Let’s add some links into our disclosure widget now. We’ll find a quick way of doing this, like, passing an unordered list.
And mapping those links. Yeah, this is cool. We could just… map in some links.
And hey! We can have a widget with a hamburger menu, and make this toggle menu links just to have a quick thing without even making it a new component. That could be fun.
[jsx code]
export default function ToggleMenuLinks() { return ( <DisclosureWidget aria-label=”fruit choices” buttonClasses={clsx(styles.disclosureButton, styles.chooseFruitButton)} buttonIcon=”bars” iconBtnClasses={clsx(styles.btnIcon)} iconOnlyBtn={true} > <ul className={clsx(styles.floatingContainer, styles.disclosureMenuList)}> {items.map((item, i) => { return ( <li className={styles.disclosureMenuListItem} key={i}> <a href={item.link}>{item.title}</a> </li> ); })} </ul> </DisclosureWidget> ); }
How about buttons?
We could pop in buttons in this list as well… What else could we do with this?
[jsx code]
export default function ToggleMenuButtons() { return ( <DisclosureWidget aria-label=”fruit choices” buttonClasses={clsx(styles.disclosureButton, styles.chooseFruitButton)} buttonIcon=”bars” iconBtnClasses={clsx(styles.btnIcon)} iconOnlyBtn={true} > <ul className={clsx(styles.floatingContainer, styles.disclosureMenuList)}> {items.map((item, i) => { return ( <li className={styles.disclosureMenuListItem} key={i} <Button>{item.title}</Button> </li> ); })} </ul> </DisclosureWidget> ); }
How about roving focus?
We could add up and down arrow key support and optional home and end key support, because you see some of those patterns.
You see that on components sometimes and even on the WAI site, so that’s nice. We’ll add that to our component. That’ll be fun.
Oh wait!
We’re doing a list, but inside this list… how about — instead of passing in a link or button — let’s like make this funky Tag component.
And then, we can pass in whatever element we want into the tag prop, and the component will render that element.
We could pass in an “a” and render a link.
Pass in a “button” and render a button.
Pass in an “input” and render an input.
This could be really cool. This could be really powerful!
[jsx code]
return ( <li> <Tag {…props} onClick={handleSelect} onKeyPress={handleSelect} ref={ref} tabIndex={focus ? 0 : -1} > {character} </Tag> </li> );
Check out my fancy list, separation of concerns, baby.
And while we’re here, we can start working on some separation of concerns.
So now that we have this fancy Tag component, we can make a list item. We can make a list, have this roving focus, and start building this pattern.
Oh, this is getting fun. Now the component’s getting kind of big.
[jsx code]
import React from “react”; import clsx from “clsx”; import ListItem from “./ListItem”; import useRoveFocus from “./utils/useRoveFocus”; import masks from “./data/masks”; styles from “./css/DisclosureWidget.module.css”;
const List = () => { const [focus, setFocus] = useRoveFocus(masks.length); return ( <ul aria-labelledby=”menubutton” className={clsx(styles.floatingContainer, styles.disclosureMenuList)} > {masks.map((mask, index) => ( <ListItem key={mask} setFocus={setFocus} index={index} focus={focus === index} mask={mask} tag=”a” /> ))} </ul> ); }; export default List;
Some Ternary magic? …Hey now. Maybe some ternary magic? Hey now…
Oh! And then… in our uber disclosure widget… we could have our enhanced widget, but then if it’s a list, we could pass it a list prop, …and we could render a List, …and we’d have ListItems where we could pass in a tag prop. …and render whatever element we want.
What could go wrong?
[jsx code]
{isOpen && isList ? ( <div ref={contentRef} id=”dwContainer”> <List /> </div> ) : ( <div className={styles.dwContainer} ref={contentRef} id=”dwContainer”> {isOpen && children} </div> )}
Maybe this is a bad idea.
Because at this point, what pattern is this? Now we’re starting to dip into different patterns. We went from a Disclosure pattern…
…into a Menu and Menubar pattern.
…and the menubar pattern has menuitem roles, and menuitem checkbox, and menuitem radio roles, and all these different states that are needed for unordered lists and their respective children.
A hamburger navigation, however, is technically part of the disclosure widget implementation.
Therefore, in a disclosure navigation pattern, no ARIA menu roles should be added to any unordered lists in a component implementation.
Because it’s a different use case. This is where devs incorrectly mix WAI patterns.
But when you start thinking about those mega menus at the top of a nav that have those fly outs that go to the right that’s simulating those desktop menus like Electron or anything else.
That’s what those mega menus are trying to simulate, with nav and the checkboxes and the radios.
That is what a mega menu pattern is, and there’s this confusion when a designer comes in with a pattern. They see this beautiful pattern, and they don’t understand the logic behind these two patterns that are being coded versus what you see in a design.
And then it gets mixed into your disclosure widget, and it doesn’t get documented.
And then you get this mega component.
And then people start using it.
And then you get into accessibility audit.
And then there’s this mess.
And so you have these components with this pattern.
That mix one pattern.
With another pattern.
Whoa, Nellie… Even though the one pattern can have many uses, it’s important to keep your pattern uses separate.
And you begin to make unwise decisions… like creating dishes with jello and shellfish. And things can go wrong very quickly.
SO… You shouldn’t be mixing your masks. And breaking the rules of ARIA.
You should be separating your components out into their purposeful intents.
You may think that your magical mask will give you access to that very exclusive Carnival masquerade, but instead you may end up at a completely different Carnival…
Like this… and then things can go wrong very quickly.
And then it can go even more wrong and…oh god. And here comes the carousel.
I do have to say, though, the Open UI W3C Community group is working on a solution for native components for this. Una Kravets will touch upon this briefly in her talk tomorrow.
I am very happy a solution is coming. So definitely check out her talk tomorrow.
Avoid chaotic carnivals like this one. The Viareggio Carnival with some extremely large floats in Italy.
…and a completely different experience than you wanted. Don’t mix your masks.
So to wrap up…
Design Systems are a Carnival!
Our users are diverse
Don’t mix your masks
Or you’ll make bad choices
Or you may end up at a completely different Carnival…
…with a completely different experience than you wanted.
And Design Systems are always the hotness.
Slide deck posted after the talk
@resource11 Twitter | Instagram | GitHub
