A presentation at Clarity Conference 2023 in in San Francisco, CA, 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, it’s the Where’s Waldo of the ocean!
Lover of my cats Thor
…and Otis.
I’m a Crystal collector
And I photograph them, but Otis…
…interferes often
…with opinions…
…about my attention. Thanks, Otis
And now Thor does the same…
He’s very satisfied with himself.
Who could resist them, though?
I’ve worked on a few design systems like…
O’Reilly Media
LaunchDarkly
Northwestern Mutual
And I love design systems; it’s exciting! Especially if you like…
…herding kittens. Always fun, with 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…
There’s the Moretta…
The Gagna…
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 about Accessibility.
Our users have different needs at different times
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 home pages. And I’m going to focus on the amount of ARIA present on the homepage.
There has been up to a 29% increase in the past year, and the amount of ARIA attributes has nearly quadrupled since 2019.
There has been up to a 29% increase in the past year, and the amount of ARIA attributes has nearly quadrupled since 2019.
There has been up to a 29% increase in the past year, and the amount of ARIA attributes has nearly quadrupled since 2019.
There has been up to a 29% increase in the past year, and the amount of ARIA attributes has nearly quadrupled since 2019.
There has been up to a 29% increase in the past year, and the amount of ARIA attributes has nearly quadrupled since 2019.
And there are 68% more detected errors on home pages with ARIA present than those without. 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.
Like the Disclosure widget, if built correctly, it can have a few uses in your design system.
This pattern can be used for popups, toggleTips, and toggleSearches.
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 share code examples and resources at the end of my talk so you can dig in.
And you can also listen to Homer’s talk later today to learn more.
The anatomy of a disclosure widget is…
A button that opens and closes a container then 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 JSX button because when this code is rendered…
…you natively get an HTML button, and an HTML button under the hood gives us:
mouse clicks, enter keypress, and spacebar keypress support for free.
Now it’s time for ARIA support. And…we’ll add just enough ARIA attributes to let screen readers know when the container is being opened and closed — or 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>If you want to take it further, you can add UX enhancements like targeted Focus management.
Meaning, we’ll set our widget up to listen for ESC key presses and return focus to the button when the widget closes
**You should test this with your assistive technology 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 make many pretty masks… like, for example…
Toggletips
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 tooltip 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 built will support what we need with a little styling, and I know you’ll 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>
Then, we’ll add some styling to the button and the icon
[jsx code]
<DisclosureWidget buttonClasses={styles.toggleTipButton)} iconOnlyBtnClasses={styles.btnIcon} </DisclosureWidget>
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 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. Let’s get back to 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> ); }
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]
<li className={styles.disclosureMenuListItem} key={i}> <a href={item.link}>{item.title}</a> </li>How about buttons?
We could pop in buttons in this list as well…
What else could we do with this?
[jsx code]
<li className={styles.disclosureMenuListItem} key={i}> <Button>{item.title}</Button> </li>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 kind of nice.
We could add up and down arrow key support We’ll add that to our component. That’ll be fun.
[jsx code]
const handleKeyDown = useCallback( (e) => { if (e.keyCode === 40) { // Down arrow e.preventDefault(); setCurrentFocus(currentFocus === length - 1 ? 0 : currentFocus + 1); } else if (e.keyCode === 38) { // Up arrow e.preventDefault(); setCurrentFocus(currentFocus === 0 ? length - 1 : currentFocus - 1); } }, [length, currentFocus, setCurrentFocus]
Oh wait.
We’re doing a list, but inside this list… how about — instead of passing in a link or button — let’s make this funky Tag component.
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] //don’t do this, yo
const Tag = ${tag};
role=”menuitem”
tabIndex={focus ? 0 : -1}
Check out my fancy list, separation of concerns, baby
And while we’re here we can start working on like some separation of concerns.
So then we can like okay, now that we have like this fancy Tag component, we can make a list item.
Now we can make a list and we have this roving focus and we can start building this pattern.
Oh this is getting fun. Now the component’s getting kind of big.
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 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 needs menuitem roles, menuitem checkbox, and menuitem radio roles, and all these different states are needed for unordered lists and their children to support assistive technologies.
A hamburger navigation, however, is the disclosure navigation menu pattern and a different use case, so ARIA is not needed. Yes, you could optionally add arrow and home/end key functionality, but it’s optional.
This is a common place where devs can start incorrectly mixing WAI patterns.
https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/
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, those patterns are simulating desktop menus or Native Electron app behavior with all the checkboxes and the radios in the dropdowns.
That is what a mega menu pattern is, and there’s this confusion between when a designer presents this beautiful pattern, and they don’t understand the logic behind the 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 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.
I am very happy a solution is coming.
Avoid chaotic carnivals like this one. The Viareggio Carnival with some extremely large floats in Italy.
http://www.grandvoyageitaly.com/travel/instead-of-heading-to-venice-try-the-viareggio-carnival
…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
Design System components are like guests at a Venetian Carnival, enjoying the festivities. One guest in particular — the disclosure widget — is known for wearing three distinct masks and elevates a Carnival into the most exclusive Masquerade Ball. Or… is it? What kind of Carnival are you attending if those masks get mixed? In this talk, you’ll learn the secret to creating a reusable — and accessible — component that can masquerade as many, and give your component library access to the most exclusive of Carnival attractions.
The following resources were mentioned during the presentation or are useful additional information.
The report on the accessibility of the top 1,000,000 home pages from 2019 through 2023
A Javascript-free popover demo using the Open Ui Popover API, created by Una Kravets
The following code examples from the presentation can be tried out live.
Here’s what was said about this presentation on social media.
![Don’t mix the masks. [image]: Red squirrel with one paw outstretched in a "please stop!" gesture](https://on.notist.cloud/slides/deck11725/large-144.jpg)
