Accessibility

A guide for auditing and maintaining accessible web sites and apps.

Basics

thoughtbot strives for AA level Web Content Accessibility Guideline (WCAG) compliance. Perform one or more of these checks to ensure your work is accessible.

Automation

Automated checks can catch a lot of common issues before they reach production.

Test the application in a browser (like Capybara-driven Acceptance Tests)
When using Capybara, use CapybaraAccessibilityAudit
Use tools such as WAVE or axe's browser extensions to run audits on your local build
Use a CI/CD solution such as AccessLint or axe. axe has integrations with popular test frameworks like RSpec and Jest

Usability

Manual usability testing ensures things work as intended.

Test your local build using a screen reader such as VoiceOver or NVDA
Use auditing tools to catch issues that cannot be found using automated checks
- Accessibility Insights accessibility auditing browser extension
- Readability Analyzer for auditing text
- axe DevTools accessibility testing browser extension
- WAVE Evaluation Tool accessibility testing browser extension
- ARIA DevTools browser extension for checking ARIA roles
- tab11y browser extension for checking tab order
- WCAG Color contrast checker browser extension
Validate your HTML with a tool like W3C's Markup Validation Service
Hire assistive technology users to user test your product

Quick checks

Design

Ensure all content's foreground color values meet the minimum contrast ratio for the background color they are placed over (WCAG 1.4.3)
Ensure all interactive content has distinct hover and focus states to help indicate interactivity (WCAG 2.4.7)
Ensure interactive elements have a visible text label
Ensure color is not the only way to determine meaning (WCAG 1.4.1)
Ensure interactive components use common UI affordances where applicable, to help users understand how they can be operated
Prefer icons and glyphs that don't rely on specialized knowledge to understand their meaning, unless being used in a domain-specific context
Prefer language that is simple and direct (WCAG 3.1)
Ensure form inputs have labels that are visible in every state
Ensure link and button text is descriptive and distinct (WCAG 2.4.4)
Prefer content that is broken into logical sections, with headings that explain the content that follows (WCAG 2.4.10)
Prefer text sizing that is set to 16px or larger
Ensure animation does not auto-play, can be paused, and avoids vestibular and seizure triggers (WCAG 2.2.2)
Ensure video content has captions (WCAG 1.2.2)
Prefer larger interactive target sizes, with some space between grouped interactive controls (WCAG 2.5.8)

Development

Full audit

When at all possible, use the guidelines in the basics and quick check sections to attempt to address accessibility in a proactive way.

If a thorough analysis needs to be performed, use the following workflow to perform a comprehensive accessibility audit that checks against most WCAG criterion:

Create a copy of the Accessibility Audit Template spreadsheet in Google Drive
Break apart the site or app to be audited into discrete user flow sections, ordered by importance
Add yourself as the section lead on the audit template, document the relevant URL and date, and set a status
For each user flow, identify each component that enables the user flow to function
For each component, check against the test criteria for each row, and then assign it one of four ratings:
- N/A: This test does not apply to this component
- Pass: This component meets this test's criteria
- Moderate: This component does not meet this test's criteria, but can worked around
- Critical: This component does not meet this test's criteria, and cannot be worked around
Once a component is completed, update its status
Continue until all user flows have been audited

Use the Notes sheet to leave per-cell comments when necessary, referencing them with a link. The next steps for an audit are handled on a per-project basis.

Uh oh!