speech-recognition

Name: speech-recognition
Author: mgifford

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

リポジトリ

speech-recognition について

音声入力や音声操作に対応するインターフェースの実装・レビューを支援するアクセシビリティスキルです。ラベル、ネイティブなセマンティクス、テキスト入力、代替操作、フィードバック、テストを扱います。

主な機能

01可視ラベルとアクセシブルネームの一致
02ネイティブなセマンティクスとキーボード操作
03ディクテーション、貼り付け、自動補完への対応
04ドラッグやジェスチャーの代替手段
05視覚とプログラムによるフィードバック
06対応環境の記録とテスト

活用シーン

01音声操作向けのコントロール名のレビュー
02ディクテーション後のフォーム検証
03ドラッグ操作やスライダーの代替設計
04音声ツールとの互換性テスト

インストール

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

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

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

同梱ファイルSYNC.md

詳細

音声認識アクセシビリティスキル

正式な参照元：mgifford/ACCESSIBILITY.md の examples/SPEECH_RECOGNITION_ACCESSIBILITY_BEST_PRACTICES.md このスキルは、そのファイルをもとにしています。判断に迷った場合は、例を正式な基準としてください。

音声入力または音声操作に対応する必要があるインターフェースを実装またはレビューする際は、以下のルールを適用してください。 keyboard/SKILL.md と併せて読み込んでください。音声ツールはキーボードやポインターのエミュレーションに依存することが多いため、キーボード要件は基礎となるものであり、代替にはなりません。

基本方針

音声認識では、テキストの入力、インターフェースの移動、コントロールの有効化、キーボード入力のエミュレーション、ポインターの操作ができます。音声認識は話者認識とは異なります。音声認識は単語やコマンドを解釈し、話者認識は誰が話しているかを特定しようとします。

基本原則：

表示されたラベルを常に示す — 隠れた名前を推測しなくても、何と言えばよいか判断できるようにします
表示ラベルとアクセシブルネームを一致させる — コントロールに表示テキストがある場合、そのテキストをアクセシブルネームに含めます
ネイティブのセマンティクスを使用する — HTML の正しい名前、ロール、状態、値、キーボード動作により、音声ツールに信頼できる情報を提供します
直接ラベルを有効化する方法以外もサポートする — キーボードのエミュレーション、名前や番号のオーバーレイ、ポインターのエミュレーションは製品によって異なります
細かなポインター操作を必須にしない — ドラッグ、軌跡を描くジェスチャー、正確な位置操作の代替手段を用意します
キーイベント以外からの入力も受け付ける — 音声入力、貼り付け、自動補完によって、想定されるキー入力イベントが発生せずにフィールドの値が変わることがあります
明確なフィードバックを提供する — 状態の変化、エラー、確認、結果を視覚的にもプログラム上も伝えます
対応環境でテストする — コマンド、オーバーレイ、動作は製品、プラットフォーム、バージョンによって異なります

音声入力を使用する人： 動き、力、器用さ、手の届く範囲、持久力に制限がある人、反復運動による負傷、痛み、震え、疲労がある人、キーボードやポインターの代わりに、または併用して音声を使う人、タイピングより音声入力が簡単な認知障害や学習障害のある人、一時的または状況に応じた制限がある人、音声とスクリーンリーダー、拡大鏡、スイッチを併用する人。音声を使う人が必ず目が見えるとは限りません。音声を使う人全員がラベル、オーバーレイ、ポインター、フォーカスインジケーター、視覚的な結果を見られることを前提に設計またはテストしないでください。

重大度レベル（このスキル）

レベル	意味
Critical	名前、オーバーレイ、キーボードやポインターのエミュレーションなど、どの音声ツールの方法を使ってもコントロールを有効化できません
Serious	アクセシブルネームに表示ラベルが含まれていません。または、検証が `keydown` のみに依存し、音声入力や貼り付けによる入力を通知なく拒否します
Moderate	同じコントロールが複数ある場合に区別しにくくなっています。または、アイコンのみのコントロールにアクセシブルネームがありません
Minor	非表示のコンテキストが表示ラベルの後ではなく前に挿入されています。または、名前のローカライズが一貫していません

重大：表示ラベルをアクセシブルネームに含める必要があります（WCAG 2.5.3）

表示テキストまたはテキストの画像があるコンポーネントでは、アクセシブルネームにその表示テキストを含める必要があります。表示テキストを名前の先頭に置くことは、文書化されたベストプラクティスですが、追加の規範要件ではありません。


<button type="submit">Save</button>


<button type="submit" aria-label="Confirm changes">Save</button>


<button type="submit" aria-label="Save document">Save</button>

aria-label／aria-labelledby は、子コンテンツから導出される名前を上書きすることがあります。ラベル付けの各ソースがすべて結合されると決めつけず、計算後のアクセシブルネームを確認してください。プレースホルダーテキストだけをラベルとして使用しないでください。音声入力中に消える可能性があり、プログラムで関連付けられた <label> の代わりにはなりません。

表示される語句は、連続した順序で保ってください：


<button>Delete <span class="visually-hidden">quarterly report</span></button>


<button aria-label="Delete the quarterly report permanently">Delete report</button>

2つ目の例には「Delete」と「report」が含まれていますが、その間に別の語句が挿入されています。音声ツールによっては、ユーザーに見えるフレーズと一致しない場合があります。非表示の接頭辞（表示語句の前に置かれるコンテキスト）は、表示テキストがそのまま含まれていれば、自動的に 2.5.3 違反になるわけではありません。ただし、ラベルの直接的な起動を難しくすることもあるため、ユーザーに見えるテキストより前に非表示の語句を置かないようにしてください。形式のヒントや制約は、名前ではなく aria-describedby の説明に含めてください。

重大：名前を変更せず、繰り返し表示されるコントロールを区別する

同じラベル（「編集」「削除」「続きを読む」など）が繰り返されると、音声ツールに複数の候補が表示されることがあります。これは自動的に適合違反になるわけではありませんが、操作の手間が増えます。簡潔にできる場合は、より具体的な表示ラベルを優先してください：

<a href="/services">Read about services</a>
<a href="/products">Read about products</a>

コンパクトな繰り返しアクションでは、表示されるアクションの後ろにコンテキストテキストを追加してください：

<li>
  Billing address
  <a href="/account/billing/edit">Edit <span class="visually-hidden">billing address</span></a>
</li>

表示ラベルを置き換えたり、順序を入れ替えたりしてアクセシブルネームを一意にしないでください。「編集」と表示されるリンクに対して、非表示の名前を「請求先住所を変更」にするのは適切ではありません。

中程度：アイコンのみのコントロール

WCAG 4.1.2 に基づき、アクセシブルネームは引き続き必要です（表示テキストラベルがない場合、2.5.3 は適用されません）：

<button type="button" aria-label="Close dialog">
  <svg aria-hidden="true" focusable="false" viewBox="0 0 24 24">
    <path d="M6 6 18 18M18 6 6 18"></path>
  </svg>
</button>

常に表示されるテキストのほうが、通常はアイコン単独より見つけやすくなります。ホバー時またはフォーカス時にのみ表示されるツールチップは、常に表示されるラベルではありません。役立つ前に、ユーザーがまずコントロールを見つけるか、対象にする必要があります。アイコンのみのデザインを維持する場合は、簡潔でローカライズされた名前を使用し、馴染みのあるアイコンを一貫して使用し、十分なターゲットサイズと間隔を確保してください。名前や番号のオーバーレイで対象を識別できるようにし、説明を色や位置だけに頼らず、サポート対象の音声ツールでテストしてください。

重大：ネイティブのセマンティクスとキーボード操作

音声ツールは、アクセシビリティ API、キーボードエミュレーション、またはポインターエミュレーションを使用することがよくあります。ネイティブ HTML なら、ロール／名前／状態／値／フォーカス／起動の動作を確実に利用できます。


<div class="button" onclick="saveDocument()">Save</div>


<button type="button" onclick="saveDocument()">Save</button>

特定の発話フレーズがすべてのロールで必ず機能すると主張する表は公開しないでください。コマンドの文法は、音声製品、プラットフォーム、ロケール、バージョンによって異なります。正しいセマンティクスは互換性を高め、他の支援技術でも引き続き必要です。機能には、キーボードインターフェースを通じて利用できるものがすべて含まれていなければなりません（機能に経路依存の入力が必要な場合を除く）。音声ソフトウェアは、そのキーボードインターフェースを操作方法の1つとして使用できます。カスタムウィジェットでは、適切なネイティブ要素で代用できない場合に限り、正しいロールを使用してください。想定されるキーボード操作を実装し、名前／状態／プロパティ／値を公開し、視覚的な状態の変更に合わせてプログラム上の状態を更新し、確立された APG パターンに従ってください。skills/keyboard/SKILL.md を参照してください。

重大：ディクテーションとテキスト入力を `keydown` のみに依存させないでください

音声ディクテーションでは、物理キーボードと同じ keydown シーケンスを発生させずに、テキストが挿入、置換、削除されることがあります。

// Correct: responds to value changes regardless of input method
search.addEventListener('input', () => updateSuggestions(search.value));

// Wrong: dictation, paste, and autocomplete may bypass this logic
search.addEventListener('keydown', event => updateSuggestions(event.key));

テキスト入力コントロールでは、ネイティブの入力フィールドやテキストエリアを使用し、常に表示されるラベルを付け、書式の説明とエラーをプログラムから認識できるようにしてください。また、貼り付け、ディクテーション、自動補完、プログラムによる値の変更を受け入れ、送信前に編集や修正ができるようにしてください。短い制限時間や発話速度に関する想定を避け、別の有効な値が許容される場合に特定の句読点の発話を要求しないでください。検証エラーが発生しても入力内容を保持してください。keydown がないからといって入力がなかったと推測しないでください — 適切なイベント時、および送信時に現在の値を検証してください。

重大：ドラッグ、ジェスチャー、空間的な操作には直接操作できる代替手段を用意してください

音声でポインターを操作してドラッグするには、複数のコマンドと正確なタイミングが必要になる場合があります。


<li>
  Budget report
  <button type="button">Move up <span class="visually-hidden">Budget report</span></button>
  <button type="button">Move down <span class="visually-hidden">Budget report</span></button>
</li>

ドラッグ＆ドロップも利用できる場合は、どちらの方法でも同じモデルを更新し、確認を提示してください。スライダーでは、ドラッグ可能なコントロールに直接入力またはステップ操作のコントロールを組み合わせてください。

<label for="volume">Volume</label>
<input id="volume" type="range" min="0" max="100" value="50">
<label for="volume-value">Volume percentage</label>
<input id="volume-value" type="number" min="0" max="100" value="50">

WCAG 2.5.7 では、制作者が作成したドラッグ操作について、不可欠な操作を除き、シングルポインターで操作できる代替手段を用意することが求められます — キーボードのみの代替手段では、このシングルポインター要件を満たさない場合があります。 パスベースまたはマルチポイントのジェスチャーにも、不可欠な操作を除き、2.5.1 に基づくシングルポインターでの代替手段が必要です。skills/touch-pointer/SKILL.md を参照してください。

中程度：フォーカス、スクロール、オーバーレイ

音声を使う人の中には、キーボードコマンドをエミュレートしたり、音声と別の入力方式を組み合わせたりする人もいます — フォーカス順序、視認性、コントロールが遮られていないことは引き続き重要です。固定ヘッダー、Cookie 通知、チャット起動ボタンでフォーカス中のコンポーネントを隠さないでください（WCAG 2.4.11）。

html { scroll-padding-block-start: var(--sticky-header-height, 4rem); }
:focus-visible { scroll-margin-block: 0.5rem; }

次の点を確認してください。開いているモーダルの背後にフォーカスが移動しないこと、ダイアログを閉じたときにフォーカスが論理的なコントロールに戻ること、直接操作した際に必要に応じて対象が画面内にスクロールされること、ドラッグやポインターの正確な移動なしでオーバーレイを閉じられること、サポート対象のビューポートサイズで不可欠なコントロールが恒久的に隠れないこと。音声入力はスクリーンリーダーと組み合わせて使われることがあるため、操作はフォーカスやオーバーレイが見えることに依存してはなりません。

重大：状態、結果、エラーのフィードバックをプログラムから認識できるようにしてください

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

aria-expanded と hidden は必ず同時に更新してください — aria-pressed、aria-checked、選択中のタブ、スライダーの値についても同様です。

<p id="cart-status" role="status" aria-atomic="true"></p>

表示テキストと適切なステータスメッセージのパターンを使用してください（skills/aria-live-regions/SKILL.md を参照） — 確認のたびにフォーカスを移動させないでください。すぐに修正が必要なエラーは、エラーをフィールドに関連付け、フォームで定められたエラー概要の方法を使用してください。次のようなフィードバックは避けてください。色、アニメーション、アイコンの変化だけで示されるもの、ホバー時にしか利用できないもの、認識される前に消えるもの、ディクテーションされた文字ごとに繰り返し読み上げられるもの、アクセシビリティ API から隠されているもの、原因となったコントロールと関連付けられていないもの。

中程度：ラベル、記号、ローカライズ

表示ラベルとアクセシブルネームには同じ言語を使用してください — aria-label、非表示のコンテキスト、説明、エラーメッセージもインターフェースのほかの部分とあわせて翻訳してください。すべての記号を無関係な単語に置き換えないでください — 適切な名前は用途によって異なります。コントロールとして使われる虫眼鏡アイコンの名前は「虫眼鏡」ではなく「検索」です。閉じるアイコンとしてのみ使われる表示上の X の機能は「閉じる」とします。サポート対象のインターフェース言語とディクテーション言語ごとに、音声との照合をテストしてください — 英語で機能するコマンドが、翻訳後も機能するとは限りません。

製品とプラットフォームによる違い

音声ツールによって、名前でコントロールを起動する方法、名前／番号／グリッドのオーバーレイの表示方法、同じ名前が繰り返される場合の区別方法、キーボード／ポインター入力のエミュレート方法、埋め込みフレームやシャドウ DOM の処理方法、コマンドモードとディクテーションモードの切り替え方法は異なります。プロジェクトが積極的に管理し、再テストしていない限り、固定のコマンドフレーズ、製品バージョン、互換性に関する主張をプロジェクト標準に含めないでください。

実際のテスト環境を記録してください。

Speech input product and version:
Operating system and version:
Browser and version:
Input and interface language:
Command, dictation, or mixed mode:
Viewport, zoom, and text size:

テスト

静的検査： 表示ラベルを特定し、計算後のアクセシブルな名前／ロールを確認します。表示されている語句が名前の中にそのまま順番どおり含まれていることを確認します。表示語句の前または内部に隠しテキストがないか確認します。状態／値／説明の関連性を検証します。同じコントロールを区別できることを確認します。アイコンのみのコントロールに簡潔な名前があることを確認します。名前と隠しテキストが翻訳されていることを確認します。計算後のアクセシビリティツリーを検査してください。属性を個別に読んで最終的な名前を推測しないでください。
キーボードの基本操作（ポインターなし）：すべての機能に到達して操作できることを確認します。論理的なフォーカス順序に従うことを確認します。カスタムウィジェットを開いて操作し、閉じられることを確認します。ダイアログ／メニュー／ポップオーバーをエスケープできることを確認します。フォーカスが表示され、遮られていないことを確認します。ドラッグ操作の代替手段を完了できることを確認します。
音声入力テスト（サポート対象の環境ごと）：ツールのドキュメントに記載された文法を使い、表示ラベルを発話して、ラベルのあるコントロールを起動します。ツールの名前／番号のオーバーレイを調べ、見つけやすさを確認します。同じコントロールを区別します。アイコンのみのコントロールやカスタムウィジェットを操作します。テキストのディクテーション、編集、置換、送信を行います。検証エラーを発生させ、修正します。モーダル／メニュー／タブ／開閉可能な項目／オートコンプリートを操作します。代替手段を使って、並べ替え／順序変更／スライダー／マップ／キャンバスのタスクを完了します。状態の変化とステータスのフィードバックを確認します。ズーム／リフロー／ローカライズの変更後に、重要なタスクを再度実行します。「Click [label]」のような一つの文字どおりのフレーズに、すべてのコントロールが応答することを求めないでください。テスト対象ツールのドキュメントに記載された文法を使用してください。
音声入力を日常的に使用するユーザーにテストしてもらってください。技術的な検査だけでは、認識エラーの修正、コントロールの区別、情報量の多いオーバーレイ内の移動に伴う負担の全容は把握できません。

自動チェックでは、アクセシブルな名前のないコントロール、一部の表示ラベルと名前の不一致、無効または欠落したロール／状態、非インタラクティブ要素に設定されたクリックハンドラー、重複するアクセシブルな名前を検出できます。一方、音声製品が実際にラベルを認識するか、同じコントロールを実用上区別できるか、コマンドの総数によってタスクが不当に難しくならないかは判断できません。不確かな自動チェック結果は、確定した不具合ではなく、レビュー項目として扱ってください。

よくある失敗

失敗	修正方法
表示されている「Save」ボタンの名前が「Confirm changes」になっている	「Save」を使うか、「Save」で始まる名前にします
表示されるフレーズの途中に、非表示の単語が挿入されている	表示される単語を連続した順序で配置します
繰り返し表示されるリンクがすべて「Read more」になっている	具体的な表示テキストを使うか、後ろに文脈を示す非表示のテキストを追加します
プレースホルダーだけがフィールドのラベルになっている	常に表示され、関連付けられた`<label>`を追加します
アイコンのみのボタンにアクセシブルな名前がない	簡潔な名前を追加します。常に表示されるテキストを優先します
ツールチップを表示ラベルとして扱っている	見つけやすさが重要な場合は、ラベルを常に表示します
スタイルを適用した`<div>`がボタンとして機能している	`<button>`を使うか、カスタムウィジェットの要件をすべて実装します
検証が`keydown`でのみ実行される	`input`、現在の値、送信に応じて処理します
並べ替えにドラッグ＆ドロップしか使えない	「上へ移動」「下へ移動」または位置を指定するコントロールを追加します
ジェスチャーだけで機能を操作する	同じ結果を得られる簡単なコントロールを追加します
固定されたコンテンツがフォーカス中のコントロールを隠す	レイアウトやスクロールを調整し、対応サイズでテストします
状態が視覚的にしか変化しない	プログラム上の状態も更新し、視認できるフィードバックを提供します
プロジェクトのドキュメントで、あらゆる音声コマンドが使えると謳っている	実際に対応している製品と言語をテストし、記載します
テストで、音声を使うすべてのユーザーが画面を見られることを前提としている	非視覚的な利用と支援技術（AT）を組み合わせた利用も含めます

完了条件チェックリスト

主要なWCAG基準

1.3.1 情報及び関係性（A）
2.1.1 キーボード（A）
2.4.3 フォーカス順序（A）
2.4.7 フォーカスの可視化（AA）
2.4.11 フォーカスが隠されない（最低限）（AA）
2.5.1 ポインターのジェスチャー（A）
2.5.3 ラベルを名前に含める（A） — 表示ラベルがアクセシブルな名前に含まれていない場合は重大
2.5.7 ドラッグ操作（AA）
3.3.2 ラベルまたは説明（A）
4.1.2 名前、ロール、値（A）
4.1.3 ステータスメッセージ（AA）

WCAG基準が示すのは達成すべき結果であり、製品固有の音声コマンドではありません。ある環境でコマンドが機能しない場合、コンテンツの不備、製品の制約、ローカライズの問題、または非対応の組み合わせが原因である可能性があります。基準への不適合と判断する前に、環境を記録して調査してください。

参考資料

標準の動向： これらのルールは WCAG 2.2 AA を対象としています。動向を確認してください：https://www.w3.org/TR/wcag-3.0/

Markdown 対応

ログインしてコメント

基本情報

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

問題を報告