アコーディオン：プログレッシブディスクロージャーのルールと例

アコーディオン は、ラベル付きの開閉コントロールをグループ化したもので、読者がその場で補足コンテンツを表示または折りたたむことができるようにします。ページの主要な回答ではなく、オプションの参照詳細に使用します。

この表示例はプログレッシブディスクロージャーを示しています。ラベルはスキャン可能なまま、1つのパネルが開いており、両方の回答が訪問者の操作の有無にかかわらずページのHTMLに存在しています。

この要素が重要な理由

プログレッシブディスクロージャーとは、現在の判断に必要な情報を表示しつつ、より深いまたはあまり一般的でない詳細をオンデマンドで利用できるようにすることです。これは、異なる知識レベルの読者に対応するページに役立ちます。リピーターの顧客は実装ノートを読み飛ばせますが、初めてのユーザーはそれらを開くことができます。このコントロールは、コンテンツを削除したり、すべての読者にすべての例外を通読させたりすることなく、視覚的な密度を低減します。

同じ利便性が隠蔽になることもあります。直接的な回答を探してページにたどり着き、8つの閉じたラベルを見た読者は、どのパネルに回答が含まれているかを推測し、余分な操作を行う必要があります。モバイルでは、繰り返しの開閉によりビューポート内でコンテンツが移動することもあります。したがって、アコーディオンは、ほとんどの読者がすべてのパネルを開かなくても主要なタスクを完了できる場合にのみ価値があります。

機械による抽出可能性は、さらに厳しいテストを追加します。抽出可能性とは、検索エンジン、AI回答システム、パーサー、支援ツールがテキストを受信し、そのラベルとの関係を保持できる能力です。すべての回答は、初期サーバーレンダリングDOM（ブラウザのページ構造表現）に存在しなければなりません。CSSは存在するパネルを視覚的に折りたたむことができますが、JavaScriptはクリック後にのみ回答をフェッチしたり作成したりしてはいけません。クローラーがクリックしたり、クライアントコードを実行したり、二次リクエストを待つことはありません。

このパターンを使用する前に、要素作成ルール に従ってください。コンテンツの目的がより具体的な型付き要素に一致する場合、その要素が優先されます。アコーディオンは許可された補足コンテンツを含むことができますが、単にページを短くするために、警告、比較、定義、手順シーケンスの名前を変更したり平坦化したりしてはいけません。

使用すべき場合

次の4つの条件すべてが満たされる場合にアコーディオンを使用します：

1. 読者がラベルからパネルの内容を予測できる。
2. コンテンツがすべての人に必要なものではなく、一部の読者にとって有用である。
3. すべてのパネルコンテンツが初期HTMLで配信され、ポインティングデバイスなしでも到達可能である。
4. 折りたたみにより、想定されるビューポートでのスキャンが実質的に向上する。

適切な候補には、オプションの互換性詳細、一般的でないエラーの分岐、補助的な定義、二次的なポリシー条項、配送例外、グループ化された参照回答が含まれます。アコーディオンは、すべての質問が可視のままで各回答が自己完結している場合、大規模なFAQコレクションにも機能します。

以下のニアミス事例は、最も一般的な誤用を示しています：

• 2つの短いセクションがある短いページ： 可視の見出しと段落の方が、2つのコントロールよりもスキャンが速い。
• 短く見せかけた長い記事： 10の実質的なセクションを折りたたむと、認識される高さは減少するが、インタラクションが増加し、ページの範囲が隠れる。
• 主要な製品情報： 価格、在庫状況、素材の制限、キャンセル条件、コア仕様は決定に影響を与えるため、展開に依存してはならない。
• 順序のある手順： 手順には順序とコンテキストが必要。閉じたパネルにより、読者が前提条件をスキップしたり、手順を順不同で実行したりする可能性がある。
• 比較： 読者は同じ基準にわたって同時に可視性を必要とする。個別のパネルは記憶ベースの比較を強いる。
• 安全警告または法的条件： 見逃した場合の結果は、隠すことによる視覚的メリットよりも大きい。
• ナビゲーションの代替： アコーディオンは目次ではない。安定したページセクションに移動するのではなく、同じ場所でコンテンツを表示する。

不明な場合は、コンテンツを可視で公開してください。余分なスクロールは通常回復可能ですが、見逃された回答、未開示の制約、または利用できないDOMノードは回復できません。

配置場所

ページが直接的な回答を提供し、読者がグループの内容を理解するのに十分な可視の説明を行った後にアコーディオンを配置します。H2と1つのスコープ文で導入します。その後、グループはそのセクション内の補足的な参照レイヤーとして機能します。

正確な配置ルール：

• それが修飾する可視の説明の後に配置し、主張とその主張を裏付けるエビデンスの間に決して置かない。
• すべての項目の主題が含まれる親セクション内に配置する。ラベルが欠落した見出しなしでは意味をなさない場合、グループは誤った位置にある。
• 製品詳細のアコーディオンは、コアバリュー、価格コンテキスト、購入条件の後に配置する。トラブルシューティングの分岐は、共通の診断と最も安全な最初のチェックの後に配置する。
• FAQアコーディオンを閉じる際は、主要な結論の後、最終的な次のアクションの前に配置する。ただし、残存する質問に回答し、繰り返しの質問ではない場合に限る。
• 読者がリンクする可能性がある場合、グループに安定したセクションアンカーを付ける。個別のパネルリンクはオプションだが、提供する場合は正しい項目を開いてフォーカスする必要がある。

アコーディオンは、タブ、別のアコーディオン、または高密度の比較表のすぐ隣に配置してはいけません。隣接するインタラクションパターンにより、読者はコンテンツを選択する前にメカニズムを選択する必要が生じます。順序付けられた手順を中断したり、警告とその結果を分離したり、製品価格とその価格を規定する条件の間に配置したりしてはいけません。グループ内または各パネルの直後にプロモーションバナーを配置しないでください。プロモーションは参照タスクと競合し、展開が販売の罠のように感じられる原因となります。

構造

ラベル付けされた構造には7つの部分が含まれます：

1. グループ見出し： 周辺のドキュメント階層内で共有の主題を指定します。
2. 項目ラベル： 「詳細を見る」のような曖昧なラベルではなく、特定の内容を予測します。
3. 開閉コントロール： キーボードフォーカスを受け取り、1つのパネルを切り替えるネイティブの summary または button。
4. 状態インジケーター： プログラム上の状態がネイティブセマンティクスまたは aria-expanded を通じて公開される一方で、視覚的に開閉を伝えます。
5. パネル： 回答または参照詳細を含み、初期DOMに残ります。
6. コントロールの関連付け： ネイティブの <details>/<summary> セマンティクスまたは aria-controls と一致するIDにより、各コントロールが正確に1つのパネルと関連付けられます。
7. 項目の境界： 間隔、境界線、DOMのグループ化により、1つのラベルが隣接する回答を制御しているように見えることを防ぎます。

表示されるシェブロンは装飾用です。展開状態がすでに意味を提供しているため、支援技術からは非表示にします。回転だけでは状態を伝えることができません。コントロールのセマンティクスがそれを伝える必要があります。

デザイン例

すべてのバリアントは同じフィールドとDOM保持ルールを使用します。装飾ではなく、読み取りタスクによってバリアントを選択します。

標準のシングルオープングループ

1つの項目を開くと、以前に開いていた項目が閉じます。パネルが代替案であり、読者が通常一度に1つだけを必要とする場合（相互に排他的なトラブルシューティング症状など）に使用します。

マルチオープン参照グループ

読者は複数のパネルを開いたままにできます。サポートされているファイルタイプやアカウント権限など、補足的な詳細を比較または組み合わせる可能性がある場合に使用します。同時比較が主要なタスクの場合は、代わりに可視の表を使用します。

デフォルトオープン設定

コンテンツパターンを示し、有用な方向性を提供する場合に、最初または最も一般的な項目を初期読み込み時に開きます。単にスペースを埋めるために複数の項目を開くことは決してしてはいけません。

コンパクトFAQバリアント

質問ラベルと簡潔なスタンドアロン回答を使用します。インタラクションそのものは構造化データを正当化しません。スキーマはコンテンツタイプと正確な可視レコードに依存します。

長文コンテンツのストレス状態

2つ以上の短い段落があるパネルは、その内容が可視セクションに値する可能性があることを示します。このストレスバリアントは、折り返し、リンク、リスト、フォーカス、レスポンシブフローのテスト用であり、通常の編集目標ではありません。

パラメーター

この契約はグループの動作と項目コンテンツを分離し、すべてのプラットフォームが同じラベル、状態、関係を保持できるようにします。

最初の親見出しが heading にマッピングされます。各ネスト項目の最初の見出しが label にマッピングされ、その後のすべてがその項目の content にマッピングされます。これは明示的なネスト項目マッピングであり、ベースの優先順位および本文ルールと一貫しています。open=true は初期表示のみを設定し、コンテンツの重要度を変更しません。linkable=true の場合、項目フラグメントへの移動はパネルを展開し、フォーカスを予測可能に移動し、見出しがスティッキーヘッダーの下に可視のまま残るようにする必要があります。

構文とコード例

以下の3つの表記はすべて1つの正規グループを表します。ラッパークラスは異なる場合がありますが、初期HTML、ソース順序、アクセシブルな名前、状態のコンテンツを保持する必要があります。

ポータブルMarkdownディレクティブ

:::accordion{mode=multiple linkable=true}
## Export details

::item{id="included-fields" open=true}
### Which fields are included?

The export contains the fields currently available to your account and report scope.
::

::item{id="filter-behavior"}
### Do filters affect the export?

Yes. Confirm the active date range, market, and status filters before creating the file.
::
:::

Hugoショートコード

{{< accordion heading="Export details" mode="multiple" linkable="true" >}}
{{< accordion-item id="included-fields" label="Which fields are included?" open="true" >}}
The export contains the fields currently available to your account and report scope.
{{< /accordion-item >}}
{{< accordion-item id="filter-behavior" label="Do filters affect the export?" >}}
Yes. Confirm the active date range, market, and status filters before creating the file.
{{< /accordion-item >}}
{{< /accordion >}}

これはHugoアダプターの仕様です。リポジトリが任意の見出しにクラスを追加するだけではこれを満たしません。ネイティブの開示HTMLまたは同等のボタンとパネルの関係を生成するレンダラーが必要です。

WordPressブロック

<!-- wp:amicited/accordion {"heading":"Export details","mode":"multiple","linkable":true} -->
<!-- wp:amicited/accordion-item {"id":"included-fields","label":"Which fields are included?","open":true} -->
<p>The export contains the fields currently available to your account and report scope.</p>
<!-- /wp:amicited/accordion-item -->
<!-- wp:amicited/accordion-item {"id":"filter-behavior","label":"Do filters affect the export?"} -->
<p>Yes. Confirm the active date range, market, and status filters before creating the file.</p>
<!-- /wp:amicited/accordion-item -->
<!-- /wp:amicited/accordion -->

登録されたWordPressブロックは、無関係なDetailsブロックの視覚的なグループに依存するのではなく、正規のフィールドを保存します。そのサーバーレンダリングは、インタラクションの前にすべての回答を出力する必要があります。

例

良い例

アカウント削除の詳細 は、削除の内容を説明する可視の説明と、元に戻せないことを示す可視の警告の後に表示されます。その3つのラベルは、「スケジュールされたエクスポートはどうなりますか？」、「リクエストされたアーカイブはどのくらい利用可能ですか？」、「別の管理者がリクエストをキャンセルできますか？」です。各パネルには1つのオプション分岐が含まれ、すべての回答がHTMLにあり、キーボードフォーカスが可視です。

これは、主要な結果と必要なアクションが可視のままであるため機能します。アコーディオンは異なる読者に適用される二次的な質問を保持し、各ラベルにより読者は開く価値があるかどうかを予測できます。

悪い例

プランを選択 には、「スターター」、「チーム」、「エンタープライズ」とラベル付けされた閉じたパネルが含まれています。価格、使用制限、契約期間、キャンセル条件、在庫状況はパネル内にあります。同時に開くことができるプランは1つだけです。

これは、購入基準に並べて表示できる可視性が必要なため失敗します。読者は繰り返しパネルを開いて事実を記憶する必要があり、非対話型の抽出ツールはクライアント側で読み込まれる価格を見逃す可能性があります。代わりに可視の価格表または仕様表を使用し、開示は請求書形式や一般的でない資格ルールなどのオプション詳細に予約します。

スキーママークアップとアクセシビリティ

アコーディオンには専用のSchema.orgタイプはありません。存在するだけでインタラクションが構造化データを供給することはありません。そのレコードが本当の質問と回答である場合、FAQコンテンツ契約が FAQPage を供給する可能性があります。グループに製品詳細、ポリシー、またはトラブルシューティングノートが含まれる場合は、ページとコンテンツによって正当化されるスキーマのみを使用します。表示テキストと構造化表現は一致しなければなりません。

単純な開示には、ブラウザがキーボード操作と状態セマンティクスを提供するため、ネイティブの <details> と <summary> を優先します。デザインまたはシングルオープン動作にカスタム実装が必要な場合、各コントロールは button であり、aria-expanded="true" または "false" を公開し、aria-controls で自身のパネルを参照し、パネルが aria-labelledby で参照できる一意のIDを持つ必要があります。クリックハンドラーを持つ div にコントロールを配置しないでください。

EnterまたはSpaceでフォーカスされたコントロールを操作する必要があります。Tabは開いているパネル内のコントロールとインタラクティブコンテンツを移動します。フォーカスは閉じたコンテンツに入ってはいけません。パネルの開閉は通常、フォーカスをそのコントロールに残します。見出し間の矢印キーナビゲーションはオプションですが、実装する場合は通常のTab動作を置き換えてはいけません。

すべてのラベルをアクセシビリティツリーに、すべての回答をソースHTMLに保持します。視覚的に閉じたパネルは、ネイティブの開示動作またはサポートされた非表示状態を使用できますが、その内容は2回目のフェッチなしで展開時に利用可能になる必要があります。折りたたみ状態により、デスクトップ用とモバイル用の別々のコピーによる重複コンテンツが発生してはいけません。200%ズーム、長いラベル、キーボードのみ、動作の抑制、スクリーンリーダーでテストします。アニメーションが抑制でき、コンテンツが遅延しない場合にのみ、高さまたはアイコンの回転をアニメーション化します。

作成ルール

ラベルはインタラクションのコストを負担するため、正確な約束をする必要があります。3～14語、通常120文字以内で記述します。FAQコンテンツには直接的な質問を、参照コンテンツには説明的な名詞句を使用します。「詳細」、「もっと読む」、「これを見る」、および番号だけで異なるラベルは避けます。

グループあたり3～8項目を使用します。各パネルは通常20～120語、最大250語を含む必要があります。2つの短いパネルは開かれた散文としてより明確であり、9つ以上はグループ化、可視ナビゲーション、または編集上の統合が必要です。ラベルは文法的に並列にし、項目は読者のタスク、予想頻度、または実際のカテゴリの順序で配置します。検索が本当にアルファベット順でない限り、アルファベット順にはしないでください。

パネルのトーンは直接的で、自己完結的で、事実に基づきます。読者はすでにインタラクションコストを支払っているため、最初の文で回答を述べます。必要な用語はパネル内、またはグループの直前の可視テキストで定義します。「考慮すべき点がいくつかあります」のような前置きで始めないでください。

以下をアコーディオン内のみに絶対に配置しないでください：

• ページの直接的な回答または独自の価値提案
• 安全警告、禁忌、法的義務、または不可逆的な結果
• 価格、在庫状況、材料製品の制限、または必要な購入条件
• 順序付けられた手順、前提条件、または完了確認
• 周辺の主張を裏付けるために必要なエビデンス
• 主要な比較または決定マトリックス
• フォーム、チェックアウトコントロール、同意、またはページの主要なコールトゥアクション
• 別のアコーディオン、タブ、またはカルーセル

コンパクトなリスト、小さな表、インラインリンク、または補助画像は、完全に1つのオプション項目に属し、モバイルで使用可能な場合に許容されます。パネルに独自の目次や複数の見出しレベルが必要な場合は、可視セクションまたは別のページに昇格させます。

使用する投稿タイプ

postTypes フロントマター配列がこの使用マトリックスのソースです。記載は、その要素が記載された条件の下で利用可能であることを意味し、そのタイプのすべてのページで必須であることを意味しません。

QAチェックリスト

• アコーディオンの前に可視の直接的な回答が表示されている。
• すべての項目がオプションの参照コンテンツであり、すべての読者に必要な情報ではない。
• グループは3～8項目で、正確で並列なラベルを持っている。
• 各パネルの完全なテキストが初期サーバーレンダリングHTMLに存在している。
• クリックトリガーのネットワークリクエストやクライアントのみの挿入に依存する回答がない。
• ネイティブの details/summary または実際のボタンが正しいキーボード動作を提供している。
• カスタムコントロールが aria-expanded、aria-controls、一意のID、および関連するパネルラベルを公開している。
• フォーカスが可視であり、切り替え後も予測可能なまま、閉じたパネルに入ることができない。
• 長いラベルがクリッピング、重なり、状態インジケーターの非表示なしで折り返される。
• レイアウトが200%ズームおよび狭いビューポートで水平スクロールなしで機能する。
• モーションが動作抑制の設定を尊重し、コンテンツへのアクセスを決して遅延させない。
• 個別のフラグメントリンク（サポートされている場合）が正しいパネルを開いて表示する。
• 構造化データはアコーディオンの外観ではなく、コンテンツの意味に基づいている。
• FAQPageレコード（出力される場合）が可視の質問と回答のテキストと正確に一致する。
• ネストされたアコーディオン、隣接するタブセット、繰り返しのモバイルコピー、メインCTAがない。
• すべてのパネルが閉じている場合でも、ページが主要な回答を伝えている。

よくある質問

フロントマターには、このページの正規のFAQレコードが保存されています。それらの回答は実装の境界を強化します。コンテンツは視覚的に折りたたまれていても、存在し、アクセス可能であり、可視の回答に対して二次的です。