bug-reporting · diff
git:20260331.745c1b6 to git:20260722.125074b
489 added, 563 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: bug-reporting
description: >
Load this skill whenever you are filing, reviewing, or generating accessibility
- bug reports — whether from automated tool output, manual testing, or AI agent
- scans. The purpose of this skill is to make accessibility errors easier to
- report accurately, so that developers can reproduce, understand, and fix them
- without additional back-and-forth. Absolutely always include the required
- fields (URL, XPath, HTML snippet, WCAG SC, rule ID, severity, frequency) in
- every report. Under no circumstances file a vague report that omits the
- failing element, the WCAG criterion, or the steps to reproduce.
+ bug reports — whether from automated tool output, manual testing, user reports,
+ or testing with disabled people. The purpose of this skill is to make
+ accessibility findings easier to report accurately, connect them to real
+ people and tasks, and let developers reproduce, understand, and fix them
+ without unnecessary back-and-forth. Absolutely always describe the barrier
+ and its task impact before citing a WCAG criterion. Under no circumstances
+ guess a disability diagnosis, treat automated tool output as a conformance
+ conclusion, or expose secrets/personal data in a report.
---
# 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, or AI agent scans.
+ from any source — automated tool output, manual testing, user reports, or
+ testing with disabled people.
---
## Core Mandate
- **Reproducibility is the single most important quality of a bug report.**
- If a developer cannot reproduce the problem, they cannot fix it.
+ 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.**
- Every report must give enough information for a developer who was not present
- during testing to reproduce, understand, and fix the problem without additional
- back-and-forth.
+ **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
---
- ## Severity Scale (this skill)
-
- | Level | Meaning | Action |
- | --- | --- | --- |
- | **Critical** | Users cannot complete a core task at all | Must fix before release |
- | **High** | Significant barrier that degrades or blocks a key workflow | Fix urgently |
- | **Medium** | Noticeable barrier with a workaround available | Fix in near-term backlog |
- | **Low** | Minor issue with minimal real-world impact | Fix when convenient |
-
- ---
+ ## Terminology
- ## Critical: Required Fields
+ | Term | Meaning |
+ | --- | --- |
+ | **Finding** | An observed or suspected accessibility barrier or test result |
+ | **Issue** | Tracked work that may contain one or more related findings |
+ | **Occurrence** | One place or state in which a finding appears |
+ | **Root cause** | The source producing one or more occurrences (e.g., a shared component) |
+ | **Affected people** | People whose task/experience is confirmed or reasonably expected to be affected — describe only as specifically as the evidence allows |
+ | **Manual accessibility evaluation** | Human evaluation using relevant inputs/settings/AT — distinct from testing with disabled people |
+ | **Testing with disabled people** | Disabled participants using representative tasks, providing evidence from lived experience |
+ | **Conformance conclusion** | A conclusion about a defined scope, standard, level, and evaluation method |
- Every accessibility bug report **must** include all eight of the following fields.
- **Omitting any required field is Critical** — the report cannot be acted on.
+ **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.
- ### 1. Page URL
+ ---
- Provide the exact URL where the issue was found, including query string and
- fragment identifier if relevant.
+ ## Severity Scale (this skill)
- ```
- URL: https://example.com/checkout?step=2#payment-form
- ```
+ | Severity | Definition |
+ | --- | --- |
+ | **Blocker** | A core task cannot be completed, or there's a serious safety/privacy/data-loss risk, with no reasonable workaround |
+ | **Major** | A task fails, is unreliable, or requires a substantial workaround |
+ | **Moderate** | The task remains possible but requires significant extra effort or assistance |
+ | **Minor** | Localized friction without material task loss |
+ | **Needs review** | The result or impact has not been confirmed |
- If the issue appears on multiple pages, list all affected URLs or describe the
- URL pattern (e.g. "all `/product/*` pages").
+ This is an example scale, not a universal standard — calibrate locally with
+ disabled people and product teams, and document local definitions.
- ### 2. XPath — Simplified
+ **Severity, priority, reach, frequency, and confidence answer different
+ questions** — do not conflate them:
- Provide the shortest XPath that uniquely identifies the failing element.
- Prefer attribute-based selectors over absolute paths.
+ | Field | Question |
+ | --- | --- |
+ | Severity | How serious is the task-level consequence in *this* occurrence? |
+ | Priority | When should the team address it? |
+ | Reach | How many people/pages/components may be affected? |
+ | Frequency | How often does the occurrence appear? |
+ | Confidence | How certain is the finding/impact/cause understanding? |
- ```
- //button[@id="submit-payment"]
- //input[@name="card-number"]
- //div[@role="dialog"][@aria-labelledby="modal-title"]
- ```
+ **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.
- ### 3. XPath — Full DOM Path
+ ---
- Provide the complete ancestor chain for disambiguation or when the simplified
- XPath could match multiple elements.
+ ## Critical: Minimum Information for a Useful Report
- ```
- /html/body/main/section[@id="checkout"]/form[@id="payment-form"]/fieldset[2]/input[@name="card-number"]
- ```
+ Include when known and relevant — do not reject a report from a user for
+ lacking technical detail; a triager can add locators, standards mapping, or
+ a verification plan later.
- Automated tools must emit **both** XPath forms. The full path supports debugging
- in environments where IDs change dynamically (e.g. React, Angular).
+ | Field | What to record |
+ | --- | --- |
+ | Title | Component/location, failure, and task effect |
+ | Location and state | Safe URL/route, component name, build, and the state in which the problem appears |
+ | People affected | Access needs/interaction methods/AT confirmed or likely affected; more than one group when relevant |
+ | Evidence basis and confidence | User report / testing with disabled people / manual evaluation / automated result / reasoned inference, plus uncertainty |
+ | Task and impact | What the person is trying to do, how the barrier affects it, workaround quality/cost |
+ | Steps or conditions | The shortest reliable path, including preconditions |
+ | Expected result | The user-facing behavior that should occur |
+ | Actual result | What was observed, including relevant AT output |
+ | Environment | Only the browser/OS/AT/input/viewport/zoom/preferences/locale that affect the result |
+ | Evidence | A small redacted excerpt or accessible attachment when it helps |
- ### 4. HTML Snippet
+ ---
- Include the minimal HTML fragment that demonstrates the problem. Trim surrounding
- markup to the smallest context that still shows the issue.
+ ## Critical: Write a Specific Title
- ```html
- <!-- Bad: no accessible name -->
- <button>
- <img src="close.svg">
- </button>
+ Identify the component, failure, and consequence.
- <!-- Good: accessible name provided -->
- <button>
- <img src="close.svg" alt="Close dialog">
- </button>
- ```
+ **Good:** `Checkout: card error text is not associated with the field` /
+ `Account menu: keyboard focus moves behind the open dialog`
- Include parent elements only when the violation depends on the parent–child
- relationship (e.g. missing `<label>` for `<input>`).
+ **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.
- ### 5. WCAG Success Criterion
+ ---
- Cite the specific WCAG 2.1 or 2.2 Success Criterion violated, including its level.
+ ## Critical: Record Location and State Safely
- ```
- WCAG SC: 1.1.1 Non-text Content (Level A)
- WCAG SC: 4.1.2 Name, Role, Value (Level A)
- WCAG SC: 1.4.3 Contrast (Minimum) (Level AA)
+ ```text
+ 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
```
- ### 6. ACT Rule or Checker Rule
-
- Reference the rule from the testing tool or from the W3C ACT framework.
-
- ```
- Rule ID: image-alt
- Rule: Images must have alternate text
- Tool: axe-core 4.x
+ 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:**
- ACT Rule: 23a2a8 — Image button has accessible name
- URL: https://act-rules.github.io/rules/23a2a8
+ ```text
+ Unsafe: https://example.com/orders/847291?token=secret-value
+ Safe: https://example.com/orders/[test-order-id]
```
- When multiple tools flag the same issue, list all rule IDs.
-
- ### 7. Severity
+ Never include production credentials — provide an approved test account
+ through the organization's secure process.
- Assign a severity level using the taxonomy above. Use it consistently across
- all reports in a project. When multiple tools report the same violation at
- different severities, use the higher severity.
+ **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.
- ### 8. Frequency / Occurrence
+ ---
- Report how often the element appears on the page and across the site.
+ ## Critical: Preconditions and Steps to Reproduce
- ```
- Frequency: 1 instance on this page
- Frequency: Appears on every page in the main navigation
- Frequency: Found on 23 of 47 pages crawled (49%)
- ```
+ List only the steps needed to reach the failure, including input method and
+ AT command when they matter:
- For automated scans, include aggregate counts:
+ ```text
+ Preconditions:
+ - Signed in as a test customer
+ - Cart contains one item
+ - NVDA is running with Firefox
- ```json
- {
- "rule": "image-alt",
- "occurrences": 14,
- "pages_affected": 6,
- "total_pages_scanned": 50
- }
+ 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.
```
- Frequency informs prioritisation. A single critical failure may warrant immediate action; a low-severity issue across hundreds of pages may need a systematic fix.
-
- **Frequency amplifies effective severity.** A "Low" rated issue on every page or a top user task (sign-in, checkout, search) should be treated with higher urgency than its base severity suggests.
-
- | Situation | Suggested priority adjustment |
- |-----------|-------------------------------|
- | Low severity, appears on every page | Treat as Medium |
- | Medium severity, appears on every page | Treat as High |
- | Low/Medium severity, on a top-task page | Escalate by one severity level |
- | Low/Medium severity, on a high-traffic landing page | Escalate by one severity level |
+ 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.
---
- ## High: Recommended Additional Fields
-
- These fields are not always required but significantly improve report quality.
- **Omitting them is a High severity gap** when the issue is complex or the audience is unfamiliar
- with the codebase.
-
- ### Issue Summary (Title)
-
- Write a concise title: `[Component] — [Failure mode] ([WCAG SC])`.
-
- **Good:**
-
- * `Close button missing accessible name (WCAG 1.1.1)`
- * `Error message not associated with form field (WCAG 1.3.1)`
-
- **Avoid:**
-
- * `Accessibility issue found`
- * `Screen reader problem on checkout`
+ ## Critical: Separate Expected and Actual Results
- ### Description
+ Write expected behavior as an **outcome**, not a required implementation:
- Explain what is wrong and why it is a barrier for users with disabilities.
+ ```text
+ 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.
- ```
- The "Close" button in the cookie-consent dialog contains only a decorative SVG
- icon with no alt text, aria-label, or visible text. Screen reader users hear
- "button" with no indication of its purpose, making it impossible to dismiss the
- dialog by voice or from a screen reader virtual cursor.
+ 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.
```
- ### Steps to Reproduce
-
- Number the steps a developer can follow to see the failure.
-
- ```
- 1. Go to https://example.com/shop
- 2. Wait for the cookie consent banner to appear
- 3. Open NVDA (or VoiceOver on macOS)
- 4. Press Tab to move focus to the "X" button in the banner
- 5. Listen to what the screen reader announces
- ```
+ 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.
- For automated test output, include the command used:
+ ---
- ```bash
- npx axe https://example.com/shop --tags wcag2a,wcag2aa --reporter json
- ```
+ ## Critical: Identify People Affected — Never Guess a Diagnosis
- ### Expected Behaviour
+ 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.
- State what the correct experience should be.
+ | Evidence status | Meaning |
+ | --- | --- |
+ | **Reported or confirmed by affected people** | A disabled person reported it, or it was observed while disabled participants performed the task |
+ | **Observed through manual evaluation** | An evaluator reproduced it using the relevant method/setting/AT — evidence of behavior, not equivalent to testing with disabled people |
+ | **Likely** | Affected population and impact reasonably inferred but not confirmed with affected people |
+ | **Unknown or needs review** | From automation or technical inspection; user impact not yet established |
- ```
- Expected: Screen reader announces "Close cookie consent dialog, button"
- or equivalent meaningful label.
- ```
+ **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."
- ### Actual Behaviour
+ **Not useful:** "This affects blind people and violates WCAG."
- State what currently happens.
+ 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.
- ```
- Actual: Screen reader announces "button" only. No accessible name is provided.
- ```
+ ---
- ### Testing Environment
+ ## Serious: Record Only the Relevant Environment
- Specify the full stack. AT bugs are often environment-specific.
+ 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**:
- ```
- Browser: Chrome 124 / Firefox 126 / Safari 17.4
- OS: Windows 11 / macOS 14 / iOS 17
- Screen reader: NVDA 2024.1 / JAWS 2024 / VoiceOver
- Zoom level: 100% / 200%
- Tool: axe-core 4.9.1 / Accessibility Insights 2.47 / Pa11y 6.2
+ ```text
+ 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
```
- ### Impact Statement
-
- Describe which disability groups are affected and how.
+ 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).
- ```
- Impact: Blind and low-vision users relying on screen readers cannot identify
- or operate the close button. Users who rely on voice control software
- (e.g. Dragon NaturallySpeaking) cannot activate an unnamed button by
- speaking its label.
- ```
+ ---
- ### Suggested Fix
+ ## Serious: Add Technical Evidence Without Exposing Data
- Provide a concrete remediation when possible.
+ Technical evidence is optional when the observed behavior is already clear.
```html
- <!-- Current (broken) -->
- <button class="close-btn">
- <svg aria-hidden="true" ...></svg>
- </button>
-
- <!-- Fixed: Option A — aria-label -->
- <button class="close-btn" aria-label="Close cookie consent dialog">
- <svg aria-hidden="true" ...></svg>
- </button>
-
- <!-- Fixed: Option B — visually hidden text -->
- <button class="close-btn">
- <svg aria-hidden="true" ...></svg>
- <span class="visually-hidden">Close cookie consent dialog</span>
- </button>
+ <label for="card-number">Card number</label>
+ <input id="card-number" name="card-number">
+ <p id="card-number-error">Enter a card number.</p>
```
- ### Personalisation and Context
+ Explain what the excerpt demonstrates — here, the visible error isn't
+ programmatically associated with the field. Do not assume an excerpt shows
+ the entire computed accessibility tree.
- Accessibility failures are not always reproducible on every page load. Many issues only surface under specific user settings, device types, or navigation paths. Always record the personalisation state and context at the time of discovery.
+ **Before sharing HTML, DOM snapshots, logs, or screenshots, remove:** tokens/
+ cookies/hidden credentials; names/addresses/account data; private form field
+ values; unnecessary internal URLs or IDs. For screenshots/recordings:
+ describe the relevant content in the issue text; use arrows/markers plus
+ text, not color alone; provide captions/transcripts for video/audio; crop or
+ redact faces/names/private content.
- **Colour scheme and display preferences**
+ ---
- ```
- Colour scheme: Light mode / Dark mode / System default
- Forced Colors: Active (Windows High Contrast) / Inactive
- Contrast mode: Standard / Increased contrast (macOS)
- ```
+ ## Serious: Standards, Rules, and Test Results
- **CSS media features**
+ **WCAG mapping** — record the exact version, criterion, and level when known;
+ use `suspected`/`needs review` when uncertain; don't add criteria merely
+ because a tool lists them as tags:
- ```
- prefers-color-scheme: light / dark
- prefers-reduced-motion: reduce / no-preference
- prefers-contrast: more / less / forced / no-preference
- forced-colors: active / none
+ ```text
+ Standard: WCAG 2.2
+ Success Criterion: 1.3.1 Info and Relationships
+ Level: A
+ Relationship: Confirmed failure
```
- **Viewport and device type**
+ **Tool/rule information** for automated results:
- ```
- Viewport: 375 × 812 px (iPhone 14, Safari iOS 17)
- Viewport: 1440 × 900 px (MacBook Pro, Chrome 124)
- Device: Mobile — iOS 17 / Android 14
- Device: Desktop — Windows 11 / macOS 14
- Orientation: Portrait / Landscape
+ ```text
+ Tool and version: axe-core 4.9.1
+ Rule ID and version: button-name
+ Configuration: wcag2a, wcag2aa tags
+ Test method: Automated
+ Raw outcome: failed
+ Human review: Confirmed / Rejected / Needs review
```
- **Navigation path and UI state**
-
- ```
- Arrived via: Direct URL / Search results link / Internal navigation from [page]
- Preceded by: Clicked "Add to cart" on product page, then navigated to checkout
- UI state: Modal open / Accordion expanded / Dropdown active
- Login state: Authenticated (standard user role) / Guest / Admin
- ```
+ Keep a tool's impact/confidence value separate from the project's severity —
+ tool metadata is a heuristic, not the task/context/workaround/root-cause
+ assessment. **If using ACT Rules Format 1.1, preserve one of its outcomes**
+ (`inapplicable`, `passed`, `failed`, `cantTell`, `untested`) — send `cantTell`
+ results for human review; a `passed`/`inapplicable` result may still need
+ other tests before a WCAG conclusion.
---
- ## Moderate: Structured Report Templates
-
- ### Markdown Template (for GitHub Issues)
-
- ```markdown
- ## Accessibility Issue: [Brief Description]
-
- **Bug ID:** `[PREFIX-xxxxxxxx]` (instance) / `[PREFIX-xxxxxxxx]` (pattern)
- **URL:** [Full URL where issue was found]
- **XPath:** `[Shortest unique XPath]`
- **Full DOM path:** `[Full ancestor chain XPath]`
- **WCAG SC:** [SC number] — [SC name] (Level [A/AA/AAA])
- **Rule:** [Tool name] — [Rule ID]
- **Severity:** [Critical / High / Medium / Low]
- **Frequency:** [Number of instances; pages affected]
- **Screen type:** [desktop / mobile] | **Colour mode:** [light / dark]
-
- ### HTML Snippet
-
- ```html
- [Minimal failing HTML fragment]
- ```
-
- ### Description
-
- [Explain what is wrong and why it creates a barrier]
-
- ### Steps to Reproduce
+ ## Serious: Plan Complementary Testing and Verification
- 1. [Step 1]
- 2. [Step 2]
- 3. [Step 3]
+ Automated testing, manual evaluation, and testing with disabled people
+ answer different questions — state which methods are required, why, and
+ their limits.
- ### Expected Behaviour
+ * **Automated:** identifies machine-testable patterns and gives repeatable
+ regression coverage; cannot determine full user impact, usability, or
+ conformance. Preserve raw result/config; require human review before
+ treating as a confirmed user-facing barrier; don't treat an automated pass
+ as sufficient closure evidence.
+ * **Manual accessibility evaluation:** required when the result depends on
+ human judgment or interaction — keyboard operation, focus, screen reader
+ output, zoom/reflow, forced colors, labels/errors/status messages, and
+ relevant states. Test a risk-based set of environments, not every
+ combination for every issue.
+ * **Testing with disabled people:** examines real tasks and lived
+ interaction; can find barriers standards-based evaluation misses. Plan it
+ when: the task is critical (authentication, payment, health, safety,
+ public services); the barrier/fix has major or uncertain impact; the
+ component is complex/novel; workaround quality is unclear; reports from
+ disabled people conflict with technical results. Do not use disabled
+ participants to rediscover obvious known failures that should be fixed
+ first. One participant confirms that person's experience — don't treat
+ them as representative of an entire disability group. This does not
+ replace standards-based evaluation, and standards-based evaluation doesn't
+ replace learning directly from disabled people.
- [What should happen]
+ Record a verification plan: automated checks required/planned/completed;
+ manual checks required/planned/completed; relevant supported environments;
+ testing with disabled people required/planned/completed with rationale.
- ### Actual Behaviour
+ ---
- [What currently happens]
+ ## Moderate: Record Scope, Frequency, and Root Cause
- ### Testing Environment
+ ```text
+ Observed occurrences: 7
+ Pages checked: 12
+ Pages affected: 5
+ States checked: Default, error, disabled
+ Likely source: Shared address form component
+ Unchecked scope: Mobile app and authenticated administrator flow
+ ```
- | Item | Value |
- |---|---|
- | Browser | [name and version] |
- | OS | [name and version] |
- | Screen reader | [name and version, or N/A] |
- | Testing tool | [name and version] |
+ Don't extrapolate from a sample without saying it's an estimate — a
+ sitewide template defect and seven unrelated content errors may share a
+ count but need different work. **Group findings conservatively** — combine
+ occurrences only when they share the same remediation unit or confirmed root
+ cause; don't merge findings merely because they share a rule ID or similar selector.
- ### Impact
+ ---
- [Who is affected and how]
+ ## Suggested Fixes and Acceptance Criteria
- ### Suggested Fix (optional)
+ A suggested fix is optional — label it as a proposal; the responsible team
+ may know a safer source-level correction:
- [Code or prose describing the fix]
+ ```text
+ Suggested fix:
+ Associate the error message with the field and expose the invalid state after
+ validation.
```
- ### JSON Schema for Automated Tool Output
-
- Use this schema when scripts or CI pipelines emit machine-readable accessibility reports.
+ Acceptance criteria should describe **verifiable user-facing behavior**, not
+ just an attribute/selector/automated-rule result:
- ```json
- {
- "$schema": "https://json-schema.org/draft/2020-12/schema",
- "title": "AccessibilityIssue",
- "type": "object",
- "required": ["url", "wcag_sc", "severity", "rule_id", "xpath", "html_snippet"],
- "properties": {
- "instance_id": {
- "type": "string",
- "pattern": "^[A-Z0-9]+-[0-9a-f]{8}$",
- "examples": ["DRU-a3f1b2c4"],
- "description": "Stable identifier for this specific violation on this page. Hash of page path + CSS selector + rule ID + screen type."
- },
- "pattern_id": {
- "type": "string",
- "pattern": "^[A-Z0-9]+-[0-9a-f]{8}$",
- "examples": ["DRU-f7e3a1b2"],
- "description": "Stable identifier for the underlying template-level pattern across pages. Hash of CSS selector + rule ID + screen type (no page path)."
- },
- "screen_type": { "type": "string", "enum": ["desktop", "mobile"] },
- "color_mode": { "type": "string", "enum": ["light", "dark"], "default": "light" },
- "url": { "type": "string", "format": "uri" },
- "xpath": { "type": "string" },
- "xpath_full": { "type": "string" },
- "html_snippet": { "type": "string" },
- "wcag_sc": { "type": "string", "pattern": "^\\d\\.\\d+\\.\\d+$" },
- "wcag_level": { "type": "string", "enum": ["A", "AA", "AAA"] },
- "rule_id": { "type": "string" },
- "act_rule_id": { "type": "string" },
- "tool": { "type": "string" },
- "severity": { "type": "string", "enum": ["critical", "high", "medium", "low"] },
- "frequency": {
- "type": "object",
- "properties": {
- "instances_on_page": { "type": "integer" },
- "pages_affected": { "type": "integer" },
- "total_pages_scanned": { "type": "integer" }
- }
- },
- "summary": { "type": "string" },
- "description": { "type": "string" },
- "impact": { "type": "array", "items": { "type": "string" } },
- "environment": {
- "type": "object",
- "properties": {
- "browser": { "type": "string" },
- "os": { "type": "string" },
- "screen_reader": { "type": "string" },
- "zoom_level": { "type": "string" }
- }
- },
- "suggested_fix": { "type": "string" },
- "steps_to_reproduce": { "type": "array", "items": { "type": "string" } }
- }
- }
+ ```text
+ - Submitting the empty field identifies the card number error in text.
+ - The field exposes the error association and invalid state programmatically.
+ - Keyboard focus remains predictable.
+ - The original interaction is manually retested.
+ - Testing with disabled people is completed when required by the verification plan.
```
- ### Example JSON Report (axe-core output mapped to schema)
+ ---
- ```json
- {
- "instance_id": "DRU-a3f1b2c4",
- "pattern_id": "DRU-f7e3a1b2",
- "screen_type": "desktop",
- "color_mode": "light",
- "url": "https://example.com/checkout?step=2",
- "xpath": "//button[contains(@class,'close-btn')]",
- "xpath_full": "/html/body/div[@id='cookie-banner']/button[contains(@class,'close-btn')]",
- "html_snippet": "<button class=\"close-btn\"><svg aria-hidden=\"true\"></svg></button>",
- "wcag_sc": "4.1.2",
- "wcag_level": "A",
- "rule_id": "button-name",
- "act_rule_id": "97a4e1",
- "tool": "axe-core 4.9.1",
- "severity": "critical",
- "frequency": { "instances_on_page": 1, "pages_affected": 12, "total_pages_scanned": 50 },
- "summary": "Close button missing accessible name (WCAG 4.1.2)",
- "description": "The cookie consent close button contains only an SVG icon with no accessible name.",
- "impact": ["blind", "low-vision", "voice-control"],
- "environment": { "browser": "Chrome 124", "os": "Windows 11", "screen_reader": "NVDA 2024.1", "zoom_level": "100%" },
- "suggested_fix": "<button class=\"close-btn\" aria-label=\"Close cookie consent dialog\"><svg aria-hidden=\"true\"></svg></button>",
- "steps_to_reproduce": [
- "Go to https://example.com/checkout?step=2",
- "Wait for the cookie consent banner to appear",
- "Open NVDA and press Tab to reach the close button",
- "Observe that NVDA announces 'button' with no label"
- ]
- }
- ```
+ ## Markdown Issue Template
- ### EARL: Evaluation and Report Language
+ ```markdown
+ ## Accessibility finding
- [EARL (Evaluation and Report Language)](https://www.w3.org/WAI/standards-guidelines/earl/) is a W3C standard for expressing test results in a machine-readable format. Use EARL when you need interoperable, tool-agnostic reports that can be processed by different systems — for example, aggregating results from multiple tools, feeding a compliance dashboard, or archiving audit evidence.
+ ### Summary
+ [Component or location: failure and task effect]
- ```turtle
- @prefix earl: <http://www.w3.org/ns/earl#> .
- @prefix dcterms: <http://purl.org/dc/terms/> .
- @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+ ### Location and state
+ - Page or route:
+ - Build or commit:
+ - Component:
+ - Preconditions and UI state:
+ - Safe locator (optional):
- [] a earl:Assertion ;
- earl:assertedBy <https://example.com/tools/axe-runner> ;
- earl:subject <https://example.com/checkout?step=2> ;
- earl:test <http://www.w3.org/TR/WCAG21/#non-text-content> ;
- earl:result [
- a earl:TestResult ;
- earl:outcome earl:failed ;
- dcterms:description "Close button contains only an SVG icon with no accessible name." ;
- dcterms:date "2025-06-01T10:30:00Z"^^xsd:dateTime
- ] ;
- earl:mode earl:automatic .
- ```
+ ### Steps or conditions
+ 1.
+ 2.
- | Term | Meaning |
- |------|---------|
- | `earl:Assertion` | A single test result (subject + test + outcome) |
- | `earl:subject` | The URL or resource that was tested |
- | `earl:test` | The criterion or rule being tested (WCAG SC, ACT rule, etc.) |
- | `earl:outcome` | `earl:passed`, `earl:failed`, `earl:cantTell`, `earl:inapplicable`, or `earl:untested` |
- | `earl:mode` | How the test was performed: `earl:automatic`, `earl:manual`, or `earl:semiAuto` |
- | `earl:assertedBy` | The tool or person that produced the assertion |
+ ### Expected result
+ [Describe the user-facing outcome.]
- EARL output can be produced by [Alfa](https://github.com/Siteimprove/alfa), [Axe Reporter EARL](https://github.com/dequelabs/axe-reporter-earl), and [ACT-Rules implementations](https://act-rules.github.io/). The W3C [WCAG-EM Report Tool](https://www.w3.org/WAI/eval/report-tool/) also exports EARL.
+ ### Actual result
+ [Describe what was observed.]
- ---
+ ### People affected and impact
+ - People confirmed or likely to be affected:
+ - Relevant access needs, interaction methods, or assistive technologies:
+ - Affected task:
+ - Consequence:
+ - Workaround and its cost, if any:
+ - Evidence basis: User report / Testing with disabled people / Manual evaluation / Automated result / Reasoned inference
+ - Confidence: Confirmed for reported scope / Observed / Likely / Unknown
+ - Scope limits or uncertainty:
- ## Guidance for Automated Tools and AI Agents
+ ### Relevant environment
+ - Test date:
+ - Browser and operating system:
+ - Assistive technology and version:
+ - Input method:
+ - Viewport, zoom, text size, and orientation:
+ - Active preferences or display modes:
- Apply these additional rules when scripts or AI agents generate reports.
+ ### Evidence
+ [Small redacted excerpt, attachment description, or link to protected evidence.]
- ### 5.1 Always Emit Both XPath Forms
+ ### Standards and tests (optional)
+ - WCAG version, success criterion, and level:
+ - Relationship: Confirmed / Suspected / Needs review
+ - Tool, rule, version, and configuration:
- Emit both the simplified XPath (shortest unique selector) and the full DOM path XPath in every violation. The simplified form aids human readability; the full form aids deterministic replay.
+ ### Verification plan
+ - Automated checks: Required / Not required / Planned / Completed
+ - Manual checks: Required / Not required / Planned / Completed
+ - Testing with disabled people: Required / Not required / Not yet determined / Planned / Completed
+ - Rationale:
- ### 5.2 Deduplicate Before Reporting
+ ### Scope and source
+ - Occurrences and sample checked:
+ - Suspected or confirmed root cause:
- Group violations by rule and normalised XPath before filing. Report one issue with `frequency.instances_on_page` set to the count rather than filing hundreds of identical issues.
+ ### Suggested fix (optional)
+ [Describe a possible approach without replacing acceptance criteria.]
- ```python
- # Pseudocode: aggregate duplicates
- issues = defaultdict(list)
- for violation in raw_results:
- key = (violation["rule_id"], violation["wcag_sc"], normalize_xpath(violation["xpath"]))
- issues[key].append(violation)
+ ### Acceptance criteria
+ - [ ] The reported user-facing barrier is no longer present.
+ - [ ] The original environment and interaction have been manually retested.
+ - [ ] An automated pass was not treated as sufficient evidence on its own.
+ - [ ] Testing with disabled people was completed when required by the verification plan.
+ - [ ] The impact statement does not go beyond the available evidence.
+ - [ ] Appropriate regression coverage has been added or updated.
- for key, group in issues.items():
- report_issue(group[0], frequency=len(group))
+ ### Privacy and attachment check
+ - [ ] Secrets, personal data, and private content have been removed.
+ - [ ] Screenshots are described and recordings have captions or transcripts.
```
- ### 5.3 Map Tool Output to WCAG Criteria
-
- Every automated rule should map to at least one WCAG SC. Maintain a rule-to-WCAG mapping table in your project so that reports consistently include the criterion.
-
- ### 5.4 Preserve the HTML Snippet
-
- Extract the failing element's outer HTML at scan time. DOM content may change after the scan. The preserved snippet allows verification of whether a deployed fix addresses the original issue.
-
- ### 5.5 Assign Severity Consistently
-
- Use a single severity taxonomy across all reports and all tools. If multiple tools report the same violation at different severities, use the higher severity.
+ ---
- ### 5.6 Include Confidence Score for Automated Detections
+ ## Machine-Readable Finding Schema
- Include a `confidence` field when the tool provides it, especially for violations that require manual confirmation (e.g. colour contrast over a gradient):
+ Machine-readable output can support imports, reporting, and regression
+ analysis — it must not require fields that don't exist for manual or
+ user-reported findings.
```json
{
- "rule_id": "color-contrast",
- "confidence": "needs-review",
- "note": "Background colour is a CSS gradient; automated contrast check may be inaccurate. Manual verification required."
+ "schema_version": "1.1",
+ "title": "Checkout: card error text is not associated with the field",
+ "location": {
+ "route": "/checkout/payment",
+ "component": "Payment form",
+ "locator": { "type": "stable-css", "value": "[data-component='payment-form']" }
+ },
+ "expected": "The field exposes its label, invalid state, and associated error programmatically.",
+ "actual": "A visible error appears, but the field has no error association.",
+ "affected_people": [{
+ "description": "People who use screen readers",
+ "status": "likely",
+ "evidence_basis": "manual-evaluation",
+ "scope_limit": "Observed with NVDA and Firefox; not yet evaluated with disabled participants"
+ }],
+ "standards": [{ "standard": "WCAG 2.2", "criterion": "1.3.1", "level": "A", "relationship": "confirmed-failure" }],
+ "test_result": { "method": "manual", "status": "confirmed" },
+ "verification": {
+ "automated": { "required": true, "status": "planned" },
+ "manual": { "required": true, "status": "completed-for-original-finding" },
+ "testing_with_disabled_people": { "required": true, "status": "planned" }
+ }
}
```
- ### 5.7 AI Agent Prompt for Filing a GitHub Issue
-
- When an AI agent files a GitHub Issue from scan output, use this prompt structure:
-
- ```
- You are an accessibility engineer filing a GitHub Issue.
- Given the following JSON violation report, create a well-structured
- GitHub Issue using the Markdown template above.
-
- Rules:
- - Use the issue summary as the title.
- - Populate all fields; write "N/A" only if the data is genuinely absent.
- - Do not paraphrase WCAG criterion names; use the exact W3C wording.
- - Include the HTML snippet in a fenced code block.
- - Add the label "accessibility" to the issue.
-
- Violation data:
- [INSERT JSON HERE]
-
- Template:
- [INSERT MARKDOWN TEMPLATE HERE]
- ```
-
- ### 5.8 Generate Stable Unique Identifiers for Violations
-
- Assigning a stable identifier to each violation enables automated pipelines to track fixes, detect regressions, and deduplicate across scan runs.
-
- **Two levels of identification**
-
- | Level | Inputs to hash | Purpose |
- |-------|---------------|---------|
- | `instance_id` | page path + CSS selector + rule ID + screen type | Identifies one occurrence on one specific page |
- | `pattern_id` | CSS selector + rule ID + screen type | Identifies the recurring pattern across pages |
-
- **Identifier format:** `[PREFIX]-[8-char-hex]` (e.g. `DRU-a3f1b2c4`)
-
- The prefix is project-specific (e.g. `DRU` for Drupal, `A11Y` as a generic default). Infer screen type from viewport width: `< 768 px = mobile`, `>= 768 px = desktop`. Default `color_mode` to `light`.
+ Version the schema, document null/omitted values, validate imports, and plan
+ migrations. Preserve a tool's raw output separately when exact round-trip
+ fidelity matters.
- **JavaScript implementation (Node.js)**
+ ---
- ```javascript
- const crypto = require('crypto');
+ ## Automation and AI Guardrails
- const MOBILE_BREAKPOINT = 768;
+ Automation can collect and organize evidence — it should **not invent
+ certainty, affected populations, or lived experience.**
- function detectScreenType(viewport) {
- return viewport && viewport.width < MOBILE_BREAKPOINT ? 'mobile' : 'desktop';
- }
+ An automated/AI-assisted workflow should:
+ 1. Preserve the raw result, tool/rule version, config, time, and tested URL/route
+ 2. Label the method: automated / semi-automated / manual / user-reported / testing with disabled people
+ 3. Retain the tool's original outcome; route `cantTell`/uncertain results to a review queue
+ 4. Remove credentials and personal data before sending evidence to another system
+ 5. **Avoid generating a WCAG mapping, affected population, impact statement,
+ severity, or root cause when the evidence doesn't support it**
+ 6. Distinguish confirmed participant evidence from manual observation and reasoned inference
+ 7. Require human validation per the project's risk/triage rules before
+ creating high-impact work or conformance claims
+ 8. Group occurrences only when the remediation unit or root cause is sufficiently established
+ 9. Update an existing issue with new occurrences instead of silently discarding duplicates
+ 10. Preserve disagreements between a tool result, evaluator review, and participant feedback
+ 11. Require manual user-facing retesting before closure when automation can't verify the outcome
+ 12. Record whether testing with disabled people is required/planned/completed with rationale
+ 13. **Never claim testing with disabled people occurred unless it actually did**
- function normalizeSelector(target) {
- return Array.isArray(target) ? target.join(' > ') : String(target);
- }
+ Do not close an issue only because the original automated rule passes — the
+ implementation may have changed the selector, hidden the tested node, or
+ introduced a different barrier.
- function generateInstanceId(pagePath, selector, ruleId, screenType, prefix = 'A11Y') {
- const input = `${pagePath}|${selector}|${ruleId}|${screenType}`;
- const hash = crypto.createHash('sha256').update(input).digest('hex').slice(0, 8);
- return `${prefix}-${hash}`;
- }
+ **Deduplication:** use the issue tracker's ID as the durable identity — a
+ scan fingerprint can help correlate repeated results but is not a permanent
+ bug ID. If fingerprints are used: version the algorithm; include tool/rule
+ version; normalize URLs/selectors carefully; expect fingerprints to change
+ when markup changes; do not infer mobile/desktop from a width threshold;
+ don't merge results solely because hashes match.
- function generatePatternId(selector, ruleId, screenType, prefix = 'A11Y') {
- const input = `${selector}|${ruleId}|${screenType}`;
- const hash = crypto.createHash('sha256').update(input).digest('hex').slice(0, 8);
- return `${prefix}-${hash}`;
- }
+ ---
- function annotateViolations(axeResults, prefix = 'A11Y', colorMode = 'light') {
- const pagePath = new URL(axeResults.url).pathname;
- const viewport = { width: axeResults.testEnvironment.windowWidth };
- const screenType = detectScreenType(viewport);
+ ## Finding Lifecycle
- return axeResults.violations.flatMap(violation =>
- violation.nodes.map(node => {
- const selector = normalizeSelector(node.target);
- return {
- ...node,
- rule_id: violation.id,
- instance_id: generateInstanceId(pagePath, selector, violation.id, screenType, prefix),
- pattern_id: generatePatternId(selector, violation.id, screenType, prefix),
- screen_type: screenType,
- color_mode: colorMode,
- };
- })
- );
- }
- ```
+ 1. **Capture:** record barrier, location, state, people affected, impact, evidence basis, safe evidence
+ 2. **Triage:** confirm the result when possible, identify missing context, separate severity from priority
+ 3. **Isolate:** find the source component/template/token/process producing the occurrences
+ 4. **Assign:** an owner who can change the source, not just the individual page
+ 5. **Define:** agree on user-facing acceptance criteria, supported environments, verification plan
+ 6. **Correct:** fix the source; update docs/examples/content guidance
+ 7. **Prevent:** add proportionate regression coverage
+ 8. **Retest:** repeat the original interaction and relevant adjacent states/preferences/environments
+ 9. **Evaluate with disabled people:** complete planned participant testing where required
+ 10. **Close:** record what changed, verification evidence, remaining limitations, follow-up
- The CSS selector (from `node.target`) is used in the hash rather than the XPath because axe-core reports it natively and it is stable across XPath conversion logic changes. Include both in the report; use only the CSS selector as the hash input.
+ If a fix is partial, record the remaining occurrences/environments rather
+ than closing the broader issue as complete.
---
- ## Reporting to External Organisations
+ ## Reporting to External Organizations
- When reporting accessibility barriers to a third-party (vendor, government,
- public website), adapt the report to the audience:
+ Look first for an accessibility statement, `accessibility@` contact, or
+ feedback form. Write for the person receiving the report, who may not be an
+ accessibility specialist. Lead with the page/feature, the barrier observed,
+ affected people/methods if known and safe to share, the task it prevents,
+ concise steps and environment, and a request for acknowledgement. WCAG
+ references and suggested fixes are optional. Do not include passwords,
+ personal information, or sensitive documents — and don't require a reporter
+ to disclose a diagnosis. There is no universal response deadline; appropriate
+ follow-up depends on the organization/contract/jurisdiction (this is not
+ legal advice).
- 1. **Check for an existing channel** — look for an accessibility statement,
- `accessibility@` email, or feedback form.
- 2. **Be specific** — provide the exact page, element, and barrier.
- 3. **Focus on impact** — explain who is affected and what they cannot complete.
- 4. **Reference WCAG and applicable law** — cite the specific criterion and relevant
- legislation (Section 508, EN 301 549, AODA, etc.).
- 5. **Offer to help** — suggest the fix; organisations act faster when a solution
- accompanies the problem.
- 6. **Set a timeline** — request acknowledgement within a defined period (e.g.
- 10 business days) and a remediation timeline for critical issues.
- 7. **Escalate if necessary** — contact the relevant enforcement body or ombudsman
- if no response is received.
+ ```text
+ Subject: Accessibility barrier in [page or feature]
- ### External Report Email Template
+ Hello,
- ```
- Subject: Accessibility barrier on [Page Title] — [WCAG SC]
+ I encountered an accessibility barrier in [page or feature].
- Dear [Organisation Name] Accessibility Team,
+ Location: [safe URL, route, or feature name]
+ Task: [what you were trying to do]
+ Barrier: [what happened]
+ People or interaction methods affected, if known: [description]
+ Impact: [how this affected the task]
- I am writing to report an accessibility barrier I encountered on your website.
+ Steps or conditions:
+ 1. [Step]
- Page: [Full URL]
- Issue: [One-sentence description of the barrier]
- Impact: [Who is affected and what they cannot do]
- WCAG SC: [SC number and name, Level]
+ Expected: [user-facing outcome]
+ Actual: [observed result]
- Steps to reproduce:
- 1. [Step 1]
- 2. [Step 2]
+ Relevant environment: [only details that affect the result]
+ WCAG reference, if known: [version, criterion, and level]
- Expected: [What should happen]
- Actual: [What happens instead]
+ Please acknowledge this report and let me know how I can follow its status.
- Suggested fix: [Brief description or code snippet if appropriate]
+ Thank you.
+ ```
- I am available to provide further information or test a proposed fix.
- I would appreciate acknowledgement within 10 business days and a
- remediation timeline for this critical barrier.
+ ---
- Thank you for your attention to this matter.
+ ## Common Reporting Failures
- [Your name / organisation]
- ```
+ * Requiring a full DOM XPath, HTML excerpt, tool rule, or WCAG criterion before accepting a report
+ * Copying an exact URL that contains a token or personal data
+ * Reporting only "fails WCAG" without describing the user-facing behavior
+ * Inferring a disability group or population-wide impact from a WCAG criterion or tool rule
+ * Treating a tool result as a confirmed defect or a conformance conclusion
+ * Treating an evaluator's use of assistive technology as equivalent to testing with disabled people
+ * **Assigning severity from a tool's impact field, or automatically increasing severity by occurrence count** (that's a priority signal, not severity)
+ * Claiming a viewport width proves the physical device type
+ * Listing every AT version instead of the environment actually tested
+ * Merging unrelated occurrences because the rule ID or selector looks similar
+ * Prescribing a code change without behavior-based acceptance criteria
+ * Skipping manual testing because an automated check passes
+ * Closing after a code merge or automated pass without repeating the original interaction
+ * Using disabled participants to rediscover known basic failures that should have been corrected first
+ * Generalizing one participant's experience to an entire disability group
+ * Disclosing a reporter's or participant's diagnosis, identity, or private content without informed permission
---
## Pre-Filing Quality Checklist
- Before filing or submitting an accessibility bug report, verify each item:
-
- * [ ] URL is exact and publicly accessible (or a test account is provided)
- * [ ] Unique bug identifiers (`instance_id` and `pattern_id`) are generated and included
- * [ ] Screen type (`desktop` / `mobile`) and colour mode (`light` / `dark`) are recorded
- * [ ] XPath (simplified) uniquely identifies the element
- * [ ] Full DOM path XPath is included
- * [ ] HTML snippet is minimal and self-contained
- * [ ] WCAG SC is cited with the correct level (A/AA/AAA)
- * [ ] Automated rule ID is included (axe-core, ACT, or tool-specific)
- * [ ] Severity is assigned using the project's standard taxonomy
- * [ ] Frequency / occurrence count is provided
- * [ ] Summary title follows `[Component] — [Failure] ([WCAG SC])` pattern
- * [ ] Steps to reproduce are numbered and complete
- * [ ] Expected and actual behaviours are stated separately
- * [ ] Testing environment (browser, OS, AT, tool) is documented
- * [ ] Personalisation context is recorded (colour scheme, CSS media features, viewport, navigation path)
- * [ ] Impact on specific disability groups is described
- * [ ] Duplicate violations are aggregated, not filed individually
- * [ ] For automated output: confidence level is included where relevant
+ * [ ] Location and state recorded with secrets/tokens/personal data removed from URLs
+ * [ ] Title identifies component, failure, and task effect (not "Accessibility issue")
+ * [ ] Steps to reproduce are numbered, minimal, and complete
+ * [ ] Expected and actual results stated as user-facing outcomes, not implementation prescriptions
+ * [ ] People affected described only as specifically as the evidence allows — no guessed diagnosis
+ * [ ] Evidence basis and confidence level stated (user report / testing with disabled people / manual / automated / inference)
+ * [ ] Only relevant environment fields recorded — not a generic browser/AT matrix
+ * [ ] Technical evidence (HTML/screenshots/logs) redacted of secrets and personal data
+ * [ ] WCAG mapping marked confirmed/suspected/needs review as appropriate
+ * [ ] Severity assigned from task impact — not from tool output or occurrence count
+ * [ ] Frequency/reach recorded separately as a priority factor, not folded into severity
+ * [ ] Verification plan states which of automated/manual/disabled-people testing is required and why
+ * [ ] Findings grouped only when remediation unit or root cause is confirmed shared
---
## Commonly Violated WCAG Criteria
| SC | Name | Level | Common Violations |
| --- | --- | --- | --- |
| 1.1.1 | Non-text Content | A | Missing `alt` on images, unlabelled icon buttons |
| 1.3.1 | Info and Relationships | A | Unsemantic heading structure, missing form labels |
- | 1.3.3 | Sensory Characteristics | A | Instructions that rely on shape, colour, or position only |
+ | 1.3.3 | Sensory Characteristics | A | Instructions relying on shape, colour, or position only |
| 1.4.1 | Use of Color | A | Status conveyed by colour alone |
- | 1.4.3 | Contrast (Minimum) | AA | Text below 4.5:1 contrast ratio |
+ | 1.4.3 | Contrast Minimum | AA | Text below 4.5:1 contrast ratio |
| 1.4.4 | Resize Text | AA | Page breaks at 200% zoom |
| 1.4.11 | Non-text Contrast | AA | UI component borders below 3:1 contrast |
| 2.1.1 | Keyboard | A | Elements not reachable or operable by keyboard |
| 2.4.3 | Focus Order | A | Illogical tab order, focus moves unexpectedly |
| 2.4.7 | Focus Visible | AA | No visible focus indicator |
| 3.3.1 | Error Identification | A | Form errors not described in text |
| 3.3.2 | Labels or Instructions | A | Form fields without visible labels |
| 4.1.2 | Name, Role, Value | A | Custom widgets missing ARIA name, role, or state |
| 4.1.3 | Status Messages | AA | Notifications not exposed to screen readers |
For the complete list, see the [WCAG 2.2 Quick Reference](https://www.w3.org/WAI/WCAG22/quickref/).
---
## References
* [Full best practices guide](https://github.com/mgifford/ACCESSIBILITY.md/blob/main/examples/ACCESSIBILITY_BUG_REPORTING_BEST_PRACTICES.md)
- * [Writing Impactful Accessibility Reports](https://medium.com/openconcept-stories/writing-impactful-accessibility-reports-d6cdd84356fd) — Mike Gifford, OpenConcept
- * [How to Fix Accessibility Bugs](https://github.com/readme/guides/fix-accessibility-bugs) — Mike Gifford, GitHub README Guides
- * [Contacting Organizations about Inaccessible Websites](https://www.w3.org/WAI/teach-advocate/contact-inaccessible-websites/) — W3C WAI
- * [How to Report Accessibility Bugs](https://www.digitala11y.com/how-where-to-report-accessibility-bugs/) — DigitalA11y
- * [Template: Reporting Accessibility Issues](https://accessibility.huit.harvard.edu/template-reporting-accessibility-issues) — Harvard University
- * [ACT Rules Community Group](https://act-rules.github.io/) — W3C
- * [Accessibility Insights for Web](https://github.com/microsoft/accessibility-insights-web) — Microsoft
- * [EARL: Evaluation and Report Language](https://www.w3.org/WAI/standards-guidelines/earl/) — W3C WAI
+ * [Website Accessibility Conformance Evaluation Methodology (WCAG-EM)](https://www.w3.org/WAI/test-evaluate/conformance/wcag-em/)
+ * [Involving Users in Evaluating Web Accessibility](https://www.w3.org/WAI/test-evaluate/involving-users/)
+ * [Using Combined Expertise to Evaluate Web Accessibility](https://www.w3.org/WAI/test-evaluate/combined-expertise/)
+ * [Contacting Organizations about Inaccessible Websites](https://www.w3.org/WAI/teach-advocate/contact-inaccessible-websites/)
+ * [EARL 1.0 Schema](https://www.w3.org/TR/EARL10-Schema/) — non-normative W3C Working Group Note, not required for routine reports
+ * [ACT Rules Format 1.1](https://www.w3.org/TR/act-rules-format/)
* [WCAG 2.2 Quick Reference](https://www.w3.org/WAI/WCAG22/quickref/)