Guide to Building an Accessible Modal Dialog Widget (WCAG 2.2)

A Modal Dialog is a window that overlays the primary content, requiring user interaction before they can return to the main page. Because modals disrupt the standard page flow, they are one of the most common places for accessibility failures.

1. Design and Visuals (Perceivable)

Modals must be visually distinct from the background to help users understand the shift in context.

Color Contrast (WCAG 1.4.3)

  • Text vs background contrast ratio ≥ 4.5:1 (normal text) or ≥ 3:1 (large text)
  • The dialog box must have a strong border or shadow to separate it from the dimmed background, and all text must meet the 4.5:1 contrast ratio.
  • Focus indicators (e.g., outline, underline, background change) must meet 3:1 contrast ratio
  • Use a visible border to indicate active/selected tabs, this provides a non-color cue (shape/connection) to indicate which tab is active
  • Focus Appearance (WCAG 2.4.13): Ensure all interactive elements have a visible focus indicator, [role="tab"]:focus-visible rule. It uses a high-contrast 4px outline and outline-offset. This ensures keyboard users can clearly see where they are
  • Ensure the modal dialog is visually distinct from the background to help users understand the shift in context.

Touch Targets (WCAG 2.5.5)

  • Ensure the "Close" button and any action buttons are at least 24px x 24px (preferably 44px on mobile) to accommodate users with limited dexterity.

2. Keyboard Usability (Operable)

Keyboard interaction is the most critical part of modal accessibility. A user should never be able to "tab out" of the modal into the background content while it's open.

Standard Interaction Pattern

  • Tab / Shift + Tab: Moves focus to the next/previous interactive element inside the modal.
  • Escape: Closes the modal and returns focus to the trigger button.
  • Enter / Space: Activates buttons within the modal.

Key Principles

  • Focus Trapping: As seen in the JavaScript above, we "trap" the Tab key so that if a user tabs past the "Save Changes" button, focus loops back to the "Close" button.
  • Focus Restoration: When the modal closes, the focus must return to the button that opened it. If focus is lost, screen reader users may have to start navigating from the top of the page again.

3. Screen Reader & Assistive Technology (Understandable & Robust)

Semantic HTML and ARIA attributes allow assistive technology to describe the modal's purpose and state.

ARIA Roles, Properties, and States

  • role="dialog": Tells the screen reader that the user is now in a dialog window, changing how the screen reader handles navigation.
  • aria-modal="true": Informs the browser that content outside this element is inert (non-interactive).
  • aria-labelledby="ID": Points to the modal title (e.g., <h2>). This is the first thing a screen reader says when the modal opens (e.g., "Account Settings, Dialog").
  • aria-describedby="ID": Points to the main description text of the modal. This provides immediate context for why the modal appeared.
  • aria-label: on Close Button: Since "X" is just a character, the aria-label="Close modal" provides a clear name for the action.