Keyboard Shortcut Systems

---
name: keyboard-shortcut-systems
description: "Design and implement cross-platform, conflict-free keyboard shortcut systems with proper scope, discoverability, and OS/browser safety."
metadata:
  tags: "keyboard-shortcuts, cross-platform, modifier-keys, conflict-resolution, scoping, discoverability, user-experience"
  source: "https://skilldb.dev/skills/autonomous-agent-skills/keyboard-shortcut-systems"
  pack: "autonomous-agent-skills"
  category: "Autonomous Agents"
---

# Keyboard Shortcut Systems

## When to use this skill
Use when the user says things like:
- "how do i implement keyboard shortcut systems"
- "explain how to register and resolve shortcut conflicts"
- "how to handle cmd vs ctrl modifiers cross platform"
- "show how to scope shortcuts to contexts and avoid browser conflicts"
- "give me best practices for discoverable shortcuts"


You are an AI agent that implements keyboard shortcut systems that are discoverable, conflict-free, and cross-platform. You understand modifier key differences between operating systems, how to scope shortcuts to contexts, and how to avoid conflicting with browser and OS shortcuts.

## Philosophy

Keyboard shortcuts are a power-user feature that, when done right, dramatically improve productivity. But they carry responsibility: conflicting with browser shortcuts confuses users, undiscoverable shortcuts are wasted effort, and shortcuts that vary by platform frustrate cross-platform users. A good shortcut system is consistent, learnable, and stays out of the way of the browser and OS.

## Techniques

### Register Key Bindings
- Listen for `keydown` events (not `keyup` or `keypress`, which is deprecated).
- Check `event.key` for the pressed key (modern, layout-aware).
- Check `event.ctrlKey`, `event.metaKey`, `event.altKey`, `event.shiftKey` for modifiers.
- Prevent default browser behavior only for shortcuts you are handling.
- Unbind listeners on component unmount to prevent memory leaks and ghost handlers.

### Handle Modifier Keys Correctly
- Use `Cmd` on macOS and `Ctrl` on Windows/Linux for primary shortcuts.
- Detect the platform and adjust modifier display and behavior accordingly.
- Use `event.metaKey` for Cmd on macOS, `event.ctrlKey` for Ctrl elsewhere.
- Show the correct modifier symbol in UI: `Cmd` or the clover symbol on Mac, `Ctrl` on Windows.
- Avoid `Alt` for common shortcuts as it activates the menu bar on Windows.

### Resolve Conflicts
- Maintain a registry of all shortcuts to detect conflicts at registration time.
- Never override critical browser shortcuts: Ctrl+T, Ctrl+W, Ctrl+N, Ctrl+L.
- Avoid Ctrl+S unless you provide save functionality (users expect file save).
- Test shortcuts in all target browsers to check for conflicts.
- Warn during development if a new shortcut conflicts with an existing one.

### Scope Shortcuts to Contexts
- Global shortcuts: available everywhere in the application (e.g., Ctrl+K for search).
- Component shortcuts: active only when a specific component is focused or visible.
- Modal shortcuts: active only within a modal dialog, suppressing global shortcuts.
- Use a stack-based system: pushing a new scope suppresses the previous one.
- Remove scope-specific shortcuts when the scope is destroyed.

### Build Shortcut Discovery UI
- Provide a shortcut cheat sheet accessible via `?` or a help menu.
- Show shortcuts next to menu items and button tooltips.
- Group shortcuts by category in the help panel.
- Allow searching within the shortcut list.
- Keep the cheat sheet synchronized with actual registered shortcuts.

### Handle Cross-Platform Differences
- `Cmd` on macOS maps to `Ctrl` on Windows/Linux for most shortcuts.
- `Option` on macOS maps to `Alt` on Windows/Linux.
- Some keys have different names: `Backspace` vs `Delete` on Mac.
- Function keys (F1-F12) may be intercepted by the OS.
- Test on both platforms or use a platform abstraction layer.

## Best Practices

1. Follow established conventions: Ctrl+Z for undo, Ctrl+S for save, Ctrl+F for find.
2. Use single-key shortcuts sparingly and only when an input is not focused.
3. Show shortcuts in tooltips so users discover them naturally.
4. Make every shortcut-triggered action also available via mouse/menu.
5. Do not intercept shortcuts when the user is typing in an input or textarea.
6. Log shortcut usage to understand which shortcuts users actually rely on.
7. Keep the total number of shortcuts manageable: quality over quantity.
8. Allow users to customize shortcuts in advanced settings.

## Anti-Patterns

- **Browser conflict**: Overriding Ctrl+T, Ctrl+W, or other browser-owned shortcuts.
- **Undiscoverable shortcuts**: Powerful shortcuts that no user knows exist.
- **Platform blindness**: Showing "Ctrl+C" to Mac users instead of "Cmd+C."
- **Global-only shortcuts**: No scoping, so shortcuts fire inappropriately when modals or panels are open.
- **Input interference**: Shortcuts that fire when the user is typing in a text field.
- **No cleanup**: Event listeners that persist after components are destroyed, causing ghost actions.
- **Modifier overload**: Requiring three-key combinations (Ctrl+Alt+Shift+K) that are hard to press.
- **Shortcut creep**: Adding so many shortcuts that they conflict with each other and become unlearnable.