Keyboard‑Accessible Controls vs. Non‑Focusable Dropdown for Version Switching: Which Improves Accessibility on Read the Docs?

Resolution

Implementing keyboard-accessible controls with ARIA attributes is the superior choice for improving accessibility. A non-focusable dropdown is a critical failure for users with motor impairments; transforming it into a focusable element ensures that the version selector is reachable via the Tab key and operable via the keyboard, directly resolving the primary accessibility gap.

Implementation Logic

The transition from a non-focusable element to an accessible one relies on combining HTML focusability with ARIA state communication. This approach is generally safe for existing theme layouts because it modifies the behavioral properties of the element rather than its visual dimensions.

1. Keyboard Focus and ARIA Integration

To make the selector accessible without breaking layouts, the following attributes should be applied to the trigger element:

• tabindex="0": Ensures the element is reachable in the natural tab order.
• role="button" or role="combobox": Identifies the element's purpose to assistive technology.
• aria-haspopup="listbox": Signals that activating the control opens a menu.
• aria-expanded="false/true": Dynamically updates to notify screen readers of the menu's visibility.

Note: Adding these attributes is insufficient without corresponding JavaScript event listeners for KeyDown (Enter and Space keys) to trigger the dropdown.

2. Impact of ARIA Landmarks

Integrating ARIA landmarks (such as role="navigation") in the navigation pane complements the accessible selector. Screen reader users can use landmark shortcuts to jump directly to the navigation area, reducing the number of Tab presses required to reach the version selector. This creates a hierarchical navigation experience: Landmark → Focusable Control → Version List.

Verification Strategy

To ensure the changes meet WCAG 2.1 Level AA standards across various themes and browsers, employ these three verification steps:

1. Tab-Only Navigation: Navigate the entire page using only the Tab and Shift+Tab keys. Verify the selector receives a visible focus indicator (ensure outline: none is not applied in the theme CSS).
2. Screen Reader Validation: Use NVDA (Windows) or VoiceOver (macOS) to confirm the selector is announced as a menu and that the expanded/collapsed state is voiced upon activation.
3. Automated Audit: Run an accessibility auditor (e.g., Axe or Lighthouse) to check for missing ARIA labels or contrast issues introduced by focus states.

Missing Diagnostic: Are you using a custom Read the Docs theme or a standard one (e.g., Sphinx)? Custom CSS often overrides default focus outlines, which would require additional styling to ensure sighted keyboard users can locate the selector.