This checklist defines the keyboard interaction tests required for each interactive component in the theme. Run through the applicable sections after implementing or modifying any component that accepts user input or manages focus.
General Keyboard Testing Procedure
Before testing individual components, verify the page-level keyboard behavior:
- Tab moves focus forward through all interactive elements in DOM order.
- Shift+Tab moves focus backward through all interactive elements.
- Enter activates buttons, links, and form submit actions.
- Space activates buttons and toggles checkboxes/radio buttons.
- Escape closes any open overlay (modal, dropdown, mobile menu).
- Arrow keys navigate within composite widgets (menus, radio groups, tabs).
- No element traps focus unexpectedly — Tab always moves to the next element or wraps to the browser chrome.
- The skip-to-content link is the first focusable element and moves focus to
<main>on activation.
Focus Management Expectations
These rules apply to every interactive component:
- Visible focus ring — every focusable element displays a clearly visible focus indicator. The focus ring must have at least 3:1 contrast against adjacent colors.
- Logical tab order — tab order matches the visual reading order (left-to-right, top-to-bottom for LTR layouts). No unexpected focus jumps.
- Focus restoration — when an overlay closes, focus returns to the element that triggered it.
- Focus trapping in modals — when a modal or dialog is open, Tab and Shift+Tab cycle only within the modal. Focus does not escape to background content.
- No focus on hidden elements — elements with
display: none,visibility: hidden, oraria-hidden="true"must not receive focus.
Component-Specific Tests
Per-component accessibility tests (navigation, dropdowns, forms, search, TOC, and other interactive components) are maintained as structured data in src/core/config/accessibility-tests.ts and rendered by the AccessibilityTests component on each component’s documentation page. See the relevant component doc page for its specific test entries.
Lightbox Keyboard Pattern
The Image Lightbox overlay (Lightbox.astro) follows the ARIA dialog pattern with these keyboard interactions:
- Escape — closes the overlay and restores focus to the trigger element
- Left Arrow — navigates to the previous image in the gallery (wraps continuously)
- Right Arrow — navigates to the next image in the gallery (wraps continuously)
- Tab — cycles focus through the overlay’s interactive elements (close button, prev, next); focus is trapped within the overlay
- Shift+Tab — reverse focus cycle within the overlay
Single images (sole member of their group) do not have prev/next controls — only the close button receives focus. The close button receives initial focus when the overlay opens.
Screen Reader Verification Basics
After passing the keyboard checks above, verify with a screen reader (VoiceOver on macOS, NVDA on Windows, or Orca on Linux):
- Page title is announced on load.
- Landmark regions (
<header>,<nav>,<main>,<footer>) are announced and navigable. - Headings form a logical hierarchy — no skipped levels.
- Links and buttons announce their accessible name and role.
- Images announce their alt text (or are skipped if decorative).
- Form fields announce their label, required state, and any error messages.
- Dynamic state changes (menu open/close, modal open/close, form errors) are announced without requiring manual re-read.
- Live regions announce updates without interrupting the current reading position (for
polite) or immediately (forassertive).