name: keyboard-shortcuts
user-invocable: false
description: UIキーボードショートカットを「公式基準（W3C APG / WCAG）＋プラットフォーム規約（Apple HIG / Fluent UI）＋デファクトスタンダード（GitHub・Gmail・Slack等）」に沿って設計し、衝突なく・発見しやすく・無効化可能な形で実装するための判断軸。
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): 単独文字キー（修飾キーなし）のショートカットには、以下のいずれかを提供する:
- 無効化する仕組み
- 修飾キー付きにリマップする仕組み
- コンポーネントがフォーカスを持つ時のみ有効にする
- WCAG 2.4.7 (AA): フォーカスインジケーターを常に可視にする。ショートカットでフォーカス移動した先も同様。
- 参照: WAI-ARIA APG Keyboard Interface / APG Patterns
2) 複合ウィジェットのキーボードパターン（APG準拠）
以下はAPGが定めるウィジェット別の標準キー割り当て。独自実装せず、このパターンに従う。
| ウィジェット |
内部移動 |
主要キー |
| Tabs |
左右矢印（水平）/ 上下矢印（垂直） |
Home, End, Delete（閉じる） |
| Menu / Menubar |
上下矢印（縦）/ 左右矢印（横） |
Enter/Space（実行）, Escape（閉じる） |
| Listbox |
上下矢印 |
Home, End, Type-ahead |
| Grid |
上下左右矢印 |
PageUp/Down, Ctrl+Home/End |
| Tree View |
上下矢印, 左（折畳）, 右（展開） |
Enter（実行）, *（全展開） |
| Dialog (Modal) |
Tab（内部循環） |
Escape（閉じる）, フォーカストラップ必須 |
| Combobox |
上下矢印（ポップアップ内） |
Escape（閉じる）, Enter（選択） |
| Radio Group |
上下/左右矢印 |
Space（選択） |
| Toolbar |
左右矢印 |
Home, End |
- フォーカス管理: Roving Tabindex（フォーカス中
tabindex="0" / 他 tabindex="-1"）または aria-activedescendant を使い分ける。
3) プラットフォーム規約（衝突回避）
修飾キーのクロスプラットフォーム対応
| 機能 |
macOS |
Windows / Linux |
| アプリコマンド |
⌘ Cmd |
Ctrl |
| 代替操作 |
⌥ Option |
Alt |
| 逆方向/拡張 |
⇧ Shift |
Shift |
予約済みキー（絶対に奪わない）
- 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）で共通して定着しているパターン。文脈が合えば積極的に採用する。
グローバルショートカット（ページ全体）
| キー |
機能 |
採用例 |
? |
ショートカットヘルプ一覧を表示 |
GitHub, Gmail, X |
/ |
検索バーにフォーカス |
GitHub, X, YouTube |
Escape |
モーダル/ポップアップ/ドロワーを閉じる |
全サービス共通 |
⌘/Ctrl+K |
コマンドパレット / クイックスイッチャー |
GitHub, Slack, VS Code, Linear |
リスト/フィード操作（vim風）
| キー |
機能 |
採用例 |
j |
次の項目へ移動 |
Gmail, X, GitHub |
k |
前の項目へ移動 |
Gmail, X, GitHub |
o / Enter |
選択した項目を開く |
Gmail, X |
x |
項目を選択/チェック |
Gmail |
ページナビゲーション（シーケンシャルキー）
| キー |
機能 |
採用例 |
g → h |
ホームへ移動 |
X |
g → i |
Inbox / Issues へ移動 |
Gmail, GitHub |
g → n |
通知へ移動 |
X |
g → p |
プロフィール / Pull Requests へ移動 |
X, GitHub |
アクション
| キー |
機能 |
採用例 |
n / c |
新規作成（ポスト / メール / Issue） |
X (n), Gmail (c) |
r |
返信 |
X, Gmail |
l / s |
いいね / スター |
X (l), Gmail (s) |
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 対応）。
進め方（最初に確認する問い）
- このUIのどの機能にショートカットを割り当てる？（全機能にショートカットは不要。頻度の高い操作を優先）
- ターゲットプラットフォームは？（Web / macOS / Windows / クロスプラットフォーム）
- リスト/フィード型のUI要素はある？（
j/k パターンの適用判断）
- コマンドパレットは実装する？（
⌘/Ctrl+K パターン）
- 既存のショートカットフレームワーク/ライブラリの有無は？（tinykeys, hotkeys-js, Mousetrap 等）
出力フォーマット（実装時）
- ショートカット一覧表: 機能 / キー / 文脈（グローバル or フォーカス内） / 参照元（APG / デファクト / カスタム）
- 衝突チェック: OS予約 / ブラウザ標準 / 支援技術との衝突がないか
- WCAG 2.1.4 対応: 単独文字キーの無効化/リマップ/フォーカス限定の方針
- フォーカス管理: ショートカット発動後のフォーカス移動先の定義
- 発見可能性:
? ヘルプ / ツールチップ / ドキュメントの提供方針
- 実装方針: イベントハンドリング・ライブラリ選定・テスト計画
チェックリスト
基本要件（WCAG準拠）
衝突回避
デファクト準拠
実装品質
よくある落とし穴
- 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 / ネイティブアプリ）
- 既存のキーボードショートカットがあるか？（あればリストを提示してもらう）
- ユーザーがショートカットをカスタマイズできる必要はあるか？
参照ドキュメント
公式基準
デファクト参照
By