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.