Skip to content

Add a document discussing the section element #496

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add a document discussing the section element #496

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4d6ab1e
Add a document discussing the section element
RSeidelsohn May 26, 2025
48bf36a
Update accessibility/08-guide-to-the-section-element.md
RSeidelsohn May 26, 2025
ccaa225
Update accessibility/08-guide-to-the-section-element.md
RSeidelsohn May 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 113 additions & 0 deletions accessibility/08-guide-to-the-section-element.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
# The section element

- [What is the use case for a section element?](#what-is-the-use-case-for-a--section--element)
- [What facts should be considered before using an accessible section element?](#what-facts-should-be-considered-before-using-an-accessible-section-element)
- [What are the requirements for making a section element accessible](#what-are-the-requirements-for-making-a-section-element-accessible)
- [Testing for a correct section label](#testing-for-a-correct-section-label)


## What is the use case for a section element?

[The HTML spec of the Web Hypertext Application Technology Working Group (WHATWG)](https://html.spec.whatwg.org/multipage/sections.html#the-section-element) says:

> The section element represents a generic section of a document or application. A section, in this context, is a
> thematic grouping of content, typically with a heading.

As a general rule, before using a section element, you should always think of a more specific element first, such
as article, aside, header, footer, nav, or main. If none of these are appropriate, you can use a section element
to point users of assistive technology (AT) to a relevant section of the page.

## What facts should be considered before using an accessible section element?

AT users who can use landmarks prefer a few well-chosen landmarks to many. And remember that a heading in
itself is a thing that an AT user can jump to directly - if you make all your sections landmarks using headings,
then you're just duplicating the headings in the landmark auditory interface, which makes the landmarks less
useful.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For me, this paragraph isn't completely clear. Is the point that perhaps not all section elements should have a heading because too many landmarks create noise?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you have a suggestion what I could do to improve this paragraph? It's quoted from @hollsk. Possibly this collides with the recommendation of using section elements only sparingly and only when the content really deservers it's own landmark.

Copy link
Contributor

@hollsk hollsk May 27, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, Jon's got it right. The section element is neutral and you can use as many as you like. A section can have as many headings as you like. It won't cause anyone any problems.

The (potential) problem is that when you apply an aria-labelledby to a section that points to one of those headings, that heading is then duplicated into the Landmarks aural interface, when it already exists in the headings aural interface. You could have a super important section and this is what you want. But you shouldn't do it as a matter of course, because the Landmarks need to be kept tight and largely separate from the headings for them to still be useful.

It's (as always!) the aria that you want to be sparing with, not the semantic HTML element.

I think the confusion has originated from this sentence that I typed off the cuff which on reflection is a bit of a car crash: "if you make all your sections landmarks using headings..."

To translate this into hopefully more comprehensible english: "if you transform all your sections into Landmarks by using aria-labelledby to programmatically associate them with a heading..."

... or something like that. If it still doesn't make sense I would very much appreciate someone translating it into human language for me as I'm not operating at peak performance today 😆

Copy link
Contributor Author

@RSeidelsohn RSeidelsohn May 27, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a very fair point. But also I would like to point out that you should not use a <section> unless you want it to be a landmark, because otherwise it's merely a <div>, and if it's a <div>, then please use a <div> and not a <section>.
What do you think about it?
As for the duplication of a headline in landmark space: You probably (hopefully) will have a lot more headlines than landmarks, and so it still can make sense to highlight one of those headlines as a landmark.
A <nav> often also has a headline, as does a <main> etc.

Copy link
Contributor

@hollsk hollsk May 27, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Semantically speaking, a section is a theme for a group of content. A div is just a meaningless block. A section can be made up of all sorts of things, including divs, but it'll always have an overarching organisational purpose. You might have a section for featured articles, say, and inside that section you could have dozens of div elements that don't really mean anything semantically. This is fine.

There's no requirement to use section, unless you're semantics nerd - they don't have any effect on AT or visual presentation, unless you do something with styling or aria to make them have an effect, so in that respect you can consider them largely useless except as a source document structuring method. Personally I don't think that's a problem - they have no real effect, so that's why I called them neutral. A div is also neutral, in that doesn't do anything by itself, and that's ok.

When it comes to a main element, most AT users would expect to find only one of these on page (and the HTML will be invalid if there are more than that), and they'd also expect the heading for main to be the H1 - so there's no need to apply aria there, as the structure is already implied by the main/h1 combo. With nav elements, you can have more than one of those on a page, so you do need to differentiate them using aria if that's the case, so that AT users can tell the difference between your main navigation and your sidebar navigation in the landmarks interface. You may or may not be using headings there. But again, nav elements show up to AT users anyway, so they have user utility, not just developer utility.

Scott O'Hara has an article on section here that is better-worded than anything I can come up with: Accessibility of the section element

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK I understand the point now. I think the sentence could perhaps be slightly clearer if the preceding paragraph had some more context about how you can create landmarks by associating a section with it's heading.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ignoring about most of the knowledge above I trapped myself into overusing labelled section.

I think there was a bit of:

unless you're semantics nerd

I'm definitely one.

As greatly formulated in Scott's article though:

its use can help other developers more quickly understand the structure of a web page, rather than having to rely on a bunch of <div>s and classes to hopefully understand the intended structure.

To be fair in our application we have a page with so much content... I thought I was being helpful in sectioning it, doing the cut at the h2s level.
It now also appears to me silly to have duplicated content into the 2 aural interfaces (thanks for enhancing my vocabulary there BTW).

Once again Scott got it greatly formulated:

Overpopulating a web page with landmarks will reduce their ability to help users find the most important parts of web pages. In other words, if everything’s a landmark then there’s nothing really special about them, is there?

That is often the case for web professionals, not screen reader dependent, that despite being full of good intentions and willing to make something the most accessible they could think of, that they take a less than ideal implementation path.
This is where I enjoy this kind of discussions and learning so much.
Thank you @hollsk for sharing your expertise and @RSeidelsohn to have taken on this task ❤️

I think using examples that make sense could support building a mental model.

I like these three:

  1. The "featured articles" example from Hollie => As a spotlight it requires its entry in the Landmarks aural interface
  2. The "Quick summary" from Smashing Magazine articles, as it is a quite convenient region to get a gist of the article while not having to spot "Quick summary" from the Headings aural interface that may be flooded with headings a post may contain, especially if its one by Vitaly 😛
  3. The "Code"/"Output"/ "Console" of an online coding playground page As these are the 3 "pillar" landmarks and as there should not be much more regions in the page to interact with it may be acceptable duplication across the 2 aural interfaces (i.e Landmarks and Headings)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Morgan! And yes, it's so easy to overuse them because it seems like the right thing to do 😅

In terms of examples, I don't think that my featured articles example should be landmarks - they're nowhere near important enough. It's reasonable for that to be a section, but it's essentially advertising, so there's little benefit to making it a landmark. The quick summary example is arguable, IMO - I can see why it might be useful, but it should have a heading anyway. Your code/output/console example is probably the strongest of the three, I think, because they're all about core utility - but on a well-structured page, all that core utility should be inside the main landmark.

Looking again at this quote from the W3C mailing list:

generally advise avoiding nested landmarks and keeping the total in the range of 5 to 7.” – Matt (blind screen-reader user)

This user isn't the only person who prefers this, the low number of default landmarks in HTML is a deliberate choice. If you've got a well-structured page with a header/banner, a main, a footer, an aside, and maybe a search landmark, that's already five landmarks right out of the gate - those all show up in the interface by default. If you're keeping your landmarks to 5-7, then you can see how few additional elements you have room for in that interface.

One of the big differences between headings and landmarks is that headings have hierarchy, and landmarks don't. That's kind of what that user is getting at when they suggest avoiding "nested landmarks" - landmarks are probably most powerful as top level elements. That said, search and aside are probably going to be nested inside main in a lot of implementations and that's not really a problem, so long as they're limited.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is so valuable @hollsk thank you for sharing!

Half way through the reading I was, hold on, wouldn't "search" landmark be nested? What you addressed in your last sentence 😛

Now though, there is a part of me that lean toward advising to use "search" and "aside" outside of "header"/"main" to echo from "generally advise avoiding nested landmarks" backed up by "headings have hierarchy".
Do you see any harm in that, or this a use case that a trend has shaped users mind to expect them to be nested? Supposedly it should not matter as long as the benefit of landmark from a screen reader user stand point is to see them pop up in the landmarks aural interface, that would not communicate any kind of hierarchy anyway.
It seems to a much easier mental model to keep them all top level, period, so that you are not scratching your head every time you through designing the page architecture.

If you're keeping your landmarks to 5-7, then you can see how few additional elements you have room for in that interface
Gold argument!

I like how you busted, with style and strong arguments, all my proposed examples, even the strongest 🙈.
Witnessing how you reason about them is very educational and helps sharpen our, yet to become more critical, minds. Thank you so much!

At this point I believe we have the best foundation we could hope to form this new contribution to the Playbook

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🙈 honestly, not trying to bust any arguments or anything, just laying out what I know as best as I can. I was thinking to myself yesterday about what sort of examples could be used, and where it would make sense to recommend adding an accessible label for a section. I couldn't really come up with one, so instead I started thinking about it in terms of a physical world analogy (we love physical world analogies, right?).

So I thought about it in terms of a hard copy book. A book might contain chapters and chapter headings and images and box callouts etc etc. But when you pick one up for the first time, you're probably going to look at the spine and the front cover, then at the back cover. Then you might open it up near the beginning to look at what's inside. And those are like using the book's landmarks - they're structurally important parts of the physical object, and because of general convention, you know roughly what you can expect to find on any of them. You know that you'll probably see an image and a title on the front cover, and a blurb and maybe some reviews on the back cover. You won't look in the middle of the book for the cover image, and you won't look at the back cover for chapter content. That's basically what landmarks are trying to achieve on the web. Whereas the table of contents with the chapter headings, and the chapter titles themselves inside the book - those are like the headings structure of a webpage. You that those to drill down into the actual content. It's like "where is the content" vs "what is the content".

(at least I didn't use a car analogy here 😆)

On recommending against nesting landmarks at all... I don't feel strongly about it, really. For most designs it'd be genuinely difficult to make all landmarks top level while still respecting the concept of main. I think the person we've quoted is kicking back against very overzealous landmarking, and is using nesting as an example of where they've seen things going wrong, but there's nothing wrong with it per se, so long as you're not nesting top level roles inside others (like putting a header inside a primary nav - that should be the other way around).

Nesting is permitted and is appropriately semantic in the aria spec for some roles. I've quoted some of Step 2 of the ARIA practices guide's General Principles of Landmark Design below:

Step 2: Assign landmark roles to each area

  • banner, main, complementary and contentinfo landmarks should be top level landmarks.
  • Landmark roles can be nested to identify parent/child relationships of the information being presented.

Caroly McLeod points out in [a post on w3c aria practices](https://github.com/w3c/aria-practices/issues/575#issuecomment-380620317):

> Happened to notice a trend in the WebAIM Screen Reader User Survey results: the use of landmark navigation is
> decreasing.
>
> [Survey 5](https://webaim.org/projects/screenreadersurvey5/#landmarks): 44% of users always or often navigate by
> landmarks<br>
> [Survey 6](https://webaim.org/projects/screenreadersurvey6/#landmarks): 39% of users always or often navigate by
> landmarks<br>
> [Survey 7](https://webaim.org/projects/screenreadersurvey7/#landmarks): 31% of users always or often navigate by
> landmarks<br>
> [Survey 8](https://webaim.org/projects/screenreadersurvey7/#landmarks): 27% of users always or often navigate by
> landmarks<br>
>
> If I had to guess why, I would say that it is most likely because landmarks are inconsistently implemented, and often
> over used. I would further guess that the lack of clarity in the spec(s) is contributing to this problem.

Furthermore, a W3C WAI-IG mailing-list thread “Landmarks without labels or no landmarks at all?” (Sept 2024) states:

> “Too many landmarks are super annoying and problematic… I generally advise avoiding nested landmarks and keeping the
> total in the range of 5 to 7.” – _Matt (blind screen-reader user)_<br>
>
> “Landmarks are supposed to be used sparingly … My main objection is the ‘noise’ that screen-reader users encounter.”
> – _Steve Green (screen-reader user & auditor)_<br>
>
> [W3C Lists](https://lists.w3.org/Archives/Public/w3c-wai-ig/2024JulSep/0118.html)

Both explain that landmark “noise” slows them down - they only want a handful that map to genuinely major regions.

While many users of assistive technology use headlines to skim over a page, it may still make sense to use a headline to
label a section element, namely if it is important enough to be given its own landmark among the landmarks of the page.


## What are the requirements for making a section element accessible?

As Stefan Judis [explains in his article on section element accessibility](https://www.stefanjudis.com/today-i-learned/section-accessible-name/),
a "section" without an accessible name is nothing but a "div".

To make a section element accessible, you need to give it a label by adding a `aria-label` or `aria-labelledby`
attribute. This label should describe the content of the section in a way that is meaningful to assistive technology
users.

Without a label, the section element is assigned the role `generic` and is not announced by screen readers, making
it effectively invisible to assistive technology users. With a label, the section element is given the role `region`
and is announced by screen readers with the name of the label.

Example:

```html
<section aria-labelledby="headline-article-details">
<h2 id="headline-article-details">Article details</h2>

<dl>
<dt class="c-submission-details__term">
Corresponding author
</dt>
<dd class="c-submission-details__description">
Charles Darwin
</dd>
</dl>
</section>
```


## Testing for a correct section label

You can test in Jest whether a section element has a proper label by checking that the `aria-labelledby` attribute is
set and that the referenced label element exists:

```javascript
describe('Your research section', () => {
let sectionElement;
let sectionLabelId;
let sectionLabelElement;

beforeAll(() => {
sectionElement = document.querySelector('[data-test="your-research-section"]');
sectionLabelId = sectionElement.getAttribute('aria-labelledby');
sectionLabelElement = sectionElement.querySelector(`[id="${sectionLabelId}"]`);
});

it('exists', async () => {
expect(sectionElement).not.toBe(null);
expect(sectionLabelElement).not.toBe(null);
});
});
```
3 changes: 1 addition & 2 deletions accessibility/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,7 @@ We maintain guides to specific areas of accessibility. You may be interested in:
* [creating accessible emails](03-accessibility-in-emails.md)
* [creating accessible PDFs](04-accessibility-in-pdfs.md)
* [learning about effective colour contrast](05-effective-colour-contrast.md)
* [make good use of the section element](08-guide-to-the-section-element.md)

If you're curious about the most common accessibility issues we see on websites, we have a set of documents on [common remediations](common-remediations/README.md) for issues that can only be detected with manual testing.

Expand All @@ -116,5 +117,3 @@ If you're a third party supplier, or you need to share guidance with one of our
### Learning resources

You can find a [list of accessibility-related resources](../learning/web-accessibility.md) in the [Learning section of the Playbook](../learning/README.md).