How to Discuss Accessibility Bugs in English
Learn the English vocabulary for reporting and discussing accessibility bugs clearly, from screen reader issues to keyboard navigation and contrast problems.
Accessibility bugs are frequently under-reported because they’re harder to describe than visual bugs — “it doesn’t work with a screen reader” is a start, but it doesn’t tell a developer what specifically fails or how to reproduce it. This guide covers the English vocabulary for writing accessibility bug reports precise enough to act on.
Key Vocabulary
Assistive technology (AT) — the general term for tools people use to interact with software differently than a typical mouse-and-screen user, including screen readers, switch devices, and voice control. “This bug was found during testing with assistive technology, specifically a screen reader — it’s not something a sighted mouse user would notice.”
Focus order — the sequence in which interactive elements receive keyboard focus when a user presses Tab, which should match the visual and logical order of the page. “The focus order skips the search bar entirely and jumps straight from the logo to the nav menu — that’s disorienting for keyboard-only users.”
Accessible name — the text a screen reader announces for an element, which may come from visible text, an aria-label, or alt text, and must actually describe the element’s purpose.
“The icon button’s accessible name just reads ‘button’ — it needs an aria-label like ‘Close dialog’ so screen reader users know what it does.”
Focus trap — a bug where keyboard focus gets stuck inside an element (often unintentionally) and the user can’t Tab out, or a missing intentional trap in a modal that lets focus escape behind it. “There’s a focus trap bug in the modal — once it opens, Tab still moves focus to elements behind it that are supposed to be inert.”
Contrast ratio — the numeric measure of the difference between text color and background color, with WCAG defining minimum ratios needed for readability. “The contrast ratio on this button is 2.8:1, well below the 4.5:1 minimum for normal text — that fails the accessibility audit.”
Common Phrases
- “This element has no accessible name — a screen reader just announces ‘button’ with no context.”
- “The focus order doesn’t match the visual order here, which is confusing for keyboard navigation.”
- “Can we verify the contrast ratio on this text against the actual background color, not just the design mockup?”
- “There’s a focus trap issue — focus escapes the modal into content that should be inert while it’s open.”
- “This works visually but fails with a screen reader — here’s specifically what it announces.”
Example Sentences
Writing a precise accessibility bug report: “Steps to reproduce: open the settings modal using Tab and Enter, then continue pressing Tab. Expected: focus should stay within the modal until it’s closed. Actual: after five tabs, focus moves to a link in the page behind the modal, which is still visually hidden but not properly inert. Tested with VoiceOver on Safari.”
Explaining the impact of a contrast issue: “This isn’t just a visual nitpick — the contrast ratio on the error text is 2.1:1, which fails WCAG AA and means users with low vision may not be able to read the error message at all.”
Describing a screen reader issue with specifics: “When navigating with a screen reader, the product cards are announced with no distinguishing information — just ‘link, link, link’ — because the accessible name is empty. Sighted users can tell them apart by the product image and title, but screen reader users currently can’t.”
Professional Tips
- Name the specific assistive technology used to find the bug (screen reader name and browser combination) — behavior can differ meaningfully between VoiceOver, NVDA, and JAWS.
- Describe focus order and focus traps as distinct, specific bugs, not just “keyboard navigation is broken” — they have different causes and different fixes.
- Quote the accessible name an element actually announces, not just that it’s “missing a label” — showing what a screen reader currently says makes the gap concrete.
- Include the actual contrast ratio number when reporting a contrast bug, not just “the text is hard to read” — it turns a subjective complaint into an objective, checkable fact.
Practice Exercise
- Write a two-sentence accessibility bug report describing a focus order problem, including how to reproduce it.
- Write one sentence describing what a screen reader currently announces for an element with a missing accessible name.
- Describe, in your own words, the difference between a contrast bug and a focus trap bug.
Navigating Nuances: Speaking Accessibility with Confidence
Communicating effectively about accessibility issues – whether it’s during a code review, a Slack conversation, or writing a pull request description – is crucial for building inclusive digital experiences. It’s not just about stating the problem; it’s about conveying how that problem impacts users and proposing solutions clearly. Many developers find this challenging due to the specialized terminology involved. Let’s focus on refining your approach by understanding common phrasing used when discussing accessibility bugs, particularly from a non-native English speaker’s perspective.
One frequent hurdle is framing the issue without sounding accusatory or technical in a way that’s difficult for everyone to understand. Instead of saying “The contrast ratio is too low,” which can immediately trigger defensiveness, try something like: “I noticed a potential usability concern regarding text readability. The current color palette may be challenging for users with low vision, particularly when reading large blocks of text.” This introduction sets the stage by acknowledging it as a potential issue and focusing on user impact. Using phrases like “usability concern” or “readability challenge” is often better received than immediately launching into technical specifications.
Another key area is detailing the steps to reproduce the problem clearly. Instead of saying “It doesn’t work with NVDA,” which offers no guidance, try: “I was able to consistently experience this issue using NVDA screen reader on Windows 10. The steps are as follows: 1. Navigate to [specific page/component]. 2. Focus on the [element name] element. 3. Using NVDA, attempt to read the content aloud.” This is more specific and provides actionable information for anyone trying to replicate the bug. Including the operating system and screen reader used adds further clarity.
Finally, remember that proposing solutions isn’t about dictating what should be done; it’s about offering options. Instead of “You need to increase the contrast,” consider: “I believe adjusting the color palette to meet WCAG guidelines for sufficient contrast would address this issue. Alternatively, we could explore using a higher-contrast font option for affected elements.” This collaborative approach demonstrates a willingness to work together and presents solutions in a constructive manner. Always back up your recommendations with reference to accessibility standards (WCAG) when possible – it adds weight to your argument and shows you’ve done your research.