Be Wary of doc-subtitle

In early March, Steve Faulkner shared this nugget for making sub-headings:

On its surface it looks pretty handy. Handy enough that Chris Ferdinandi wrote about it in his July 23 post How to create accessible subtitles. Handy enough that Chris Coyier wrote about it in his August 6 post HTML for Subheadings and Headings.

Neither of these talks about support (first Chris is updating his post) nor where the role comes from (first Chris is updating his post again). So let’s wade into both.

The ARIA

If you really need to convey to screen reader users that your sub-head is a distinct yet related heading, then Steve provided a trick. As a reminder, only screen readers do anything with ARIA. Browsers expose it in the accessibility tree, but no other assistive technology uses it. So this solution is strictly for screen reader users.

The doc-subtitle role comes from the Digital Publishing WAI-ARIA Module 1.0, which has been a recommendation since December 2017 (so it is not a new role).

That spec exists for “long-form” documents, which are essentially ebooks.

This specification is a modular extension of WAI-ARIA designed for the digital publishing industry. The goals of this specification include:

  • Expanding [wai-aria-1.1] to produce structural semantic extensions to accommodate the digital publishing industry.
  • […]

The roles defined in this specification are derived from the EPUB Structural Semantics Vocabulary.

1. Introduction, Digital Publishing WAI-ARIA Module 1.0, W3C Recommendation 14 December 2017

It also has a very specific audience.

  • User agents that process content containing WAI-ARIA and Digital Publishing WAI-ARIA features;
  • Assistive technologies that provide specialized reading experiences to users with disabilities;
  • Authors of digital publications;
  • […]
1.1 Target Audience, Digital Publishing WAI-ARIA Module 1.0, W3C Recommendation 14 December 2017

Some of the other roles defined in the spec are clearly aimed at digital versions of paged media: doc-chapter, doc-pagebreak, doc-pagelist.

This does not mean it is technically invalid or incorrect to use doc-subtitle. However, given its purpose in ebooks, its exposure strictly to screen reader users, its lack of contribution to page semantics, and the potential support issues outside of its intended context, doc-subtitle may not be what you want.

As to whether you should expect screen readers to expose it exactly as you expect when browsing in a web context, I’ll let Léonie comment on that:

Support

Léonie Watson quickly tested the role in March, Steve followed up with his own quick tests the same day and again on August 7.

The doc-subtitle role is exposed as a heading with no level. In ARIA 1.1, a level-less heading defaults to level 2, suggesting what we might hear when we test. Under IAccessible2 (IA2), the xml-roles object attribute exposes doc-subtitle, so a screen reader could differentiate if this came into common use. You can explore the MSAA and IA2 properties in Windows using the Accessibility Viewer (aViewer) from TPG.

In Steve’s demo, he adds aria-roledescription to give readers more insight into what this thing is. While you may recall I have opinions on this attribute, I do make an exception for this case because it genuinely does not exist in HTML.

I made a test page (debug view, embedded below), both with and without aria-roledescription to give some insight into support. The examples for my test page come from the Common Idioms section of the HTML 5.2 document, specifically § 4.13.1. Subheadings, subtitles, alternative titles and taglines.

Skip ahead to the verdict if you want to be spared some of the details.

See the Pen RwaaMgB by Adrian Roselli (@aardrian) on CodePen.

Only the second group has aria-roledescription.

Safari with VoiceOver on macOS 10.15.6 will report every instance of doc-subtitle as a heading level 2, even when nested inside an <h1> (the Ramones example). VoiceOver also ignores all instances of aria-roledescription.

JAWS 20 with Chrome 84 also reports every instance of doc-subtitle as a heading level 2. You can override the announcement with aria-roledescription, but JAWS still treats them as heading level 2 in the headings viewer and if you navigate by either H or 2.

JAWS with IE11 ignores doc-subtitle, except for the Ramones example with aria-roledescription. In the Ramones example JAWS announces the value of aria-roledescription but otherwise does not indicate anything related to headings is there. The nodes with doc-subtitle are not exposed in the headings viewer.

NVDA 2020.2 with Firefox 80 announces each in the first group as a heading, except for the Ramones example (where doc-subtitle is on a <span> inside the <h1>) where it announces as level 1 (this is correct). Where aria-roledescription is used, it announces that value instead, and in the Ramones example it also announces as level 1 (this is still correct).

VoiceOver with Safari on iOS and iPadOS 13.4.1 announces all instances of doc-subtitle as heading level 2, except for the one nested in the Ramones example (it seemingly ignores the doc-subtitle). It also completely ignores all instances of aria-roledescription.

TalkBack with Chrome on Android 10 announces each as a subtitle and can navigate to each of them via heading navigation — except for the Ramones example, where it never finds the nested <span> nor its content. It ignores aria-roledescription completely.

TalkBack with Firefox on Android 10 announces each as a heading (no level) and can navigate to each of them via heading navigation. In the Ramones example if you navigate by heading it reads it twice, once as level 1, once as no level. It ignores aria-roledescription completely.

I did not test VoiceOver on macOS with Firefox or Chrome, Narrator on Windows, Orca on GNOME, or other combinations not listed here. You can do that on your own.

Verdict

In a web (not epub) context:

Broadly, do not put a doc-subtitle inside an <h#>.

What Is Your Goal?

If your goal is genuinely to provide additional context to screen reader users when they encounter a sub-title:
then doc-subtitle and maybe careful use of aria-roledescription could be useful if your audience is only NVDA or TalkBack with Firefox.
If you have some SEO-driven objective (meaning, if you are arguing for using <h#> because search results):
then take a look at alternativeHeadline at Schema.org instead (or some other microdata format).
If you just want it to look different:
consider using the redefined (as of 4 July 2022) <hgroup>, a class, or some other non-structural style hook. Then apply your styles, being careful with display properties that can unintentionally impart meaning owing to browser bugs.
If you are convinced you need something else:
look at § 4.13.1. Subheadings, subtitles, alternative titles and taglines and pull one of those patterns.

Of course, no matter which you choose, test.

Update: 18 August 2020

Steve Faulkner is running an informal poll (go read responses for some useful feedback):

He has opened an issue against JAWS to try to get a better announcement in place: 429: Implement support for role=”doc-subtitle”

Update: 16 July 2022

The Document Outline Algorithm is now gone from the WHATWG HTML specification.

It took 6¾ years from when Steve Faulkner first opened the issue, with the intervening time seeing piles of evidence ignored, the backing of dozens of experts, spec editor gatekeeping, a pull request, and help shepherding it through the WHATWG process, but Steve pulled it off.

If you see any tools, editors, articles, “experts”, etc., pitching the Document Outline Algorithm, remind them they are wrong (and have been).

With it came with an update to <hgroup> as of 4 July 2022. It now only allows a heading and one or more <p> elements. Its exposure to accessibility APIs is no different than a <div>. Browsers need not make any changes since they never supported <hgroup> as anything other than a generic node anyway.

20 July 2022: Steve is Keeping <hgroup> Real

Steve has gathered information about the redefined <hgroup> along with some considerations of actual use and provided us with some guidance:

Do not use h1-h6 to mark up Subheadings, subtitles, alternative titles and taglines in <hgroup>, use <p> elements.

Whether the semantics of the <hgroup> and the specifics of child <p> elements are to be conveyed to users is a decision for the assistive technology developers in consultation with their users. What browsers can and should do is ensure that unambiguous semantics are exposed in the accessibility tree.

It may be worth looking at any internal organization guidance you have and linking to Subheadings, subtitles, alternative titles and taglines in HTML. There will be time for AT to decide if or how it cares to expose this information, especially as the HTML Accessibility API Mappings work through how it should be exposed by browsers.

2 Comments

Reply

I think the ideal solution would be to combine hgroup and doc-subtitle.

Here’s a demo of the hgroup approach. In case your browser doesn’t have “view source” functionality, here’s the same page sent as text/plain.

Tested to work with Orca, NVDA, and VO.

In response to Seirdy. Reply

Seirdy, I am not sure how you expect this to work. When I fire up the demo with NVDA 2022.1 / Firefox 102, I get the following:

heading level 2 A subsection’s title! (h2)
heading level 3 Not personally a fan of subsection subheadings but hey (h3)

If I remove the doc-subtitle, I get this:

heading level 2 A subsection’s title! (h2)
heading level 3 Not personally a fan of subsection subheadings but hey (h3)

If I use JAWS 2022 / Chrome 103, I get this:

heading level 2 A subsection’s title! (h2)
heading level 3 Not personally a fan of subsection subheadings but hey (h3)

If I remove the doc-subtitle, I get this:

heading level 2 A subsection’s title! (h2)
heading level 3 Not personally a fan of subsection subheadings but hey (h3)

There is no difference between the two sets of announcements.

Granted, all this is moot since <hgroup> has been updated as of 4 July 2022 to only allow a heading and one or more <p> elements. Its exposure to accessibility APIs is no different than a <div>.

Leave a Reply to Seirdy Cancel response

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>