Fix keyboard navigation in a component
Finds and fixes keyboard barriers in a UI component (focus order, traps, invisible focus, mouse-only controls) and adds a keyboard test checklist. Use when a widget fails without a mouse.
Keyboard access is the base layer for screen-reader users, switch and voice-control users, and people who cannot use a mouse. The barriers are usually small and mechanical: a div with a click handler, outline: none with no replacement, a positive tabindex, focus that falls to the top of the page when a dialog closes, a menu that opens only on hover, or a custom widget that ignores the arrow keys every other app uses for it.
Fix keyboard access in this component (widget type: ; if empty, infer it from the code and say what you inferred):
- Trace the component as a keyboard user would: Tab into it, operate each control with Enter, Space, the arrow keys and Escape as its role demands, and Tab out. Note each place this fails.
- Check for these, citing the WCAG criterion for each failure:
- Mouse-only controls (2.1.1): click handlers on non-focusable elements, hover-only reveals, drag-only actions without an alternative (2.5.7).
- Traps (2.1.2): focus that cannot leave, or a modal that lets focus escape behind it.
- Focus order (2.4.3): positive
tabindex, DOM order that differs from visual order, and focusable elements that are hidden off-screen. - Focus visible (2.4.7) and not obscured (2.4.11): removed outlines, focus hidden behind sticky headers.
- Focus management: where focus goes when content opens, closes, is deleted or loads.
- Composite widgets: the expected keys from the WAI-ARIA Authoring Practices for this widget type, with one Tab stop for the group using roving
tabindexoraria-activedescendant. - Single-character shortcuts (2.1.4) and context changes on focus (3.2.1).
- Fix each barrier, preferring native elements:
buttonanda hrefinstead of handlers ondiv,dialogwithshowModal()for modals, andinertfor background content. Use:focus-visiblefor focus styles with at least a 2 px outline that contrasts 3:1 with its surroundings. - Read keys with
event.key, not the deprecatedkeyCode. Do not swallow Tab, and do not prevent default on keys you do not handle. - Keep the visual design and public API the same unless a fix requires a change. Note any change you had to make.
- Fix only keyboard and focus issues. List other accessibility problems you notice in one line each at the end.
- Never add
tabindexgreater than 0. Addtabindex="0"only to elements that need focus and have a role. - Read the relevant code before making a claim about it. Do not guess what a file, function or config contains.
- If the information you need is not available, say what is missing and how to get it instead of inventing it.
Barriers
| # | Problem | WCAG SC | Location | Fix |
Fixed code
A unified diff against the given code, or the full component if the changes are extensive.
Keyboard test checklist
| Step | Key | Expected result | Covering entering, operating, leaving, and opening and closing every popup or dialog, ready for QA.
1 required value still a placeholder; the assistant will ask for it.
details
- kind
- Prompt: a task you run by name to get one finished thing back
- domain
- Software engineering
- category
- Accessibility
- level
- Intermediate
- made for
- Frontend engineer, QA / test engineer
- needs
- repo-read, file-write
- risk
- edits-files
- version
- v1.0.0 · incubating
- reviewed
- 2026-10-02
- works in
- Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity, OpenCode, Windsurf, Zed, Continue, AGENTS.md
use in
npx @hermes-hq/hodios install fix-keyboard-navigation --target claude-codenpx skills add hermes-hq/hodios-dist --skill fix-keyboard-navigation -a claude-codeclaude plugin marketplace add hermes-hq/hodios-distclaude plugin install hodios-software-engineering@hodiosThe plugin brings every entry in this domain at once.
pairs well with
All of AccessibilityAccessibility specialist
Accessibility specialist who builds and reviews with WCAG, the ARIA Authoring Practices and real assistive-technology behaviour in mind, ranking barriers by who is blocked.
accessibility-specialistBuild an accessible ARIA widget
Implements a combobox, tabs, dialog, menu, disclosure, tree or listbox per the ARIA Authoring Practices pattern, using native elements whenever they suffice. Use for custom interactive widgets.
build-aria-widgetAudit web accessibility against WCAG 2.2
Audits markup or components against WCAG 2.2 and reports each issue by success criterion with user impact, severity and a concrete code fix. Use before a release or a compliance review.
audit-web-accessibilityAudit a mobile screen for accessibility
Audits an iOS, Android, React Native or Flutter screen for labels, traits, focus order, text scaling, touch targets, contrast and gestures, with platform fixes and a VoiceOver or TalkBack test script.
audit-mobile-accessibilityBuild or fix an accessible form
Builds or repairs a web form with programmatic labels, grouping, autocomplete, helpful error messages and announced validation. Use for sign-up, checkout, settings or any data-entry form.
fix-form-accessibilityReview colour contrast and fix the palette
Checks colour pairs or design tokens against contrast requirements and proposes the nearest passing alternatives that keep the brand hue. Use when defining or auditing a palette or theme.
review-color-contrast