Consider drafting guidance section on the appropriate use of headings and heading levels

[ZoeBijl]

From @fstorr on December 14, 2015 22:45

In 4.2.7 Providing Navigable Structure within Web Pages, there are recommendations for multiple <h1> elements in a page, which goes against the warning in the HTML 5.1 Headings And Sections spec.

Copied from original issue: w3c/aria#127

[ZoeBijl]

From @AmeliaBR on December 15, 2015 17:15

Can you ( @fstorr or @MichielBijl ) clarify which warning you are referring to? I don't see any conflict.

The ARIA practices guide includes the following suggestion as a way to make it easy for screen reader users to easily find and navigate to all important content:

Make the head of each perceivable region (search bar, stock quote, TV Listing, etc.) an <H1> tag

So long as each of those regions is wrapped in an HTML <article>, <aside>, <section> or similar sectioning element, this is valid HTML 5.

Perhaps the concern is with respect to the following warning in the HTML spec:

h1– h6 elements must not be used to markup subheadings, subtitles, alternative titles and taglines unless intended to be the heading for a new section or subsection.

I am fairly certain that this is only intended to warn against the practice of using double-leveled headings, as would have been coded in HTML 4.1 with an <hgroup>.

In other words, this would be bad HTML, because there are multiple heading elements in places where there is really only one heading/section:

<article>
   <h1>Big news</h1>
   <h2>You'll never believe how big this news is</h2>
   <p>Blah, blah, blah</p>
</article>
<aside>
  <h1 class="section-type">Hot tip</h1>
  <h1>How to know if big news is not so big</h1>
   <p>Blah, blah, blah</p>
</aside>

But the following is OK:

<article>
   <h1>Big news</h1>
   <p class="sub">You'll never believe how big this news is</span></p>
   <p>Blah, blah, blah</p>
</article>
<aside>
  <h1><span class="section-type">Hot tip</span>
      How to know if big news is not so big</h1>
   <p>Blah, blah, blah</p>
</aside>

Each heading introduces a section, albeit in completely separate regions of the document.

[ZoeBijl]

From @stevefaulkner on December 15, 2015 17:23

Hi Amelia, I think it is in reference to this: http://www.w3.org/TR/html5/sections.html#outlines

There are currently no known implementations of the outline algorithm in

graphical browsers or assistive technology user agents, although the algorithm is implemented in other software such as conformance checkers. Therefore the outline http://www.w3.org/TR/html5/sections.html#outline algorithm cannot be relied upon to convey document structure to users. Authors are advised to use heading rank http://www.w3.org/TR/html5/sections.html#rank (h1 http://www.w3.org/TR/html5/sections.html#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements -h6 http://www.w3.org/TR/html5/sections.html#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements) to convey document structure.

so your example should be like this as the headings are not scoped to body:

<article>
   <h2>Big news</h2>
   <p class="sub">You'll never believe how big this news is</span></p>
   <p>Blah, blah, blah</p>
</article>
<aside>
  <h2><span class="section-type">Hot tip</span>
      How to know if big news is not so big</h2>
   <p>Blah, blah, blah</p>
</aside>

Note: the HTML validator warns against use of <h1> in article and section elements

[ZoeBijl]

From @fstorr on December 15, 2015 17:34

Sorry for not being clearer, Amelia. Steve's feedback above is what I was referring to.

[ZoeBijl]

From @AmeliaBR on December 15, 2015 20:45

Thanks for the clarification @stevefaulkner. Didn't scroll far enough to see that warning.

I'm not sure using arbitrary heading levels for equivalent content in different pages is helpful. (Screen reader users are really the only ones navigating by heading type. Would using <h1> for the topmost heading in each independent region be more or less useful than having a single heading hierarchy for the entire page, considering that users cannot actually rely on either model being consistent from one site to another?) But that's another debate that is not directly relevant to @fstorr's issue.

For the original issue:

The mention of multiple <h1> elements is given as an example of a pre-ARIA strategy for making content regions discoverable, rather than as a current recommendation. So the editorial change required would be to add an extra bullet point under "There are number of problems with this approach". E.g. "Users and HTML validation checkers expect a single <h1> heading element on each page which encompasses all page content".

The main recommendation for the authoring practices guide (use clearly defined and labelled landmarks to identify independent content regions) is still the preferred approach, although the text and examples should probably be updated to include the native HTML landmark elements.

But that still leaves the question of whether clear guidance on heading levels should be included somewhere in the guide. Probably in the section on headings and nesting, possibly by linking to existing recommendations for HTML (if such exist). I'll leave that up to those of you who know more about this than I (& stop poking my nose in to topics where I'm not familiar with all the issues!).

[ZoeBijl]

From @stevefaulkner on December 16, 2015 11:9

Hi Amelia, unclear about what you are asserting re heading levels; what encouraging devs to use the correct heading level, for a sectioning elements nesting level, does is attempt to implement the spirit of the un implemnted outline algorithm. The rank of a heading as per the outline algorithm is not based on its numbering its based on its nesting:

<body>
<h1> i am a heading level 1</h1>
<section>
<h1>i am a heading level 2</h1>
<article>
<h1>i am a heading level 3</h1>
</article>
<section>

but as the outline algorithm is not implemented the advice is to use h1 to h6 to represent the nesting structure:

<body>
<h1> i am a heading level 1</h1>
 <section>
 <h2>i am a heading level 2</h2>
   <article>
   <h3>i am a heading level 3</h3>
   </article>
 <section>

further details: https://www.w3.org/wiki/HTML/Usage/Headings/h1only

[ZoeBijl]

From @AmeliaBR on December 16, 2015 19:42

To reformulate @stevefaulkner's examples as a best practice, a potential recommendation is:

"Authors should ensure that heading level that would be calculated using the HTML outline algorithm—based on the nested structure of sectioning elements—matches the heading level defined by the HTML tag name (<h1> to <h6>)."

That seems like a good, forward-focused recommendation. If any browser/AT starts reporting heading levels based on the sectioning rules instead of tag names, the page would still have the same apparent structure to users. But that rule is not clearly stated anywhere. The warning in the HTML spec says that you should use tag names for document structure, but doesn't insist that they match the nesting structure. I'm also not clear how headings defined by role and aria-level would fit in.

A natural extension of this recommendation is that <h1> should never be nested inside HTML sectioning content such as <section>, <article>, or <aside>. It could still be used inside sectioning root content such as <blockquote>, though. If you want to discourage that, you would need a separate guidance.

(I guess part of my mental block was that I logically see an <article>, and to lesser extent <nav> and <aside>, as being equivalent to sectioning root elements that would have their own independent hierarchy. E.g., a blog post title should, in my brain, have the same heading level regardless of whether it is inside the <main> of a single-post page or inside an <article> in a blog index page. But it's a little too late for that argument.)

A separate issue is whether you should only have one <h1> top level headings in a page (e.g., as a direct child of the <body> or <main>). One of the examples from the HTML specs suggests that is OK to have multiple top level headings within the body. So for certain types of landmark regions (those which are not HTML sectioning elements, such as <header>, <main>, and <footer>), you could have <h1> headings for each landmark without causing a conflict with the HTML outline algorithm. Again, if you want to discourage this, it should be clearly stated. If it's OK, then modify the "problems with multiple <h1>" warning accordingly.

Another common recommendation re heading levels is that levels should not be skipped (e.g., don't have <h3> without <h2>). I think that would also be covered by the recommendation to ensure that the outline-algorithm level matches the tag-name level, but I haven't dissected the algorithm carefully enough to be sure.

[mcking65]

The section with the heading guidance was removed by commit eabf6ca5a102af42f876ff4856e92c85b735cecd.

It is not clear that appropriate use of heading levels falls within the scope of the APG. We will not be able to address this in the initial APG 1.1 release that will coincide with ARIA 1.1 PR.

I want to preserve this excellent discussion so we can utilize it if we draft guidance on this topic. So, I am changing the title of the issue and assigning it to the first milestone after ARIA 1.1 PR.