Accessibility (a11y) Best Practices
Accessibility issues rarely show up as bugs in typical manual testing, since most testing is done by sighted users navigating with a mouse — which is exactly the group least likely to notice a keyboard trap or a missing screen-reader label.
Last updated 2026-09-08
Ensure every interactive element is keyboard-operable
Anything clickable with a mouse — buttons, links, custom dropdowns — needs to be reachable and operable via keyboard alone (Tab to focus, Enter/Space to activate). This is the single most common accessibility gap in custom UI components.
Maintain sufficient color contrast
Text that's technically readable to someone with typical vision can still fail WCAG contrast requirements, making it genuinely hard to read for users with low vision or in bright-light conditions. Check contrast ratios explicitly rather than relying on visual judgment.
Use ARIA attributes to supplement, not replace, semantic HTML
ARIA can describe custom widget behavior to assistive tech, but it's a supplement for cases semantic HTML doesn't cover — reaching for ARIA roles on elements that have a native semantic equivalent (like role='button' on a div instead of using a real button) usually indicates the wrong base element was chosen.
Make focus states visible
Removing the default focus outline (outline: none) without providing a replacement leaves keyboard users with no visual indication of where they are on the page — a serious usability regression, not just a cosmetic one.
Test with an actual screen reader periodically
Automated accessibility checkers catch a meaningful subset of issues but miss things that only become apparent by actually navigating with a screen reader — genuinely testing this way surfaces problems automated tools structurally can't detect.
Common Mistakes to Avoid
- ⚠Custom dropdowns, modals, or buttons that only work with a mouse, not a keyboard
- ⚠Removing focus outlines without providing any visible replacement
- ⚠Color combinations that fail WCAG contrast ratios
- ⚠Images with missing or unhelpful alt text
- ⚠Relying solely on color to convey information (like error state), with no additional indicator
Frequently Asked Questions
What's the minimum contrast ratio I should aim for?
WCAG AA requires 4.5:1 for normal text and 3:1 for large text — a widely accepted baseline that meaningfully improves readability for users with low vision, without being an extreme standard to meet.
Do I need to test with a real screen reader, or is an automated tool enough?
Automated tools (like axe or Lighthouse) catch a real but limited subset of accessibility issues — genuine keyboard and screen-reader testing catches problems, like confusing focus order or unclear announcements, that automated tools structurally can't detect.