Add a document discussing the section element

[RSeidelsohn]

I have added a document with details about the <section> element we gathered in a discussion thread in Slack's #accessibility channel.

The document informs about the basic definition of what a <section> element is meant for, lists some facts with feedback from diverse users about what to care about before using an accessible <section> element, explains that is required to make a <section> element accessible and shows a code snippet of a Jest test for a valid accessible <section> element.

[Copilot]

Pull Request Overview

This PR adds documentation regarding the accessible use of the

element and a corresponding Jest test snippet.

• Added a new guide explaining best practices for using the
  element
• Updated the README to include a link to the new guide

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
accessibility/README.md	Added a link to the new guide
accessibility/08-guide-to-the-section-element.md	Introduced a new document with guidelines and a Jest test snippet for accessible section elements

[jon-stevens]

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?

[RSeidelsohn]

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.

[hollsk]

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 😆

[RSeidelsohn]

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.

[hollsk]

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

[jon-stevens]

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.

[morgaan]

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)

[hollsk]

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.

[morgaan]

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

[hollsk]

🙈 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.