From 34c22a816684c7c61554a8f4c887f08a46f96106 Mon Sep 17 00:00:00 2001 From: web-padawan Date: Fri, 28 Aug 2026 16:10:02 +0300 Subject: [PATCH 1/2] docs: add Accessibility section to Accordion page --- articles/components/accordion/index.adoc | 30 ++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/articles/components/accordion/index.adoc b/articles/components/accordion/index.adoc index 04f66c86ec..ec8b6de8c6 100644 --- a/articles/components/accordion/index.adoc +++ b/articles/components/accordion/index.adoc @@ -139,6 +139,36 @@ include::{root}/frontend/demo/component/accordion/react/accordion-disabled-panel endif::[] -- +== Accessibility + +Each panel's summary is rendered as a heading -- an element with `role="heading"` that wraps a button -- and the panel's content as a region labeled by that heading, as recommended by the WAI-ARIA accordion pattern. Screen readers can therefore list the summaries as headings and announce whether each panel is expanded or collapsed. + +By default, the headings have no level, so screen readers announce them at their default level. The level can be [since:com.vaadin:vaadin@V25.3]#set explicitly# to match the surrounding page structure. Use the following to set `aria-level` on the heading of each panel to level 3 for an accordion inside a section with an `

` title: + +[.example] +-- +ifdef::flow[] +[source,java] +---- +accordion.setHeadingLevel(3); +---- +endif::[] + +ifdef::lit[] +[source,html] +---- + +---- +endif::[] + +ifdef::react[] +[source,tsx] +---- + +---- +endif::[] +-- + == Best Practices Accordions are suitable when users need to focus on smaller pieces of content at any given time. However, when all of the content is relevant to the user to make a decision, Accordions should be avoided. Content areas that are logically linked should be grouped together in one panel. From 66c5ecc8097fccee2222114b32dcacbf460ff92d Mon Sep 17 00:00:00 2001 From: web-padawan Date: Fri, 28 Aug 2026 17:15:41 +0300 Subject: [PATCH 2/2] docs: simplify Accordion heading level wording Co-Authored-By: Claude Opus 5 (1M context) --- articles/components/accordion/index.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/articles/components/accordion/index.adoc b/articles/components/accordion/index.adoc index ec8b6de8c6..73d2da141b 100644 --- a/articles/components/accordion/index.adoc +++ b/articles/components/accordion/index.adoc @@ -143,7 +143,7 @@ endif::[] Each panel's summary is rendered as a heading -- an element with `role="heading"` that wraps a button -- and the panel's content as a region labeled by that heading, as recommended by the WAI-ARIA accordion pattern. Screen readers can therefore list the summaries as headings and announce whether each panel is expanded or collapsed. -By default, the headings have no level, so screen readers announce them at their default level. The level can be [since:com.vaadin:vaadin@V25.3]#set explicitly# to match the surrounding page structure. Use the following to set `aria-level` on the heading of each panel to level 3 for an accordion inside a section with an `

` title: +By default, the headings have no level, so screen readers announce them at their default level. The `aria-level` attribute can be [since:com.vaadin:vaadin@V25.3]#customized# to match the surrounding page structure -- for example, level 3 inside a section with an `

` title: [.example] -- @@ -169,6 +169,9 @@ ifdef::react[] endif::[] -- +The same level is applied to all panel headings. + + == Best Practices Accordions are suitable when users need to focus on smaller pieces of content at any given time. However, when all of the content is relevant to the user to make a decision, Accordions should be avoided. Content areas that are logically linked should be grouped together in one panel.