Turn Modal Dialog Findings into Accessibility Tickets
A modal dialog ticket is useful when it describes the exact focus path: what opens the dialog, where focus lands, whether background content remains reachable, and where focus returns after close.
Use this guide for findings about checkout drawers, cookie preference dialogs, newsletter modals, size guides, account-edit overlays, confirmation dialogs, and custom React/Vue components that behave like modals.
Draft the dialog ticket first
Open a prefilled modal finding in the generator with focus behavior, naming, Escape handling, background isolation, and retest criteria already filled in.
What to capture from the finding
- Trigger and state: the exact button, link, route change, validation event, or timeout that opens the dialog.
- Dialog type: confirmation, form, cart drawer, size guide, cookie preferences, help overlay, alert dialog, or non-modal popover that was implemented as modal.
- Focus on open: whether focus moves to the dialog heading, first useful control, first field with an error, or stays behind the overlay.
- Containment: whether Tab and Shift+Tab stay inside the dialog, reach browser chrome only, or leak into background page controls.
- Name and semantics: role, accessible name source, visible title, close button name, and whether screen readers announce the dialog context.
- Close and recovery: Escape support, close button behavior, outside-click behavior, destructive confirmation behavior, and focus return target.
Ticket structure
Title: [Severity] Flow or component: modal dialog does not manage focus and background access User impact: Explain the task that becomes confusing or blocked when keyboard or screen reader users cannot tell a dialog opened, cannot stay inside it, or cannot return to the original control. Evidence: - Page or flow: - Dialog trigger: - Dialog title or purpose: - Focus location after open: - Tab / Shift+Tab behavior: - Escape and close behavior: - Focus return target: - Screen reader announcement: - Affected component or selector: Likely WCAG references to verify: - 2.1.1 Keyboard, when the dialog cannot be opened, used, or closed with the keyboard. - 2.1.2 No Keyboard Trap, when users cannot leave the dialog or regain a predictable page position. - 2.4.3 Focus Order, when focus moves behind the modal, skips useful controls, or returns to the wrong place. - 4.1.2 Name, Role, Value, when the dialog role, accessible name, close control, or expanded/modal state is not exposed. Acceptance criteria: - Opening the dialog moves focus to a predictable target inside the dialog. - The dialog exposes a role and accessible name that match its visible title or purpose. - Tab and Shift+Tab remain within the dialog while it is modal. - Background content is not reachable by keyboard or screen reader while the dialog is active. - Escape or a clearly named close control dismisses the dialog unless a documented blocking confirmation is required. - Closing the dialog returns focus to the triggering control or the next logical workflow target.
Paste your modal dialog note into the generator when you want this structure drafted from raw audit text.
Example conversion: focus stays behind the dialog
Raw note: Newsletter signup dialog opens from the Activate offer button. Focus stays on the background page. Tab reaches header links behind the overlay. Escape does not close the dialog. The visible dialog title is not used as the accessible name. Developer ticket: [High] Newsletter signup dialog: focus stays on the background page after open User impact: Keyboard and screen reader users may not realize the dialog opened and can continue navigating inactive page content behind the overlay. This makes the signup flow confusing and can block completion. Evidence: - Flow: newsletter signup - Trigger: Activate offer button - Dialog title: Sign up for updates - Focus after open: remains on the background trigger area - Tab behavior: reaches header links behind the overlay - Close behavior: Escape does not dismiss the dialog - Screen reader announcement: dialog title is not exposed as the dialog name Likely WCAG references to verify: - 2.1.1 Keyboard - 2.1.2 No Keyboard Trap - 2.4.3 Focus Order - 4.1.2 Name, Role, Value Acceptance criteria: - Activating the trigger moves focus into the dialog. - The dialog has an accessible name from the visible heading. - Tab and Shift+Tab stay inside the dialog until it closes. - Escape and the visible close button dismiss the dialog. - Focus returns to Activate offer after close. - Background page content is not reachable while the modal is open.
Common fix directions
- Use the platform first: prefer a well-tested native or framework dialog pattern before adding custom keyboard code.
- Name the dialog: connect the visible heading to the dialog with a reliable accessible name instead of relying on surrounding page context.
- Choose the first focus target deliberately: headings work for informational dialogs; the first invalid field may be better for correction dialogs; destructive confirmations may need the least destructive action first.
- Isolate the background: modal content should keep keyboard and screen reader navigation away from inactive page content until close.
- Restore focus: returning to the trigger is usually right, but checkout steps and route changes may need the next logical workflow target.
- Retest repeated variants: check the same component in drawers, mobile breakpoints, nested forms, error states, and stacked confirmation flows.
Paste-ready input for the generator
Modal dialog finding: Page or flow: Dialog trigger: Dialog title or purpose: Current role/name/state: Focus after open: Tab and Shift+Tab behavior: Escape and close behavior: Focus return target: Screen reader announcement: Affected selector or component: Acceptance criteria needed:
Open the accessibility ticket generator and paste this structure with the audit note.