/focus-management

Focus Management

Purpose

Focus is the keyboard and screen reader user's position in the interface. Every time the DOM changes — a dialog opens, an item is deleted, a route changes — focus either moves somewhere intentional or falls back to <body> and the user is lost at the top of the page. This skill decides the destination for every change.

When to Use

• Building dialogs, drawers, popovers, menus, comboboxes, tabs
• Lists where items can be deleted, added, moved, or filtered
• Client-side routing
• Forms with async submission or error summaries
• Inline editing, expand/collapse, "load more", infinite scroll
• Bug reports: "after closing the modal I'm at the top of the page", "screen reader didn't say anything"

Core Principles

1. Every DOM change that removes or replaces the focused element needs a planned destination. Otherwise focus is lost.
2. Move focus only when the user's context changed. Opening a dialog changes context; a toast appearing does not. Unrequested focus moves are disorienting.
3. Return focus to where the user came from when a temporary context closes — or to the nearest logical substitute if that element is gone.
4. Announce what the user cannot see. Changes that don't move focus but matter (results updated, saved, error) are announced through live regions.
5. Visible focus is non-negotiable. A focus destination the user cannot see is not a destination.
6. Tab order follows visual and logical order. Use DOM order; avoid positive tabindex.

Workflow

1. List the focus events

For the feature, list every interaction that opens, closes, adds, removes, or replaces content.

2. Decide the destination for each

Reference rules:

3. Handle "the return target is gone"

The element that opened a dialog may no longer exist (it was the delete button of a row you just deleted). Define a fallback chain per case: next sibling → previous sibling → container heading → main heading. Never let it fall to <body>.

4. Contain focus where required

• Modal dialogs: focus cannot leave until closed; background is inert (inert attribute or native showModal()); Escape closes unless the dialog guards unsaved input.
• Non-modal panels/popovers: focus can leave; Escape closes and returns focus; clicking outside closes without stealing focus from the clicked element.
• Nested dialogs: avoid; if unavoidable, each level returns focus to its own trigger.

5. Composite widgets use roving focus

Toolbars, menus, tab lists, listboxes, grids, and radio groups are a single Tab stop; arrow keys move within. Track the active item with roving tabindex or aria-activedescendant.

6. Verify

Walk every event with keyboard only, then with a screen reader (VoiceOver, NVDA). At each step: Where is focus? Can I see it? Did I hear what changed?

Checklist

• Every open/close/add/delete/replace event has a focus destination
• Dialogs return focus to their trigger, with a fallback if the trigger is gone
• Modal dialogs contain focus and make the background inert
• Destructive confirmations do not focus the destructive button first
• Deleting an item moves focus to a neighbor or logical fallback
• SPA route changes move focus to the page heading/main and announce the title
• Form errors move focus to a summary or first invalid field
• Toasts and background updates never steal focus, but are announced
• Composite widgets use arrow-key navigation with a single Tab stop
• Focus indicator visible on every focus destination (including tabindex="-1" headings)
• No positive tabindex; DOM order matches visual order
• Verified with keyboard and at least one screen reader

Common Mistakes

• Custom modal built from divs without containment; Tab walks into the page behind.
• Closing a dialog leaves focus on <body>, so the next Tab starts at the top of the page.
• Deleting a row removes the focused button; focus is lost.
• SPA navigation with no focus move, so screen reader users hear nothing and are still at the old link.
• Autofocus on page load into a search field, skipping the page content and hijacking mobile keyboards.
• Toasts with role="alert" for routine success, interrupting whatever the screen reader is reading.
• outline: none with no replacement.
• Live region added to the DOM at the same time as its message, so nothing is announced (the region must exist before content changes).

Example

Focus map: task list with inline delete and undo

Implementation Notes

• Native <dialog> + showModal() provides focus containment, inert background, and Escape; you still set initial focus and return focus deliberately where the default is wrong.
• The inert attribute makes background content unfocusable and hidden from assistive tech for custom overlays.
• Store the trigger (document.activeElement) before opening; restore after closing, checking isConnected.
• For headings that receive programmatic focus: tabindex="-1" and a visible :focus-visible style.
• Keep a single persistent polite live region (and one assertive) mounted at the app root; write messages into it.
• Framework routers: add a route-change hook that focuses the new <h1> and updates document.title.
• After async DOM replacement, focus in requestAnimationFrame or after the framework commits, not synchronously before the element exists.

Output Expectations

Produce:

1. Focus event list for the feature.
2. Focus map — Event | Focus before | Focus after | Fallback | Announcement.
3. Containment rules for each overlay.
4. Live region plan — which messages, polite vs assertive.
5. Findings — when reviewing, each lost/misplaced focus case with reproduction steps and file/line.