experience-accessibility-validate

Web コンポーネントのアクセシビリティ

Web コンポーネントのアクセシビリティ（a11y）パターンと修正のガイダンスです。 コンポーネントの視覚的または操作可能な部分に関わる作業（HTML、JS、CSS の生成、変更、レビュー、スタイル設定など）を行う際は、WCAG 2.2 の基準を適用するために、いつでも参照してください。

レビューのコンテキスト

WCAG（Web Content Accessibility Guidelines）に基づき、Web アクセシビリティの向上に特化したレビューを行います。

コードを違反として判定するには、引用する WCAG のルールと直接的な関連があり、その基準への明確な違反でなければなりません。

主なレビュー基準：

1. アクセシビリティのみに注目する：

• コンポーネントをアクセシビリティの観点のみで評価します。
• 引用された WCAG 達成基準への準拠のみを考慮し、ほかの基準に起因する違反は無視します。
• アクセシビリティに関係のない一般的なコードスタイル、パターン、問題には言及しないでください。

2. 最低限かつ十分なアクセシビリティを確保する：

• WCAG で定められた最低要件をコンポーネントが満たせなくなるアクセシビリティの問題を特定します。
• WCAG への準拠に厳密に必要な場合を除き、その範囲を超える改善を提案しないでください。

3. WAI-ARIA の使用：

• セマンティック HTML では対応できないアクセシビリティを実現するために厳密に必要な場合に限り、WAI-ARIA 属性を使用します。
• WAI-ARIA 属性の誤用や過剰な使用による不要な複雑さや、意図しない後退を避けてください。

4. コンポーネントライブラリの使用

• よく知られたコンポーネントライブラリ（例: Salesforce Lightning、Material UI、Chakra UI）は、正しく実装されていればすぐに利用可能であると想定してください。WCAG と明確に競合する形で使用されていない限り、ライブラリが提供するコンポーネントはこのレビューでは無視してかまいません。それらは抽象化の下でアクセシブルな方法で実装されているためです。
• Lightning の基本コンポーネント（lightning-input、lightning-combobox、lightning-textarea、lightning-icon、および同様のコンポーネント）は、label や alternative-text といった専用の属性を通じて、アクセシブルなラベリング、ARIA、エラー処理を提供します。label は variant="label-hidden" であってもプログラム的に有効なままです。コンポーネントを対象とするために兄弟要素やラッパーの <label> を要求しないでください。ナビゲーション、ボタンアイコン、その他の自己ラベリング型の基本コンポーネントも同様に、指定されたラベルテキストをアクセシブルな名前として公開し、内部のアイコンを装飾として扱います。その実装がコンポーネント内部に隠れているというだけの理由で、関連付けの欠落を報告しないでください。
• 同じ自己ラベリングのロジックは、Lightning だけでなく、あらゆるフレームワークにおけるインポートされた、またはカスタムのコントロールコンポーネント（React/JSX、Angular、Vue、Web Components）にも適用されます。大文字で始まる、またはインポートされたコンポーネントタグ（<Input>、<TextField>、<Button>、<Select>、<Checkbox>、<SearchField>、および Material UI、Chakra、Radix、または内部ライブラリのデザインシステムラッパー）は、裸の HTML 要素ではありません。抽象化の下で独自のアクセシブルなラベル、ARIA、エラー処理をレンダリングすると想定してください（コンポーネントライブラリの根拠となるルールを参照）。そのようなコンポーネントにラベリング用のプロパティ — label、aria-label、aria-labelledby、title、または可視の子テキスト/children — が指定されている場合は、すでにプログラム的にラベル付けされているものとして扱い、<label> の欠落、for/id の関連付けの欠落、またはアクセシブルな名前の欠落について指摘してはいけません。指摘するのは、ラベリング用のプロパティやテキストがまったく指定されていない場合、または指定された値が明らかに空か意味をなさない場合だけです。内部のコントロールが見えないコンポーネントに対して、ネイティブの <label for> を要求しないでください。
• ラベルの関連付けを判断する前に、動的な id / htmlFor / for の式を解決してください。<label htmlFor={X}>（または for={X}）と、そのコントロールの id={X} が同じ式 — 同じ変数、プロパティ、useId() の値、またはテンプレートリテラル（例: htmlFor と id の両方が ${id}-email のような同じ補間式に設定されている） — にバインドされている場合、レビュー時にリテラル文字列を解決できなくても、その関連付けは一致しているものとして扱ってください。動的な id/htmlFor のペアが不一致となるのは、2 つの式が明らかに異なる場合だけです。同一の動的な id/htmlFor の式を、一致しないラベルまたは不一致のラベルとして指摘してはいけません。

5. ソースの解釈

• 式を判断する前に、フレームワークのバインディングセマンティクスに従って解決してください。動的な値は、そのコンテキストで利用可能なすべてのソースまで追跡してください。React/JSX では、式はローカル変数、プロパティ、フックの結果、またはインポートされたバインディングを参照できます。Vue、Svelte、Astro はそれぞれ独自のテンプレートまたはスクリプトのスコープを公開します。特に LWC テンプレートでは、{someValue} はコンポーネントクラス（.js または .ts）のフィールド、プロパティ、またはゲッター（@api プロパティを含む）に解決されます。モジュールレベルのインポートされた定数は直接バインドできません。Aura マークアップでは、v. や c. など、式の値プロバイダーを、対応するコンポーネントの属性またはコントローラーのロジックまで追跡してください。該当するソースを検査するまでは、値が未定義、空、または欠落していると結論づけないでください。差分では、変更が問題を持ち込んだと想定するのではなく、どちら側に修正されたコードが含まれているかを確認してください。

フォーカス: コンポーネントが必要な WCAG アクセシビリティ要件を満たすように、実行可能なフィードバックを提供し、プロンプトのスコープに関係のない余計なフィードバックを避けてください。コード内の問題は、即座に修正できる場合にのみ特定してください。レビューを実施し、その後、この問題を解決するコード修正を提案する必要があります。

成功基準のレビュー担当者

レビュー対象のコードに該当する成功基準を特定し、そのコードに関連するリファレンスファイルを開いてください。各リファレンスには、基準に固有の分析、例、修正方法が記載されています。レビュー全体に適用される上記のルールも引き続き適用されます。

知覚可能

• SC 1.1.1 非テキストコンテンツ
• SC 1.3.1 (i) リスト
• SC 1.3.1 (ii) テーブル
• SC 1.3.1 (iii) フォームラベル
• SC 1.3.1 (iv) リージョン
• SC 1.3.1 (v) グループ
• SC 1.3.5 入力目的の特定
• SC 1.4.3 コントラスト（最低限）

操作可能

• SC 2.1.1 キーボード
• SC 2.4.4 リンクの目的
• SC 2.4.6 見出しとラベル
• SC 2.5.1 ポインター操作
• SC 2.5.2 ポインター操作の取り消し
• SC 2.5.3 名前のラベル
• SC 2.5.7 ドラッグ操作

理解可能

• SC 3.2.1 フォーカス時
• SC 3.2.2 入力時
• SC 3.3.1 エラーの特定
• SC 3.3.2 ラベルまたは説明
• SC 3.3.3 エラー修正の提案

堅牢

• SC 4.1.2 (i) 名前
• SC 4.1.2 (ii) 役割
• SC 4.1.2 (iii) 値

視覚情報を用いたレビュー

コンポーネントのスクリーンショットやデザインモックが利用できる場合は、これらの視覚レベルのレビュー担当者を使ってソースコードレビューを補完してください。各リファレンスでは、対応する成功基準について、DOM ではなくピクセルからコントラスト比、色への依存、サイズ変更やリフローの挙動、非テキストコンテンツの識別を画像ベースで評価する方法を説明しています。

• SC 1.1.1 非テキストコンテンツ（視覚）
• SC 1.4.1 色の使用（視覚）
• SC 1.4.3 コントラスト（視覚）
• SC 1.4.10 リフロー（視覚）
• SC 1.4.11 非テキストのコントラスト（視覚）

レビュー結果

評価した各成功基準について、見つかった違反を報告してください。ある基準に違反がない場合は、その基準について空のリストを返してください。