Skip to content

Instantly share code, notes, and snippets.

@theetrain

theetrain/accessibility.md

Last active October 17, 2025 22:59
Show Gist options
  • Save theetrain/0f12fefe10e5a4e31d6755fa5b4b5a79 to your computer and use it in GitHub Desktop.
Save theetrain/0f12fefe10e5a4e31d6755fa5b4b5a79 to your computer and use it in GitHub Desktop.
Download ZIP
Accessibility pledge
Raw
accessibility.md

Accessibility

Why

When providing services to people in various regions, we are beholden to certain laws and regulations:

These regulations point to the latest iteration of the Web Contents Accessibility Guidelines (WCAG), which is an international standard maintained by the W3C. Our digital experiences must meet or exceed WCAG 2.2 guidelines in order to mitigate risk from legal action by our end users, as well as provide meaningful and optimized experiences, which can lead to benefits that include:

  • Content and interactive elements have sufficient contrast and affordances.
  • Interaction feedback, leading to intuitive use of our software and fewer support requests.
  • Thoughtful and clear copy, written in the language of our users.
  • Cached responses, leading to cost-effective use of our infrastructure.
  • Baseline experiences, allowing our software to be used under a spectrum of network conditions; while allowing power users to utilize enhanced features.

What

Accessible digital experiences have traits and features that cater to users with a wide spectrum of abilities. Oftentimes, our users navigate web and mobile applications with assistive technology either out of permanent necessity or temporary need.

Note this statistic:

Being mindful of the continuum from permanent disabilities to situational impairments helps us rethink how our designs can scale to more people in new ways. In the United States, 26,000 people a year suffer from loss of upper extremities. But when we include people with temporary and situational impairments, the number is greater than 20M.

— Microsoft

WCAG covers many considerations for human experiences. It's worth reading the full guide, but at the very least it's worth understanding the four main principles of accessibility: perceivable, operable, understandable, robust.

According to The WebAIM Million project, the top million front pages on the Internet have detectable violations. Users with disabilities would expect to encounter errors on 1 in every 21 home page elements. Common violations can be easily detected and avoided with automatic tools.

How

You may find a brief, yet practical guide to producing accessible experiences here: https://www.solidstart.info/.

Measures of success

Determining whether a digital experience is accessible cannot be measured with numbers alone. The following represent an ideal target:

  • Zero violations in automatic assessment tools such as lighthouse or Axe. This is a very inexpensive and uncomplicated goal to attain.
  • Zero violations from internal audits, covering the a11yproject checklist in full.
  • All feedback addressed from usability testing sessions.

Audits can be performed by anyone, anytime. All violations in accessibility MUST be triaged as a high priority bug, because they are bugs.

Put into practice

The pursuit of designing and building accessible experiences involves making considerations for access as early as possible, and continuously throughout the development process:

  1. During feature ideation, think about the people using your software, their abilities, their situational environments, hardware capability, and frequency of use.
  2. When designing, plan for the most straightforward way possible to access information or manipulate data. Keep in mind the four principles of accessibility.
  3. When developing, implement visual and interactive designs while accounting for how information is perceived or read out loud by screen readers.
  4. When testing, ensure common assistive technologies are accounted for, as well as various OS-level settings. See the a11yproject's checklist for more.
  5. When running our applications in any capacity (locally, on a staging server, etc), the moment a violation is found, they MUST be reported to a corresponding product owner to triage and resolve as early as possible.

Tools

There are some tools anyone can install on their web browser to detect accessibility violations. Note that these tools only cover roughly 56% of violations; a machine is not an adequate replacement for a real manual human test.

  • WAVE
  • Axe, also featured as a Playwright plugin for end-to-end tests
  • VisBug
  • Lighthouse
  • Web browser and screen reader pairings
    • macOS, iOS: VoiceOver + Safari
    • Windows: NVDA + Firefox
    • Windows: JAWS + Google Chrome
    • Windows: Narrator or JAWS + Microsoft Edge
    • Android: Talkback + Google Chrome

Resources, patterns, and inspiration

It's always a good idea to double check implementations with the years of research and expertise catalogued online. When looking up resources, always note the date certain articles were posted or updated; improvements (and regressions!) can occur over time on web browsers, screen readers, or operating systems. Also keep in mind that not every resources covers all four WCAG principles, which need to be supplemented by our own efforts.

References

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment