Change guidance on sections and landmarks in HTML

[tombye]

An attempt to rewite the guidance on use of <section> tags to solve the problems in #617.

Problems with the current guidance

I think the current guidance on use of <section> tags is unclear because:

• the approach it recommends (using aria-labelledby to get their accessible name from the heading) creates a region landmark¹ but the examples seem to show content that wouldn't benefit from being in one
• from looking through a lot of GDS repos, I couldn't find any code following this pattern
• it seems to clash with the current HTML5 spec'², which includes similar content examples but doesn't use of aria-labelledby to set an accessible name

Causes of the confusion the issue describes

I think a major cause of this confusion comes from the HTML5 spec's description of <section> tags. At the point this guidance was written, it said they should be used with <h1>s to create the document outline, something never implemented in any browser and therefore confusing for developers:

https://www.tpgi.com/html5-document-outline/

This has since been changed (see whatwg/html#7829) but, without an impact on the document outline, they are now effectively just there to mark the block of content a heading labels:

<header>
 <hgroup>
  <h1>My Book</h1>
  <p>A sample with not much content</p>
 </hgroup>
 <p><small>Published by Dummy Publicorp Ltd.</small></p>
</header>
<section class="chapter">
 <h2>My First Chapter</h2>
 <p>This is the first of my chapters. It doesn't say much.</p>
 <p>But it has two paragraphs!</p>
</section>
<section class="chapter">
 <h2>It Continues: The Second Chapter</h2>
 <p>Bla dee bla, dee bla dee bla. Boom.</p>
</section>

(This is from the current HTML5 spec`.)

This arguably makes the HTML easier to read, and allows those blocks to be styled, but doesn't add any new semantics (because <section>s without accessible names are basically <div>s) so I'm wary of including guidance for it here.

Reasoning behind these changes

These changes instead intend to clear up the existing guidance on use of <section> tags by making it clear that this approach creates region landmarks and that using them in other ways (without assigning an accessible name) removes any semantics they add.

Other notes

These changes gratefully borrow from https://www.scottohara.me/blog/2018/03/03/landmarks.html

This is not meant as a critique of the excellent work done on the current guidance by @ChrisBAshton but rather an iteration of it, to help clear up some of the confusion in developers minds caused by how <section>s have been implemented and explained over the years.

Final note: I expect a bit of discussion on this pull request so intend to update the date of the page these changes are in
if and when they are agreed to be the correct approach to the issue.

Footnotes

1. By 'region landmark', I mean an element with role="region". ↩

2. the HTML5 spec' on <section>. ↩

[36degrees]

Agree with the change in principle. A few comments on some of the wording, but hopefully nothing major…

[36degrees]

Appreciate this is just tidying up existing guidance, but would be tempted to talk about accessible names here, and reference both aria-labelledby and aria-label – unless we want to express a preference for one over the other.

[tombye]

Should be addressed in 7747132.

[DavidBiddle]

This looks really good @tombye, and think you've addressed the points Ollie raised.

My only feedback is that you may want to bump the last_reviewed_on date since this PR has been around a while.