SuperAPI AI Directory
Partner中文AI newsFavorites
Skillskeyboard-shortcuts

keyboard-shortcuts

Design & creation

View repository

Updated 10-15 20:09

About this skill

Keyboard Shortcuts Skill

Trigger conditions (when to apply)

  • Apply when the request is for "keyboard shortcuts," "key bindings," "hotkeys," "shortcut keys," or "keyboard navigation."
  • When handling interactive elements in UI implementation (/design-ui / /design-assemble / front-end implementation), use together as needed.
  • accessibility-engineer Often used in combination with the skill (keyboard operation in general is covered by that one; this skill specializes in shortcut design).

Basic policy of this Skill (organizing axes)

  • Official standards first: Treat W3C APG keyboard patterns and WCAG 2.1/2.2 success criteria as the highest-level basis.
  • Respect platform conventions: Do not hijack OS reserved keys (macOS: ⌘+Space, ⌘+Tab, etc. / Windows: Win+L, etc.) or browser standard keys (Ctrl+T, Ctrl+W, etc.).
  • Leverage de facto standards: Adopt patterns widely established in GitHub, Gmail, Slack, X, etc. (? help,/ to search,j/k to move through lists, etc.) according to context, reducing the user's learning cost.
  • Discoverability and disableability: Shortcuts are not hidden features. Always provide a list view (?), tooltips, and a means to disable/remap them.

Philosophy (decision rules)

1) Compliance with official standards (WCAG / APG)

  • WCAG 2.1.1 (A): All functionality must be operable via keyboard. Shortcuts are an added convenience, and it is a prerequisite that functionality be usable without shortcuts.
  • WCAG 2.1.2 (A): Do not create keyboard traps. Focus traps inside modals are an exception, butEscape must always allow escape.
  • WCAG 2.1.4 (A): Single-character keys(without modifier keys) shortcuts must provide one of the following:
    1. A mechanism to disable them
    2. A mechanism to remap them to include a modifier key
    3. Enable them only when the component has focus
  • WCAG 2.4.7 (AA): Always keep the focus indicator visible. The same applies to the destination after moving focus via a shortcut.
  • Reference: WAI-ARIA APG Keyboard Interface / APG Patterns

2) Keyboard patterns for composite widgets (APG-compliant)

The following are the standard key assignments per widget defined by APG. Do not implement your own; follow these patterns.

widget Internal movement Primary keys
Tabs Left/Right arrows (horizontal) / Up/Down arrows (vertical) Home, End, Delete (close)
Menu / Menubar Up/Down arrows (vertical) / Left/Right arrows (horizontal) Enter/Space (activate), Escape (close)
Listbox Up/Down arrows Home, End, Type-ahead
Grid Up/Down/Left/Right arrows PageUp/Down, Ctrl+Home/End
Tree View Up/Down arrows, Left (collapse), Right (expand) Enter (execute), *(expand all)
Dialog (Modal) Tab (internal cycle) Escape (close), focus trap required
Combobox Up/Down arrows (within popup) Escape (close), Enter (select)
Radio Group Up/Down/Left/Right arrows Space (select)
Toolbar Left/Right arrows Home, End
  • Focus management: Roving Tabindex (focused tabindex="0" / others tabindex="-1") or aria-activedescendant are used appropriately.

3) Platform conventions (conflict avoidance)

Cross-platform support for modifier keys

Function macOS Windows / Linux
app command ⌘ Cmd Ctrl
Alternative operation ⌥ Option Alt
Reverse direction/extension ⇧ Shift Shift

Reserved keys (never take over)

  • macOS: ⌘+Space（Spotlight）, ⌘+Tab(app switch), ⌘+Q(quit), ⌘+H(hide), ⌘+M(minimize), Ctrl+F1/Ctrl+F7(keyboard access)
  • Windows: Win+L(lock), Alt+Tab(switch), Alt+F4(quit), Ctrl+Alt+Del
  • Common to browsers: Ctrl/⌘+T(new tab), Ctrl/⌘+W(close tab), Ctrl/⌘+L(address bar), F5/⌘+R(reload), Ctrl/⌘+F(find in page)
  • Assistive technology: Avoid CapsLock / Insert (used as screen reader modifier keys)
  • Reference: Apple HIG - Keyboards / macOS shortcut list

4) De facto standards (industry-common patterns)

Patterns commonly established across major services (GitHub / Gmail / Slack / X / Notion / VS Code). Adopt them actively when the context fits.

Global shortcuts (entire page)

key Function Adoption example
? Show shortcut help list GitHub, Gmail, X
/ Focus the search bar GitHub, X, YouTube
Escape Close modal/popup/drawer Common to all services
⌘/Ctrl+K command palette / quick switcher GitHub, Slack, VS Code, Linear

List/feed operations (vim-style)

key Function Adoption example
j Move to next item Gmail, X, GitHub
k Move to previous item Gmail, X, GitHub
o / Enter Open selected item Gmail, X
x Select/check item Gmail

page navigation (sequential keys)

key Function Adoption example
g → h Go to home X
g → i Go to Inbox / Issues Gmail, GitHub
g → n Go to notifications X
g → p Go to profile / Pull Requests X, GitHub

action

key Function Adoption example
n / c Create new (post / email / Issue) X (n), Gmail (c)
r Reply X, Gmail
l / s like / star X (l), Gmail (s)

5) Principles for implementation

  • Use KeyboardEvent.key: keyCoderather than (deprecated) event.key for detection. When physical layout matters (games, etc.), use event.code appropriately. Reference: W3C UI Events KeyboardEvent key Values
  • Normalization of modifier keys: macOS の ⌘ と Windows の Ctrl are mapped to the same function (event.metaKey || event.ctrlKey）。
  • sequential key: g → i For two-key sequences like this, set a timeout (500–1000ms) and provide visual feedback for the intermediate state.
  • Avoiding conflicts with input fields: <input>, <textarea>, [contenteditable] When focus is on this, disable global shortcuts.
  • Customization support: Provide a UI or settings that let users disable or remap shortcuts (WCAG 2.1.4 compliance).

Approach (questions to confirm first)

  1. Which features of this UI should be assigned shortcuts? (Not every feature needs a shortcut. Prioritize frequently used operations.)
  2. Target platforms? (Web / macOS / Windows / cross-platform)
  3. Are there list/feed-type UI elements? (j/k deciding whether to apply the pattern)
  4. Will a command palette be implemented? (⌘/Ctrl+K pattern)
  5. Are there existing shortcut frameworks/libraries? (tinykeys, hotkeys-js, Mousetrap, etc.)

Output format (at implementation time)

  1. Shortcut list: Feature / Key / Context (global or within focus) / Source (APG / de facto / custom)
  2. Conflict check: Whether there are conflicts with OS-reserved / browser standard / assistive technology keys
  3. WCAG 2.1.4 compliance: Policy for disabling single-character keys / remapping / limiting to focus
  4. Focus management: Definition of where focus moves after a shortcut is triggered
  5. Discoverability: ? Policy for providing help / tooltips / documentation
  6. Implementation policy: Event handling, library selection, test plan

checklist

Basic requirements (WCAG compliance)

  • All interactive elements are operable via keyboard (2.1.1)
  • No keyboard traps exist (2.1.2)
  • Provide disable/remap/focus limitation for single-character key shortcuts (2.1.4)
  • Focus indicators are visible (2.4.7)
  • Focus is not obscured by other elements (2.4.11)

Conflict avoidance

  • Does not conflict with OS-reserved keys (⌘+Space, Win+L, etc.)
  • Does not conflict with browser standard keys (⌘+T, ⌘+W, ⌘+F, etc.)
  • Does not use assistive technology modifier keys (CapsLock, Insert)
  • Global shortcuts do not accidentally trigger during text input

De facto compliance

  • Considered whether to adopt the j/k pattern for list/feed operations
  • Considered whether to adopt the / pattern for search focus
  • Provided shortcut help display (?)
  • Escape closes modal/popup

Implementation quality

  • event.key Is used (keyCode deprecated)
  • Implemented cross-platform support for macOS / Windows
  • sequential keys have timeout and feedback
  • The shortcut list is documented

Common pitfalls

  • Overriding OS/browser reserved keys — This breaks the user's basic operations. Check the conflict table in advance.
  • Accidental triggering inside input fields — <input> / <textarea> has focus but j/k triggers and moves through the list. Do not neglect to determine the focused target.
  • WCAG 2.1.4 violation — j/k/n Implementing single-character keys such as these without providing a way to disable them. They trigger accidentally during dictation by voice input users.
  • Undefined focus destination — After navigating screens via a shortcut, focus returns to the top of the page. Design the destination explicitly.
  • Over-assigning shortcuts — Trying to assign keys to every function makes them impossible to remember and causes conflicts. Narrow it down to 10–20 frequently used operations.
  • Inconsistent modifier keys — macOS で ⌘+K, the same function on Windows as Alt+K , and so on, with mappings varying across platforms.⌘ ↔ Ctrl Follow the mappings for
  • Incorrect platform detection — navigator.platform(deprecated).navigator.userAgentData or feature detection.
  • keyCode / which use of — It is deprecated and has locale-dependent issues.event.key Use

Short question template (do not guess missing information)

  • What is the main interaction pattern of this app? (List browsing / editor / dashboard / form-centric)
  • What is the target platform? (Web-only / Electron / PWA / native app)
  • Are there any existing keyboard shortcuts? (If so, ask them to provide a list)
  • Do users need to be able to customize shortcuts?

Reference documents

Official standards

De facto references