wcag-keyboard-navigation

Reference catalog for how to verify keyboard-navigation conformance. Pairs with the runner skills (axe-a11y, pa11y-a11y, lighthouse-a11y).

Overview

WCAG 2.2 organizes accessibility into four principles - Perceivable / Operable / Understandable / Robust - at three conformance levels - A / AA / AAA (wcag22).

Keyboard navigation lives under Operable (Principle 2) and spans six key Success Criteria covering keyboard operability, focus management, and focus visibility.

When to use

• Reviewing a component's keyboard interaction surface during PR review.
• Authoring a keyboard-navigation test plan for a new component.
• Triaging an accessibility audit finding tagged with one of the SCs below.
• Configuring per-rule severities for axe-a11y / pa11y-a11y.

Success Criteria

SC 2.1.1 - Keyboard (Level A)

Per wcag22: "All functionality of the content is operable through a keyboard interface" without requiring specific timings. Path-dependent input (handwriting) is exempt.

Test script (Playwright):

test('SC 2.1.1 - interactive elements are keyboard-operable', async ({ page }) => {
  // Tab to the button, activate with Enter
  await page.keyboard.press('Tab');
  await page.keyboard.press('Enter');
  await expect(page.locator('[data-testid="action-result"]')).toBeVisible();

  // Repeat with Space for elements that should accept Space
  await page.keyboard.press('Tab');
  await page.keyboard.press('Space');
  await expect(...).toBeVisible();
});

SC 2.1.2 - No Keyboard Trap (Level A)

Per wcag22: "Focus must be movable away using standard methods; users should be informed of exit procedures if non- standard keys are required."

See wcag-focus-trap for the intentional-trap convention (modal focus management) which is distinct from a violation.

SC 2.1.4 - Character Key Shortcuts (Level A, added in 2.1)

Single-character shortcuts (/ to focus search, j/k to navigate items) must offer at least one of:

• Off mechanism - user can disable the shortcut globally.
• Remap mechanism - user can rebind to non-character or modifier-prefixed combinations.
• Active only on focus - shortcut active only when the associated component has focus.

This SC exists because users with speech-input software produce spurious key presses; unguarded single-character shortcuts trigger unintended actions.

SC 2.4.3 - Focus Order (Level A)

Per wcag22: components must "receive focus in an order that preserves meaning and operability."

SC 2.4.7 - Focus Visible (Level AA)

Per wcag22: "Any keyboard operable user interface has a mode of operation where the keyboard focus indicator is visible."

SC 2.4.11 / 2.4.12 - Focus Not Obscured (Level AA / AAA, NEW in 2.2)

Per wcag22: components receiving focus cannot be "entirely hidden due to author-created content."

2.4.11 (Minimum, Level AA): focus must NOT be entirely obscured.

2.4.12 (Enhanced, Level AAA): focus must NOT be partially obscured. Stricter; relevant for high-stakes forms.

Per-component test patterns

Form

1. Tab through every field; verify focus order matches reading order.
2. Verify each interactive element has a visible focus ring.
3. Verify label-input association via <label for="..."> or aria-labelledby.
4. Activate submit via Enter from any field.
5. After submit error: verify focus moves to the first invalid field (per SC 3.3.1 - Error Identification).

Modal / dialog

1. On open: focus moves to the first interactive element (or to the dialog's close button if no other focusable element).
2. Tab cycles through dialog content only - does NOT escape to page behind.
3. Shift+Tab from first → last interactive element (cycle).
4. Escape closes the dialog and returns focus to the trigger.

(See wcag-focus-trap for the full modal pattern.)

Menu / dropdown

1. Tab focuses the trigger.
2. Enter / Space / Down-arrow opens the menu; first item focused.
3. Down/Up arrows navigate items; Home/End jump to first/last.
4. Enter / Space activates the focused item.
5. Escape closes the menu and returns focus to the trigger.

This matches the ARIA Menu pattern (referenced from aria-authoring-patterns).

Tabs

1. Tab focuses the active tab (one tabstop per tab group).
2. Left/Right arrows navigate between tabs (no Tab key).
3. Activation: automatic on focus OR explicit on Enter/Space (manual activation; ARIA Authoring Practices defaults).
4. After tab change: Tab moves to the panel content.

CI integration

The patterns above translate to per-test assertions in axe-a11y / pa11y-a11y configurations. The a11y-violation-gate skill gates the build on new violations of these SCs.

Anti-patterns

References

• wcag22 - WCAG 2.2 specification.
• wcag-focus-trap - focus management for modals (the intentional-trap pattern).
• wcag-color-contrast - for SC 1.4.11 focus-indicator contrast.
• aria-authoring-patterns - for canonical interactive-widget patterns.
• axe-a11y, pa11y-a11y, lighthouse-a11y - runners that detect SC violations programmatically.