keyboard-navigation

Installation
SKILL.md

Keyboard Navigation

Design interactions so that every task can be completed using only a keyboard. This is non-negotiable — it's the foundation of all interaction accessibility.

Who This Is For

  • People with motor disabilities who cannot use a mouse
  • People using switch devices or mouth sticks
  • Screen reader users (keyboard is their primary input)
  • Power users who prefer keyboard for speed
  • Anyone with a temporarily injured hand or arm

Core Principles

Everything Must Be Reachable

  • Every interactive element must be focusable via Tab key
  • Focus order must follow the visual reading order (left to right, top to bottom in LTR languages)
  • No element should be reachable only by mouse hover or click
  • Custom components need explicit tabindex and keyboard handlers

Focus Must Be Visible

  • Focus indicator must be visible on every interactive element
  • Minimum: 2px solid outline with 3:1 contrast against background
  • Never use outline: none or outline: 0 without a visible replacement
  • Focus style should be consistent across the entire interface
  • Test: can you always see which element is focused?

Focus Must Be Managed

  • When a modal opens, move focus into the modal
  • When a modal closes, return focus to the element that opened it
  • When content is deleted, move focus to a logical next element
  • When a page section updates dynamically, manage focus appropriately
  • Never trap focus unintentionally (only trap inside open modals)

Keyboard Patterns by Component

Navigation Menus

  • Tab moves between top-level items
  • Arrow keys move within a dropdown
  • Enter/Space activates a menu item
  • Escape closes an open dropdown and returns focus to trigger

Tabs

  • Tab moves to the active tab panel, not through all tabs
  • Arrow keys move between tabs
  • Enter/Space activates a tab (if not automatic)

Modals / Dialogs

  • Focus moves to first focusable element inside modal on open
  • Tab cycles only within the modal (focus trap)
  • Escape closes the modal
  • Focus returns to trigger element on close

Forms

  • Tab moves between fields in logical order
  • Error messages are focusable or announced
  • Submit via Enter key on the last field or a visible button
  • Required field indicators are not conveyed by colour alone

Drag and Drop

  • Always provide a keyboard alternative (move up/down buttons, select-and-place, or arrow key reordering)
  • Announce the current position and available actions

Carousels / Sliders

  • Arrow keys move between items
  • Provide visible previous/next buttons
  • Pause autoplay on focus or hover
  • Announce current position ("Item 2 of 5")

Skip Links

Every page should have a "Skip to main content" link as the first focusable element. This lets keyboard users bypass repeated navigation.

  • Visible on focus (can be visually hidden until focused)
  • Links to the main content area via an anchor
  • Consider additional skip links for long pages ("Skip to search", "Skip to footer")

Assessment Checklist

  • Every interactive element is reachable via Tab
  • Focus order matches visual order
  • Focus indicator is visible on every element (2px, 3:1 contrast)
  • Modals trap focus and return it on close
  • All custom components have keyboard handlers
  • Drag-and-drop has a keyboard alternative
  • Skip link is present and functional
  • No keyboard traps exist anywhere in the interface
  • Dynamic content changes manage focus appropriately
Weekly Installs
8
GitHub Stars
40
First Seen
Today