hermes

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.

context

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.

task

Fix keyboard access in this component (widget type: ; if empty, infer it from the code and say what you inferred):

  1. 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.
  2. 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 tabindex or aria-activedescendant.
  • Single-character shortcuts (2.1.4) and context changes on focus (3.2.1).
  1. Fix each barrier, preferring native elements: button and a href instead of handlers on div, dialog with showModal() for modals, and inert for background content. Use :focus-visible for focus styles with at least a 2 px outline that contrasts 3:1 with its surroundings.
  2. Read keys with event.key, not the deprecated keyCode. Do not swallow Tab, and do not prevent default on keys you do not handle.
  3. Keep the visual design and public API the same unless a fix requires a change. Note any change you had to make.
constraints
  • Fix only keyboard and focus issues. List other accessibility problems you notice in one line each at the end.
  • Never add tabindex greater than 0. Add tabindex="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.
output format

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

Edit on GitHubReport a problem

use in

Hodios CLI
npx @hermes-hq/hodios install fix-keyboard-navigation --target claude-code
Agent Skills
npx skills add hermes-hq/hodios-dist --skill fix-keyboard-navigation -a claude-code
Add the Hodios marketplace (once)
claude plugin marketplace add hermes-hq/hodios-dist
Install the software-engineering plugin
claude plugin install hodios-software-engineering@hodios

The plugin brings every entry in this domain at once.

pairs well with

All of Accessibility
PersonaAccessibility

Accessibility 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-specialist
PromptAccessibility

Build 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-widget
PromptAccessibility

Audit 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-accessibility
PromptAccessibility

Audit 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-accessibility
PromptAccessibility

Build 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-accessibility
PromptAccessibility

Review 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