frontend-a11y-focus-keyboard-inert

name	frontend-a11y-focus-keyboard-inert
description	Use when authoring any focusable UI surface : modals, popovers, drawers, tabs, menus, listboxes, comboboxes, toolbars, grids, trees, or any custom widget that responds to keyboard input. Use when implementing focus styles (`:focus-visible`, `:focus-within`), choosing a tabindex value, designing arrow-key navigation, deciding between roving tabindex and `aria-activedescendant`, isolating background content behind an overlay, capturing-and-restoring focus around a dialog, or enforcing Escape semantics. Use when reviewing CSS for the classic `outline: none` deletion or the `aria-hidden` on background anti- pattern. Prevents the six dominant focus failures of 2010s authoring : invisible keyboard focus (`outline: none` without `:focus-visible` replacement), positive `tabindex` shattering DOM-order navigation, `aria-hidden` on the background of a modal instead of `inert` (keyboard still tabs in, screen reader still says nothing useful), focus traps that swallow Escape, programmatic `focus()` calls on non-focusable elements (silent no-ops), and forgetting to restore focus to the trigger element on dialog close. Covers the `inert` global attribute (six effects : no click, no focus, no find-in-page, no selection, no edit, AT-hidden), the automatic inertness applied by `<dialog>.showModal()` to the rest of the page, the `:focus-visible` UA-heuristic vs the always-on `:focus` selector, the `:focus-within` ancestor matcher, tabindex semantics (0, -1, and why positive values are an anti-pattern), the roving-tabindex pattern for composite widgets vs `aria-activedescendant` for combobox-style widgets, 1D and 2D arrow-key navigation per the W3C WAI APG keyboard interface, Home / End / PageUp / PageDown bindings, automatic vs manual activation, the Escape key plus the `closedby` attribute on `<dialog>`, and the manual focus-restoration pattern that `<dialog>` requires (unlike the Popover API, which restores focus to the invoker on Esc-close automatically). Keywords: inert, :focus-visible, :focus-within, tabindex, tabindex 0, tabindex -1, positive tabindex, roving tabindex, aria-activedescendant, focus management, focus restoration, focus trap, focus indicator, WCAG 2.4.7, WCAG 1.4.11, document.activeElement, HTMLElement.focus, preventScroll, focusVisible option, top-layer, dialog.showModal, closedby attribute, autofocus dialog, Escape key dialog, arrow-key navigation, Home End PageUp PageDown, APG keyboard interface, focus stuck, tab order broken, focus invisible, modal background interactive, focus jumps to top, focus on hidden element, keyboard user lost, focus escaped modal, how to manage focus, what is inert, how to make modal accessible, how do I make focus visible only for keyboard, how to trap focus in a modal, how to restore focus after dialog close, accessible focus styles, why is my outline missing, how to remove tab from background.
license	MIT
compatibility	Designed for Claude Code. Requires Frontend Design evergreen-2026.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

Frontend Accessibility : Focus, Keyboard Navigation, and Inert

Authoritative reference for keyboard-first interaction primitives. Modern foundation : inert (Baseline Widely Available since April 2023) and <dialog>.showModal() replace the brittle hand-rolled focus-trap + aria-hidden + tabindex="-1"-on-all-things patterns of the 2015 to 2022 era.

Quick Reference

Baseline status

Feature	Baseline	Source
inert attribute	Widely Available since April 2023	MDN : inert (verified 2026-05-19)
:focus-visible	Widely Available since March 2022	MDN : :focus-visible (verified 2026-05-19)
:focus-within	Widely Available since January 2020	MDN : :focus-within (verified 2026-05-19)
<dialog> + showModal()	Widely Available	MDN : dialog (verified 2026-05-19)
closedby attribute on <dialog>	Modern (gate where legacy support matters)	MDN : dialog (verified 2026-05-19)

The four primitives

/* 1. Focus indicator : :focus-visible, NOT :focus, NOT outline:none */
:focus-visible {
  outline: 2px solid var(--focus); /* MUST meet WCAG 1.4.11 : 3:1 vs adjacent */
  outline-offset: 2px;
}

/* 2. Ancestor matcher : :focus-within for parent state */
.field:focus-within { : (--accent); }