← 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.

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