React components Accessibility-flavored make your design system delicious

Kathleen McMahon @resource11

Welcome everyone! I’m Kathleen McMahon and I’m here today to show how Accessibility-flavored React components make your design system delicious!

Before we begin, let’s get some details out of the way.

Since time is compressed, and I’d love to talk at a reasonable pace for our live captioner….

My slide deck will be posted on Notist at https://noti.st/resource11/1ecxhG, including links to resources I briefly touch upon.

The full URL will be available later today on Twitter.

And here are my social links.

You can follow me at:
@resource11 Twitter | Instagram | GitHub

Now… here’s an outline of what we’ll be covering today.

Good grief, there’s an agenda…

Topics covered • Why accessibility first? • Design systems are a cookbook. • Design systems and React • Icons, Buttons, Inputs • Documentation

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

I’m the Tech Lead for O’Reilly Media’s Design System

And I race bikes… very badly.

Mostly, you’ll find me at the back of the pack

Racing 2 laps to your 6 on a singlespeed…

Wearing a costume!

Because who doesn’t love a clown?

Well maybe not this clown

One thing I almost forgot to mention…

I’m a dev dinosaur. And I find it fascinating see…

…how far we’ve come from the tools we had for computing…

And software…

And software.

Storage…

…and reference.

[alt] Collection of 1990s era software design and development books stacked on the floor.

While our browser choices were minimal… Netscape, anyone?

…our stack has stood the test of time. HTML + CSS + JS

Fast forward to now and the industry is moving at a really fast pace…

…and it can feel overwhelming to keep up, much less find the place where you can thrive if you have both design and engineering skills, and love that fundamental stack.

Imagine my excitement when I joined O’Reilly, and discovered we had a design system, and we were just starting work on streamlining the codebase in our component library.

My inner dinosaur literally did a backflip.

Now this was a place where that trusty stack is needed.

Especially an industry where the div has become the reluctant king.

Admittedly, this was my first time working on an official design systems team, so there was a bit of a learning curve of what goes into a design system

And our team is small.

We had the benefit of two contractors pitching in for the first few months, but in essence, our core team has mostly been about 3-4 people.

We’ve had to choose what to tackle first in our reboot, which is tough with so many moving parts.

Our first priority?

Extracting out any business logic in the components, while at the same time building with accessibility in mind.

Fix our colors, our components, our patterns, reboot our docs, and improve our tooling.

You may ask, why accessibility first?

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…

…Unlabeled inputs

…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

And 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…

And look past the outdated views…

You’ll find interesting recipes…

Questionable food combinations that included Jello and meat…

…and an impressive level of detail paid to the structure of every single part of the cooking process.

…and an impressive level of detail paid to the structure of every single part of the cooking process.

…and an impressive level of detail paid to the structure of every single part of the cooking process.

…and an impressive level of detail paid to the structure of every single part of the cooking process.

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.

Your components are your tried and true recipes

And WCAG is your reference material

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)

Follow the directions

And provide helpful hints as best practices.

Let’s take those principles and apply them to some components.

Let’s talk Icons.

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 to be announced.

There is more than one way to create an accessible icon.

Two of the most recent ways are… SVGs and icon fonts.

We initially used SVG icons in our design system combined into a sprite sheet, yet we ran into some problems when we started testing.

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.

Icon fonts to the rescue

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.

The span containing our icon font…

…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 aria-hidden “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.

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, which is the most important pattern.

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.

This way, 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 in DOM if the value exists.

aria-hidden is one of those.

Buttons.

Buttons perform an action on the page…

…should look and act like a button…

…and 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 “Read more…” buttons.

This way, a user that’s scanning all the links at once on the page with a screen reader will be able to know . they’re reading more about dinosaurs.

There is a caveat here…

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 resource will be shared in Notist later for those interested.

This is an accessible button in JSX.

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

We wrap button contents in a span for positioning.

Note: we’re using inline level elements only inside buttons.

This is because you can only pass in inline content as button children. A div is not inline, it’s a block level element and renders implicitly as a p element in the DOM. P is a block level element.

You also shouldn’t nest buttons or other controls like links 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.

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.

They’re hard to style across browsers, and placeholders aren’t auto translated.

Be kind to your screen magnification users, and don’t force them to scroll horizontally to read your content.

Make sure your inputs are no wider than 80 characters.

Keep labels and error messages stacked vertically in close proximity

Labels above input, errors below input, so users that are using Picture-in-picture screen zoom feature have all the information in a small window of space, so they’re not hunting around for the purpose of an input, and steps to correct an error if something needs fixing.

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 text to announce any errors for 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.

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.

Since we’re still exploring how to scale our system, our docs use Gatsby for our style guide and Storybook to document our components. We host static instances of these sites on Now.

I want to touch upon Storybook for a moment.

Storybook is a great way to Sandbox your components in isolation.

You can play with UI logic without the complexities of business logic.

The accessibility add-on is a must.

That add-on uses Deque’s axe-core engine, and does the heavy lifting for you, by performing quick audits on your components and testing then against WCAG success criteria.

The add-on is great because it Identifies errors, tells you how serious they are, and gives you steps to fix them before you continue doing your manual testing.

Add helpful hints to help developers choose how to implement your components.

For example, how to give use an informative icon.

Or a implement a decorative icon.

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

Component dos and don’ts are essential.

Also, 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.

So to wrap up…

Our users are diverse.

Your design system is a cookbook.

Cookbooks have personality.

React is a kitchen utensil.

You are the cook.

Components are your tried and true recipes.

WCAG is your reference material.

…and Document, document, document.

And remember…

Dinosaurs are always the hotness.

Thank you.

https://noti.st/resource11/1ecxhG

Slide deck posted after the talk.

@resource11 Twitter | Instagram | GitHub