Keyboard shortcuts are documented and non-conflicting

Custom keyboard shortcuts that override browser defaults — Ctrl+W, Ctrl+T, Ctrl+L — can trap users who reach for familiar browser actions and instead trigger in-app behavior. WCAG 2.2 SC 2.1.4 (Character Key Shortcuts) is a Level A requirement: any keyboard shortcut using only printable characters must be remappable, togglable, or active only on focus. Undocumented shortcuts are also inaccessible to AT users who need to know what keyboard controls are available.

Document all custom keyboard shortcuts in an in-app help panel, avoid overriding critical browser shortcuts, and add the ability to disable or remap shortcuts.

// Keyboard shortcut registry — avoids browser-reserved combinations
const SHORTCUTS = [
  { key: '?', action: 'Open keyboard shortcuts help' },
  { key: 'Ctrl+K', action: 'Open command palette' },
  // Avoid: Ctrl+W (close tab), Ctrl+T (new tab), Ctrl+L (address bar)
]

export function KeyboardShortcutsHelp() {
  return (
    <dialog aria-labelledby="shortcuts-title">
      <h2 id="shortcuts-title">Keyboard shortcuts</h2>
      <ul>
        {SHORTCUTS.map(s => (
          <li key={s.key}>
            <kbd>{s.key}</kbd> — {s.action}
          </li>
        ))}
      </ul>
    </dialog>
  )
}

Open the help panel with ? and link to it from the app's navigation so users know shortcuts exist. Per WCAG 2.2 SC 2.1.4, single-character shortcuts must be disableable or remappable.

• ID: accessibility-wcag.robust.keyboard-shortcuts

• Severity: info

• What to look for: Enumerate every relevant item. Check for keyboard shortcuts in the application (e.g., Ctrl+S, Cmd+/, Alt+Enter). Verify that shortcuts are documented and do not conflict with browser or OS defaults. Check that non-printable key combinations do not require remapping for alternative input methods.

• Pass criteria: At least 1 of the following conditions is met. Any custom keyboard shortcuts are documented (in a help section or ? key). Shortcuts do not override critical browser shortcuts.

• Fail criteria: Keyboard shortcuts are not documented, or shortcuts conflict with browser/OS shortcuts.

• Skip (N/A) when: The project has no custom keyboard shortcuts.

• Detail on fail: Example: "App uses Ctrl+W to close a panel, conflicting with browser's close-tab shortcut. No documentation of available shortcuts"

• Remediation: Document and test shortcuts:

  // Document shortcuts
  export function KeyboardHelp() {
    return (
      <div>
        <h2>Keyboard Shortcuts</h2>
        <ul>
          <li><kbd>?</kbd> — Open this help menu</li>
          <li><kbd>Ctrl + K</kbd> — Open command palette</li>
          <li><kbd>Escape</kbd> — Close modal</li>
        </ul>
      </div>
    )
  }
  
  // Implement shortcuts
  useEffect(() => {
    const handleKeyDown = (e) => {
      if (e.key === '?') showHelp()
      if (e.ctrlKey && e.key === 'k') showCommandPalette()
    }
    document.addEventListener('keydown', handleKeyDown)
    return () => document.removeEventListener('keydown', handleKeyDown)
  }, [])