mgifford/accessibility-skills/bug-reporting

Accessibility Bug Reporting Skill

Canonical source: examples/ACCESSIBILITY_BUG_REPORTING_BEST_PRACTICES.md in mgifford/ACCESSIBILITY.md

This skill is derived from that file. When in doubt, the example is authoritative.

Apply these rules when filing, reviewing, or generating accessibility bug reports from any source — automated tool output, manual testing, user reports, or testing with disabled people.

Core Mandate

A useful report lets another person understand the barrier, identify the people affected, reproduce it when possible, judge its impact, identify the responsible source, and verify the correction. Not every field applies to every finding — do not delay a valid report because a selector, tool rule, WCAG mapping, or code-level fix is unavailable.

Principles:

1. Describe the barrier before the standard — state what task or interaction fails and under what conditions
2. Identify the people affected — describe access needs/interaction methods/AT when evidence supports it; never infer a diagnosis or imply one person represents an entire disability group
3. State the evidence basis — distinguish user reports, testing with disabled people, manual evaluation, automated results, and reasoned inference
4. Record observed facts separately from assumptions, suspected causes, and suggested fixes
5. Use complementary testing methods — automated, manual, and testing-with-disabled-people answer different questions; none substitutes for the others
6. Collect only relevant context — browser/AT/viewport/preferences matter only when they affect the result
7. Protect people and systems — remove personal data, credentials, tokens, and private content from every attachment
8. Treat tool output as evidence, not a conformance decision
9. Separate severity from priority — task impact and workaround quality inform severity; reach, frequency, deadlines, and business context inform priority
10. Fix the source when possible — a shared-component/template/token fix is usually safer than many page-specific patches
11. Close with verification evidence — a code change, automated pass, or visual check alone may not prove the user-facing barrier is gone

Terminology

A failed automated rule does not automatically prove a WCAG failure. A passed automated rule does not prove conformance. Confirm the result and its scope before making a conformance claim.

Severity Scale (this skill)

This is an example scale, not a universal standard — calibrate locally with disabled people and product teams, and document local definitions.

Severity, priority, reach, frequency, and confidence answer different questions — do not conflate them:

Frequency and reach can increase priority, but they do not change the severity of one occurrence — do not automatically escalate a low-severity issue to higher severity just because it appears on many pages; record that as a priority factor instead.

Critical: Minimum Information for a Useful Report

A report can be valid at intake without being ready for remediation — these are different bars. Do not reject a report from a user for lacking technical detail; a triager collects locators, standards mapping, and a verification plan afterward. See Actionable Findings and Repeatability below for the full stage model.

Valid intake needs only: title, location/state (as precisely as the reporter can safely give), task and impact, actual result, evidence basis.

Additional fields for evaluation and remediation — collected by triage, not required from the reporter:

Critical: Write a Specific Title

Identify the component, failure, and consequence.

Good: Checkout: card error text is not associated with the field / Account menu: keyboard focus moves behind the open dialog

Avoid: Accessibility issue, Screen reader bug, WCAG failure — these don't identify the affected behavior. Including a WCAG criterion in the title is optional; the report should stay understandable to someone who doesn't know the criterion number.

Critical: Record Location and State Safely

Page or route: /checkout/payment
Build or commit: 2026.07.18.2
Component: Payment form
UI state: Form submitted with an invalid card number
Account role: Test customer

Use an exact URL only when its query/fragment values are relevant AND safe to share. Remove or replace session identifiers, access tokens, email addresses, names, account numbers, and other secrets/personal data:

Unsafe: https://example.com/orders/847291?token=secret-value
Safe:   https://example.com/orders/[test-order-id]

Never include production credentials — provide an approved test account through the organization's secure process.

Element locators: start with a human-readable component name and location; add a stable technical locator if it helps ([data-component="cookie-settings"] [data-action="close"], a tool-native selector, an accessibility-tree path, a test ID, or a short XPath). A full absolute DOM XPath should not be mandatory — absolute paths are brittle when wrappers, list positions, or generated markup change. If no reliable locator exists, describe the visible label, accessible name, role, nearby heading, and interaction state instead. Record iframe/shadow-root boundaries when relevant.

Critical: Preconditions and Steps to Reproduce

List only the steps needed to reach the failure, including input method and AT command when they matter:

Preconditions:
- Signed in as a test customer
- Cart contains one item
- NVDA is running with Firefox
 
Steps:
1. Open the checkout payment step.
2. Leave the card number empty.
3. Move to the Submit order button with Tab.
4. Activate the button with Enter.
5. Listen for feedback without moving focus.

For intermittent findings, record how many attempts reproduced it, timing/ network/loading conditions, and the earliest known build. "Cannot reproduce" is a triage state, not evidence the report is invalid — preserve the original conditions.

Critical: Separate Expected and Actual Results

Write expected behavior as an outcome, not a required implementation:

Expected:
After submission, the card number error is associated with the field. When
focus moves to the field, its label, invalid state, and error are available.
 
Actual:
The visible error appears, but the card number field has no programmatic error
association. When focus moves to the field, NVDA announces only its label.

Avoid putting a specific ARIA attribute or JS method in the expected result unless the product contract requires that implementation — put possible code changes under "Suggested fix" instead.

Critical: Identify People Affected — Never Guess a Diagnosis

Connect the barrier to people and a task, not only to a technical defect or tool rule. Describe people in terms of access needs/interaction methods/AT when evidence supports it — do not guess a diagnosis, require disclosure of one, or imply every person in a disability group has the same experience.

Useful: "People who use screen readers are likely to be affected, including some blind and low-vision people. Manual evaluation with NVDA and Firefox found that submission failure was not announced. The impact has not yet been confirmed through testing with disabled participants."

Not useful: "This affects blind people and violates WCAG."

A report can identify more than one affected population — avoid assuming a one-to-one relationship between a WCAG criterion or automated rule and a disability group.

Serious: Record Only the Relevant Environment

An environment list is useful only when it describes conditions that produced the result — do not paste a generic browser/AT matrix into every issue:

Test date and time: 2026-07-18 14:30 EDT
Browser: Firefox 140
Operating system: Windows 11 24H2
Assistive technology: NVDA 2026.1
Input: Keyboard
Viewport: 1280 by 720 CSS pixels
Zoom or text size: 200% text size
Color scheme: Dark
Forced colors: Active
prefers-reduced-motion: reduce
prefers-contrast: more
Locale and language: en-CA

Use the value actually tested — do not infer a device type from a viewport-width breakpoint; viewport, input capability, browser, OS, and physical device are separate facts. Relevant CSS preference values: prefers-color-scheme (light/dark), prefers-reduced-motion (reduce/no-preference), prefers-contrast (more/less/custom/no-preference), forced-colors (active/none).