Cross-Platform Keyboard Shortcuts Playbook

Scope

This guide standardizes keyboard shortcut behavior across browser and OS environments.

Core Rules

• detect modifier as metaKey || ctrlKey
• normalize key string to lowercase
• register listeners in lifecycle hooks only
• remove listeners on teardown

Context Gating

Do not trigger global shortcuts when focus is in:

• text input
• textarea
• contenteditable region

Allow opt-in exceptions with explicit data attributes.

Conflict Policy

Define reserved combinations:

• browser critical shortcuts remain untouched
• product shortcuts must call preventDefault() only when intentional
• add compatibility notes for Firefox and Safari differences

Suggested Utility

export function isGlobalShortcutAllowed(target: EventTarget | null): boolean {
  const el = target as HTMLElement | null;
  if (!el) return true;
  const tag = (el.tagName || "").toLowerCase();
  const editable = el.getAttribute("contenteditable") === "true";
  return !editable && tag !== "input" && tag !== "textarea";
}

Registration Pattern

• register in top-level layout on mount
• delegate to feature-specific handlers
• keep one global listener to prevent duplicates

QA Matrix

Platform:

• macOS with Cmd modifiers
• Linux and Windows with Ctrl modifiers

Browsers:

• Chromium
• Firefox
• WebKit

States:

• modal open
• input focused
• route transitions

Telemetry

• shortcut_pressed
• shortcut_blocked_by_context
• shortcut_conflict_detected

Anti-patterns

• binding listeners in multiple nested components
• hardcoding one OS behavior
• executing global actions from inside text input fields