mgifford/accessibility-skills/keyboard

Keyboard Accessibility Skill

Canonical source: examples/KEYBOARD_ACCESSIBILITY_BEST_PRACTICES.md in mgifford/ACCESSIBILITY.md

This skill is derived from that file. When in doubt, the example is authoritative.

Apply these rules to every interactive UI element and feature.

Core Mandate

All interactive functionality must be fully usable with a keyboard alone — no mouse or touch required, except where the underlying function genuinely depends on path-based movement. Keyboard access is not equivalent to pressing Tab through every control — native and composite widgets use different key conventions, and users must understand how to operate custom widgets.

Severity Scale (this skill)

Do not assign severity from the rule alone — determine the actual effect on the task. Consider whether the defect prevents reaching, operating, or leaving a component; whether it blocks an essential task or only an optional feature; whether focus is lost or placed misleadingly; and whether a reasonable keyboard method remains available.

Critical: No Keyboard Trap

If focus can enter a component, users must be able to move focus away using Tab, Shift+Tab, arrow keys, or Escape (depending on the component). If leaving requires an unusual command, provide instructions before or within the component.

A keyboard trap with no exit is Critical. Restricting focus temporarily is NOT a trap when it is a modal dialog with a standard/documented exit: focus moves in on open, Tab/Shift+Tab stay within it, a keyboard-operable control closes/completes it, and closing returns focus to the invoking control or another logical location.

Test embedded editors, third-party widgets, iframes, media players, remote desktops, and canvas applications carefully — they commonly consume Tab or other keys and need an available, documented exit.

Critical: All Interactive Elements Must Be Keyboard Reachable

Every element that can be activated by mouse must be reachable and activatable by keyboard. Use native elements — they provide keyboard behaviour, focusability, semantics, states, and browser integration built in at zero extra cost:

<!-- Good: built-in keyboard support -->
<button type="button">Save</button>
<a href="/about">About</a>
 
<!-- Avoid: requires full ARIA + JS to match native behaviour -->
<div role="button" tabindex="0">Save</div>

Adding role="button" and tabindex="0" does not add button behaviour by itself — a custom button must also implement Enter and Space activation, disabled state, focus styling, and the expected accessible name/state. Test the actual result, not merely whether a keydown handler exists. Mouse and touch handlers must not be the only way to operate a control.

Critical: Expected Key Behaviours

Deviating from expected widget key behaviour is Critical — it breaks the mental model AT users depend on. Do not override standard browser behaviour on native controls without a documented need. Follow the current WAI-ARIA APG for custom widgets (versioned independently of WCAG — APG patterns are design guidance, not WCAG requirements by themselves; always confirm the current version).

Do not implement a widget from a summary table alone — use the complete current APG pattern, document any variation, and test with representative browsers and assistive technologies.

Critical: Dialog Focus Management

Incorrect dialog focus management is Critical — keyboard and screen reader users lose their place, or cannot reach dialog controls at all.

Preferred approach: native <dialog> with showModal()

A modal dialog opened with showModal() places the rest of the document in an inert state automatically — this is now the preferred pattern over manually applying inert to every sibling.

<button type="button" id="delete-trigger">Delete project</button>
 
<dialog id="delete-dialog" aria-labelledby="delete-title">
  <h2 id="delete-title">Delete project?</h2>
  <p>This action cannot be undone.</p>
  <form method="dialog">
    <button value="cancel" autofocus>Cancel</button>
    <button value="confirm">Delete project</button>
  </form>
</dialog>

const trigger = document.getElementById('delete-trigger');
const dialog = document.getElementById('delete-dialog');
trigger.addEventListener('click', () => dialog.showModal());
dialog.addEventListener('close', () => {
  if (trigger.isConnected) trigger.focus();
});

Initial focus depends on the dialog's content — a short confirmation might focus Cancel; a long informational dialog might focus a heading with tabindex="-1" so users can read from the beginning. Do not always focus the first interactive element without considering the content. If the trigger is removed while the dialog is open, return focus to the nearest logical workflow location rather than the document body.

Do not add aria-modal="true" to a container and assume it creates modality — ARIA does not make content inert, contain focus, add keyboard handling, or restore focus.

Native modal behaviour does not remove the need to test: initial focus location, Tab/Shift+Tab containment, Escape and visible close controls, form submission/cancellation, focus restoration, nested/stacked overlays, screen reader announcement, and browser support in the project's support matrix.

Manual approach (when native <dialog> is unavailable)

The inert attribute prevents all interaction (focus, click, AT) with elements outside the open dialog. It has good browser support (baseline 2023) and is simpler and more reliable than manual focusable-element cycling:

function openDialog(dialog, trigger) {
  document.querySelectorAll('body > *:not(#dialog-container)')
    .forEach(el => el.setAttribute('inert', ''));
  dialog.removeAttribute('hidden');
  dialog.querySelector(focusableSelectors)?.focus();
}
function closeDialog(dialog, trigger) {
  document.querySelectorAll('[inert]').forEach(el => el.removeAttribute('inert'));
  dialog.setAttribute('hidden', '');
  trigger.focus();
}

For environments without inert, use the `focus-trap` library (production-tested) rather than hand-rolling focus-cycling logic, or use the `wicg-inert` polyfill.

Critical: Non-Modal Disclosures and Popovers Must Not Trap Focus

Do not trap focus in ordinary disclosures, tooltips, menus, or non-modal popovers unless the interaction pattern explicitly requires restricted focus. For simple show/hide content, a button with aria-expanded is sufficient:

<button type="button" aria-expanded="false" aria-controls="filter-panel">
  Filters
</button>
<div id="filter-panel" hidden><!-- Filter controls --></div>

When open content overlays the page: ensure keyboard users can enter and leave it; close non-persistent content when interaction moves away; support Escape where users reasonably expect it; return focus when closing would otherwise cause focus loss; prevent the overlay from obscuring the new focus location; do not open complex content merely because its trigger receives focus.

The HTML Popover API can be used where it meets the requirement — still test focus behaviour and dismissal for the selected popover type.

Serious: Focus Visibility

Every focusable element must have a clear, persistent visible focus indicator. Removing focus outlines without an equally visible replacement is Serious.

:focus-visible {
  outline: 3px solid var(--focus-color, #005fcc);
  outline-offset: 3px;
}
@media (forced-colors: active) {
  :focus-visible { outline-color: Highlight; }
}

Distinguish the applicable requirements:

• 2.4.7 Focus Visible (AA): a visible mode of operation in which focus is visible
• 1.4.11 Non-text Contrast (AA): component states may need 3:1 contrast against adjacent colours
• 2.4.13 Focus Appearance (AAA): an enhanced minimum indicator area and 3:1 change between focused/unfocused pixels — do not describe this AAA formula as an AA requirement

A 3px solid outline with adequate contrast is a useful project default, not the complete Focus Appearance formula. Test focus in light, dark, increased-contrast, and forced-colours modes, and on every background a control appears against.

Serious: Focus Not Obscured (WCAG 2.4.11/2.4.12)

Sticky headers, sticky footers, cookie notices, chat panels, toolbars, virtual keyboards, and persistent disclosures can obscure the focused element even though focus is technically visible. A focused element fully hidden behind a sticky overlay is Serious.

html {
  scroll-padding-block-start: var(--sticky-header-height, 0);
  scroll-padding-block-end: var(--sticky-footer-height, 0);
}
[id] {
  scroll-margin-block-start: var(--sticky-header-height, 0);
}

CSS scroll spacing helps but does not prove conformance — test every breakpoint, zoom level, text-spacing configuration, and persistent overlay. WCAG 2.4.11 (AA) requires the focused element is not entirely hidden; partial obscuring is Moderate, complete hiding is Serious. Prefer designs where the complete focused component and its indicator remain visible — that exceeds the AA minimum and aligns with 2.4.12 Focus Not Obscured Enhanced (AAA).

Serious: Focus Order

Tab order must follow logical reading and interaction sequence. Illogical focus order is Serious — screen reader users build a spatial model of the page from the focus sequence, and out-of-order focus breaks that model.

• Use semantic DOM order as the primary mechanism; align visual order with DOM

order — do not use CSS order, grid placement, or absolute positioning to create a misleading visual sequence

• Never use positive tabindex values — they create a separate, hard-to-maintain

focus sequence

• tabindex="0" — only when an element legitimately belongs in sequential

focus order and no native element provides the semantics

• tabindex="-1" — only for programmatic focus targets and inactive items in

roving-tabindex patterns

• Do not add non-interactive headings/paragraphs/containers to the Tab order

without a specific interaction requirement

• Do not use autofocus unless placing initial focus there is expected, tested,

and won't surprise users

• When content is inserted, removed, reordered, or filtered, preserve focus or

move it to a logical location — never leave focus on a deleted element

Serious: Composite Widgets (Roving Tabindex)