Testing Guides

Keyboard Accessibility Guide

All interactive elements must be operable via keyboard alone (WCAG 2.1.1). This isn't an edge case — many users rely on keyboards due to motor disabilities, repetitive strain injuries, or simple preference. If your site can't be navigated without a mouse, it's broken for a significant portion of your audience.

Essential keyboard interactions

Every keyboard user relies on a small set of standard key combinations. If your site breaks any of these expectations, users will get stuck.

Tab order

Tab order follows the DOM order of your HTML. This is almost always the right behavior. The most common tab-order mistakes:

• Positive tabindex values — tabindex="1" or higher overrides natural order and creates unpredictable navigation. Never use positive tabindex.
• CSS reordering without DOM reordering — using flexbox order or grid placement moves elements visually but tab order still follows the DOM.
• Focusable hidden elements — off-screen elements that receive focus confuse keyboard users. Use display: none or visibility: hidden instead of just moving elements off-screen.

Focus indicators

WCAG 2.4.7 requires a visible focus indicator on all interactive elements. WCAG 2.2 added 2.4.11 (Focus Appearance) at Level AA, which sets minimum requirements for focus indicator size and contrast: at least a 2px solid outline with 3:1 contrast against the unfocused state.

The most reliable approach is a visible outline:

:focus-visible {
  outline: 2px solid #3b63e0;
  outline-offset: 2px;
}

Never use outline: none without providing an alternative focus indicator. Removing the default browser outline without a replacement is the single most common keyboard accessibility failure.

Skip navigation links

A skip link lets keyboard users bypass the navigation and jump directly to the main content. Without one, users have to Tab through every nav link on every page load. WCAG 2.4.1 (Bypass Blocks) requires a mechanism to skip repeated content.

<a href="#main-content" class="sr-only focus:not-sr-only
  focus:absolute focus:z-50 focus:top-4 focus:left-4
  focus:rounded-md focus:bg-ink focus:px-4 focus:py-2
  focus:text-white">
  Skip to main content
</a>

<!-- Later in the page -->
<main id="main-content">
  ...
</main>

Keyboard traps

A keyboard trap occurs when focus enters a component and can't leave via keyboard. WCAG 2.1.2 (No Keyboard Trap) requires that users can always navigate away from any component. Common causes:

• Modal dialogs that don't return focus when closed — focus should move back to the trigger element
• Embedded video players that capture keyboard events without an Escape handler
• Third-party widgets (chat widgets, cookie banners) that trap focus without proper dismiss handling

Note: Modal dialogs shouldtrap focus while open (focus should cycle within the dialog). The trap becomes a violation only when the user can't dismiss the dialog via keyboard (Escape key or a close button).

Focus management in SPAs

Single-page applications change content without a full page reload. When a route changes, the browser doesn't automatically move focus — a screen reader user may not notice the page changed at all.

The standard approach: on route change, move focus to either the new page's <h1> or the <main> container. Next.js handles this automatically for page navigations, but custom route transitions may need manual focus management.

Testing keyboard accessibility

The easiest accessibility test you can run: unplug your mouse and try to use your site. Can you reach every interactive element? Can you see where focus is? Can you activate every button and link? Can you close every dialog?

Automated tools like SweepHound's dual-engine scanner can detect missing focus indicators, positive tabindex values, and some keyboard trap patterns — but manual keyboard testing remains essential for verifying the actual user experience.

Want to find keyboard accessibility issues on your site automatically? Run a free SweepHound scan — it can flag missing focus indicators, some tab-order problems, and keyboard trap patterns on scanned pages.