keyboard

Name: keyboard
Author: mgifford

github.com/mgiffordデザイン・UI57207 回インストール6 週間前に更新

リポジトリ

keyboard について

keyboard は、インタラクティブな UI を実装・レビューする人向けのキーボードアクセシビリティスキルです。標準的なキー操作、フォーカス管理、複合ウィジェットを扱い、ネイティブ要素の活用とテストを重視します。

主な機能

01キーボードでの到達と操作
02一般的なコントロールのキー操作
03ダイアログのフォーカス管理
04フォーカスの可視性と順序
05複合ウィジェットのキー操作

活用シーン

01キーボードだけで操作できるか確認
02モーダルダイアログのフォーカス動作を確認
03フォーカス表示とタブ順序を改善

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/mgifford/accessibility-skills --skill keyboard

インストール後、Claude Code で/keyboardを入力して読み込まれたか確認します。

同梱ファイルSYNC.md

詳細

キーボードアクセシビリティスキル

正規のソース：mgifford/ACCESSIBILITY.md の examples/KEYBOARD_ACCESSIBILITY_BEST_PRACTICES.md このスキルはこのファイルを基にしています。判断に迷った場合は、例を優先してください。

すべてのインタラクティブな UI 要素と機能に、以下のルールを適用してください。

中核となる要件

すべてのインタラクティブ機能は、マウスやタッチを使わず、キーボードだけで完全に操作できなければなりません。ただし、基盤となる機能が経路に沿った移動を本当に必要とする場合は除きます。キーボードで操作できることは、すべてのコントロールを Tab キーで順に移動できることと同じではありません。ネイティブウィジェットと複合ウィジェットではキー操作の規則が異なり、ユーザーはカスタムウィジェットの操作方法を理解できる必要があります。

重大度の基準（このスキル）

レベル	意味
致命的	キーボードユーザーと支援技術（AT）ユーザーがタスクを完了できなくなる
深刻	キーボードでの操作が大きく損なわれ、妥当な回避策がない
中程度	キーボードユーザーに不便が生じるが、回避策がある
軽微	ベストプラクティスからの逸脱で、キーボード操作への影響はわずか

ルールだけから重大度を決めないでください。タスクへの実際の影響を判断してください。不具合によってコンポーネントへの到達、操作、または退出が妨げられるか、必須のタスクが阻まれるのか、それとも任意の機能だけが使えなくなるのか、フォーカスが失われるか誤解を招く場所に置かれるか、妥当なキーボード操作方法が残されているかを考慮してください。

致命的：キーボードトラップがないこと

フォーカスをコンポーネント内に移動できる場合、ユーザーは Tab、Shift+Tab、矢印キー、または Escape を使って（コンポーネントに応じて）フォーカスを外へ移動できなければなりません。退出に特殊なコマンドが必要な場合は、コンポーネントの前、またはコンポーネント内に操作方法を示してください。

脱出方法のないキーボードトラップは致命的です。 モーダルダイアログで、標準化された、または文書化された退出方法がある場合に一時的にフォーカスを制限しても、トラップには該当しません。開いたときにフォーカスがダイアログ内に移動し、Tab／Shift+Tab でダイアログ内を移動でき、キーボードで操作可能なコントロールで閉じるか完了でき、閉じたときにフォーカスが起動元のコントロール、または別の論理的な場所に戻る必要があります。

埋め込みエディター、サードパーティ製ウィジェット、iframe、メディアプレーヤー、リモートデスクトップ、キャンバスアプリケーションは、Tab キーやその他のキーを消費することが多く、利用可能で文書化された退出方法が必要となるため、慎重にテストしてください。

致命的：すべてのインタラクティブ要素にキーボードで到達できること

マウスでアクティブにできるすべての要素は、キーボードで到達し、アクティブにできなければなりません。ネイティブ要素を使用してください。 ネイティブ要素は、キーボード動作、フォーカス可能性、セマンティクス、状態、ブラウザーとの統合を、追加コストなしで備えています。


<button type="button">Save</button>
<a href="/about">About</a>


<div role="button" tabindex="0">Save</div>

role="button" と tabindex="0" を追加しただけでは、ボタンの動作は追加されません。カスタムボタンでは、Enter キーと Space キーによるアクティブ化、無効状態、フォーカスのスタイル、期待されるアクセシブルな名前／状態も実装する必要があります。keydown ハンドラーが存在するかどうかだけでなく、実際の動作をテストしてください。コントロールの操作方法がマウスやタッチのハンドラーだけにならないようにしてください。

重大：想定されるキー動作

想定されるウィジェットのキー動作から逸脱することは重大です。支援技術を利用するユーザーが頼りにしているメンタルモデルを損ないます。文書化された必要性がない限り、ネイティブコントロールの標準的なブラウザー動作を上書きしないでください。カスタムウィジェットには、最新のWAI-ARIA APGに従ってください（APGはWCAGとは独立してバージョン管理されています。APGのパターンは設計ガイダンスであり、それ自体がWCAGの要件ではありません。必ず最新バージョンを確認してください）。

コントロール	必須キー
ボタン	`Enter`、`Space`
リンク	`Enter`
チェックボックス	切り替えには`Space`
ラジオグループ	オプション間の移動には矢印キー、選択には`Space`
`<select>`	ナビゲーションと選択にはブラウザー／プラットフォームの慣例に従う
メニュー／メニューバー	矢印キー、項目の実行には`Enter`、閉じるには`Escape`
タブウィジェット	タブ間の移動には矢印キー、アクティブなパネルへの移動にはTab
ダイアログ	閉じるには`Escape`、開いている間はフォーカスを内部に閉じ込める
コンボボックス	編集可能か選択専用かによって異なります。一般に`Escape`で閉じます
ツリービュー	表示中のノード間の移動には上／下、展開／進入には右、折りたたみ／親への移動には左
スライダー	値の変更には矢印キー、最小値／最大値には`Home`／`End`、大きな刻みでの変更にはPage Up／Down
グリッド	セル間の移動には矢印キー、複合ウィジェットへの進入／退出には通常Tab
`<details>`の要約	開示内容の切り替えには`Enter`／`Space`

要約表だけを参考にウィジェットを実装しないでください。必ず最新のAPGパターン全体を使用し、差異があれば文書化したうえで、代表的なブラウザーと支援技術でテストしてください。

重大：ダイアログのフォーカス管理

ダイアログのフォーカス管理の誤りは重大です。キーボードやスクリーンリーダーを利用するユーザーは、元の位置を見失ったり、ダイアログ内のコントロールにまったく移動できなくなったりします。

推奨される方法：ネイティブの`<dialog>`と`showModal()`

showModal()で開いたモーダルダイアログは、ドキュメントの残りの部分を自動的に不活性な状態にします。そのため、すべての兄弟要素に手動でinertを適用するよりも、現在はこちらが推奨されるパターンです。

<button type="button" id="delete-trigger">Delete project</button>

<dialog id="delete-dialog" aria-labelledby="delete-title">
  <h2 id="delete-title">Delete project?</h2>
  <p>This action cannot be undone.</p>
  <form method="dialog">
    <button value="cancel" autofocus>Cancel</button>
    <button value="confirm">Delete project</button>
  </form>
</dialog>

const trigger = document.getElementById('delete-trigger');
const dialog = document.getElementById('delete-dialog');

trigger.addEventListener('click', () => dialog.showModal());
dialog.addEventListener('close', () => {
  if (trigger.isConnected) trigger.focus();
});

初期フォーカスの位置は、ダイアログの内容によって異なります。短い確認ダイアログでは「キャンセル」にフォーカスを当てる場合があり、情報量の多いダイアログでは、ユーザーが冒頭から読み進められるよう、tabindex="-1"を設定した見出しにフォーカスを当てる場合があります。内容を考慮せず、常に最初の対話要素にフォーカスを当てないでください。ダイアログが開いている間にトリガーが削除された場合は、ドキュメント本文ではなく、ワークフロー上で最も近い適切な位置にフォーカスを戻してください。

コンテナーにaria-modal="true"を追加しただけでモーダルになると思わないでください。ARIAは、コンテンツを不活性にしたり、フォーカスを閉じ込めたり、キーボード操作を追加したり、フォーカスを復元したりしません。

ネイティブのモーダル動作があっても、テストは必要です。初期フォーカスの位置、Tab／Shift+Tabでの移動範囲、Escapeキーと視認できる閉じるコントロール、フォームの送信／キャンセル、フォーカスの復元、入れ子／重ね合わせのオーバーレイ、スクリーンリーダーでの通知、プロジェクトのサポート対象に含まれるブラウザーでの対応状況を確認してください。

手動で行う方法（ネイティブの`<dialog>`が利用できない場合）

inert属性は、開いているダイアログの外にある要素とのあらゆるインタラクション（フォーカス、クリック、支援技術による操作）を防ぎます。ブラウザーのサポート状況は良好で（ベースラインは2023年）、フォーカス可能な要素を手動で巡回させる方法よりも簡潔で信頼性があります。

function openDialog(dialog, trigger) {
  document.querySelectorAll('body > *:not(#dialog-container)')
    .forEach(el => el.setAttribute('inert', ''));
  dialog.removeAttribute('hidden');
  dialog.querySelector(focusableSelectors)?.focus();
}

function closeDialog(dialog, trigger) {
  document.querySelectorAll('[inert]').forEach(el => el.removeAttribute('inert'));
  dialog.setAttribute('hidden', '');
  trigger.focus();
}

inertを利用できない環境では、フォーカス巡回ロジックを独自に実装するのではなく、実運用でテストされているfocus-trapライブラリを使用するか、wicg-inertポリフィルを使用してください。

重大：非モーダルの開示とポップオーバーでフォーカスをトラップしないでください

通常の開示、ツールチップ、メニュー、非モーダルのポップオーバーでは、インタラクションパターンでフォーカスの制限が明示的に必要とされない限り、フォーカスをトラップしないでください。単純な表示／非表示コンテンツには、aria-expanded を指定したボタンで十分です。

<button type="button" aria-expanded="false" aria-controls="filter-panel">
  Filters
</button>
<div id="filter-panel" hidden></div>

開いたコンテンツがページに重なる場合は、キーボードユーザーがその中に入って出られるようにし、操作が離れたときに永続しないコンテンツを閉じ、ユーザーが当然期待する場面では Escape キーに対応し、閉じるとフォーカスが失われる場合はフォーカスを元に戻し、新たなフォーカス位置がオーバーレイで隠れないようにしてください。トリガーにフォーカスが当たっただけで、複雑なコンテンツを開かないでください。

要件を満たす場合は HTML Popover API を使用できます。ただし、選択したポップオーバーの種類について、フォーカスの動作と閉じ方を必ずテストしてください。

重大：フォーカスの可視性

フォーカス可能なすべての要素に、明確で常に表示されるフォーカスインジケーターを設けてください。 同等に視認性の高い代替手段を用意せずにフォーカスアウトラインを削除することは、重大な問題です。

:focus-visible {
  outline: 3px solid var(--focus-color, #005fcc);
  outline-offset: 3px;
}
@media (forced-colors: active) {
  :focus-visible { outline-color: Highlight; }
}

該当する要件を区別してください。

2.4.7 Focus Visible (AA)： フォーカスが可視である操作モード
1.4.11 Non-text Contrast (AA)： コンポーネントの状態には、隣接する色に対して 3:1 のコントラストが必要となる場合があります
2.4.13 Focus Appearance (AAA)： インジケーターの最小面積の拡大と、フォーカス時と非フォーカス時のピクセル間における 3:1 の変化 — この AAA の計算式を AA の要件として説明しないでください

十分なコントラストを備えた 3px の実線アウトラインは、プロジェクトの既定値として有用ですが、Focus Appearance の計算式を完全に満たすものではありません。ライトモード、ダークモード、コントラスト強化モード、強制配色モードで、またコントロールが表示されるすべての背景上でフォーカスをテストしてください。

重大：フォーカスが隠れないこと（WCAG 2.4.11/2.4.12）

固定ヘッダー、固定フッター、Cookie 通知、チャットパネル、ツールバー、仮想キーボード、永続的に表示される開示は、フォーカスが技術的には可視でも、フォーカスされた要素を隠してしまうことがあります。フォーカスされた要素が固定オーバーレイの背後に完全に隠れることは、重大な問題です。

html {
  scroll-padding-block-start: var(--sticky-header-height, 0);
  scroll-padding-block-end: var(--sticky-footer-height, 0);
}
[id] {
  scroll-margin-block-start: var(--sticky-header-height, 0);
}

CSS のスクロール間隔は役立ちますが、適合性の証明にはなりません。すべてのブレークポイント、ズームレベル、テキスト間隔の設定、永続的なオーバーレイでテストしてください。WCAG 2.4.11 (AA) では、フォーカスされた要素が完全に隠れていないことが求められます。一部が隠れる場合は中程度、完全に隠れる場合は重大な問題です。フォーカスされたコンポーネント全体とそのインジケーターが見える状態を維持するデザインを優先してください。これは AA の最低基準を上回り、2.4.12 Focus Not Obscured Enhanced (AAA) に沿ったものです。

重大：フォーカス順序

Tab の順序は、論理的な読み取り順序と操作順序に従う必要があります。 論理的でないフォーカス順序は重大な問題です。スクリーンリーダーのユーザーは、フォーカス順序からページの空間的なモデルを構築するため、順序が崩れるとそのモデルが損なわれます。

意味のある DOM 順序を主要な仕組みとして使用し、視覚上の順序を DOM 順序に合わせてください。CSS の order、グリッド配置、絶対位置指定を使って、誤解を招く視覚的な順序を作らないでください
正の値を持つ tabindex は使用しないでください。保守が困難な独立したフォーカス順序が作られます
tabindex="0" — 要素が順次フォーカス順序に正当に含まれる必要があり、ネイティブ要素ではその意味を表現できない場合に限ってください
tabindex="-1" — プログラムによるフォーカス先と、ロービングタブインデックスパターンにおける非アクティブ項目に限ってください
特定の操作上の要件がない限り、操作できない見出し、段落、コンテナーを Tab 順序に追加しないでください
初期フォーカスの配置が想定され、テスト済みで、ユーザーを驚かせない場合を除き、autofocus を使用しないでください
コンテンツの挿入、削除、並べ替え、絞り込みの際は、フォーカスを維持するか、論理的な位置に移してください。削除された要素にフォーカスを残さないでください

深刻：複合ウィジェット（ロービング tabindex）

複合ウィジェット（ツールバー、ラジオグループ、ツリービュー、タブリスト、メニューバー）では、通常 Tab の停止位置を 1 つだけ設け、矢印キーなどの仕様で定められたキーで内部の項目間を移動します。認められている方法は 2 つあります。

ロービング tabindex： 1 つの項目に tabindex="0" を設定し、ほかの項目には -1 を設定します。移動時に値と DOM フォーカスを更新します。
aria-activedescendant： DOM フォーカスはコンテナーに置いたまま、この属性でアクティブな子孫を示します。

該当するウィジェットパターンで指定された方法を選択してください。ネイティブのラジオグループに独自のロービング tabindex を追加しないでください。ブラウザーがすでにキーボード操作に対応しています。

<div role="toolbar" aria-label="Text formatting">
  <button type="button" tabindex="0"  aria-pressed="false">Bold</button>
  <button type="button" tabindex="-1" aria-pressed="false">Italic</button>
  <button type="button" tabindex="-1" aria-pressed="false">Underline</button>
</div>

toolbar.addEventListener('keydown', (event) => {
  const items = Array.from(toolbar.querySelectorAll('button:not([disabled])'));
  const current = items.indexOf(document.activeElement);
  let next = current;

  if (event.key === 'ArrowRight' || event.key === 'ArrowDown') next = (current + 1) % items.length;
  else if (event.key === 'ArrowLeft' || event.key === 'ArrowUp') next = (current - 1 + items.length) % items.length;
  else if (event.key === 'Home') next = 0;
  else if (event.key === 'End') next = items.length - 1;
  else return;

  event.preventDefault();
  items.forEach((item, index) => { item.tabIndex = index === next ? 0 : -1; });
  items[next].focus();
});

本番環境で使うツールバーでは、向き、文字の方向、無効な項目、動的な項目追加にも対応する必要があります。ウィジェットの種類ごとの具体的な矢印キーの方向については、APG のロービング tabindex の実践ガイドを参照してください。

中程度：文字キーのショートカット（WCAG 2.1.4）

印字可能な文字、句読点、数字、記号だけを使うショートカットでは、少なくとも次のいずれかを用意してください。ショートカットを無効にする方法、印字されない修飾キーを含むように割り当てを変更する方法、または該当するコンポーネントにフォーカスがあるときだけ有効にする方法です。1 文字のショートカットは、音声入力で誤って実行されることがあります。ブラウザー、OS、支援技術のショートカットを横取りしないでください。また、コンポーネントがアクセス可能な同等の動作に置き換えるのでない限り、既定の動作を妨げないでください。ショートカットの説明は、支援技術が認識できる形式で表示してください。

中程度：スキップリンクとランドマーク

スキップリンクの欠如は中程度の問題です — 視覚を使うキーボードユーザーは、ページを読み込むたびにすべてのナビゲーションを Tab キーで通過しなければなりません。スクリーンリーダーユーザーにはランドマークナビゲーションという代替手段がありますが、スキップリンクが最も手軽な回避手段です。

<a class="skip-link" href="#main-content">Skip to main content</a>
<header>…</header>
<nav aria-label="Primary">…</nav>
<main id="main-content" tabindex="-1">…</main>
<footer>…</footer>

.skip-link {
  position: fixed;
  z-index: 1000;
  inset-block-start: 0.5rem;
  inset-inline-start: 0.5rem;
  padding: 0.75rem 1rem;
  color: #ffffff;
  background: #000000;
  transform: translateY(-200%);
}
.skip-link:focus { transform: translateY(0); }

スキップリンクはフォーカス時に表示される必要があります。常に非表示（display: none）にすると、WCAG 2.4.1 に違反する深刻な問題になります。冗長な role 属性は付けずにネイティブのランドマークを使用してください（<header> を使い、<header role="banner"> は使いません）。ただし、その状況で要素本来のランドマークロールが公開されない場合は例外です。複数のナビゲーションランドマークには、それぞれ異なるアクセシブルネームを付けてください。

中程度：非表示、利用不可、操作不可のコンテンツ

意図する状態に合った仕組みを選択してください。

仕組み	視覚的な表示	Tab によるフォーカス移動	アクセシビリティツリー
`hidden` / `display: none`	非表示	対象外	通常は除外
`visibility: hidden`	非表示	対象外	通常は除外
`inert`	個別にスタイルを指定しない限り、通常は表示	子孫を除外	子孫を除外
`aria-hidden="true"`	変化なし	変化なし	コンテンツを支援技術から隠す

フォーカス可能な要素を aria-hidden="true" のサブツリー内に決して置かないでください — aria-hidden はキーボードフォーカスを防ぎません。そのため、スクリーンリーダーには公開されていないのに、フォーカスを受け取るコントロールが生じることがあります。閉じた開示コンテンツを利用不可にするには hidden を使用してください。表示中のコンテンツを一時的に操作不能にする必要がある場合は inert を使用してください。showModal() を使うネイティブの <dialog> は、すべての兄弟要素に手動で inert を適用することなく、ドキュメント全体でモーダル動作を提供します。hidden / inert を解除するときは、フォーカス順序が論理的であることを確認してください。

中程度：動的コンテンツとクライアントサイドナビゲーション

コンテンツが更新されたというだけでフォーカスを移動しないでください。新しい操作コンテキストが必要な場合や、移動しないとユーザーが現在位置を失う場合に移動してください。適切な例として、モーダルを開閉するとき、送信失敗後にエラーの概要へフォーカスするとき、クライアントサイドのルート変更後にメイン見出しへ移動するとき、フォーカス中の要素が削除された場合にフォーカスを回復するときがあります。ルート変更時は、ドキュメントタイトルを更新し、適切な見出しまたはメインコンテナーへフォーカスを移動し、新しいコンテキストを重複して通知することなく知らせ、期待される戻る／進むの動作を維持してください。アプリケーションのフォーカス管理に、正の値の tabindex や、Tab キーイベントの合成を繰り返し使わないでください。

中程度：タッチおよびポインターの代替手段（WCAG 2.5.x）

要件	説明	深刻度
2.5.1 ポインタージェスチャー	複数点または軌跡に基づくジェスチャーには、シングルポインターまたはキーボードによる代替手段が必要です	深刻
2.5.3 名前に含まれるラベル	表示されているラベルのテキストは、アクセシブルな名前に含まれている必要があります	深刻
2.5.8 ターゲットサイズの最小値	インタラクティブなターゲットは最低24×24 CSSピクセル、推奨サイズは44×44です	中程度
user-scalable=no	ピンチズームを決して無効にしないでください。弱視のユーザーが利用できなくなります	深刻
ドラッグによる並べ替え	キーボードで操作できる代替手段（切り取り／貼り付け、上下ボタン）が必要です	深刻


<meta name="viewport" content="width=device-width, user-scalable=no">

<meta name="viewport" content="width=device-width, initial-scale=1">

テストに関する期待事項

ページレベル： ブラウザーのツールバーからページにTabで移動し、ページ全体をTab／Shift+Tabで両方向に操作します。すべてのインタラクティブな機能に移動して操作できること、非アクティブまたは非表示のコントロールにフォーカスが当たらないこと、フォーカスインジケーターが常に表示されること、固定または重ねて表示されるコンテンツがフォーカスを完全に隠さないことを確認し、スキップリンクを有効にします
コンポーネント： ブラウザーの動作を上書きせずにネイティブコントロールをテストします。各カスタムウィジェットで、文書化されているすべてのキーをテストします。最初／最後／無効な項目や、動的に追加／削除される項目をテストします。Tab／Shift+Tabでの移動と離脱をテストします。該当する場合は書字方向と向きをテストします。キーボードでの有効化がポインターでの有効化と一致することを確認します
ダイアログ／オーバーレイ： 初期フォーカスが適切であることを確認します。モーダルダイアログからフォーカスが外れないこと、表示されているコントロールとEscapeキーで閉じられること、フォーカスが論理的に元の位置に戻ることを確認します。非モーダルコンテンツがフォーカスを閉じ込めないことを確認し、オーバーレイの入れ子や繰り返しの開閉をテストします
支援技術と表示： スクリーンリーダーを起動した状態でキーボード操作をテストします。200%／400%のズーム、320pxのビューポート、ライト／ダーク／高コントラスト／強制カラーの各モードをテストします。表示ラベルをコマンドとして使用するコントロールでは、音声入力もテストします

自動チェックでは、正の値のtabindex、インタラクティブでない要素のクリックハンドラー、aria-hidden／inertなコンテンツ内にあるフォーカス可能な子孫要素、アクセシブルな名前の欠如、フォーカスインジケーターに関する一部の問題を検出できます。しかし、フォーカス順序全体が適切か、カスタム操作が想定されるキーボード操作モデルに従っているかは判断できません。新規または変更されたインタラクションパターンでは、手動でキーボード操作を一通り確認してください。

完了条件チェックリスト

主要な WCAG 達成基準

2.1.1 キーボード操作（A） — 違反した場合は重大
2.1.2 キーボードトラップなし（A） — 違反した場合は重大
2.1.4 文字キーのショートカット（A）
2.4.1 ブロックスキップ（A）
2.4.3 フォーカス順序（A）
2.4.7 フォーカスの可視化（AA）
2.4.11 フォーカスが隠れない（最低限）（AA、WCAG 2.2）
2.4.12 フォーカスが隠れない（強化）（AAA、WCAG 2.2）
2.4.13 フォーカスの外観（AAA）
2.5.1 ポインタージェスチャ（A）
2.5.3 名前のラベル（A）
2.5.8 ターゲットサイズ（最低限）（AA、WCAG 2.2）

参考資料

ベストプラクティスガイド全文
WAI-ARIA オーサリングプラクティスガイド（APG） — WCAG とは独立してバージョン管理されています
APG：キーボードインターフェースの開発
APG：ダイアログモーダルパターン
HTML Living Standard：dialog 要素
HTML Living Standard：inert 属性
focus-trap ライブラリ
wicg-inert ポリフィル

今後の標準動向： これらのルールは WCAG 2.2 AA を対象としています。WCAG 3.0 は開発中です。キーボード操作とフォーカスに関する要件は、2.2 と広く互換性を保つ見込みです。動向の確認先：https://www.w3.org/TR/wcag-3.0/

Markdown 対応

ログインしてコメント

基本情報

作者: mgifford
リポジトリ: mgifford/accessibility-skills
カテゴリ: デザイン・UI
インストール数: 207
GitHub スター: 57

問題を報告