keyboard-shortcuts

Files (1)

• SKILL.md

SKILL.md (first lines)

# Keyboard shortcuts: audit and implement

Most codebases arrive at shortcuts the same way: a `useEffect` with `addEventListener('keydown')` in one component, another in a modal, a `cmdk` palette somebody wired up for search, and a `Cmd+S` handler that fights the browser. The keys nobody documented stop working when a text field has focus, and no two of them agree on what counts as "focused".

The job here is not to add more listeners. It is to find what is missing, separate the genuine defects from the nice-to-haves, and replace the scattered handlers with one small system where bindings are data and discoverability falls out for free.

Work in phases. Do not skip the audit and go straight to code: the value of this skill is mostly in deciding what deserves a key, and a keymap invented without reading the app will be wrong.

## Phase 0: scope the app before auditing it

Two questions decide the size of everything that follows.

**Is this a keyboard-relevant surface at all?** A marketing site, a CLI, a backend service, or a docs build gets Phase 1 Tier 0 only (keyboard access is still a legal and usability requirement) and nothing else. Say so and stop rather than bolting a command palette onto a landing page.

**What shape is the app?** This picks the interaction model, and getting it wrong is the most common failure:

| App shape | Model | Real examples |
|---|---|---|
| Lists of objects the user acts on (issues, emails, rows, records) | Bare letters plus prefix sequences | Linear, Superhuman, Gmail, GitHub |
| A document or text editor | No bare letters at all. Typed triggers (`/`, `@`, `[[`, markdown autoformat) plus modifier chords | Notion |
| A canvas, board, or IDE-like tool | Bare letters for tools (canvas focus is not text focus) plus heavy chords | Figma, VS Code |
| Forms, dashboards, settings, content | Tier 0 and Tier 1 only. No bare letters. | Most CRUD apps |

All four converge on `Mod+K` for the palette, and all four then overload `Mod+K` to "insert link" inside a text field. Plan for that overload from the start.

Record the answer. Everything downstream refers back to it.

## Phase 1: audit

### Find what exists

Run these against the repo (adjust globs to the stack). The first one matters most: existing ad-hoc listeners are what you are going to consolidate and delete.

```bash
# Ad-hoc key handling: the thing to replace
rg -n "addEventListener\(['\"]keydown|onKeyDown|useHotkeys|tinykeys|hotkeys\(|Mousetrap" -g '!node_modules'
# Existing palette / kbd / a11y annotations: extend these, do not duplicate them
rg -n "cmdk|CommandDialog|kbar|CommandPalette|<kbd|aria-keyshortcuts"
# Modals, dialogs, drawers, popovers
rg -n "role=[\"']dialog|<Dialog|<Modal|<Sheet|<Drawer|<Popover"
# Lists, tables, grids, menus
rg -n "role=[\"'](grid|listbox|menu|table)|<table|<DataTable|<Virtuoso" -g '*.tsx'
# Forms and submits
rg -n "<form|onSubmit|handleSubmit"
# Search inputs
rg -n "type=[\"']search|placeholder=[\"'][^\"']*[Ss]earch"
# Destructive actions: each one needs undo or keyboard-reachable confirm
rg -n "delete|archive|remove|destroy|revoke" -g '*.ts*' -l
# Editors: the Mod+K overload zone
rg -n "contentEditable|@tiptap|ProseMirror|lexical|slate|CodeMirror|monaco"
# Mouse-only handlers: an accessibility defect and a shortcut gap at once
rg -n "onClick" -g '*.tsx' | rg -v "<button|<a |role=|onKeyDown"
```

### Classify every gap into one of four tiers

**Tier 0, must. Report these as bugs, not as features.** They are correctness and accessibility defects, and framing them as enhancements is how they stay unfixed.

| Surface | Required | Why it is a defect without it |
|---|---|---|
| Modal, dialog, drawer, popover | `Escape` closes it, focus moves inside on open, focus returns to the trigger on close, `Tab` stays trapped inside | WCAG 2.1.2 No Keyboard Trap and 2.4.3 Focus Order. A keyboard user is stranded. |
| Any list, grid, menu, or combobox the mouse can traverse | Arrow keys move, `Enter` activates, `Home`/`End` jump, `Escape` exits | WCAG 2.1.1 Keyboard. Mouse-only traversal is a hard failure. |
| Every form | `Enter` submits single-line forms, `Mod+Enter` submits multi-line ones | The user cannot finish the task without a mouse. |
| Every destructive action | Undo, or a confirm that the keyboard can reach and dismiss | A key that destroys data with no way back is worse than no key. |
| `onClick` on a div, span, or styled non-button | `onKeyDown` for `Enter` and `Space`, plus `tabIndex` and a `role` | WCAG 2.1.1 again. Extremely common in React codebases and usually the largest single finding. |
| Primary search | Reachable in one keystroke (`/` or `Mod+K`) | |

**Tier 1, should. Ordered by value per unit of effort.** These are what make an app feel fast.

`Mod+K` palette · `?` help sheet · `Escape` dismisses anything transient · `Mod+Enter` submit · `Mod+Z` / `Mod+Shift+Z` undo and redo · `Mod+S` with a "Saved" toast even when the app autosaves (intercepting it is mostly about stopping the browser's Save Page dialog and reassuring the user, which is why Figma and Notion both do it) · `/` focuses search · arrows plus `Enter` in every result list.

**Tier 2, could. Only for the list-shaped model from Phase 0.**

`J`/`K` move · `G` then a letter to go somewhere (`G I` inbox) · bare letters acting on the focused row (`E` archive, `A` assignee, `X` select) · `Shift+click` range select · `Mod+1..9` switch views · `Mod+\` sidebar · `Mod+[` and `Mod+]` history · copy-the-thing shortcuts, which are quietly high value (Linear has separate keys for copy ID, copy URL, and copy git branch name).

**Never bind.** `Mod+W`, `Mod+T`, `Mod+N`, `Mod+Q`, `Mod+L`, `Mod+Shift+N`, `Mod+Shift+T`. Firefox removed `Ctrl+N`/`T`/`W` from script control and closed it WONTFIX, so some of these cannot be intercepted at all. Also never: a bare letter for a destructive action without undo, a shortcut for something a user does once a month, and `Mod+F` unless you are shipping an in-app find that genuinely beats the browser's.

### How much is enough

A skill like this fails in two directions. Under-applying leaves Tier 0 defects in place. Over-applying puts forty bindings into a settings page nobody navigates by keyboard. The tier system is the guard: Tier 0 is unconditional, Tier 1 is near-unconditional for any app with a logged-in workflow, and Tier 2 needs the app to actually be list-shaped. If you find yourself adding `J`/`K` to a billing settings form, go back to Phase 0.

### Report before you build

Write the audit to `docs/keyboard-audit.md` and show the user the summary. Use this shape:

```markdown
# Keyboard audit

App shape: <one of the four models, and why>
Existing key handling: <N ad-hoc listeners across M files, list them>

## Tier 0: defects (N)
| # | Surface | File:line | Missing | Standard |

## Tier 1: recommended (N)
| # | Binding | Command | Scope | File(s) affected |

## Tier 2: considered and declined
<what you are not adding, and why. This matters as much as what you are adding.>

## Conflict map
| Key | Meaning in scope A | Meaning in scope B | Resolution |

## Proposed keymap
<the full table, as it will appear in the code>
```

Then stop and get agreement on the keymap. Bindings are muscle memory and changing them later is expensive, so a five-minute review now is cheap. If the user has already said to just do it, proceed straight to Phase 2 but still write the report, since it is the document the help sheet and the PR description come from.

## Phase 2: build the spine

Commands and keys are separate things. The registry holds commands; the keymap maps keys to command **ids**, never to functions. Do this and the palette, the help sheet, the tooltips, user remapping, and telemetry all become views over one data structure. Skip it and the palette and the keymap drift apart within a month, which is the single most common way this work rots.

This is the model VS Code uses (`key`, `command`, `when`, resolved last-match-wins so user overrides appended at the end beat defaults). Build it directly rather than reaching for a framework.

Create these files under `src/keyboard/` (match the repo's own conventions for location and style):

### `context.ts` — the observable map that scopes everything

From nparashar150/claude-keyboard-shortcuts, MIT.