Storybook Accessibility Tickets

Storybook accessibility findings are most useful when the ticket connects the failing story to the reusable component, affected product flows, and the states that need retesting.

Use this guide for component review notes from Storybook, Chromatic, addon-a11y, manual keyboard testing, screen reader checks, or design-system QA. Keep the ticket focused on the component behavior, not only the isolated demo.

Open this Storybook finding in the generator

When to write a Storybook ticket

The failing state is reusable: loading, empty, error, expanded, selected, disabled, validation, or high-contrast state appears in more than one product flow.
The story hides production risk: the demo passes a scanner, but keyboard, screen reader, zoom, or voice-control testing exposes a behavior problem.
The example teaches a bad pattern: story markup, controls, args, or documentation encourage teams to omit labels, relationships, focus handling, or status messages.
The fix needs rollout: a component package, shared CSS, design token, Storybook story, and product implementation all need coordinated retesting.

Ticket structure

Title:
[Severity] Storybook component: accessibility behavior fails in [state]

User impact:
Describe the real task that becomes blocked or unreliable when teams reuse this component.

Evidence:
- Story or component:
- State or args:
- Affected product flows:
- Test method:
- Actual behavior:
- Expected behavior:

Rollout notes:
- Component package or template owner:
- Stories that need updates:
- Product flows to retest:
- Documentation or usage notes to change:

Acceptance criteria:
- The component works in the failing state.
- The Storybook story demonstrates the accessible behavior.
- Known product flows are retested after rollout.
- Documentation names the required keyboard, screen reader, or visual-state behavior.

Example conversion: async combobox

Raw note:
The shared combobox story passes axe, but ArrowDown does not move through options after async results load. Used in product search, account country selection, and admin user lookup.

Developer ticket:
[High] Storybook combobox: async options cannot be reached with arrow keys

User impact:
Keyboard users may not be able to choose an option from reusable search and selection controls after results load.

Evidence:
- Component: Combobox
- Story state: async options loaded
- Affected flows: product search, country selection, admin user lookup
- Actual result: ArrowDown does not move through loaded options
- Expected result: keyboard users can move through options, inspect the active option state, select an option, and continue from a predictable focus position

Likely WCAG references to verify:
- 2.1.1 Keyboard
- 4.1.2 Name, Role, Value

Acceptance criteria:
- Loaded, empty, loading, and error states have Storybook examples.
- Keyboard operation works after async options render.
- The active option state is exposed correctly.
- At least one real product flow using the component is retested.

Common Storybook traps

Scanner-only confidence: addon-a11y can catch missing labels and contrast issues, but it will not prove meaningful keyboard behavior through custom widgets.
Happy-path stories only: components often fail in loading, empty, error, validation, disabled, or long-label states that are missing from the story set.
Demo-only fixes: fixing the story without updating the shared component leaves production flows broken.
Unowned usage guidance: if teams must pass labels, IDs, descriptions, or status text into the component, the story and docs should show the required props.

Paste-ready input for the generator

Storybook accessibility finding:
Component or story:
State or args:
Affected product flows:
Test method:
Actual behavior:
Expected behavior:
Likely owner:
Stories or docs to update:
Product flows to retest:
Acceptance criteria:

Open the accessibility ticket generator and paste this structure with the Storybook evidence.