Be Wary of doc-subtitle
In early March, Steve Faulkner shared this nugget for making sub-headings:
👉If you want to semantically identify a heading subtitle, look no further than role="doc-subtitle" w3.org/TR/dpub-aria-1.0/#doc-subtitle
#HTML #ARIA #WebDev pic.twitter.com/uaHcVRp6oz
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.
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;
- […]
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:
That's arguable. How many people read eBooks in the browser as opposed to an eBook reader application and/or device?
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:
- Safari on macOS will claim they are all heading level 2 (ignoring
aria-roledescription
), polluting the headings navigation and complicating the perceived page structure; - JAWS with Chrome will also claim they are all heading level 2, polluting the headings navigation and complicating the perceived page structure;
- Internet Explorer users will get no benefit from
doc-subtitle
; - NVDA with Firefox works well;
- VoiceOver on iOS will also claim they are all heading level 2, and offers no context from
aria-roledescription
; - TalkBack with Chrome does not assign a level, but if you nest
doc-subtitle
within a native<h#>
the content will be hidden. - TalkBack with Firefox works well.
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 ofaria-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>
, aclass
, or some other non-structural style hook. Then apply your styles, being careful withdisplay
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):
📢Screen Reader people. What word best describes for you a supplementary heading associated with a numbered (h1 – h6) heading? If "something else" please provide in a reply.
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.
Replace the outline algorithm with one based on heading levels (thanks stevefaulkner!)github.com/whatwg/html/commit/6682bdeee…
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
I think the ideal solution would be to combine
hgroup
anddoc-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 astext/plain
.Tested to work with Orca, NVDA, and VO.
In response to .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 Comment or Response