使い方ガイド

SpeakableでHTMLアクセシビリティを分析するために必要なすべて — インストールからCI/CD連携まで。

インストール

プログラムでの利用やCIパイプライン用にプロジェクト依存関係としてインストールするか、どこからでもCLIにアクセスできるようグローバルにインストールします。

Terminal

# Install as a project dependency
npm install @reticular/speakable

# Or install globally for CLI access
npm install -g @reticular/speakable

CLIコマンド

speakableバイナリはHTMLファイルパスを引数として受け取ります。すべてのオプションはフラグです — サブコマンドはありません。

Terminal

# Basic analysis (JSON output, NVDA by default)
speakable page.html

# Choose output format: json, text, audit, or both
speakable page.html -f text
speakable page.html -f json
speakable page.html -f audit
speakable page.html -f both

# Choose screen reader: nvda, jaws, voiceover, or all
speakable page.html -s nvda
speakable page.html -s jaws
speakable page.html -s voiceover
speakable page.html -s all

# Filter to specific elements with a CSS selector
speakable page.html --selector "button"

# Compare two HTML files (semantic diff)
speakable new.html --diff old.html

# Batch process multiple files
speakable --batch file1.html file2.html file3.html

# Write output to a file
speakable page.html -o output.json

# Read from stdin
cat page.html | speakable -

# Validate round-trip serialization
speakable page.html --validate

出力フォーマット

Speakableは4つの出力フォーマットをサポートしており、それぞれ異なるワークフローに適しています。

Format	Flag	Description
JSON	-f json	Canonical accessibility model as deterministic JSON. Best for CI/CD, snapshot testing, and programmatic comparison.
Text	-f text	Screen reader announcement text. Shows what each reader would say, line by line. Human-readable.
Audit	-f audit	Structured report with landmark structure, heading hierarchy, interactive elements, detected issues (error/warning/info), and summary statistics.
Both	-f both	JSON model and screen reader text combined in a single output.

Pro機能

バッチ処理

1回の実行で複数のファイルを分析します。バッチモードは個々のファイルが失敗しても処理を続行し、最後にサマリーを報告します。

speakable --batch file1.html file2.html file3.html

セマンティック差分

変更前後のHTMLを比較してアクセシビリティの回帰を検出します。差分はプロパティレベルの詳細（名前、ロール、状態、フォーカス）で追加、削除、変更されたノードを特定します。

speakable new.html --diff old.html

CI/CD連携

終了コードとJSON出力を使用してパイプラインチェックを自動化します。Exit 0 = 成功、exit 1 = ユーザーエラー、exit 2 = コンテンツの問題または差分の変更、exit 3 = システムエラー。

npx @reticular/speakable page.html -f audit

Webアナライザー

/toolのWebアナライザーでは、HTMLを直接貼り付けて即座に結果を確認できます — インストールは不要です。

テキストエリアにHTMLを貼り付けます
スクリーンリーダーを選択します（NVDA、JAWS、VoiceOver、またはすべて）
必要に応じてCSSセレクターを入力して特定の要素に絞り込みます
「解析」をクリックして予測出力を確認します

差分モードを切り替えて、2つのHTMLスニペットを並べて比較します。Speakableは、2つのバージョン間でアクセシビリティツリーのどのノードが追加、削除、または変更されたかを正確に表示します。

分析後、出力ツールバーの🔊アイコンをクリックして結果を音声で聞くか、1行ずつモードに切り替えてキーボードショートカットを使用して出力を1つずつナビゲートします。

音声アナウンサー

Webアナライザーとブラウザ拡張機能には、ブラウザのネイティブSpeechSynthesis APIを使用して分析出力を音声で読み上げる組み込みの音声アナウンサーが含まれています。

すべて再生

行間にポーズを入れ、スクリーンリーダーセクション間にはより長いポーズを入れて、出力全体を順番に読み上げます。

1行ずつナビゲーション

スクリーンリーダーユーザーが実際にナビゲートする方法を模倣します：一度に1つの要素ずつ。

Key	Action
↓ / j	Move to next line and speak it
↑ / k	Move to previous line and speak it
Enter / Space	Play all from current line
Escape	Stop speech and exit line-by-line mode

音声と速度のコントロール

音声ドロップダウンには音声セレクターと0.5xから2.0xまでの速度スライダーが含まれています。

ベストプラクティス

CIで回帰検出を実行する

ビルドパイプラインにSpeakableを追加して、すべてのPRでアクセシビリティの変更をチェックします。

コンポーネントレベルの分析にセレクターを使用する

ページ全体を分析するのではなく、--selectorで特定のコンポーネントに焦点を当てます。

3つのリーダーすべてを確認する

-s allを使用してクロスプラットフォームの違いを確認します。NVDA、JAWS、VoiceOverにはそれぞれ固有のアナウンスパターンがあります。

スナップショットテスト用にJSONベースラインを保存する

JSON出力をベースラインとして保存し、--diffを使用してバージョン間の変更を検出します。

監査レポートから始める

-f auditを使用して、特定のリーダー出力を詳しく調べる前にアクセシビリティの健全性の概要を確認します。