How to write an accessibility bug report a developer can reproduce

‘The form is inaccessible’ tells a developer there is a concern. It leaves several questions unanswered: which task is blocked, what happened and how can someone else see the same behaviour?

A useful accessibility bug report connects a person’s task to a specific barrier and a repeatable observation. It gives a developer enough information to investigate, while keeping the effect on the user visible.

You can write that report as a developer, tester, designer, Product Owner or someone learning to assess a website. Begin with what you observed. Add technical analysis where you have evidence for it.

Describe the task before the defect

A screen reader presents interface information through speech or braille. Keyboard navigation lets a person move between controls without using a mouse. These are different ways of interacting with a product, and the report should identify which you tested.

Start with the intended task: save a profile change, choose a delivery option or find a document. Then describe where the person loses information or control. ‘The save control is announced without a name’ gives an investigator a more specific starting point than ‘screen readers do not work’.

State the task impact carefully. If your test showed that a control’s purpose was unclear, describe that uncertainty. Claim that a task was impossible only when that is what the evidence supports.

Include four kinds of evidence

1. The starting conditions

Purpose: Let another person reach the same state.

Record the page, product build, device or operating system, browser and versions. Where relevant, include the screen reader, its version and any settings that affect the test. Say whether you used keyboard navigation, a touch gesture or another method.

Explain account state and test data without exposing real personal information. An approved fixture account or fictional record is easier to share safely than a screenshot of a customer’s profile.

2. The action sequence

Purpose: Make the observation repeatable.

Write the smallest sequence that reaches the barrier. Identify the starting page, action and control. Include a change of mode if that affects what a screen reader announces. If you cannot reproduce the issue consistently, record that rather than hiding it.

Avoid directions that depend entirely on seeing the screen, such as ‘click the little icon at the top’. Name the control or describe its place in the task. If the missing name is the defect, explain how you located it during your test.

3. Expected and observed behaviour

Purpose: Separate the requirement from what happened.

Write both. The expected behaviour might be that the save control identifies its purpose when focused. The observation might be that the screen reader announced only ‘button’. Add the exact announcement if you recorded it, keeping a transcript or permitted recording where useful.

A screenshot can show visual context, but it cannot establish what a screen reader announced. Keep the text observation available alongside any image or video.

4. The impact and next check

Purpose: Help the team decide what to investigate and retest.

Describe the affected task and any tested workaround. A workaround can reduce immediate disruption while still leaving a barrier to fix. Name a proposed owner or triage route according to your team’s process.

Write down how you will repeat the check after a change. Keep the original conditions visible so a passing test in a different environment does not silently replace the reported case.

A fictional report: the unnamed save control

Illustrative example: a fictional member-directory service lets someone edit a display name. The tester reaches an icon control after the name field. In this invented test, the screen reader announces ‘button’, with no description of the save action. These observations are teaching material, not results from a real service.

The team can investigate the accessible name: the name exposed to assistive technology for a control. W3C’s Name, Role, Value guidance explains the importance of exposing appropriate information about interface components. A developer still needs to inspect the implementation before choosing a repair.

Copy a task-first reporting template

Title: which control or journey has which problem?
User task and impact: what becomes difficult or blocked?
Environment: build, device, browser, assistive technology, versions and relevant settings.
Starting conditions: page, account state and permitted sample data.
Steps: the smallest repeatable action sequence.
Expected / observed: two separate descriptions, with evidence.
Scope: what else was checked, and what remains unknown?
Follow-up: triage owner and the conditions for retesting.

Ask a colleague to replay the report

Give someone the issue without narrating it for them. Ask them to reach the same starting point and explain where the barrier occurs. If they need your memory to fill in a missing step, improve the report together.

Treat that replay as a check of the report’s usefulness. A single repaired issue does not establish that a whole product is accessible. W3C’s Easy Checks guidance makes the limits of an initial review clear.

For your next issue, replace a broad label with a precise task, observation and retest. That makes the barrier easier to understand and the repair easier to verify.

The example and template are original Coded Female teaching material. W3C provides the technical background. NV Access’s 14 October 2026 beta announcement, which invites issue reports, prompted this focus on useful testing feedback. No specific browser or screen-reader combination was tested for this fictional example.

W3C: Understanding Name, Role, Value. W3C: Easy Checks. NV Access: NVDA 2026.3beta5 available for testing.