Suggest adding a warning about outline algorithm

[stevefaulkner]

Currently the HTML standard does not provide any advice in regards to the outline algorithm not being implemented, This has lead to some developers believing that the outline algorithm has an effect in browsers and assitive technology which it does not. THis can lead to developers using markup patterns that don't convey document structure. Suggest adding a warning, for example this is the warning in the W3C HTML spec

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 algorithm cannot be relied upon to convey document structure to users. Authors are advised to use heading rank (h1-h6) to convey document structure.

[domenic]

I kind of feel we should either leave as-is or just remove the outline algorithm altogether...

[gsnedders]

An outline algorithm probably makes sense to keep around, given outlining is used in some sense in most screenreaders, as far as I'm aware. That said, may well make sense to drop the current one (and the semantics that go along with it...).

[Hixie]

The algorithm just describes the semantics of the elements. If the tools aren't supporting the semantics, they're buggy and should be fixed. Changing the semantics would be a pretty drastic change to the spec, especially as people have been using these elements for years.

We can't just remove the outline algorithm, either. We need something to define the semantics of these elements. Even if we were to say that tools should ignore the semantics and just use the h1-h6 elements in the naive flat way (ignoring tree structure, as if we were back in the 90s), you'd still need the algorithm to be able to define the authoring conformance criteria (so that conforming documents only used h1-h6 in a manner consistent with the semantics). That's pretty silly though. The right solution is just to fix the tools.

[domenic]

@Hixie, when you say "tools," do you include user agents and their accessibility bindings?

At some point we cannot claim that user agents are broken. They are instead rejecting our change request. https://www.w3.org/Bugs/Public/show_bug.cgi?id=25003 contains comments from both Firefox and Chrome accessibility developers explicitly rejecting the idea of implementing the outline algorithm in their accessibility bindings. It also outlines the history of JAWS removing their support. Although their reasoning may be wrong, it doesn't seem fruitful at this point to challenge them.

I think it would be better for the semantics in the spec to match the semantics already exposed through accessibility bindings in implementations. People have been using these elements for years, but either (a) they have been using them in a way supported by user agents, which contradicts the spec; or (b) they have been using them in the way specified, which means their content is broken in current user agents (for users which count on those accessibility bindings). Neither of these seem good.

[domenic]

My last message wasn't entirely clear. I agree with @gsnedders and phrasing this as "removing the outline algorithm" was incorrect. Rather, we should update the outline algorithm to reflect implementations. In some ways this is a "revert" of the "change request" that proposed a sectioning-based outline algorithm; it differs only in degree from https://github.com/whatwg/html/commit/a4313d39a35d94fcf0e660a0a86241233dafd142, which was a revert of the change request https://github.com/whatwg/html/commit/78f1994463a1f19685ea2ca5beb335ca2a91ca14 to simplify selector case-sensitivity matching rules.

[Hixie]

If we want to require that authors use h1-h6 instead of being able to do the XHTML-style <h1>-everywhere, then we need two outline algorithms: one that describes how user agents are to act, and one that describes the restrictions that authors have to follow in order for their h1-h6 headers to not contradict the sectioning semantics. (And maybe a third one, that describes how an authoring tool could convert from the saner one-heading-element style to the legacy h1-h6 style for UAs.)

But IMHO that's a poor place to be in. I don't really see why accessibility tools couldn't expose the real semantics here. It doesn't require a complex algorithm (you only need "previous", "next", and "up" to be able to navigate the tree, and walking around the tree that way is pretty straight-forward as far as I can tell). Accessibility tools are notoriously slow about catching up to implementing new features, this algorithm is not that old by their time scales. (I mean, they still haven't implemented stuff from the 90s correctly, even though there's obvious usability gains to be had by doing so.)

[domenic]

Can you explain why you need two outline algorithms? Authors would use the sectioning elements the same way they are exposed in accessibility technologies: just like divs.

[gsnedders]

That ignores that fact that both Firefox and Chrome have explicitly refused to support it, and that algorithm is hella old by their standards (it's what, seven years old now?). I think the battle's lost at this point, sadly. I don't have strong opinions on what we should do, but the spec as it stands now is fiction and will remain fiction. Your argument that they should implement it because they're buggy per spec is trying to oblige behaviour by spec, and we know that's a fallacy when everyone is refusing to implement it.

[Hixie]

@domenic Consider the following:

<h1>A</h1>
<section>
 <p>aaa
 <h1>B</h1>
 <p>bbb
</section>
<p>bbb

What are the sections in that document? If the <section> element doesn't align with that answer, then what are the semantics of <section>?

@gsnedders I don't think the battle's been fought. Any time I've seen people say they don't want to do it (e.g. in the bug above) the reasons they've given don't actually fit the facts (e.g. I've heard complaints that it would be prohibitively expensive, but that's only if you recomputed the entire tree, which as far as I can tell is unnecessary). But in any case in my comment above I gave two paths: one that I think is the right path, and another path for the case where we give up on making accessibility tools give good results. We could go down the second path, certainly. It's not just removing text from the spec, though, as I described above.

[domenic]

My understanding is that as implemented section has no semantics, just like div. I am not sure that implementations have a concept of "sections of a document" as much as they have an accessibility tree plus an outline tree which consists of links into nodes in the accessibility tree. But I am not sure on that; presumably @SteveFaulkner has done the research there.

[Hixie]

I'm not sure what it would mean for <section> to have "implemented" semantics. Semantics by their very nature are about the meaning of the elements, which is something for humans. It's how you get maintainable documents that different people who have never met can approach and understand.

[annevk]

Yeah, I guess either you keep the current outline algorithm, or you obsolete <section>/<h1> & <hgroup>?

[domenic]

Is the idea to keep the current outline algorithm but the output of the algorithm is only something that exists in authors' minds? If so I'd be fine moving it to some section with a preface like "If you want to assemble a mental outline, that does not match that displayed by screen readers, follow the following algorithm: ... NOTE: authors are advised not to author documents that produce outlines catering to this algorithm, but instead author documents catering to accessibility tools, which follow the algorithm in $cross-link-here, according to the priority of constituencies (users over authors)"

But that seems kind of pointless.

[annevk]

It all depends on whether user agents will implement these elements. If they don't, we should scrap them and the outline algorithm can be simplified to what is supported. If they do, or we expect them to within the next five years or so, it might be worth waiting a little longer.

[domenic]

Hmm, to be clear, what does "implement these elements" mean? They implement them as HTMLElement instead of HTMLUnknownElement, but they do not implement the accessibility mapping implied by the current outline algorithm, and as discussed up-thread at least a couple have publicly stated they are not planning to do so. (Are those the only two relevant requirements on implementations, or am I missing some?)

[annevk]

There are some styling and parser requirements too. And there are some speculative CSS features that would build upon the outline algorithm. We would have to check. But styling and outline would be the most important aspects.

[domenic]

Ah right, thanks for pointing those out.

Also, when you say "obsolete <section> etc.", we could give them "the <main> treatment" instead of "the <dir> treatment". I'm not sure there's any practical difference besides what section they go in, but it's worth pointing out.

[annevk]

Perhaps it would end up like main since it still has some default ARIA semantics that might be useful. Not sure. I haven't studied this in detail, but I do agree with @Hixie that the fix isn't as simple as adding a note to the outline algorithm or dropping it altogether.

[stevefaulkner]

@domenic section is mapped to a region role in browsers, section is not exposed in the aural UI unless it has an accessible name.

There are 2 document scope navigation methods implemented across AT:

• landmark navigation of header/footer/nav/main/form/section(only if accessible name present) elements.
• heading navigation via h1-h6 elements.

Implementation of accessibility layer semantics for html element landmarks and h1-h6 is complete in chrome, firefox, Safari

Data on the utilisation of each can be found in webaim screen reader surveys

[stevefaulkner]

The reason for the warning is so authors are not mislead into thinking that use of sectioning elements actually does anything for users who consume heading semantics to make sense of and navigate document content.

[JohnnyWalkerDigital]

Adding a similar warning makes most sense, IMO, at least until the Outline Algorithm starts being more adopted. Many authors most likely think that (correctly) placing a <h1> element both inside and outside an <article> will be understood by those using assistive technology.

[alastc]

I do quite a bit of accessibility training and regularly come across developers who think they should just use H1s (they don't always know about sectioning either). I agree that it would be more elegant to use sectioning, but unless someone is going to campaign for UAs to implement it, then the spec should align with the reality.

[JohnnyWalkerDigital]

I would love to help campaign UAs to use it. It would make everyone's lives (developers and users) if they did.

[nhoizey]

Has a web developer, I also would be really happy if the outline worked as intended with sectioning elements, at last.

Working with only h1 is much easier when you want to include (server-side or with Ajax) the same HTML fragment in several places of your pages, with appropriate hierarchy.

[domenic]

Some Twitter discussion reminded me about this neglected issue. I wanted to summarize the action items here:

• We are not interested in simply adding a warning like the W3C fork does. "Warning: ignore the following. Here is a bunch of normative text about outlines..." We have higher standards for our specs than that kind of self-contradictory patchwork. Instead, we should actually update the spec to reflect reality.
• The outline algorithm should be rewritten or replaced to reflect @stevefaulkner's description of implemented AT mechanisms in https://github.com/whatwg/html/issues/83#issuecomment-137051768. Namely, it should primarily inform about landmark navigation and heading navigation. (Or maybe only the latter of these?)
  • Maybe these are already specced somewhere we should be referring to?
  • It should reflected implemented heading level semantics as announced by screen-readers, not the ones derived from nesting level.
  • We should do some serious hands-on testing with a11y tools (or we could continue to lean on a11y experts to do so for us, but that is not very good) to figure out how to best phrase these things. For example it's not entirely clear to me whether headings are presented as a nested list, or as a flat list with heading level numbers. We should encourage authors to have a mental model that matches what's implemented.
• With these in mind, we should carefully change the authoring guidance and semantics for related elements (article, section, nav, aside, h1-h6, hgroup, header, footer). In general I think we can keep the "spirit" of existing semantics, e.g. nothing needs to change about what a section "is". But the advice about how to use it relative to headings, or how to use markup patterns that give it an accessible name, and how that impacts the document outline, will need to be carefully reviewed.
  • One exception may be hgroup. But maybe we should leave it as-is for the first pass.

Potential future work:

• Consider the fate of hgroup further. Does it impact a11y processing anywhere? Should it be repurposed, or obsoleted, or...? Does it have semantics independent of its a11y processing, like non-accessible-name'd sections could be said to?
• Propose a <h> element that actually gets treated like people want <h1> to be treated. (If we can get the a11y teams of various browsers to implement, then we can merge it into the spec. But let's not add something until we have experimental implementations and commitments.)

---

All that said, this isn't that high on my priority list, or my employer's. If someone does have the time to devote to this, I'd be happy to help review patches.

[stevefaulkner]

"Warning: ignore the following. Here is a bunch of normative text about outlines..."

While there is normative requirement for UAs to implement the outline algorithm, many web developers have been lead to believe it is implemented, the whatwg spec continues to perpetrate the myth. However you choose to modify the spec to bring it closer to reality will be an improvement.

[sideshowbarker]

I agree with much of the comments fro @Hixie and @annevk in this thread, especially the comment from @Hixie that “We can't just remove the outline algorithm” without needing to make other changes as a consequence, and the question “Yeah, I guess either you keep the current outline algorithm, or you obsolete <section>/<h1> & <hgroup>?”.

But all that said, I have over the years learned a huge amount of things from @stevefaulkner around the problems that some things in the spec cause for AT users, and I think others should read his comments here very carefully. We’re here to solve existing real problems for real users—not to hypothetically solve problems for some of them if we could somehow just get browser implementors to see things our way and implement what we’ve specced, or get AT vendors to fix their horribly broken/buggy tools.

In that spirit I agree very strongly with the implicit goals in the latest comment that @domenic posted and with his concrete suggestions there about how to get progress here. See the related IRC discussion.

Some ways I could help with this might be:

• Experimentally implementing a Show Outline feature in the Nu HTML Checker that shows a “Here’s what the outline of your document looks like to AT users in practice” view—in parallel to or even in place of the current Show Outline view the checker provides, which shows what the outline looks like according to the outline algorithm in the HTML spec.
• Adding further experimental warnings to help authors avoid using H1-H6 headings in any way bad for AT users; basically that amounts to uses of H1-H6 in ways different from how we told authors they should use them before we added section and article and allowed nested H1s to be used within them, and allowed uses of H2-H6 that break the existing simple hierarchical use of them.

As far as the second item above, I have already implemented experimental support in the checker for reporting (mis)use of H1 as anything other than a top-level head, and that’s been deployed in the checker for quite a long time now, and I think it’s been helping. But I’d like to help more if I can. I want to make the HTML checker be a tool that helps developers avoid making uninformed authoring choices that are going to cause problems in practice for real users.

[stevefaulkner]

We should do some serious hands-on testing with a11y tools (or we could continue to lean on a11y experts to do so for us, but that is not very good)

Unclear what you mean here, who is the 'we'? Are people such as myself who have some knowledge about accessibility implementations in browsers and assistive tech and who contribute to HTML not part of the group considered to be 'we'?

It strikes me as counter productive "not very good" not to embrace the knowledge and input of the wider web standards community.

[domenic]

I meant the spec editors should actually do the testing themselves, instead of always leaning on people like you to do it for us :). It seems irresponsible of us to always be speculating about a11y tool behavior until you or someone else comes into the thread to set us straight. Not that it isn't appreciated! It just shouldn't be necessary.

[stevefaulkner]

Hi Domenic, thanks for clarifying, it's difficult to know sometimes when 'we' is used, who it is referring to.

While I encourage the editors to become more familiar with AT, I warn against drawing conclusions based on a single AT and limited understanding. I also suggest not to make decisions about AT interaction behaviour, and what is 'good' for users, without consulting users and understanding the constraints of AT. It is relatively easy to test the technical accessibility implementation aspects in browsers, it is more complicated with AT. Recent tests I carried out on one small aspect of HTML links , may be helpful reading http://thepaciellogroup.github.io/AT-browser-tests/acc-name-test/a-href.html

Related articles by James Teh (a Screen Reader implementer and user)

http://blog.jantrid.net/2015/12/woe-aria-surprisingly-but-ridiculously.html?m=1

http://blog.jantrid.net/2015/12/woe-aria-aria-describedby-to-report-or.html?m=1

[stevefaulkner]

@sideshowbarker wrote:

Experimentally implementing a Show Outline feature in the Nu HTML Checker that shows a “Here’s what the outline of your document looks like to AT users in practice” view—in parallel to or even in place of the current Show Outline view the checker provides, which shows what the outline looks like according to the outline algorithm in the HTML spec.

It is now in the validator: example https://validator.w3.org/nu/?showoutline=yes&doc=http%3A%2F%2Fapple.com#headingoutline

[fititnt]

Much of my work involves working with sites like CMSs that part of the content is supplied by the user or third-party extensions. The document outline, and the sectioning logic was perfect.

The HTML 5.0 brought many features. So many people were more concerned with how the tag video worked than semantics. Just don't give up. Headings navigation is very important to assistive technologies. And can be even for standard users.

It's not hard to do creative uses, how to use devices without screen, or even a phone via voice commands to know what's on a website. I can find people to do something like that in 2017 to allow ordinary developers or even customers to test they site "on the phone", with a friendly voice.

If the developers can't test with AT, this at some point can be just a marketing thing that someone will sell with buzzwords like IoT and people using Raspberry PIs programmed with JavaScript with just voice can access e-commerce and a buy a product. And at some, after these proof of concept, we can have like cars with voice commands, 3rd apps or even by default apps on cellphones that at the end are just one AT with a soft voice that can buy a a product in sites using default Magento template.

Someone at some point can just create a icon with buzzwords like "Site IoT Ready" or "Compatible with voice commands" and make ARIA great again by calling a different name.

[fititnt]

I feel that most of you are disappointed because you have not been heard by everyone. These changes were a little large, and depended on different people accept at the same time.

It's like everyone expects other people to accept first. And you don't have time to insist, because you're too busy. But I can find people who have the patience to go after it.

What I and some friends we can help here

• It the problem is browsers to implement, change the browsers, not the documentation
• If browser vendors do not do it, it's simple, I and some friends created extensions for all of them, and we started a campaign to say that they don't know how to do it right
• About Assistive Technologies needs change, ok too. For all that are Open Source, at least for Python, I find someone help us here. JAWS will need a few emails, explanation and help with testing, but we can do it
• I can help to force the changes on CMS. I'm a Joomla guy for almost 10 years, and I can find people from Wordpress and Drupal. We are talking here about 60% of entire internet

What we need in return

• You here to decide the best path, explain it, and be consistent (think that for CMSs there's no guarantee h1-h6, that HTML 5.0 document outline was good)
• If need, ensure that the official Validators do not accuse validation error for those who follow this rule immediately (i.e. do not wait years for HTML 5.X)
• At least for open source software CMSs, LMSs etc, ensure that if they accept help to change default templates, and my friends submit improvements, you here will test and give feedback before it was released for the public.

---

You here can decide the best path, assuming that ATs, web developers and browsers (with extensions) will follow after just 6 months. If the best way is to implement the outline as already described, say that. If it involves creating new element, say that too. But lets decide what is best, theoretically speaking.

No problem if this decision just break something, just can't break more than it already is broken.

A very good date to have a plan would be before Google Summer of Code 2017. I was mentor twice. If there is sufficient awareness here, I believe I can convince even more people than just the folks from Joomla, Wordpress and Drupal. Each organization can have at least a almost full time student just for implement this feature, who will also make documentation on how to use it for extension developers of these CMSs.

I spoke of CMSs, but maybe I can try to contact all organizations today keeps open source screen reader and try to help them be a part of the GSoC program with the condition that they accept what you set here.

[annevk]

Here’s a proposal that I’d like to pursue if there’s interest from @whatwg/a11y and implementers. If we cannot get agreement I’ll work on defining the status quo and aligning the HTML Standard with that, bitter sweet as it may be.

Having read through this issue and its links, the recurring theme is that the existing outline algorithm is too complex to implement. More importantly, it doesn’t match with the UI of assistive technology, which exposes landmarks and headings as distinct concepts. Unfortunately, this feedback was not addressed, which I suspect is why it never took off. However, developers do favor it (also indicated by the comments in this issue).

I think what’s worth pursuing is a variation on what @cookiecrook suggested back in 2014:

• Focus on headings alone and leave landmarks to their own UI.
• h2-h6 always have heading level 2-6, unless their parent is hgroup, in which case hgroup is the heading and h2-h6 are just content.
• h1 and hgroup have heading level 1 + the number of ancestor sectioning content / sectioning root elements. (We include sectioning roots as it seems sensible that a h1 inside a blockquote should have a higher level than the one in the section or article the blockquote is in.)
• hgroup presents itself as a heading (role=heading) and its h1-h6 children as ordinary content (no role, like span).

I wrote a polyfill for this proposal (demo, demo 2. It gives results that seem pretty good in Safari using VoiceOver and I think those results would translate elsewhere given ARIA support being pretty good. If that’s confirmed, it would give a transition path for developers while implementers update the mappings in browsers.

We’d also define an algorithm that finds all the h1-h6 and hgroup elements in a document so they can be presented as an outline. Léonie Watson mentioned such a view existing and it’s also useful for server-side tooling, such as what we use to publish various standards.

In conclusion, this proposal would avoid the massive complexity that the current outline algorithm imposes on computing a heading level as well as it mixing headings and landmarks. Effectively, we replace having to traverse previous siblings and their descendants, than the parent’s previous siblings and their descendants, etc. with counting ancestor elements of a specific type. And as a bonus, this would make the accessibility mapping match the rendering.

Looking forward to your feedback!

[othermaciej]

I like this proposal. I believe it is implementable and would work well. Does the computed heading level in this proposal fully match the rules for choosing heading font size here? https://html.spec.whatwg.org/multipage/rendering.html#sections-and-headings

[LJWatson]

This feels like a good solution. Quick back/packet testing suggests that the polyfill is well supported across current Windows browser/screen reader combinations.

[annevk]

@othermaciej the main difference is https://html.spec.whatwg.org/multipage/sections.html#sectioning-root which this proposal includes, but the rendering section does not (and the rendering section only goes up to level 6). Given it's likely uncommon to have a heading there the difference seems acceptable (in that you can add the necessary styling in such uncommon situations), but might be worth thinking about a bit more.

[othermaciej]

It sounds like there are two differences between the AT-exposed heading level in this proposal and the existing hN rendering rules:

1. This proposal counts total of both sectioning root ancestors and sectioning content ancestors, while rendering only counts sectioning content.
2. This proposal can represent heading levels higher than 6, while the rendering section has no extra styling beyond 6 levels.

On (1), if headers in those spots are rare anyway, it seems better to be consistent between rendering and AT-exposed level.

On (2), that seems like an ok difference. We can model it as the default rendering being the same for levels 6 and up.

I wonder if it's useful to expose the computed heading level to CSS selectors in some way? (Probably out of scope for this change).

[stevefaulkner]

@annevk this looks interesting, a few suggestions: Gather data about nesting of sectioning content that do not have interleaved headings (hint to @sideshowbarker) , for example:

<body>
<h1>An h1</h1>
<section>
<section>
<h1>An h1</h1>
</section>
</section>
</body>

Results in the h1 in the nested sections having a level=3. I surmise that in many cases nesting of this type is not what a developer would have intended, but is the effect of sectioning content on the outline being opaque and therefore not understanding how sectioning elements effect the outline.

Gather data about how hgroup is used. As you may know it was obsoleted in w3c land as it was considered not fit for purpose, that is not to suggest the same necessarily occurs here, but to investigate how it is used in order to better understand if how it is specified reflects usage and how it is best exposed in the accessibility layer, if it is exposed. I see some issues in relation to rolling up all content into one big heading in cases where there is largish amounts of structured content in hgroup.

Look at how role=heading and aria-level are to be factored into the algorithm as they represent an outline to users.

[cookiecrook]

A couple suggestions to consider:

1. Backwards compatibility may be safer to only compute levels if no h2-h6 headings occur on the page. In other words, the presences of one of those elements counts as an explicit opt-out. I acknowledge that there are potential downsides to this edit. For example, if this edit were made, the inclusion of a legacy block of markup (with an h2) may inadvertently cause validly nested heading levels to not be computed. I'm fine with either.

2. A computed (probably readonly) Element.headingLevel property may be useful for authors and for spec testability. This suggestion may be out-of-scope.

I support the proposal as-is regardless if these suggestions are included.

[cookiecrook]

@stevefaulkner wrote:

Look at how role=heading and aria-level are to be factored into the algorithm…

Presence of role=heading (no aria-level specified) or role=heading aria-level=1 could be considered identical to h1 for the algorithm. If h2-h6 ends up opting the page out of automatic level computation, the same should be true for ARIA levels not equal to 1.

[cookiecrook]

Heading levels are exposed in the Mac AX API as any positive integer, so <h1 aria-level="42">foo</h1> for example will cause VoiceOver to speak "heading level 42, foo." VoiceOver braille output will display something like hd lvl 42, foo…

It may be worthwhile to check other platform accessibility APIs (particularly MSAA and UIA) to see if restrictions apply. For example, can you represent a heading level larger than 6 in NVDA? I don't know the answer.

[othermaciej]

I'm not sure role=heading or aria-level needs to play into this algorithm at all. The algorithm provides the presumed default header level for H1s that can then be used by accessibility mapping specs when an explicit aria level is not provided. It makes using all h1 headers with nested section elements do the right thing for AX without adding ARIA markup.

ARIA is not supposed to affect semantics for cases other than accessibility, so I think it would be a layering violation for it to apply at this level (even though it will affect the final result exposed to AT).

Also, there is no giant per-page mode switch. Using a single h2 element will not stop h1s from getting a computed level based on count of section ancestors.

[stevefaulkner]

@othermaciej

I'm not sure role=heading or aria-level needs to play into this algorithm at all.

That may well be the correct view. What we do know is that role=heading and aria-level=x will represent the document in the acc layer regardless of the <Hx> levels. So user agents such as JAWS will expose, potentially a different document outline to users than the one expected/experienced by developers. I suggest that it is worth considering a normative requirement that software such as conformance checkers should provide a representation that includes the document outline as computed with ARIA taken into account, which would reflect AT exposure, as the UI for aural user agent users is a core constituency for consumption of headings semantics.

[annevk]

On data gathering: I think what would be interesting to look at are pages that use more than a single h1 today as they might be impacted by this algorithm. hgroup usage would indeed be interesting as well.

On hgroup: we might want to further revise hgroup such that only the first child would be seen as part of the outline or when skipping through headings (in the polyfill this could be accomplished with aria-labelledby). It seems that's the conclusion from W3C's efforts on subheadings (I haven't taken the time yet to find the deliberation).

On role=heading and the outline algorithm: I'm a little torn on this one. Obviously browsers will expose and include them in their assistive technology interface, but semantically ARIA is supposed to be neutral, I thought. I suspect that means we'll end up with two algorithms. It does seem that the conformance requirements around ARIA and HTML usage need to take this into account as to make sure that assistive technology is not presented with an outline that skips levels.

On falling back when h2-h6 are found: it seems this would be quite expensive, especially with dynamic changes. And given legacy data migration as you mentioned it might actually be quite acceptable to have them there while other parts of a large document are being refactored.

On having an API of sorts to enable testing: I like the idea of having a :heading(level) pseudo-class as suggested by @othermaciej and also @jakearchibald out-of-band. That would also make things easier for developers wanting to style these headings differently so that might make sense to ship at the same time too. (There's precedent for defining new pseudo-classes in the HTML Standard by the way; :defined is a recent addition.)

[alastc]

Possibly an aside, but:

Obviously browsers will expose and include them in their assistive technology interface, but semantically ARIA is supposed to be neutral, I thought. I suspect that means we'll end up with two algorithms.

I think the more common understanding is that ARIA is an over-ride for semantics. That's built in to how it works, applying a role to an element overrides the default element semantics for AT (but not styling, unless you get clever with attribute selectors).

With my developer hat on (rather than accessibility consultant), you'd only use role=heading + level if you couldn't use standard Hx elements, so you'd be over-riding the markup to generate the desired heading levels.

Therefore, it appears there should be one algorithm which takes into account ARIA levels.

[annevk]

@alastc what I mean by neutral is that I don't think, e.g., :heading(level) should end up matching role=heading, just like :link doesn't match role=link. I think that leads to two systems, which from the AT view end up being one.

[alastc]

@annevk I'd rather they did match (so the override works universally), but I assume it's too late for that.

The outline algorythm is more important for this though, where I'd hope we'd have one for simplicity & sanity.

[cookiecrook]

@alastc wrote:

I'd rather [the CSS :heading(level) selector] did match [ARIA headings] (so the override works universally), but I assume it's too late for that.

We looked into doing something similar a few years ago with a :role() selector. Example: *:role(heading) would have been equivalent to h1, h2, h3, h4, h5, h6, *[role^="heading"]

Unfortunately the implementation of :role() was so complicated that it would have required major rewrites of every rendering engine. In WebKit and Blink for example, CSS selection would have become dependent on the accessibility runtime, which is dependent on the render tree, which is dependent upon CSS. Similar circular dependencies existed in other implementations, too. Maybe not impossible, but definitely not worth it.

We could probably shortcut the :heading() selector to work in most cases with ARIA headings, but in order for the heading selector to perfectly include ARIA heading levels, you need to spin up the accessibility runtime to verify the role. E.g. Is role="anotherRole heading" really a heading, or is that just the fallback for anotherRole the runtime knows about? Once you need to verify the role for the :heading() selector to include ARIA headings, you've reached the same implementation complexity as the abandoned role selector.

Given the previous experimentation, I think it's okay for :heading(level) to forego including ARIA headings. If a web author needs that functionality, recommending a dual selector is reasonable: :heading(2), [role="heading"][aria-level="2"] { }

[alastc]

Thanks @cookiecrook, good to know. I missed your messages that came in overnight (for me), scanning back I was essentially agreeing with:

Presence of role=heading (no aria-level specified) or role=heading aria-level=1 could be considered identical to h1 for the algorithm.

To keep it simple for developers, if you need to adjust headings with ARIA it would make sense for the outline to assume they are an over-ride therefore dealt with the same way in the algorithm.

I'd also emphasis @stevefaulkner's point:

I surmise that in many cases nesting of this type is not what a developer would have intended, but is the effect of sectioning content on the outline being opaque and therefore not understanding how sectioning elements effect the outline.

When running training, it is fairly common to come across someone assuming that you can use all H1s, but they don't really understand how the nesting works. It isn't unusual to have over-nested headings (e.g. in an article, which is in a section, which is in another section because sections are better than divs, right?).

Therefore I certainly support the h2-6 aspect of @annevk's proposal above.