Draft guidance to help authors understand the difference between landmark regions and outline sections

[carmacleod]

I don't have the required github permissions to reopen issue #562 (only repo collaborators can reopen issues that they have closed). So I am opening this new issue in order to discuss https://github.com/w3c/aria-practices/issues/562#issuecomment-350497167.

I think we need to clarify what it means to use a section element without a label. If we can't come up with a good description of what an unlabelled section element is useful for, then I think its use should be discouraged.

Please also read:

• Leonie's article on section elements
• my comment in the previous issue
• the HTML spec for section, which says that "Each section should be identified, typically by including a heading (h1-h6 element) as a child of the section element."

[joanmarie]

The following comments were placed in https://github.com/w3c/aria/issues/696. In order to ensure that role-parity issues stay focused on role-parity, and ARIA issues stay focused what is specific to ARIA, I am moving them here as the closest, open issue.

@carmacleod said:

Question about section (with accessible name): region:

Does accessible name include (or will it ever include) the first heading child (h1 - h6 or even h), even without an explicit aria-labelledby pointing to that child?

@mcking65 responded:

carmacleod commented:

Question about section (with accessible name): region:

Does accessible name include (or will it ever include) the first heading child (h1 - h6 or even h), even without an explicit aria-labelledby pointing to that child?

While I understand the appeal, I would not support it.

1. Browsers should not guess at author intentions with respect to content. Semantics should be explicit.
2. I do not think it would be good to make such a feature an explicit part of the HTML spec; it would be unnecessarily limiting for authors.
3. In current content, It would create lots of regions where regions should not exist; not every section should be a region, even if that section contains a heading.

@carmacleod said:

Agree completely, @mcking65.

I was asking because I hoped the answer was "no". :) After mulling over what you said in https://github.com/w3c/aria-practices/issues/562, I finally "get it":

• Outlines are for the information architecture of the page, aka "the content".
• Landmarks are a convenient way to skip around the "structure" of the page.
• Sections with headings go in the Outline.
• Sections with aria-label or aria-labelledby are Landmarks.
• Landmarks don't belong in the Outline unless they have a heading child with aria-labelledby="id-of-heading-child".
• Landmark navigation and Outline navigation are completely separate concepts, and they always will be, even if "the broken outline algorithm" is fixed some day.

So I think we should explicitly state that the accessible name for a section element can only be defined by aria-label or aria-labelledby. (i.e. Don't leave it open to interpretation).

Further, we should make it explicitly clear that a heading child that is not referred to by aria-labelledby does not, and will never, define an accessible name for a section element. This means that a heading child cannot by itself change the semantics of a section from "thing that belongs in an outline" to "landmark region". Only aria-label or aria-labelledby can do that.

I think that if we make this abundantly clear in all specs, then the world can move forward on the outline vs landmarks stalemate.

The following are sources of confusion that need clarification: 1) The HTML spec says that region is the default role for section, however it does not say that: 2) Setting role="region" on an element does not make it a [landmark] region unless it has an aria-label or aria-labelledby. 3) The HTML spec for section has other statements that could also be misleading, such as:

• "Each section should be identified, typically by including a heading (h1-h6 element) as a child of the section element." ("identifying" could be mistaken for "giving an accessible name")
• "A general rule is that the section element is appropriate only if the element’s contents would be listed explicitly in the document’s outline." (... it's not "only" for outlines... it's also for defining a landmark if it has an accessible name)
• "For example the role of the element, which in this case is "region", can be announced by screen reader software when a user navigates to an section element." (.. not if it doesn't have a name...)
• "When an element is needed only for styling purposes or as a convenience for scripting, authors are encouraged to use the div element instead." (this note needs to have stronger words, like using section without either a heading or an accessible name is an author error)

Hopefully we can help tighten all of these statements up.

(Sorry to dump this all in a "Role Parity" issue. I can create a new issue if this is off topic. I just wanted to have the discussion here, so that I can create a pull request for the HTML spec clarifications.)

[carmacleod]

Thank-you, @joanmarie !

[mcking65]

@carmacleod, very, very well said!!

In addition to cleaning up specs, it seems that guidance on this should be part of the APG. Should I change this issue into the to-do for drafting that guidance?

[carmacleod]

Yes, please, @mcking65 ! This issue is all about bringing clarity to the relationship between section element, region role, landmarks, outlines, and headings. The APG is probably the best place to start, and then we need to make sure that the clarity is propagated to "all the places". The HTML spec is particularly unclear on this. One point to consider is how AT should handle a section or region that has an aria-labelledby pointing to a heading child. This situation is kind of a cross-over where the section would be a landmark, and it would be in the outline, which leads to problems like this NVDA issue that I opened. Thanks, Matt!

[carmacleod]

I've been pondering the one sticking point, which is that a section element with aria-labelledby pointing to a heading will end up being in both the outline and the list of landmarks.

To walk through how common this problem would be, please imagine the following scenario:

• An author decides that they want to define a landmark region in order to allow users to easily navigate to a particular region of the page.
• They do not want the region to be in the outline, because the region is not related to the information architecture of the page; it is a part of the structure of the page.
• They decide to choose the HTML section element to contain the region, because, after all, region is the default role for section elements.
• They want to have a visible label at the top of the region, in order to name the region, and to briefly explain the purpose of the region.
• They decide to use a heading element to contain the visible label, because, after all, that is what headings are for.
• They read the ARIA spec for region role, and learn that they need to use aria-labelledby to point to the id of their heading, and so this is what they do.

At this point, they have a well-defined region. Unfortunately, they also have a well-defined section that will most definitely show up in the outline, which is not what they intended. This is the sticking point that I keep coming back to, and it is the reason, I think, for a lot of the confusion around sections, regions, headings, and outlines.

I can think of 2 possible ways out of this conundrum.

The first is to specify that if a section element has an (aria-label or) aria-labelledby attribute, then it MUST NOT show up in the outline. There are a couple of reasons why I don't like this idea:

• It's too convoluted. It's like saying, "If this AND that, BUT NOT that, then it's one thing, and not the other".
• More importantly, it means that sections with headings can't have an accessible name, at least, not without some other convoluted spec wording.

The other way to clear up things immensely is to create a new role. Let's call it "outline", and let's make "outline" be the default role for section elements, instead of "region". If we do this, then I think the author's intent can be completely clear:

• If they are creating a piece of content that they want to go in the outline, they simply use a section element, give it a heading, and into the outline it goes.
• If they are creating an area of the page that they want to be a landmark region, they use a section element with role="region", give it a heading, and it's a landmark.

One other beautiful result of creating a new "outline" role is that the first heading child of a section can be a part of the accessible name calculation for the section, whether it has role="outline" or role="region". This would work because the semantics for each section element would be crystal clear without needing to use the aria-label or aria-labelledby attribute as part of the role.

Of course, the obvious down side is that it's not backward compatible. Anyone who relied on section-with-accessible-label=region would need to go back and add role="region" to their sections in order to get their landmark regions back. I would argue that the current spec is so convoluted that authors aren't always getting what they expect anyhow.

Another complication is... which elements would we allow role="outline" on? Section, obviously (default - do not set). But what about div? span? Maybe. This could complicate the already-complicated rethink of the outline algorithm. However, taking region landmarks out of the outline may also simplify the outline algorithm, at least from the point of view of AT.

@mcking65, what do you think? @joanmarie, I'd love to have your take on this as well.

[carmacleod]

Happened to notice a trend in the WebAIM Screen Reader User Survey results: the use of landmark navigation is decreasing.

• Survey 5: 44% of users always or often navigate by landmarks
• Survey 6: 39% of users always or often navigate by landmarks
• Survey 7: 31% of users always or often navigate by landmarks
• Survey 8: 27% of users always or often navigate by landmarks

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.

In Survey 5, an additional question was asked: how many landmarks is optimal? The typical answer was 4 - 6. This was before the introduction of html5 section elements and the region role. My best guess for today would be that the optimal number would be 4 - 8 (header, nav, main, footer, maybe a search, maybe an aside or two, or a region or two, maybe another nav, or a form).

I don't see this "rule of thumb" for the number of landmarks actually mentioned anywhere in the specs (HTML spec, ARIA spec, APG). There's no indication that having too many landmarks can effectively render them useless to the users who could benefit from them.

We should at least add a note to that effect in the landmarks section of the APG, and maybe even repeat it in the section on region landmark.

Edit: Number and type of landmarks on some popular home pages:

• Google: 1 (search)
• YouTube: 4 (banner with search, main, nav)
• Facebook sign up page: 2 (main, contentinfo - they should add the form)
• Wikipedia: 13 (main, search, banner, contentinfo, plus 9 navs - wow!)
• Reddit: 3 (banner, search, main)
• Yahoo!: 6 (2 (unlabelled) navs, main, and complimentary with a contentinfo that is incorrectly declared twice)
• Amazon: 7 (banner with nav with search, main with complimentary, another complimentary, and a nav that should be a contentinfo)
• Twitter: 4 (nav, search, complimentary, main)
• Instagram: 3 (main, contentinfo with nav)
• LinkedIn sign up page: 1 (main)
• Wordpress sign up page: 7 (banner with nav, and a contentinfo with 4 unlabelled navs)
• Pinterest: 2 (search, main)
• Apple: 6 (nav with search, main, contentinfo with "Footnotes" region and nav)
• Microsoft: 11 (banner with nav, main, 4 "Slideshow" regions with horribly long labels, a "Social media links" region that should be a nav, and a contentinfo containing a nav and another contentinfo)
• Vimeo: 10 (banner with search and nav, another banner? that seems to be offscreen, 4 unlabelled complimentary regions, and a contentinfo with another unlabelled complimentary)
• Flickr: 6 (nav with search, nav, main with a contentinfo that is incorrectly declared twice and should not be contained in main)
• NYTimes: 7 (banner with nav, main, nav, and a contentinfo with 2 navs. None of the navs are labelled)
• BBC: 7 (banner with nav and search, main, complimentary with nav, contentinfo)
• USA.gov: 7 (banner with inner banner, nav, and search, main, contentinfo with nav)
• Canada.ca: 7 (banner with search and nav, main, contentinfo with 2 unlabelled navs)
• gov.uk: 7 (banner, main with search and 3 labelled regions, contentinfo)

[carmacleod]

I suppose that a third way out of the conundrum mentioned previously is to simply not care if some landmarks end up in the outline.

For example, as things currently stand, the following landmark will end up in the outline:

<section aria-labelledby="foo">
  <h2 id="foo">Foo</h2>
  Foo section content
</section>

And the following landmark won't be in the outline (at least, I don't think so, because it doesn't have a heading, although the outline algorithm seems to be getting a complete rewrite, so I'm not sure):

<section aria-label="Bar">
  Bar section content
</section>

And maybe that's ok? @mcking65 What do you think? (Although maybe we should wait until the outline algorithm thing gets ironed out).

[carmacleod]

Just a heads-up that the proposed whatwg outline algorithm rewrite advises against having a section element without a heading. The following quote is from the section about the section element:

Note: The section element is not a generic container element. When an element is needed only for styling purposes or as a convenience for scripting, authors are encouraged to use the div element instead. A general rule is that the section element is appropriate when used in conjunction with a heading.

And the following quote is from the almost completely rewritten section on Headings and Sections:

Authors are encouraged to avoid a sectioning content element section without a heading descendant whose nearest ancestor sectioning content element is not section.

(That sentence is a real doozy - I've asked them to simplify it - but I believe it is trying to say "no sections without headings).

Another heads-up: they are going back to trying to make <h1> headings work properly inside <section> elements. So, as far as I can tell, the algorithm is supposed to tell the browsers to "do the right thing" when calculating section heading levels. If they get it right, it will be a good thing, because it would let chunks of content move around and magically get the correct heading levels.

[carmacleod]

Interesting. The HTML-AAM mapping for a section element without an accessible name has been changed to be the same as div. See https://github.com/w3c/html-aam/issues/79 for background.

This doesn't really affect the scenario in https://github.com/w3c/aria-practices/issues/575#issuecomment-368170052, which is summarized as:

• author wants a labelled region landmark
• decides to use section element with a heading child
• points to the heading with aria-labelledby

The above still defines both a landmark region (because the section element has an accessible label), and an outline section (because of the heading). I don't know whether that matters. We'll probably have to wait and see whether the outline algorithm mess is ever cleaned up. The only way to remove sections from the outline would be to explicitly prune any that have an accessible label, but I don't think that's currently on the table. I don't know what authors' or users' expectations would be in this case.

[carmacleod]

Noticed that the APG example code for region landmark includes the following HTML Technique:

<section aria-labelledby="region1">
    <h2 id="region1">title for region area 1</h2>
    ... content for region area 1 ...
</section>

Perhaps this should be rewritten to use a span for the region's name, and not an h2? Or, it should clearly state that if the author points to an h2 for the region's label, then they are defining a landmark that must be included in the page outline (which may be a bit weird?). Authors also need to know that such "double-duty" regions will very likely have both the landmark name and the heading name announced by screen readers. In addition, "double-duty" regions can be navigated to by both landmark navigation and heading navigation methods.

[JAWS-test]

Perhaps this should be rewritten to use a span for the region's name, and not an h2?

I think that is wrong for a number of reasons:

• if a heading is marked with span, this is a violation of WCAG SC 1.3.1
• double output is not avoided with span. To achieve this, the heading would have to be marked aria-hidden=true.
• the problem occurs not only at section, but at all landmarks labeled like this
• headings are more important than landmarks or sections, because headings are the primary navigation method
• Double output is better than missing output
• To avoid this problem, I would rather suggest not to label all content that has headings with landmarks and section, or not to label the landmarks if they are unique (like <main> or <footer>). For page areas without headings, landmarks and regions should be used (and labeled according to specification, if necessary).

I would also close the NVDA ticket as I think that NVDA outputs the example correctly.