AddThisFeature

Accessible Focus Management

Put keyboard and screen-reader users in the right place after the interface changes.

moderate Accessibility & Internationalization

What it adds

A deliberate policy for where focus goes whenever the page changes underneath the user — navigation, validation, deletion, insertion, and async updates.

What your agent is told to do

6
  1. 1

    Inventory every moment the interface changes without a full page load: client-side route changes, form submissions, rows being deleted, content being appended, filters re-rendering a list.

  2. 2

    Decide for each one whether focus should move, and write it down. On a route change, move focus to the new page heading or main region so a screen reader starts reading the new page instead of staying on a link that no longer exists.

  3. 3

    When validation fails, move focus to the first invalid field and make sure its error message is associated with it, so the user hears the problem rather than hunting for it.

  4. 4

    When an element that had focus is removed, move focus to a stable neighbour — the next row, the list container, or the control that triggered the removal. Never let focus fall back to the document body; the user loses their position entirely.

  5. 5

    Announce background changes (saved, imported, ten new results) through a polite live region, and route all such announcements through one shared mechanism rather than scattering live regions through the markup.

  6. 6

    Do NOT move focus for updates the user did not initiate — a poll result, an incoming notification, an autosave. Stealing focus mid-sentence destroys typed input and is far worse than silence.

Edge cases it handles

7
  • Focus must never be sent to an element that is hidden, disabled, or already detached from the document.
  • An element that only exists to receive focus needs tabindex="-1", not tabindex="0" — it should be programmatically focusable but stay out of the tab order.
  • Focus moves must happen after the new content is actually in the DOM, not in the same tick as the state change.
  • An assertive live region interrupts whatever is being read; reserve it for errors and use polite everywhere else.
  • Rapid successive updates must be coalesced before announcing, or the user hears a stream of half-read messages.
  • Deleting the last row of a list leaves nothing to focus — send focus to the empty state and make sure the empty state is focusable.
  • Scrolling caused by a focus move must not jump the viewport unexpectedly; keep the target in view without an animated scroll when prefers-reduced-motion is set.

Definition of done

8
  • Every interface change that removes or replaces the focused element has a defined focus destination.
  • A client-side route change moves focus into the new page content.
  • A failed validation moves focus to the first invalid field with its error associated.
  • Deleting an item leaves focus on a sensible neighbour, never on the body.
  • Background updates are announced through a shared polite live region and never steal focus.
  • Focus is never moved to a hidden, disabled, or removed element.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.