Case Study: Building Accessible Reusable React Components at GitHub

Hey, I'm Sid, and I work on the design systems team at GitHub. I want to talk to you about something we do in Primer, and most of the code I talk about today is open source. You can actually find it on GitHub.com slash Primer slash React.

Let's talk about building accessible React components with a focus on screen readers. So, fair warning first. I'm not an accessibility expert. I'm just a silly React boy. But over the last one and a half years, I have worked with a lot of accessibility experts, and maybe this perspective of coming from a React developer instead of an accessibility engineer, maybe that's just a better or an easier introduction, a more accessible introduction, if you might, for an introduction to accessibility.

So, things you need for an accessible experience, if you ask Twitter, you get this advice, which is just don't use a div, use a button, and that's kind of it. It usually is accompanied by a purple background with some code screenshot. So, that's the first step, I guess. Use the correct HTML element, and that's it. But, of course, there's so much more that goes into it. And I slightly, even though this advice is correct, that use the right HTML element, I find it a bit annoying because it's very reductive to all the work that accessibility engineers do.

So, for example, this is a UI you may or may not have seen on GitHub. If you press the code button in the repository, you get these three options. And it's kind of nice. There are these three tabs that you can toggle through. And each of them have their own options. There's a panel underneath. We've seen this pattern so many times, right? And we know that these are tabs and these are clickable because you see this tiny hill on the first one. And the first one is darker. It has a border. So, we know that this is the selected one. But there's nothing on the page that says it's just a design pattern that we have seen so often that it kind of becomes an established thing. And to make these tabs, I use buttons because I'm a professional. And, yeah, so this is how it works. Using some React to wire it up. And that's kind of what it is. So, let's see what somebody who is visually impaired and uses the screen reader to access this website.

What do they see? So, I'm going to enable the screen reader and walk you through what happens. VoiceOver on application. React app.

So, whenever you turn on the screen reader, it first sets the context. It tells you where you are. In this case, I'm on the React app. My app is called React app. And it tells you where the focus is. Code. Menu popup. Button. Has keyboard focus.

So, I know a button with a label code has focus. And I also know that it has a menu popup, which means I can press the enter key and it should open the popup and then I can navigate inside it with my tab key. Local button. Coda spaces. Button. Copilot. Button. Copy URL to clipboard. Button. HTTPS. GitHub. Open with GitHub desktop. Button. Download zip. Button. Local. Button. Something interesting happens here.

What I heard here, if I can't see the UI, what I'm hearing is button, button, button, button. Very long input. Button, button. And then you go back to the first button.

There was no mention of a tab here. Like, which one of these are tabs? And it's because screen readers cannot really look at your visual implementation, visual design, and infer things like these are tabs.

And so, if you don't provide that information, a screen reader wouldn't really get to know that they can switch the first three buttons, they can switch between them. And so, how do we... We probably did something wrong here, right? Because the button element, maybe we didn't use the right element. Maybe we should use the tabs element. But of course, there is no tabs element. That doesn't exist on the web, at least yet. So, we still just have these divs and buttons.

And this is where the ARIA spec comes in. ARIA stands for Accessible Rich Internet Application. It's a spec. It's an interesting read. And something that the ARIA spec has are roles. So, ARIA provides us with a list. It's a fixed list of roles that conveys the semantics of structure. So, for example, layout, the appearance, how the content is structured, like headings, lists, tables, tabs. These are provided by roles. And one of the roles is tab list. So, this is what we need here.

How you can use these roles is we go back to the div and we add a role tab list. And to each button here, we are going to add a role tab.

So, we've done something interesting. A button by default has a role button. But when you add a role tab to it, it actually overrides the semantics and no longer considers it a button. We could, in fact, remove the button element and just use a div and it would convey the same exact semantics.

The only thing we would lose is the ability to focus on it with our keywords. And you can add that back with a tab index. So, that's the interesting thing here that role overrides whatever HTML semantics, whatever HTML element semantics you had.

Now, and the panels would have role tab panels. That's the connection here. So, before we do anything else, let's first see what a screen reader user would hear with our new roles. Screen Reader Screen Reader Menu pop-up button. Screen Reader All right, let's open it up. Screen Reader Local selected tab one of three. Screen Reader Cata spaces selected tab two of three. Screen Reader Copilot selected tab three of three. Screen Reader Nice. There's a few very nice things happening here. The first one is that now these are identified as tabs, not buttons. It tells you how many tabs are there in the tab list. It told you one of two, two of three. And the third thing that's very cool is how it pronounces code spaces. It always says code spaces, which I think at this point we should rebrand. I think that's a better name, code spaces.

But there's also something weird that's happening. The screen reader thinks each one of these tabs is selected. And it's because the default behavior of a tab is when you switch to it, it auto-focuses. So that's what it's expecting here. Even though that's not what we are doing. What we're doing is you have to either click or hit enter on a tab to see the tab panel there, which is valid behavior, but there is no way the screen reader would know because, again, it can't really look at your hills, the borders on the tab.

So we're back to the spec. And something that the spec also has is states and properties, which provide additional information about the elements. So, for example, it's current characteristics or its state or its relationship with other elements, including selection. So we could add aria-selected attribute. And this takes true or false.

And because I'm using React, I could use an expression here. And what I'm doing is basically saying if it's a selected tab, then aria-selected should be true, otherwise false. Now, that should fix. Let's check. Local selected tab one of three. Cata spaces tab two of three. Copilot tab three of three. Nice. So only one of them was selected. I can also go back, of course, with a shift plus tab. Cata spaces tab two of three. Local selected tab one of three.

Okay. Now that I'm back on the first tab, what I want to do is access the tab panel. So let's say I want to copy this URL. The way to navigate into the tab panel, I guess, would just be to tab back again. So I'm going forward. Cata spaces tab two of three. Copilot tab three. Copy URL to clipboard. Button. And this is very disorienting, because I was on the local tab, but I first have to go through the list of all of the tabs. And then remember, eventually I will come back to a button which is probably connected to the local. Like, something's gone wrong here. And what's happening here is that we have a group here with the old tab list. And then we have another group here with the old tab panel. And we need a way to jump between these two. We need some way of navigating. The spec doesn't say a lot about this behavior, but it does say this very important line, which is in rich Internet applications, the user tabs to significantly complex widgets. They call them widgets.

And use the arrow key to navigate within the widget. Which means when we're inside the tab list, we should be able to navigate between the other tabs at the arrow keys. But when you press tab, it should jump to the next widget, which in this case is perfect because the next widget is the tab panel.

So to do this, I'm removing all the tabs from the tab index. I'm adding minus one to them. Or in this case, because of the div, I could just remove tab index, same effect.

And I need a way to enter this tab list widget. So I'm going to say only the selected tab should be focusable so that you can enter it. And then the rest are not part of the tab index. So you can't navigate with the tab key. But I'm going to implement arrow keys. And how that works is you add a key down event. And you essentially, if event key is arrow right, focus the next tab. You do element.focus on it. And if it's the previous, then you find the previous tab, call element.focus on that tab. So it's very problematic. And it's very, like, it feels very manual. And that is kind of how it is. And it's such a common pattern that we actually have extracted it. Okay. First, let me show you. So arrow keys to navigate between the tabs. And once you know where you are, you press tab to enter the tab panel. And then you can, of course, press shift tab to go back up. And once you're in the tab list widget, you can again navigate. So keyboard navigation. And this is a common pattern that we created a hookout of it. Again, primary open source. You can use the code. You can copy the code.

And something interesting is that you need to decide which keys to bind. So in this case, we need arrow horizontal keys. But if this was a list box, which is usually vertical, you can do focus keys dot arrow vertical. And the funny weird thing here is that even though if you are using a screen reader, you're not a visual user, you don't have a concept of tabs are horizontal, lists are vertical. But because these become common patterns in our industry, if it's tabs, screen reader users would expect almost that it's probably horizontal and use the left to right arrow keys. They would try that first. So if you get funky with this, if you want vertical tabs, you almost break a certain expectation, even though you're doing nothing wrong. Nothing about tabs says that it should be horizontal. But patterns tend to establish behavior.

Something we can also do is change the selected tab on focus. So then you use your arrow keys as you move the tab also changes. The panel changes. So that whichever you are on, when you hit tab, you directly jump to it. And how do you decide if something should have like when the tab should change? Should it change on interclick or should it just change live whenever you focus? And the ARIA spec actually has no opinions on this. It leaves it pretty open. But there is another resource which is the ARIA authoring practices guide called the APG which has a list of patterns, common patterns, including tabs. And that actually has a list of things like what are the keyboard interactions that you should listen to? When should you decide when the focus should change? And just to give you a hint here, you need to decide based on whether the tab is going to load some data. Can it be instant? If it can't be instant, then it probably should be activated. And how do you convey that? So I'm going to leave that to you. Leave that for you to read. But just something to consider. This is the additional resource.

While the ARIA spec is a recommendation from W3C, the recommendation is important because browsers, accessibility software, and authors like you and me should implement the spec, right? Like we need to follow the spec and that is the expectation. On the other hand, the APG is an informative resource. So it's just like a nicer way of saying this is just a blog. This is not the spec. So you can't really get mad about screen readers when they don't really follow the APG and different screen readers might have different behavior baked in for that. Just a warning.

So you can't really get mad about screen readers when they don't really follow the APG and different screen readers might have different behavior baked in for that. Just a warning.

So things we need for an accessible experience. We still need to use a correct HTML element as much as we can. But we also need to add ARIA roles to convey semantics and structures. We need to add ARIA properties and states to let the user know what's happening live. We need to implement keyboard navigation on our own to help the user navigate. And of course, there's more.

So let's use a second example. This is from the notification settings in GitHub. So this is pop up where it gives you the options of where you would like to notify. I like email. And then it reveals this additional option that you can only be notified for failed workflows. And I think that's very useful. So and it also shows what setting was saved. Pretty nice UI. The way I wrote this is I used a button, I used a popover, I used a form, there's a field set, there's a legend. Each input has a label, the save and cancel, submit and cancel. Very semantic, all the right elements. But let's see what a screen reader user would see. Or would hear. So we start with the focus. Me. Never. Menu pop up collapsed. Button. Notify me never. It reads the current status. It's a button pop up collapse. I can open it with the enter key. On GitHub.

Tick box. Select notification channels. Group. Interesting. So then you open the pop up, the focus is on the first check box. So that is what it will read first. It says on GitHub, it's an un ticked tick box tick box tick box. Same thing. And then it tells you where this on GitHub is. So it's part of a group called select notification channels. And that kind of establishes what you're doing here, what this popover is about. And you can tap through to see what are the other options in the same group.

So we know there's one option, which is on GitHub. Email on tick tick box. App on tick tick box. Cancel button. Save button. Okay, so we know that there are three options, and then there's a save and cancel button. As I told you, I like email, so I'm going to go back to email. And then I'm going to save that, I guess. Cancel app email on tick tick box. Tick email tick box. Nice. It even tells me that it's ticked it. And now because this is a form and I've seen all the options, I'm going to hit enter to submit my form. Change is saved. Notify me. Email. Menu popup collapsed button. Nice.

Very nice because it tells me change is saved. It tells me what is the new setting, notify me by email. And it tells me where is my focus. It recontextualizes me on the page. It's on the menu popup, which is collapsed. It's on the button which has a menu popup collapsed.

So some of you already know what went wrong here, and this is a pretty common pattern in templating languages, including React, templating frameworks, including React. We tend to not render elements based on conditions. So in this case, if none of the options are selected, we don't render the fourth option. We only render it when one of the channels is selected.

And it's really common to render null in React when your condition is false. But they're essentially hiding the fourth option from screen users, and they will only discover it by accident when they're navigating all the channels again, or if they navigate to the save button in the end. But revealing things later progressively is usually a bad pattern when it comes to screen reader users, and it would be nice if we just don't hide things from users. So I'm removing the conditional. And of course, my button should... The fourth button should only... The fourth checkbox should only be activated when one of the other three are... It can't be used in isolation. So maybe we can disable it until that is needed.

And that gives us the nice tiles, and you can't click it in the browser. But disabled has its quirks. You can't actually access disabled elements with the keyboard. It would skip right over them. So again, screen reader users would never land on a disabled element. The fix for that is don't use disabled, use IR disabled. And what that does is it brings it back into the... It makes it accessible again for screen reader users, for keyboard users. But it doesn't do styling. It doesn't do the click cancellation. So you have to implement it yourself.

You have to add your own class name, and you also have to make sure folks can't enter or click on it, and it doesn't fire things, because it should be disabled right now. But it is accessible by keyboards again. That's nice.

SCREEN READER Only notify for failed workflows. Dimmed unticked. Tick box. So it called out what the label is, and then it says dimmed, unticked tick box. Dimmed is a way for voiceover on Mac to say it's IR disabled. And different voiceovers can have different ways of saying this. And typically users on an OS would know what this means. It's dimmed. They know it's disabled for some reason. In this case, you can't really tell what the reason is. So it would be nice if we can also add that.

So I'm adding another span here, which says requires at least one channel. And this one is not conditionally rendered. And I'm adding an aria-describeby on the input. So this is pretty interesting, that you can add additional labels and descriptions on most elements. And in this case, the input is labeled by my label element with the fault. But it can be conditionally described by an additional description.

So this is how that would be rendered. SCREEN READER Only notify for failed workflows. Requires at least one channel to be selected. Dimmed unticked. Tick box. Nice. So now you know what the label is. You also know why is it disabled. And you know it's dimmed. SCREEN READER And so now let's look at the whole flow in one go.

And let's see if it's If I mean.

Never. Menu popup collapsed.

Button. On GitHub. Unticked. Tick box. Select notification channels. Group. Email. Unticked. Tick box. App. Unticked. Tick box. Only notify for failed workflows. Requires at least one channel to be selected. Dimmed unticked. Tick box. Cancel. Button. SCREEN READER Good. SCREEN READER Only no. App. Email. Unticked. Tick box. Ticked. Email. Tick box.

App. Only notify for failed workflows. Unticked. Tick box. Ticked. Only notify for failed workflows. Tick box.

SCREEN READER Change is saved. Notify me. Email. Failed workflows only.

SCREEN READER Nice. So it's. This is like way more descriptive. You kind of go through the flow. You know all your options up ahead. You know one was disabled. You went back. Enabled something else. It became enabled again. So you can come back to it. Much much much more clear. Now this is just my opinion. But I think the even for people who are sighted users. This flow seems more intuitive. Or at least more clear where you see all the options. And you can see an option become enabled. When something else changes. So I think this is overall for everyone. This feels like a better UI.

So back to things we need. So we still need all the other four things. But in addition, we need to design with accessibility in mind. So accessibility isn't something that you can just sprinkle on in the end. We have to design. We have to bring it way earlier in the stage. All the way to the design stage.

And lastly, we need to be careful when disabling elements. So unless you want to disable completely non-accessible. Not visible for a screen reader users. You should use RLDisabled.

Of course, there's more. But I think we could be here all day all night. So I'm going to stop here. And this is like my short list of six things to consider. All of the links from things I showed are on my website at this link. You can follow me on Blue Sky. That's where I'm more active. Not so much on Twitter these days. And that's enough from both of us, Groob. All right, that's enough. Voice over off. Bye.