keyboard-shortcuts

Keyboard Shortcuts Skill

発火条件（適用タイミング）

• 依頼が「キーボードショートカット」「キーバインド」「ホットキー」「ショートカットキー」「キーボードナビゲーション」なら適用する。
• UI実装（/design-ui / /design-assemble / フロント実装）でインタラクティブ要素を扱うとき、必要に応じて併用する。
• accessibility-engineer skill と組み合わせて使うことが多い（キーボード操作全般はそちらが基本、このskillはショートカット設計に特化）。

このSkillの基本方針（整理軸）

• 公式基準ファースト: W3C APG のキーボードパターンと WCAG 2.1/2.2 の成功基準を最上位の根拠とする。
• プラットフォーム規約の尊重: OS予約キー（macOS: ⌘+Space, ⌘+Tab 等 / Windows: Win+L 等）やブラウザ標準キー（Ctrl+T, Ctrl+W 等）を奪わない。
• デファクトの活用: GitHub・Gmail・Slack・X 等で広く定着したパターン（? でヘルプ、/ で検索、j/k でリスト移動等）を文脈に応じて採用し、ユーザーの学習コストを下げる。
• 発見可能性と無効化: ショートカットは隠れ機能ではない。一覧表示（?）・ツールチップ・無効化/リマップ手段を必ず提供する。

思想（判断ルール）

1) 公式基準への準拠（WCAG / APG）

• WCAG 2.1.1 (A): すべての機能がキーボードで操作可能であること。ショートカットは利便性の追加であり、ショートカットなしでも機能が使えることが前提。
• WCAG 2.1.2 (A): キーボードトラップを作らない。モーダル内のフォーカストラップは例外だが、Escape で必ず脱出可能にする。
• WCAG 2.1.4 (A): 単独文字キー（修飾キーなし）のショートカットには、以下のいずれかを提供する:
  1. 無効化する仕組み
  2. 修飾キー付きにリマップする仕組み
  3. コンポーネントがフォーカスを持つ時のみ有効にする
• WCAG 2.4.7 (AA): フォーカスインジケーターを常に可視にする。ショートカットでフォーカス移動した先も同様。
• 参照: WAI-ARIA APG Keyboard Interface / APG Patterns

2) 複合ウィジェットのキーボードパターン（APG準拠）

以下はAPGが定めるウィジェット別の標準キー割り当て。独自実装せず、このパターンに従う。

• フォーカス管理: Roving Tabindex（フォーカス中 tabindex="0" / 他 tabindex="-1"）または aria-activedescendant を使い分ける。

3) プラットフォーム規約（衝突回避）

修飾キーのクロスプラットフォーム対応

予約済みキー（絶対に奪わない）

• macOS: ⌘+Space（Spotlight）, ⌘+Tab（アプリ切替）, ⌘+Q（終了）, ⌘+H（隠す）, ⌘+M（最小化）, Ctrl+F1/Ctrl+F7（キーボードアクセス）
• Windows: Win+L（ロック）, Alt+Tab（切替）, Alt+F4（終了）, Ctrl+Alt+Del
• ブラウザ共通: Ctrl/⌘+T（新規タブ）, Ctrl/⌘+W（タブを閉じる）, Ctrl/⌘+L（アドレスバー）, F5/⌘+R（更新）, Ctrl/⌘+F（ページ内検索）
• 支援技術: CapsLock / Insert（スクリーンリーダの修飾キーとして使用）は避ける
• 参照: Apple HIG - Keyboards / macOS ショートカット一覧

4) デファクトスタンダード（業界共通パターン）

主要サービス（GitHub / Gmail / Slack / X / Notion / VS Code）で共通して定着しているパターン。文脈が合えば積極的に採用する。

グローバルショートカット（ページ全体）

リスト/フィード操作（vim風）

ページナビゲーション（シーケンシャルキー）

アクション

5) 実装時の原則

• KeyboardEvent.key を使う: keyCode（非推奨）ではなく event.key で判定する。物理配置が重要な場合（ゲーム等）は event.code を使い分ける。参照: W3C UI Events KeyboardEvent key Values
• 修飾キーの正規化: macOS の ⌘ と Windows の Ctrl を同一機能にマッピングする（event.metaKey || event.ctrlKey）。
• シーケンシャルキー: g → i のような2打鍵は、タイムアウト（500〜1000ms）を設け、中間状態を視覚的にフィードバックする。
• 入力フィールドとの競合回避: <input>, <textarea>, [contenteditable] にフォーカスがある時はグローバルショートカットを無効化する。
• カスタマイズ対応: ユーザーがショートカットを無効化・リマップできるUIまたは設定を提供する（WCAG 2.1.4 対応）。

進め方（最初に確認する問い）

1. このUIのどの機能にショートカットを割り当てる？（全機能にショートカットは不要。頻度の高い操作を優先）
2. ターゲットプラットフォームは？（Web / macOS / Windows / クロスプラットフォーム）
3. リスト/フィード型のUI要素はある？（j/k パターンの適用判断）
4. コマンドパレットは実装する？（⌘/Ctrl+K パターン）
5. 既存のショートカットフレームワーク/ライブラリの有無は？（tinykeys, hotkeys-js, Mousetrap 等）

出力フォーマット（実装時）

1. ショートカット一覧表: 機能 / キー / 文脈（グローバル or フォーカス内） / 参照元（APG / デファクト / カスタム）
2. 衝突チェック: OS予約 / ブラウザ標準 / 支援技術との衝突がないか
3. WCAG 2.1.4 対応: 単独文字キーの無効化/リマップ/フォーカス限定の方針
4. フォーカス管理: ショートカット発動後のフォーカス移動先の定義
5. 発見可能性: ? ヘルプ / ツールチップ / ドキュメントの提供方針
6. 実装方針: イベントハンドリング・ライブラリ選定・テスト計画

チェックリスト

基本要件（WCAG準拠）

• すべてのインタラクティブ要素がキーボードで操作可能（2.1.1）
• キーボードトラップが存在しない（2.1.2）
• 単独文字キーショートカットに無効化/リマップ/フォーカス限定を提供（2.1.4）
• フォーカスインジケーターが可視（2.4.7）
• フォーカスが他要素に遮蔽されない（2.4.11）

衝突回避

• OS予約キー（⌘+Space, Win+L 等）と衝突しない
• ブラウザ標準キー（⌘+T, ⌘+W, ⌘+F 等）と衝突しない
• 支援技術の修飾キー（CapsLock, Insert）を使用していない
• テキスト入力中にグローバルショートカットが誤発動しない

デファクト準拠

• リスト/フィード操作に j/k パターンを採用しているか検討した
• 検索フォーカスに / パターンを採用しているか検討した
• ショートカットヘルプ表示（?）を提供した
• Escape でモーダル/ポップアップが閉じる

実装品質

• event.key を使用している（keyCode 非推奨）
• macOS / Windows のクロスプラットフォーム対応をした
• シーケンシャルキーにタイムアウトとフィードバックがある
• ショートカット一覧が文書化されている

よくある落とし穴

• OS/ブラウザ予約キーの上書き — ユーザーの基本操作を壊す。事前に衝突テーブルを確認する。
• 入力フィールド内での誤発動 — <input> / <textarea> にフォーカスがあるのに j/k が発動してリスト移動する。フォーカス対象の判定を怠らない。
• WCAG 2.1.4 違反 — j/k/n 等の単独文字キーを実装して無効化手段を提供しない。音声入力ユーザーのディクテーション中に誤発動する。
• フォーカス移動先の未定義 — ショートカットで画面遷移した後、フォーカスがページ先頭に戻る。移動先を明示的に設計する。
• ショートカットの過剰割り当て — すべての機能にキーを割り当てようとして、覚えきれない・衝突する。頻度の高い操作10〜20個に絞る。
• 修飾キーの不統一 — macOS で ⌘+K、同じ機能を Windows で Alt+K にする等、プラットフォーム間で対応がバラバラ。⌘ ↔ Ctrl の対応を守る。
• プラットフォーム検出の誤り — navigator.platform（非推奨）に依存する。navigator.userAgentData や feature detection を使う。
• keyCode / which の使用 — 非推奨でロケール依存の問題がある。event.key を使う。

短問テンプレ（不足情報を推測しない）

• このアプリのメインの操作パターンは？（リスト閲覧 / エディタ / ダッシュボード / フォーム中心）
• ターゲットプラットフォームは？（Web専用 / Electron / PWA / ネイティブアプリ）
• 既存のキーボードショートカットがあるか？（あればリストを提示してもらう）
• ユーザーがショートカットをカスタマイズできる必要はあるか？

参照ドキュメント

公式基準

• W3C WAI-ARIA Authoring Practices Guide (APG)
• APG - Developing a Keyboard Interface
• WCAG 2.1 - 2.1.4 Character Key Shortcuts
• W3C UI Events KeyboardEvent key Values
• Apple HIG - Keyboards
• macOS Keyboard Shortcuts
• Windows Keyboard Accessibility

デファクト参照

• GitHub Keyboard Shortcuts
• Gmail Keyboard Shortcuts
• Slack Keyboard Shortcuts
• VS Code Keybindings