Turn ARIA Findings into Developer Tickets

ARIA findings are easy to paste into a backlog and hard to fix well. A useful ticket explains what the broken ARIA is trying to represent, which user task is affected, and how the repaired component must behave with keyboard and assistive technology.

Start with native HTML where possible. The ticket should not ask for more ARIA when a button, label, fieldset, dialog, or status message would solve the problem more reliably.

What to capture

Rule or finding: axe rule, Lighthouse audit, manual note, or code review comment.
Affected component: modal, menu, tabs, custom select, accordion, error summary, cart update, or form group.
Element and relationship: selector, accessible name source, aria-labelledby target, aria-describedby target, owned item, or live region.
State: expanded, selected, disabled, invalid, current, hidden, loading, opened dialog, or validation error.
User task: the task that becomes unclear, impossible, or slower when the name, role, relationship, or state is wrong.

Common ARIA ticket patterns

Missing accessible name: icon buttons, links, form controls, and landmark regions that are announced only as a generic role.
Broken reference: aria-labelledby or aria-describedby points to a missing, hidden, duplicated, or unhelpful element.
Wrong role for behavior: a custom control exposes menu, tab, dialog, switch, or combobox semantics without the matching keyboard behavior.
Missing state: expanded/collapsed, selected, checked, current, invalid, or busy state is visible but not programmatically exposed.
Silent update: validation, cart totals, saved settings, search result counts, or route changes update visually without a useful announcement.

Examples

Broken aria-describedby reference

Raw finding:
axe rule: aria-valid-attr-value
Selector: #checkout-email
Message: ARIA attributes must conform to valid values. aria-describedby references "email-error", but no matching element exists after submit.

Developer ticket:
[High] Checkout email field loses its validation error relationship

User impact:
Screen reader users may not hear why checkout submission failed and may not know how to correct the email field.

Evidence:
axe rule: aria-valid-attr-value on #checkout-email.
After an invalid submit, aria-describedby references email-error, but that ID is not present in the DOM.

Acceptance criteria:
- The email field keeps a valid relationship to its visible error text when validation fails.
- The error is announced or discoverable in context with VoiceOver/Safari and NVDA/Firefox.
- The fix does not create duplicate IDs when multiple validation messages appear.

Menu button exposes state visually only

Raw finding:
Manual screen reader note: mobile menu button changes icon from hamburger to close, but VoiceOver still announces "Menu, button".

Developer ticket:
[Medium] Mobile navigation menu button does not expose open state

User impact:
Screen reader users cannot tell whether the navigation drawer is open or closed before moving focus through the page.

Evidence:
VoiceOver/Safari on mobile navigation. The button label remains "Menu" after opening. The visible icon changes, but no expanded state is exposed.

Acceptance criteria:
- The menu trigger exposes a clear name and expanded/collapsed state.
- Opening the menu moves focus predictably into the navigation or keeps the next Tab stop inside the opened menu.
- Closing the menu returns focus to the trigger.

Custom tab role without keyboard behavior

Raw finding:
Code review note: product detail tabs use role="tab" and aria-selected, but arrow keys do not move between tabs.

Developer ticket:
[Medium] Product detail tabs expose tab semantics without tab keyboard behavior

User impact:
Keyboard and screen reader users receive tab widget semantics but cannot operate the component with expected tab-list navigation.

Evidence:
Product detail page tabs use role="tablist", role="tab", and aria-selected. Left and Right Arrow do not move focus between tabs.

Acceptance criteria:
- Either implement the expected tab keyboard pattern, or replace the ARIA tab pattern with simpler native controls that match the actual behavior.
- Selected state is exposed programmatically and visually.
- The active panel has a reliable relationship to its tab.

Retest checklist

Confirm the accessible name, role, value, and state in at least one browser accessibility inspector.
Retest keyboard behavior before screen reader behavior; ARIA cannot rescue a component that cannot be operated.
Check dynamic states, not only initial page load.
Verify references remain valid after validation errors, filtering, async loading, or route changes.
Prefer the simplest markup that communicates the same behavior.

Paste-ready input for the generator

ARIA finding:
Rule or source:
Affected component:
Selector or element:
Accessible name / role / state problem:
Referenced IDs or related elements:
User task:
Keyboard behavior observed:
Screen reader behavior observed:
Expected behavior:
Acceptance criteria notes: