← A11y Tickets

WCAG Issue Ticket Template

WCAG references help when they point developers toward a fix. They become noise when they are pasted without a user impact, page context, or retest path.

Turn one WCAG row into a ticket

Open a checkout contact-field example in the generator with WCAG references, field evidence, expected behavior, retest steps, and acceptance criteria already filled in.

Open the WCAG row in the generator

Recommended structure

  1. Impact first: describe the task that is blocked, confusing, or slower.
  2. Then evidence: include the page, component, selector, assistive technology, or raw tool output.
  3. Then WCAG: cite likely success criteria to verify, not decorative labels.
  4. Then fix and retest: provide implementation direction and acceptance criteria.

WCAG ticket skeleton

# [Severity] Flow: user-facing problem

## User impact
Who is affected, and what task becomes harder or impossible?

## Evidence
- Page / component:
- Assistive technology or tool:
- Observed behavior:
- Raw finding / selector:

## Likely WCAG references to verify
- 1.3.1 Info and Relationships — if visual structure is not available programmatically.
- 2.1.1 Keyboard — if a control or flow cannot be operated by keyboard.
- 2.4.3 Focus Order — if focus moves unpredictably or stays behind an overlay.
- 3.3.1 Error Identification — if errors are not communicated clearly.
- 4.1.2 Name, Role, Value — if controls do not expose their purpose or state.
- 4.1.3 Status Messages — if updates appear visually but are not announced.

## Fix direction
What should change in markup, focus behavior, labels, state, or validation handling?

## Acceptance criteria
What must be true before this ticket can close?

Example wording

Suggested WCAG references to verify:
- 4.1.2 Name, Role, Value — the button does not expose an accessible name.
- 3.3.2 Labels or Instructions — the input purpose is not clear without visual context.

User impact:
Screen reader users cannot determine what information is required and may abandon the form.

Acceptance criteria:
- The field has a visible label or an equivalent accessible name.
- The error/help text is associated with the input.
- The flow can be completed with NVDA and keyboard only.

Related resources