Improving accessibility, by example

Install Node, then run the following on the command line:

npm install
npm start

The commands above will install necessary dependencies, then start the app on your machine.

The master branch contains an app with bad accessibility. Checkout the fixed branch to try the app with improved accessibility. Use the screen readers below to see the huge difference.

Slides from "Building Accessible Web Apps"

• It's the right thing to do
• It makes development and test easier too by encouraging semantic markup
• The American Council for the Blind and others are filing suits. Number/year keeps growing.

• The first rule of ARIA: Don't use ARIA. Consider it a last resort. Start with semantic HTML.
• Read the other rules of ARIA
• "Shift a11y left" - Design in a11y from the start. Don't merely put the onus on developers. Designers should design for a11y. Examples:
  • Anything a mouse can do, a keyboard user needs to be able to do.
  • Figma tools like Stark and A11y Annotation Kit allow designers to convey a11y info.
  • Visual treatments should have sufficient contrast and not rely upon color alone. Use WCAG contrast checker
• Semantic HTML is the foundation. div or span is a last resort. Use the tag that's designed for the job. Avoid creating custom elements when a native one exists. Here's an example where a custom element was useful
• aria-label is basically only for interactive and landmark elements. It's also a code smell. (prefer visible text or visually hidden text if possible). Also, aria-label often doesn't translate, so prefer visual text, or aria-labeledby pointing to visible text, or sr-only text.
• Role is a last resort. Again, prefer a specific tag first.
  • h1 has a role="heading
  • button has role="button"
  • section has role="region"
  • footer has role="complimentary",
  • header has role="banner" (when not nested under aside, article, main, nav, or section.) (and yes, header/footer can be used elsewhere in the page to mark up headers footers for sections too.
• The most broadly useful roles (because they don't have an HTML tag equivalent):
  • feed
  • img (for grouping separate images together for a shared description)
  • search - Apply to search input's form tag
  • switch - For 2 on/off states, like a more specific checkbox.
  • tab
• Be deliberate and careful with motion. Check prefers-reduced-motion and minimize motion if set.
• Add a heading to each major section of the UI, like navigation, even if visually hidden because many screen reader users don’t navigate by landmarks but do navigate by headings.
• After client-side routing, Provide a skip link that takes focus on a route change within the site, with a label that indicates what the link will do when activated: e.g. "skip to main navigation". Include an ARIA Live Region on page load. On a route change, append text to it indicating the current page, e.g. "Portfolio page".
• Avoid built-in form validation. Ironically, it's not accessible
• Consider HTML order. Remember that screen readers read top down. So avoid putting extraneous things before the main content (sharing, tags, ads, etc)
• For toggles, make it clear whether it's selected. And what will happen if it's clicked. For example prefer "Currently muted, click to unmute" over "muted".
• Announce when something is expanded or collapsed.
• Avoid spelling phonetically because Braille readers get confused. Screen reader users are used to words being mispronounced.
• Set the tabindex=-1 to convey that something can only be focused via a func call. Useful for headers that you want to focus programmatically when an anchor is clicked.
• WCAG text notes - If the text is 18pt / 24 px or larger, it counts as “large-scale text” and only needs to meet a 3:1. For headings to pass 3:1, they need to be at least 24 px (or 14px bold). A submit button is a user interface component, so it also only needs to meet 3:1. WCAG defines a user interface component as “a part of the content that is perceived by users as a single control for a distinct function”. A submit button is a single control, sitting on its own line with padding and a background color. If it were a text link in the middle of a paragraph, it wouldn’t meet the same requirements and would thus need to meet 4.5:1. Unless it was 24px or larger!

• Is first tab "skip to main content"?
• Are form labels tied to the input?
• Are form errors announced immediately, and marked as errors?
• Do toggles and buttons announce their state via aria-pressed?
• Is aria-haspopup used for elements trigger a popup?
• Are required fields marked via aria-required (or the required attribute if you want native behavior)?
• Are invalid fields (that failed validation) marked via aria-invalid?
• Do errors have a role="alert"?
• Are any buttons disabled? Don't. Disabled buttons suck. Instead, use aria-disabled and ignore clicks. Or, consider these disabled button approaches and alternatives. My tweet on this
• Is Navigation well-named?
• Open the screen reader's rotor: Are links, heading, buttons all well named? (Avoid links with text of "click here"). Do headings start at h1 and descend logically?
• Is the HTML lang tag set when the language changes?
• Is autocomplete set on the relevant form fields?
• Are aria-live and a skip link being used to announce new content/alerts/pages? Note: The aria-live attribute must be present in the DOM right from the beginning, even if the element doesn’t hold any message yet, otherwise, Assistive Technologies may not work properly.
• Is aria-current being used to mark and style active links?
• Can I navigate the app via the keyboard in a logical order? Can I always see what is focused? (use inert for invisible, rendered elements). Check tab, arrows keys, focus rings, escape.
• Are radios and other related fields wrapped in a fieldset? - NOTE: When you do, wrap each radio in a div, not a p
• Is the input type specified as specific as possible?
• Is aria-busy being used? Don't. Few screenreaders honor it, and it ironically makes the content inaccessible
• Is the title attribute used anywhere? Don't. It hides content from mobile and tablet users as well as assistive tech users and keyboard only users.
• When I click on a link, does it focus the proper item? If I click an anchor, does it focus the heading?
• Is the markup semantic? Does it use the most specific tag possible.
• Does the app work well zoomed in? Are font sizes declared in em/rem? Other values like padding/margin/border width should be declared via pixels so they don't change and take up a bunch of space when the user has font size/zoom cranked up (which would make content harder to read by making each line very short). Rule: If the value should increase with the default font size, use rem. Otherwise, use px.
• Search the code: Where is role used? Could a semantic tag be used instead?
• Are useful landmarks displayed in the rotor? (Use good semantic markup, and apply roles when semantic markup isn't possible/sufficient)
• Are buttons and anchors being used as intended? They operate differently. (search code for these tags to focus audit). My summary in a tweet
• Have we reviewed everything that can't be automated that's on a11y-automation? This site lists the status of each thing to check, and whether it can be automated.

1. Make sure things are rendered in the browser as expected.
2. Try navigating the site with only my keyboard, taking note of what does and doesn't work.
3. Scan the page with developer tools (Accessibility Insights is one of my go-tos).
4. Take note of how screen readers behave on Mac, Windows, and even mobile devices & emulators.
5. Zoom in and out and watch for how content reacts. The Web Content Accessibility Guidelines (WCAG) state that in order to be accessible, a site should be usable at 200% zoom. This number is really a minimum - many folks with vision disorders often zoom any farther.

Once I've got a list of things that need addressed from the user side of things, I start in on the code. I often start conversations with Creative/Design teams as well to prevent accessibility issues earlier in the software development lifecycle.

As I dive in to fix accessibility problems with code, I prioritize them based on user impact and the Web Content Accessibility Guidelines. I aim to fix things one viewport size at a time, though it's important to double check that changes in one place don't have an effect on others.

Aviod them. There's no free lunch. Here's more on why

• Chrome Audits tab (powered by Lighthouse)
• Accessibility Insights for Chrome
• Axe accessibility checker Chrome extension
• Lighthouse
• Axe Core CLI Axe CLI - Useful for CI.
• Nu Validator
• IBM Accessibility Tool
• Wave accessibility evaluation tool for Chrome
• Siteimprove
• ChromeLens
• Color contrast checker
• Testing Library - Encourages writing accessible apps by writing tests that mimic how user's interact.
• ESLint A11y plugin
• Pa11y - Run a11y checks on your CI server
• Complete Guide to a11y tooling

Many queries in jest-dom help encourage a11y:

• toBeRequired
• toBeInvalid
• toHaveFocus
• toHaveDescription
• toHaveDisplayValue

These sites contain UI components that are focused on a11y. Good to use as foundations or as inspiration.

• digitala11y

• Windows: NVDA - Free Vid on usage, or Jaws - Paid
• Mac: VoiceOver - Built into Macs
• Windows, Mac, Linux: ChromeVox for Chrome

• Learn HTML including new stuff in HTML5
• Check for screenreader accessibility support for specific features
• Web Content Accessibility Guidelines
• WebAIM Checklist - A distilled version of WCAG guidelines
• Accessible Routing
• 18f accessibility guide
• A11yCasts on YouTube
• Free Udacity Web Accessibility Course by Google
• Aria Spec on W3
• Aria Authoring Practices Guide - Guide for how to create your own accessible components
• Accessibility Fundamentals from Google
• In Browser ChromeVox Demo
• Aria Roles
• Frontend Handbook
• Frontend Checklist
• Marcy Sutton's Blog on Accessibility
• Accessibility in React Apps
• Video of someone using a screenreader on multiple sites
• A11y myts

I offer on-site training and consulting on JavaScript, React, and accessibility at reactjsconsulting.com.

• I prefer configuring it to use the Caps Lock key as the NVDA key.
• NVDA+n activates the NVDA menu

Chromevox docs

• Chromevox = Ctrl+cmd on Mac
• Chromvox + . = Show all commands and search box
• Navigate elements: Ctrl+cmd+arrows

Announce table cell header:

• Cmd+ctrl+backslash while reading table cell to enter table mode.
• Cmd+ctrl+T+H to announce current cell's headers.

• Open/close: CMD+F5 (or, via toolbar if enabled in preferences)
• "VO" default chord: Ctrl+Alt
• Mute: Ctrl
• Rotor: VO+U (so Ctrl+Alt+U), then use left/right arrows to shift between
• Quick Nav: Hold both arrow keys to toggle. (allows navigating via arrows). Press up down to change sections, left right to nav within a section. Note that tables read out the headers as you navigate the content. To Nav between table cells: Ctrl+Alt+arrow.
• TIP: Voiceover works best in Safari. Avoid using Voiceover on a browser with many tabs/windows open. Doing so will cause it to take a long time to initialize. So if you have many tabs open in Chrome for instance, use Firefox or Safari.
• More tips / keyboard shortcuts

• Use two finger rotation to engage the rotor
• Drag one finger around the screen to explore via touch
• Swipe left and right with one finger to move the cursor one element at a time
• Double tap with one finger to activate the current element
• 2 finger tap to pause VoiceOver speaking