capacitor-accessibility

Capacitor アプリのアクセシビリティ

UI は WKWebView / Android WebView 内のウェブコンテンツであるため、標準的なセマンティック HTML と ARIA で大部分に対応できます。このスキルでは、WebView とネイティブレイヤーの動作がブラウザーと異なる点を扱います。

使用するタイミング

次の場合に使用します：

• ユーザーが VoiceOver / TalkBack のサポート、アクセシビリティ監査、WCAG 2.2 / EAA / ADA への準拠を求めている。
• iOS の「さらに大きな文字」でテキストが大きくならない、または Android の大きなフォントサイズでレイアウトが崩れる。
• スクリーンリーダーがページの変更、トースト、読み込み状態を読み上げない。
• ネイティブビュー（地図、カメラプレビュー、動画プレーヤー）にスクリーンリーダーで移動できない。
• ユーザーが @capacitor/screen-reader または @capacitor/text-zoom を使いたい。

使用しない場合：

• Ionic コンポーネント API / テーマ設定 -> ionic-design；Konsta / Tailwind -> konsta-ui、tailwind-capacitor。
• ノッチ / ホームインジケーターの下にあるコンテンツ -> safe-area-handling。
• キーボードが入力欄を覆う場合 -> capacitor-keyboard。
• E2E テストのインフラストラクチャ -> capacitor-testing。

手順

1. 画面を一覧化して TODO リストを作成します（認証、メインタブ、フォーム、モーダル、メディア、設定）。一度に 1 画面ずつ監査します。
2. 自動チェックをウェブビルドで実施します。axe（テストでは @axe-core/playwright、または npx @axe-core/cli@latest http://localhost:5173）を実行し、まず違反（名前、ロール、コントラスト、ラベル）を修正します。
3. デバイスでのチェックを画面ごとに実施します。VoiceOver と TalkBack、最大の文字サイズ、「視差効果を減らす」、Bluetooth キーボード（iPad）を使用します。references/testing.md のチェック項目を使います。
4. 以下の Capacitor 固有の注意点を修正します。
5. 画面ごとに、WCAG の達成基準、重大度、修正内容を含めて調査結果を報告します。大規模なリファクタリングの前に報告し、デザイントークン（色、フォントサイズ）を変更する前に確認を求めます。

Capacitor 固有の落とし穴

1. iOS のダイナミックタイプはデフォルトでは無視されます。 WKWebView は、「設定」＞「アクセシビリティ」＞「さらに大きな文字」の設定に関係なく、px／rem の文字を固定サイズで表示します。選択肢：
   • CSS：html { font: -apple-system-body; } を指定し、それ以外はすべて rem／em でサイズを指定します（WebKit がユーザーの文字サイズカテゴリに合わせて変換し、変更はその場で反映されます）。
   • または、起動時および resume 時に @capacitor/text-zoom の TextZoom.getPreferred()、続けて TextZoom.set({ value }) を呼び出します。iPad では、capacitor.config.* に ios.preferredContentMode: 'mobile' を設定する必要があります。 どちらか一方を選んでください。両方を使うと、文字が二重に拡大されます。
2. Android ではフォントスケールが自動的に適用されます。 Android WebView はシステムのフォントサイズに合わせて文字を拡大するため、高さ固定のコンテナー、line-clamp、絶対配置のレイアウトは 200% であふれます。adb shell settings put system font_scale 2.0 でテストし、リフローに対応できるよう設計してください（WCAG 1.4.4、1.4.10）。
3. ピンチズーム。 zoomEnabled のデフォルト値は false で、多くのテンプレートでは user-scalable=no が設定されています。ユーザーは落とし穴 1／2 の方法で文字を拡大できます。ズームに頼る場合は、zoomEnabled: true を設定し、user-scalable=no を削除してください。
4. SPA の画面遷移は通知されません。 ルートの変更ではページ読み込みがアナウンスされません。画面遷移後に document.title を設定するか、フォーカスをメイン見出し（<h1 tabindex="-1">）に移すか、ポライトなライブリージョンを更新してください。主な方法として ScreenReader.speak を使わないでください。これはスクリーンリーダーが有効な場合にしか読み上げず、ユーザーの読み上げ設定も適用されません。
5. WebView の下または上にあるネイティブビュー。 @capacitor/google-maps は透明な WebView 領域の背後にネイティブマップを表示します。カメラプレビュープラグインも同様です。スクリーンリーダーが認識するのは WebView であり、ネイティブビューではありません。HTML にアクセシブルな代替手段（マーカーの一覧、テキストによる要約、ラベル付きの撮影ボタン）を用意してください。
6. ネイティブプラグインの UI。 公式プラグインのダイアログ、アクションシート、共有シート、ピッカーはネイティブであり、デフォルトでアクセシブルです。独自プラグインのカスタムネイティブ画面には accessibilityLabel／contentDescription が必要です（references/native.md を参照）。
7. タッチターゲット。 Apple HIG の最小サイズは 44x44 pt、Material は 48x48 dp、WCAG 2.2 2.5.8 の最小サイズは 24x24 CSS px です。アイコンボタンには、小さな SVG だけでなくパディングも必要です。
8. モーションとコントラスト。 prefers-reduced-motion と prefers-contrast のメディアクエリーは、どちらの WebView でも動作します。動きを減らす設定では視差効果や自動再生するトランジションを無効にしてください。「コントラストを上げる」設定もテストしてください。
9. 状態の変更。 トースト（@capacitor/toast はネイティブで、読み上げられます）、インラインエラー、スピナーには、Web のトーストで role="status"／aria-live="polite" を使い、読み込み中の領域に aria-busy を設定してください。role="alert" はエラーにのみ使ってください。
10. ネイティブ画面から戻った後のフォーカス。 ネイティブモーダル（カメラ、共有、認証ブラウザー）を閉じた後、フォーカスが <body> に移ることがあります。appStateChange／Promise の解決後に、起動元のコントロールへフォーカスを戻してください。

検証

• axe：監査対象の各ルートで重大または深刻な違反がゼロであること。
• VoiceOver（iOS）および TalkBack（Android）：すべてのコントロールに読み上げられる名前、ロール、状態があること。スワイプ順が視覚上の順序と一致していること。ルートの変更がアナウンスされるか、フォーカスが見出しに移ること。
• 最大サイズの文字：xcrun simctl ui booted content_size accessibility-extra-extra-extra-large と adb shell settings put system font_scale 2.0 を実行し、文字の切り詰めや重なりがなく、body に横スクロールが発生しないこと。
• grep：grep -rnE "user-scalable=no|maximum-scale=1" index.html src/ と grep -rn "outline: *none\|outline: *0" src/ を実行します（それぞれに :focus-visible による置き換えが必要です）。
• テスト後にリセット：adb shell settings put system font_scale 1.0、xcrun simctl ui booted content_size large。

エラー処理

症状／メッセージ	対処方法
Web で ScreenReader.isEnabled が拒否される／利用できない	Web ではサポートされていません（スクリーンリーダーを検出できないため）。Capacitor.isNativePlatform() でガードしてください。
Web で speak がエラーをスローする	ブラウザーに SpeechSynthesis がありません。ネイティブでのみ呼び出すか、'speechSynthesis' in window で機能を検出してください。
"TextZoom" plugin is not implemented on web	text-zoom はネイティブ専用です。Web ではスキップしてください。
iPad でテキストズームが効かない	ios.preferredContentMode: 'mobile' を設定してください。
iOS でテキストが二重に拡大される	-apple-system-body と TextZoom の両方が使われています。どちらか一方だけを使用してください。
VoiceOver が名前なしで「ボタン」と読み上げる	アイコンのみのコントロールに aria-label または表示テキストがありません。

参考資料

トピックに関係する場合のみ読み込んでください。

• references/testing.md：VoiceOver／TalkBack のジェスチャー、Accessibility Inspector、Android Accessibility Scanner、adb／simctl の設定コマンド、Playwright での axe、画面ごとのチェックリスト。
• references/native.md：カスタムネイティブプラグインビュー向けの Swift／Kotlin アクセシビリティ API、ネイティブコードからのアナウンスの送信。