---
name: keyboard-paths
description: "Use when a web task cannot be completed by keyboard or focus disappears, skips controls, or becomes trapped."
---

# Repair keyboard paths

Start with the actual task and its entry point: for example, select a project, rename it, then return to the project list. Record the browser and input method. Follow the task with Tab, Shift+Tab, Enter, Space, and the widget's documented keys before changing markup. A list of focusable elements does not prove the task works.

Prefer native links for navigation and buttons for actions. Replace clickable containers before adding keyboard handlers to them. Keep DOM order consistent with the meaningful reading order; positive tabindex usually conceals a layout problem. A disabled control may leave the tab sequence, so give users another way to discover why an action is unavailable. Tooltips alone are insufficient.

For each change that removes the focused element, choose the next logical destination. Deleting a row might focus the next row's action, the previous row, or the empty-state heading. Do not always return to the page top. Composite widgets need their own documented movement model; do not apply arrow navigation to every collection of buttons.

Deliver the smallest repair plus a short task trace: starting focus, keys used, expected destination, and actual result. Use [the worked trace](references/task-trace.md) when the task crosses several surfaces.

Verify both forward and reverse traversal, visible focus under sticky headers, activation without a pointer, Escape where applicable, and focus after asynchronous updates. Repeat with zoom sufficient to expose clipping. If screen-reader testing is unavailable, report keyboard evidence separately and leave that coverage explicitly untested. Do not turn a successful task trace into a site-wide accessibility claim.

Primary reference for related platform rules or documentation practice: [Keyboard interaction and focus](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/). Verify the relevant version when applying technical details.