Heading mark-up in notes

[marcoscaceres]

This was originally filed on ReSpec by @aardrian... but I feel we need to have a larger discussion.

The following is a copy/paste from @aardrian's bug linked to above.

Description of problem

It is common practice for developers to view-source on pages for guidance on how patterns are coded, or just to take code as-is for their own use. There is HTML in the WAI-ARIA Authoring Practices 1.1 that I feel should be adjusted to better follow the principles of ARIA and best practices.

The headings in the Notes throughout the document are not coded with <h#>, but instead rely on ARIA attributes to convey their structure. Eg:

<div class="note">
 <div role="heading" class="note-title marker" id="h-note-10" aria-level="6">
  <span>Note</span>
 </div>
 […]
</div>

A screen shot showing an example of a note on the page.

While this does not go against 2.1 No ARIA is better than Bad ARIA as outlined in this document (because it is not incorrect), it is counter to 2.1 First Rule of ARIA Use. In particular, I do not believe "visual design constraints rule out the use of a particular native element" in this case.

Suggest replacing each of the <div>-as-heading instances with the following, as appropriate for the heading level:

<h4 class="note-title marker">Note</h4>
<h5 class="note-title marker">Note</h5>
<h6 class="note-title marker">Note</h6>

The following CSS will allow the headings to look the same as the current <div>-as-heading instances:

.note h4, .note h5, .note h6 {
    margin: 0;
    padding-right: 1em; /* or make div.note-title not specific to div */
    min-width: 7.5em; /* or make div.note-title not specific to div */
    font-weight: normal; /* for the h4 */
    font-style: normal; /* for the h5 */
}

Note: this is carried over from github.com/w3c/aria-practices/issues/761.

cc @awkawk

[marcoscaceres]

From the ReSpec side, I personally don't have a strong opinion - and would be happy to follow the ARIA best practices here if it's appropriate. It might require some modifications to base.css or related style sheets. Super interested in @fantasai's and @tabatkins take on this.

[awkawk]

It seems that the aria used here would be what I would expect if we weren't able to modify some existing markup that needs to express a heading, but since we can write it using the native semantic element, I agree that it is desirable. @jnurthen will likely agree.

[marcoscaceres]

For more context, the current guidance around "boxes" (notes, issues, etc.) is here: https://w3c.github.io/tr-design/src/readme.html#boxes

[awkawk]

Both the note and example guidance should indicate that the "Note" and "example" text needs appropriate level heading treatment.

[fantasai]

Looks like neither ReSpec nor Bikeshed is following the expected markup convention for the box label in https://www.w3.org/StyleSheets/TR/2016/readme.html#note :/

We don't insert a heading into notes because they are most often paragraph-level insertions, and are not followed by another heading but by the rest of the prose of the section. Putting a heading at the beginning of the note would make it seem like any text following the note belongs to the note, which it does not.

It would probably make sense if ReSpec and Bikeshed generated ASIDE instead of DIV for notes and issues, fwiw. This would make it clearer to AT where they start and end.

[tabatkins]

I'm happy to have Bikeshed generate whatever markup is determined to be best.

That won't necessarily affect anyone manually creating a class=note element, of course, but as long as you're doing Bikeshed-style Note: foo paragraphs, I can generate whatever.