How to write an accessibility bug ticket your development team can act on

June 2026 | BarrierScan

Getting an accessibility scan report is step one. The step that actually fixes things is turning the report findings into developer tickets that someone can pick up without asking you six follow-up questions. Most accessibility tickets fail at that step: they are either too vague ("make the site accessible") or they dump raw WCAG technical language with no context about where the problem lives or what the fix looks like.

This guide walks through what goes into a well-structured accessibility bug ticket, with complete examples for the barrier types that appear most often on e-commerce stores.

What makes an accessibility ticket different from a regular bug

A standard bug ticket describes observable behavior: "the checkout button is not working." An accessibility bug often describes behavior that is invisible to someone using a mouse: "a screen reader user cannot identify what this button does because it has no accessible name." The developer cannot reproduce the problem by clicking around the way they would with a visual bug. They need to know exactly what element is affected, what assistive technology would encounter, and what the correct markup looks like.

Good accessibility tickets do three things a vague ticket does not:

1. They identify the exact element or component (not just "a button on the product page").
2. They include the current broken code and the corrected version.
3. They explain the user-facing impact in plain terms, so the developer understands what they are fixing and why.

The essential fields

An accessibility bug ticket needs these fields. Most issue trackers (Linear, Jira, GitHub Issues, Shortcut) support them in some form.

• Title. A single sentence naming the component and the violation: "Product image carousel buttons have no accessible name" or "Checkout form: city field is missing an HTML label."
• Page or template. The URL of the affected page, or the name of the template/component if the issue appears across multiple pages (e.g., "product card component, all collection pages").
• Severity. Critical, serious, moderate, or minor. This tells the developer where to slot the work.
• WCAG criterion. The specific success criterion being violated (e.g., "WCAG 2.1 SC 4.1.2 Name, Role, Value"). You can pull this directly from the scan report. The developer does not need to read the full WCAG spec to fix the issue, but the reference is useful if they want to understand the rule.
• How to reproduce. Steps to observe the problem. For most accessibility issues this means: navigate to the page, identify the element (by visual description or CSS selector), use a keyboard or screen reader to interact with it, and observe the failure. Even a one-sentence version ("Tab to the cart icon button; VoiceOver announces 'button' with no label") is far better than nothing.
• Current code. The relevant snippet of what the scanner found. Pull this from the "before" code example in the scan report.
• Expected code. The fix. Pull this from the "after" code example in the scan report or from the fix guidance section.
• User impact. One sentence explaining who is blocked and how: "Screen reader users cannot identify this button and may not be able to use the feature at all."

Complete example: unlabeled icon button

This is the most common critical finding on e-commerce stores. Wishlist, cart, and search buttons built with icons and no visible text frequently have no accessible name, making them invisible to screen readers.

<button class="wishlist-btn">
  <svg viewBox="0 0 24 24" aria-hidden="true">
    <path d="M12 21.35l-1.45-1.32C5.4 ..." />
  </svg>
</button>

<button class="wishlist-btn" aria-label="Add to wishlist">
  <svg viewBox="0 0 24 24" aria-hidden="true">
    <path d="M12 21.35l-1.45-1.32C5.4 ..." />
  </svg>
</button>

Complete example: form field missing a label

Missing form labels are the other critical finding that comes up on nearly every e-commerce store with a newsletter signup, account registration, or checkout form. Placeholder text is not a substitute for an HTML label -- it disappears when the user starts typing, and screen readers do not reliably read placeholder text as a field label.

<input
  type="email"
  name="email"
  placeholder="Enter your email"
  class="newsletter-input"
>

<label for="newsletter-email">Email address</label>
<input
  type="email"
  id="newsletter-email"
  name="email"
  placeholder="Enter your email"
  class="newsletter-input"
>

<label for="newsletter-email" class="visually-hidden">Email address</label>
<input
  type="email"
  id="newsletter-email"
  name="email"
  placeholder="Enter your email"
  class="newsletter-input"
>

/* CSS for visually-hidden class */
.visually-hidden {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

Common mistakes

• "Fix WCAG issues on the checkout page." Which issues? All of them, or the ones in the report? WCAG has 78 success criteria. A ticket that names a WCAG level without naming a specific violation type is not actionable.
• "Make the site accessible." This is a project, not a ticket. Break accessibility work into individual component-level tickets. Developers can estimate, track, and close individual tickets. They cannot estimate or close "make accessible."
• No code example. The developer needs to find the broken element in the codebase. A code snippet from the rendered page is the fastest way for them to locate the template or component that needs fixing. Without it, they are searching through code by guessing what element might match a vague description.
• No reproduction steps. Accessibility bugs require a non-visual reproduction path. "I can see the button is a heart icon" does not help the developer understand what the screen reader hears. Even "Tab to the button and listen to VoiceOver" is better than nothing.
• Grouping unrelated findings in one ticket. A ticket that says "fix 23 unlabeled buttons" cannot be estimated, assigned, or closed at a useful granularity. Group by component (all product card button issues in one ticket, all checkout form label issues in another), not by violation type across the whole site.

A reusable ticket template

Copy this into your issue tracker as a template. Most platforms (Linear, Jira, Notion) support saved templates for recurring work types.

**Title:** [Component name]: [what is broken] -- [page or template]

**Page / component:** [URL or template name; note if the issue appears across multiple pages]

**Severity:** [Critical / Serious / Moderate / Minor]

**WCAG criterion:** [e.g., WCAG 2.1 SC 4.1.2 Name, Role, Value]

**How to reproduce:**
1. Open [URL]
2. [Navigate to the element: Tab key, or describe its location]
3. [Observe: what a screen reader announces, or what fails on keyboard-only navigation]

**Current code:**
```
[paste the "before" snippet from the scan report]
```

**Expected code:**
```
[paste the "after" snippet from the scan report]
```

**User impact:** [One sentence: who is affected and how]

**Instance count:** [How many instances on the site; note if fixing one template resolves all]

Tracking fixes with monitoring

Once tickets are filed and fixes are deployed, the question is whether the fix actually worked in production. Accessibility fixes fail silently more often than regular bug fixes: the attribute gets added locally but does not make it through a build step, or the fix is applied to the wrong variant of a component template, or a deploy overwrites it two weeks later.

An automated monitoring subscription handles this by rescanning on a schedule and comparing each scan to the previous one. The diff report shows what was fixed (the scanner no longer sees the violation), what is new (a finding that was not present before, possibly introduced by a recent deploy), and what regressed (a finding that was fixed in a prior scan and has reappeared). That removes the manual follow-up work of checking whether a fix landed, and it catches regressions before they accumulate into a new report's worth of work.

If you received a BarrierScan report and want help structuring tickets from the findings, reply to the email you received it in. We can help identify which findings trace to the same component and how to group them for your development workflow.