Accessibility-flavored React components make your design system delicious!

A presentation at Indigo Ag Lunch & Learn by Kathleen McMahon

My slide deck will be posted on Notist, that’s https://noti.st/resource11, including links to resources I briefly touch upon. The full URL will be available later today on Twitter.

You can follow me at. Resource11 on Twitter, Instagram, and GitHub.
Now… here’s an outline of what we’ll be covering today.

Why accessibility first? Design systems are a cookbook. Design systems and React Icons, Buttons, Inputs, Disclosure Widgets Documentation

Let’s back up so I can introduce myself better…

[image] Me on a cyclocross bike, hopping over barriers and riding through mud.
And… I race bikes. Very badly.

[image] Me on a cyclocross bike, in Spam, Ninja Turtle, Nerds candy box, Medusa costumes
Mostly you’ll see me in costume, racing two laps to your six, at the back of the pack, on a singlespeed.
Mostly. Unless something happens.

[image] Big Bird kicks open the apartment door
Like… a pandemic kicking in our doors. Then your racing season is postponed.

[image] Pictures of me on a cyclocross bike, in costume
So while I’m an engineer, and a super slow bike racer…

[image] A group of dinousaurs grazing, lift their heads up in unison
I’m also a dev dinosaur. And I find it fascinating see…

[image] Amiga computer from the 1990s
…how far we’ve come from the tools we had for computing…

[image] Photoshop 3 user interface
And software…

[image] Macromind director user interface
And software…

[image] box of older storage tech, including 3.5" floppy disks, Zip disks, Bernoulli disks, SyQuest disks
Storage…

[image] Arrangement of all my software reference books from the 1990s through early 2000s
…and reference.

[image] Netscape logo

…our stack has stood the test of time. HTML, CSS, and JavaScript

JavaScript Framework of the week
Fast forward to now and the industry is moving at a really fast pace…

[image] Stanley Spadowski shouts "OPEN WIDE!" and douses boy with a fire hose
…and it can feel overwhelming to keep up, much less find the place where you can thrive.
Especially if you have both design and engineering skills, and love that fundamental stack.
But fear not!

[image] Person in inflatable dinosaur costume flips into a raft floating on a pond and claps with glee
Dinosaurs are always the hotness.
Those old-school HTML/CSS/JavaScript skills are highly valuable and transferrable — no matter which framework you use — and they will give you an edge in the industry where the div has become the reluctant king.

So before working at CarGurus, I was the Tech Lead for O’Reilly Media’s design system.
I learned a lot about streamlining component libraries during my time there.

If you’ve ever worked on a design system, you know there are a lot of things to consider.

And great design systems combine two key factors: user experience, and END user experience.

[image] woman attempting to arrange 10 squirming kittens in a straight line, with varied success
However. Similar to herding cats, creating a great design system can be tough with so many moving parts.
If you are rebooting a design system, will have to choose what to tackle first.
If your design system team is small, you have to be very strategic. For example…

If any business logic in the components, your first priority should be to extract that out, and build with accessibility in mind.
Fix your colors, your components, then reboot your docs.

Well, our users have varied needs, and… because so often, that’s what is handled last.
Which sends a poor message to our users.

If you’ve read the WebAIM Million report, the results are depressing

With the amount of errors found on pages…

…and unnecessary ARIA attributes, we’re making the web worse in the name of good intentions.

While we have things like the Web Content Accessibility Guidelines to follow which is a really low bar, we’ve been missing the mark in the industry when it comes to making sure all our users can use our apps.

Imagine, though, if you had accessibility baked into some commonly-used components.
A design system is the perfect place for this.

I like to say your design system is a cookbook

Cookbooks have personality.
My Mom is a serious fan of cooking, and lately I’ve been enjoying digging through the cookbooks she’s collected over the years to read how recipes evolved over time.
If you take a look at some of the cookbooks published in the 1940s-60s…

[image] Betty Crocker cookbook from the mid 20th century, "Why nearly 9 million women cherish this cookbook" prominently featured as a callout
And look past the outdated views…

[image] Betty Crocker cookbook from the mid 20th century displaying various dishes
You’ll find interesting recipes…

[image] Shrimp and lime jello mold, plated with apple slices
Questionable food combinations that included Jello and shellfish.

[image] Meats and poultry cookbook reference page
…and an impressive level of detail paid to the structure of every single part of the cooking process.

[image] Soups and sauces reference page
…and an impressive level of detail paid to the structure of every single part of the cooking process.

[image] Vegetables reference page
…and an impressive level of detail paid to the structure of every single part of the cooking process.

[image] Desserts reference page
…and an impressive level of detail paid to the structure of every single part of the cooking process.

[image] Table settings and enertaining reference page
There’s even a section on table settings and entertaining!
This is very similar to how a design system works.

Now what does that have to do with React?

There’s always some debate about how using a Javascript framework creates inaccessible apps

Yet… React fully supports building accessible websites, by using standard HTML/CSS techniques.

A better way to think of React is to consider it a kitchen utensil. It’s not the only utensil in your kitchen.

You are the cook
In my opinion, It’s up to the developer to have that standard HTML/CSS/JavaScript and accessibility knowledge to be able to leverage a utensil correctly.
And that includes React.

That said, if your developers are unsure how to start building inclusive apps,
Empower with your design system.
Build some features into your components to help them along.

Then you can start celebrating when your co-workers make those apps accessible without you having to ask for it

Components are your tried and true recipes

And creating a component is like following a recipe

First, you Start with high-quality ingredients (semantic HMTL)

Mix in seasonings (just a touch of ARIA)

And provide helpful hints as best practices
Let’s take those principles and apply them to some components…

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

But wait! Icons can be interpreted in so many different ways!
  True.

For example, you may see the heart symbol used to favorite something in an app

Other apps may use a star. This leaves way too much up to interpretation by the user.

Ideally, you should be pairing any icons you use with visible text.

This way, users will have a clear context on its purpose.
Of course, there is a big BUT in here, and depends on the buy in you get for icon usage in your designs. And whether you can get a design approved that uses a label paired with an icon like this.
That said, in general terms…

There is more than one way to create an accessible icon. Two of the most recent ways are… SVGs and icon fonts.
At O’Reilly, we initially used SVG icons in our design system combined into a sprite sheet, yet we ran into some problems when we started testing.

[image] Natalie Portman, weeping in the corner
We discovered a bug in Safari on High Sierra, where VoiceOver would announce every single one of those 100 or so icons in that sprite sheet.
It made me sad. So…we had to think fast to find a different solution.

We converted all our icons into a font set for the time being, and chose to revisit SVG icons later, since that HighSierra bug has now been fixed.
Let’s go over an example of how we make an accessible icon component using semantic HTML and the icon font technique.

This is what you typically see as an icon font pattern in the wild, but it’s not accessible.

This is an accessible icon pattern. Let’s break it down.

Has been sprinkled with a pinch of aria-hidden=”true”, to hide the icon font from screen readers

This second span contains the descriptive name for our icon

And has a visuallyHidden class added to it. This removes the visual presentation of that text, yet keeps that text available to screen readers.

In the wrapping span, we use a CSS class to convert the span’s native display property from inline to inline-block.
This allows us to support margin/padding customization on all four sides of the element

Notice that spans are being used for all three elements. This is on purpose for when we pair this component with a button

Now before we refactor this pattern into React, let’s consider whether this icon is informative or decorative?

If our icon is informative, we keep this markup as is, because informative icons should announce

If our icon is decorative, we’d add this aria-hidden attribute to the wrapping span to ensure the entire group is not announced to a screen reader.

Now that we have an accessible icon pattern, let’s pop this into a functional component and convert this to JSX

Change class to className, convert that “true” string to a boolean value, and self close that empty span element

Now this is a static icon component in JSX.
Let’s make this component more flexible

…and expand that syntax to support three incoming props: iconHidden, iconName, iconTitle and add some guardrails

[image] Moody view of empty bowling lanes
It’s important to create ‘guardrails’ for your components so you can be sure that devs are always using the accessibility features you’ve mixed in.
For our icon component, we added three guardrails.

The first guardrail we’ve set up is a check if the iconName the dev passes in to the component is in our icon library.
If the icon doesn’t exist in the library, the component doesn’t render in the app.

The second guardrail we’ve set here is to ensure if the dev doesn’t pass in descriptive text to that iconTitle prop, the icon’s default name is always exposed a fallback

The last guardrail is the iconHidden prop.
If the dev passes in iconHidden true, the containing span’s will render in the DOM with an aria-hidden=”true” attribute
If no iconHidden prop is passed in, the aria-hidden attribute isn’t attached to the wrapping span at all.

We’re guaranteeing that the icon will read out to screen readers no matter what, unless the dev purposely specifies otherwise by passing in iconHidden value
This true or null pattern works well with HTML attributes that only need to be added if the value exists. aria-hidden is one of those

You may still be saying… what about SVGs? What if I haven’t rolled my own icon set?
There are great options out there to do this with SVGs as well.
Like…

Fontawesome is still a great option for this.

In fact, Fontawesome now has an official React component you can use.

And it has been built with accessibility in mind.

It’s pretty straightforward to use this component…

…and it adds the right properties for you under the hood by default. There is a slight bug if you want to use the component as a standalone informative icon.

Say you want the icon to announce as a beverage in this case…

Because the SVG element already has an aria-hidden attribute attached, that aria label will do nothing here.

However. You can get around this by using the Icon component we built and swapping out that span using the CSS class…

…and swapping in the FontAwesome component

…then you can leverage that visually-hidden span to make your icon informative.

Buttons perform an action on the page
Buttons should look and act like a button
Buttons get screen reader and keyboard functionality for free

Our high quality ingredient here is the button element.

We sprinkle in an aria-label to support instances where we have multiple buttons with the same name on the page to give context to screen reader users. Like those times when you have 10 ‘read more’ buttons on the page. With this label, you know that this button allows you to read more about dinosaurs.

It’s important when using an aria-label like this to match the first words in the aria-label with the button text to support voice recognition software

If your app needs to support localization, Adrian Roselli just wrote a great article with a different pattern that uses the aria-describedby attribute. That article will be shared in the resources later.

If we want to support button text with icons, we mix in our Icon component

And we wrap button contents in a span for positioning
Note: we’re using inline level elements inside buttons
No nesting buttons or other controls inside a button’s children
That’s not valid HTML

The JSX is popped into the Component’s render method, and we add props, onClick handler and disabled button support

The one guardrail we add ensures if no iconName is passed in, no icon will render in the button

Inputs need labels and error messages
Labeled inputs give all users more context

Placeholders are NOT labels
Avoid using placeholders instead of labels, users will lose context
Hard to style across browsers
Placeholders aren’t auto translated

We’ve built our input components to minimize horizontal scrolling, and stack our labels above the input, error messages below the input to support screen magnification users.
You can also place the error message right below the label for even better discoverability

This is an accessible input pattern. It’s a bit hard to read so let’s zoom in.

We start with our high-quality ingredients

Pairing labels and error messages to the input

And in JSX we associate the label with the input by pairing the label’s htmlFor prop value with the input id value

Mix in key ARIA spices for validation
Aria-invalid, aria-required, and the pair the aria-describedby and error text id values

We also add an aria-live=“polite” to error message span to announce errors to screen readers

To make this more flexible… mix in disabled attribute support
onChange and OnKeypress synthetic events to capture keyboard actions
Add true/null handling for the boolean props

Add your guardrails. If the dev doesn’t pass in a label, the whole input won’t render. Neither will the icon.
This will help guide the developer to follow best practices when implementing a component, and it will become second nature

Same goes for the error handling, if the developer doesn’t pass in both the invalid prop and the error message prop to the component, it won’t render.

Disclosure widgets. A disclosure widget is an interactive pattern that uses a button to control the visibility of a section of content.

This pattern is great, because it’s flexible, keyboard/mouse operable, and its base functionality is very similar for more than one type of interactive component.

Some common patterns are nav menus, toggle tips, and settings disclosures.
Others types of widget patterns are custom select menus and autocompletes.
We won’t be talking about those today because — in addition to enter/spacebar/escape keys — these two patterns also need up/down arrow keys and the home/end key support.

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.

This can be problematic for any sort of touch device which doesn’t support hover, like a non-mouse pointer or eye tracker.
Also, anyone using a screen magnifier may accidentally dismiss a tooltip by moving their field of view and hovering away.

The three primary interactions we will focus on are the space bar/Enter key — which comes natively when you use a button to open the disclosure — the ESC key, and mouse clicks.

For special cases, like a search menu that toggles into view, you can optionally send focus to the first item in the open container.

Let’s take a look at a disclosure widget pattern in this Codesandbox

Documentation. Those massive design systems out there definitely have some drool-worthy patterns for us to dream about. If your team is small, showing examples of the many ways your component can be used is a good first step.

When we were rebooting the docs, we used Gatsby for our style guide to leverage the power of MDX, and Storybook to document our component playground.

and deployed static instances of our docs using Zeit’s Now…

I want to touch upon Storybook for a moment.
It’s a great way to Sandbox your components in isolation, and play with UI logic without the complexities of business logic.
Supports MDX as well. The Accessibility addon is a must here.

Uses axe-core engine, does a quick audit of your components
Identifies errors, tells you how serious they are, and
Gives you steps to fix them before you start your manual accessibility testing.

When documenting components, you should add helpful hints to help developers choose how to implement your components. For example, how to make an informative icon.

Be sure to add prop tables for your components, so your developers know which prop does what, and whether it’s required.

Dedicate a page to accessibility resources and links. The WCAG success criteria is really intense to parse.
If you have curated any articles that help explain how to implement common accessibility patterns, add those to your docs.

Document, document, document. And remember…

https://noti.st/resource11
Slide deck posted after the talk @resource11 Twitter | Instagram | GitHub

Kathleen McMahon
@resource11

1 / 156

Design Systems are a popular way to bake your product. An often-missing ingredient, however, is accessible UI components. In this talk, you’ll learn the recipe for a delectably inclusive design system by mixing accessibility flavor into some commonly-used React components including icons, buttons, inputs, and disclosure patterns. You’ll also learn how to spice up your design system’s documentation with approachable, accessibility best-practices guidance including interactive examples, and component dos and don’ts. Even if you’ve never seen React before, join me to learn how to make your design system delicious.

Resources

The following resources were mentioned during the presentation or are useful additional information.

Code

The following code examples from the presentation can be tried out live.

https://codesandbox.io/s/disclosure-widget-patterns-resource11-f7bx9?file=/src/App.js

Disclosure Pattern examples

Accessibility-flavored React components make your design system delicious!

[image] Me on a cyclocross bike, hopping over barriers and riding through mud.

[image] Me on a cyclocross bike, in Spam, Ninja Turtle, Nerds candy box, Medusa costumes

[image] Big Bird kicks open the apartment door

[image] Pictures of me on a cyclocross bike, in costume

[image] A group of dinousaurs grazing, lift their heads up in unison

[image] Amiga computer from the 1990s

[image] Photoshop 3 user interface

[image] Macromind director user interface

[image] box of older storage tech, including 3.5" floppy disks, Zip disks, Bernoulli disks, SyQuest disks

[image] Arrangement of all my software reference books from the 1990s through early 2000s

[image] Netscape logo

JavaScript Framework of the week

[image] Stanley Spadowski shouts "OPEN WIDE!" and douses boy with a fire hose

[image] Person in inflatable dinosaur costume flips into a raft floating on a pond and claps with glee

[image] woman attempting to arrange 10 squirming kittens in a straight line, with varied success

[image] Betty Crocker cookbook from the mid 20th century, "Why nearly 9 million women cherish this cookbook" prominently featured as a callout

[image] Betty Crocker cookbook from the mid 20th century displaying various dishes

[image] Shrimp and lime jello mold, plated with apple slices

[image] Meats and poultry cookbook reference page

[image] Soups and sauces reference page

[image] Vegetables reference page

[image] Desserts reference page

[image] Table settings and enertaining reference page

[image] Natalie Portman, weeping in the corner

[image] Moody view of empty bowling lanes

[image] Person in inflatable dinosaur costume flips into a raft floating on a pond and claps with glee

Link for this presentation:

HTML code for embedding:

Share on social media:

Disclosure Pattern examples