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

• Ensure every focusable or interactive element has an accessible name (WCAG 4.1.2)
• Follow the Cardinal Rules of Naming:
  1. Heed Warnings and Test Thoroughly
  2. Prefer Visible Text
  3. Prefer Native Techniques
  4. Avoid Browser Fallback
  5. Compose Brief, Useful Names
• Ensure semantic markup is used to describe content
• Ensure content does not disappear off the screen when zoomed (WCAG 1.4.10)
• Ensure that interactive content can be tabbed to and activated using the keyboard, and that the tab order matches reading order (WCAG 2.1.1, WCAG 2.4.3)
• Ensure that heading elements are used, and that heading levels are placed in a logical order (WCAG 2.4.10)
• Ensure that landmarks are used to describe the overall layout of the page or view
• Ensure that alternative descriptions for image content are concise, descriptive, and use punctuation (alt attributes for images, title elements for SVGs)
• Ensure labels are programmatically associated with their inputs
• Prefer implementing a method to allow users to skip sections of repeated content (WCAG 2.4.1)
• Ensure each page or view has a unique title that describes the content it contains (WCAG 2.4.2)
• The title attribute is only used to describe iframe element contents
• Ensure that links are used to navigate to other locations and buttons are used to trigger actions
• Ensure that focus is trapped inside of modal interactions
• Ensure fieldset and legend elements are used to group related inputs and label them
• Ensure form feedback messaging is programmatically associated with the relevant inputs (WCAG 3.3.1)
• Ensure that dynamic changes to a web page are announced (WCAG 4.1.3)
• Prefer using role selectors in automated acceptance tests
  • capybara_accessible_selectors
  • Testing Library's getByRole()
  • Playwright's getByRole()

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:

1. Create a copy of the Accessibility Audit Template spreadsheet in Google Drive
2. Break apart the site or app to be audited into discrete user flow sections, ordered by importance
3. Add yourself as the section lead on the audit template, document the relevant URL and date, and set a status
4. For each user flow, identify each component that enables the user flow to function
5. 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
6. Once a component is completed, update its status
7. 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.