Add accessibility role mappings to element definitions

[LJWatson]

The developer's edition of HTML doesn't presently include role mapping information for elements. I think this information is helpful to authors, especially as we get closer to role parity for HTML.

It would be a positive step to add this information to this version of HTML. If there is agreement to do so, I'd be happy to work on it.

[brucelawson]

Happy to help, too. Anything that helps authors make more accessible sites is groovy.

[domenic]

I think this would be great, both in the developer's edition and the normal one. The main issue is keeping it up to date, so it's not just a source of confusion that could at times contradict the normative source in the AAM spec. So we should get this to be auto-generated from the AAM spec via the build process.

Probably the first step, then, is to have some JSON file (or similar simple-to-parse format) with the mappings, hosted and maintained by the AAM spec editor(s) and kept always updated in parallel with AAM. Does that exist yet perhaps? I'm on my phone and haven't checked the AAM spec or its repo yet.

[LJWatson]

I don't think there is a JSON export of the mappings data ATM, but assume one could be created.

[LJWatson]

Worth noting that role conformance for HTML is defined in ARIA in HTML, rather than the HTML AAM (though the AAM is the source of some data within the ARIA in HTML spec).

[domenic]

Hmm, I thought this issue was about accessibility role mappings though, not role conformance?

[LJWatson]

The suggestion is to reference the implicit role for each element, but I think there's a case to be made for also referencing the explicit roles that may be applied.

[domenic]

I see. So this would basically be reversing f619b0c then, right? (With much more up-to-date content, of course; I know @stevefaulkner and others have done a much more conscientious job maintaining that content over the last few years than Hixie did when it lived in HTML pre-2015.)

If that's the proposal then I'd really worry about duplicating the same information in two places which could get out of sync. So if folks have come to believe over the last two years that this is best in HTML instead of in a separate document, then perhaps what we need to do is merge those portions of AAM/ARIA in HTML back into the HTML Standard?

[sideshowbarker]

So this would basically be reversing f619b0c … perhaps what we need to do is merge those portions of AAM/ARIA in HTML back into the HTML Standard?

I don’t think that would be a good idea. There was a strong rationale for moving it out, and I believe that rationale remains as strong as it always has been. I don’t know what problems merging it back in would fix. Keeping the normative text in the ARIA in HTML spec, there’s nothing that prevents also having (repeating) the per-element-ARIA-roles information at point of use in HTML non-normatively (adding meta-language as needed to HTML to make it clear that it’s just referencing ARIA in HTML).

As mentioned in earlier comments, that just comes with the logistical need to make sure the info in the HTML spec stays in sync with what the ARIA in HTML spec has. But that’s doable.

[LJWatson]

<So this would basically be reversing f619b0c then, right?<

AIRC the primary reason for that PR was that the ARIA in HTML spec had been pulled out of the W3C HTML spec into its own module.

<So if folks have come to believe over the last two years that this is best in HTML instead of in a separate document, then perhaps what we need to do is merge those portions of AAM/ARIA in HTML back into the HTML Standard?<

The HTML AAM is one of a set of closely related and co-ordinated specs maintained at W3C. Fragmenting that work makes no sense to me.

Providing information in context to help authors does make sense though.

[domenic]

I guess I'm still unclear on what's being proposed. If not duplicating the information from AAM/ARIA in HTML into the HTML Standard, what is the proposal?

If it is about duplicating the information, then although having everything in one document is helpful for web authors in some cases, it's unclear how much that makes sense if another document is where the work is actually being done. In all other cases we prefer to reference other documents instead of copying their contents into the spec.

[annevk]

I'm somewhat surprised at the pushback against including normative accessibility mappings in the HTML Standard. It seems that just like the APIs for elements and their rendering information, you'd want accessibility mappings to be tightly coupled so accessibility gets considered when these elements get implemented or refactored in implementations.

And furthermore, it would also ensure accessibility gets considered when adding new elements or changing existing elements. Much more so than it is today as today it is easily overlooked, which goes somewhat against the idea that you need to consider accessibility from the get go.

[annevk]

cc @whatwg/a11y

[patrickhlauke]

there's too much politics tied to this, but let me see: am i right in understanding that there's a question here of why there's a pushback to moving AAM/ARIA in HTML over to the WHATWG spec directly? If so, I may just quote something @jakearchibald said to me on twitter yesterday: "why should the work move to a fork?" (https://twitter.com/jaffathecake/status/940513109118251008)

It would be good if the WHATWG spec included all the accessibility mappings etc, but asking for the work which quite nicely is proceeding under W3C be moved wholesale here seems a bit of a landgrab. Unless I'm misunderstanding the point.

[annevk]

I tried to give a perspective from an engineering standpoint as to what I think would help improve accessibility by making a larger group of people responsible for maintaining it rather than applying it as a monkey patch of sorts on top of the HTML Standard. That is, from an architecture standpoint the split does not make sense to me. (And also results in some implementation inefficiencies since there the cost is also typically being carried by a rather small team rather than the folks that maintain the implementation of the element and its API.)

I guess you're saying that's not possible for political reasons and that's too bad. I really think it could help a lot.

[patrickhlauke]

of course it would be so much easier if everything was worked on just in one place. but of course the reality of the situation is that WHATWG forked HTML. saying now that it would be easier if other things worked on at W3C also moved over to WHATWG of course makes sense from an engineering point of view, but I really doubt it will find much traction.

[patrickhlauke]

so with that said, is there a way of cross-referencing W3C stuff from WHATWG that avoids duplication? and is there a way to ensure that people working on WHATWG stuff also ensure that if their stuff has potential a11y implications, it gets properly reviewed? (and no, i don't think @whatwg/a11y alone can carry that particular burden)

[annevk]

The W3C i18n community has tooling that allows them to track a specific label that we apply to issues that we think concern i18n. Does the W3C a11y community have such tooling? (Of course, this still doesn't help in the case where it's forgotten due to lack of tight coupling. For that you need some ongoing monitoring and review.)

[patrickhlauke]

On the same note, is there tooling that allows WHATWG to track changes to W3C AAM etc to review any potential impact of changes there?

[annevk]

We could set something up if that's useful. I think for now if you ping @domenic in any relevant PR that'd be great.

[jakearchibald]

the reality of the situation is that WHATWG forked HTML

When the WHATWG 'forked' HTML, it was not being worked on at the W3, so it's kinda different to the W3 fork of the WHATWG HTML spec.

[patrickhlauke]

@jakearchibald thanks for the history clarification. now, back to topic here: accessibility specs (and how they tie/are closely coupled with html and various other related specs) are being actively worked on at W3C, so let's discuss how this can be moved forward.

[guest271314]

@annevk

If we can include normative accessibility mappings in the HTML Standard can we also fork Web Speech API to HTML Standard? There is a relationship between accessibility mappings and Web Speech API in that we can, for example, convert Braille to audio, and audio to Braille, etc.; see #2823.

While HTML Standard can make efforts to stay up to date with W3 version, will W3 also remain up to date with any changes made at HTML Standard version relevant to accessibility?

//cc @domenic

[domenic]

I think this thread is getting off-topic; @patrickhlauke I think you were not over the line but just to make things a bit more amicable perhaps you could have avoided provoking people with the fork comment; @jakearchibald and @guest271314 I think you are rather off-topic and I'd encourage you to take such conversations elsewhere. Let's please turn back to the issue opened by the OP and give that proposal the full attention it deserves.

For my part, I understand @annevk's point about the technical benefits of integrating the work. But, I think if the editors working on those mappings are more comfortable in a different venue, we definitely should be respectful of that. I don't at all think there should be a "landgrab" there; it's up to the people doing the work, and if they think it would be nice to integrate, then we'd welcome them, but if they'd rather keep it separate, that's fine too.

From my point of view that leaves us in a place where we want to address the question

is there a way of cross-referencing W3C stuff from WHATWG that avoids duplication?

And I think we can, and already do! That's the intent of https://html.spec.whatwg.org/multipage/dom.html#wai-aria. So I'm wondering if there's some way we could improve that to address the OP's point, although again, without duplication. I'd love to hear more about the ideas there.

(Note: again, I think this is a separate question from whether @patrickhlauke thinks that the folks in the @whatwg/a11y team are able to provide good review, which he mentions in his next sentence. That concern should be moved to whatwg/meta, if people want to discuss it further.)

[othermaciej]

I am not entirely clear on what this issue is originally asking for. I could imagine 3 possibilities:

(1) Reference appropriate A11Y specifications for the normative accessibility implementation requirements for HTML elements, by pointing to canonical specs defining this. My understanding is that this is already the case, but perhaps we could make the reference clearer or better. If there's a specific suggestion for improving the existing references, it would be great to hear it.

(2) Move some or all of the normative accessibility requirements from other specs into HTML. There are benefits to this from the perspective of readability for browser engineers and content authors, and spec development benefits since it would be harder to forget accessibility for new elements.. And it sounds like HTML editors would be open to this. However, we would only want to do this if the contributors of the current specifications actually wanted this. There is no intent to fork or land grab here.

(3) Duplicate normative accessibility requirements by copying text from other specifications, where the official requirement would still be in that other spec. This is a risky choice. It would be hard to maintain the text in sync, and there would be a risk of mismatches. From the perspective of a browser engine implementor, I'd worry that a possibly out-of-sync copy would be a trap for me and my colleagues, more than a benefit. If this is in fact what's being proposed, then perhaps I misunderstand the details and it might work out better than I think.

Out of these, Reference is the status quo, Move has potential benefits but is ultimately up to the writers and contributors of those specs, and Duplicate is tricky to do unless very carefully thought out.

[LJWatson]

The information in ARIA in HTML is intended primarily for conformance tools. It includes the implicit roles for elements (documented in the Core AAM and HTML AAM specs), plus the explicit roles that are permitted on each element.

The suggestion is to pull this information in from ARIA in HTML as an informative reference for authors. Where the characteristics of an element (categories, content model etc.) are shown for each element, the "implicit role" and "permitted roles" could be added.

Keeping the information up to date is an important consideration. The information in ARIA in HTML is very stable. Most changes to date have been the result of a new version of ARIA being released, rather than incremental/scattered alterations, so doing it manually isn't impossible.

That said, it would be easier for everyone if some tooling could be deployed to automate it. Ping @sideshowbarker for thoughts?

Discussing this idea with @stevefaulkner, he suggested attaching a particular label to commits to ARIA in HTML that would flag them for inclusion in the HTML standard.

[domenic]

Hmm, so to be clear, you are proposing Duplicate, right? I am still not sure whether that is a good idea. I don't believe there are any other specs that we choose to Duplicate instead of Reference. I'd love to hear from other editors on their thoughts.

One idea is that, if the goal is to provide better guidance for developers, perhaps instead of creating duplications in specs, updating MDN might make more sense? Remember that the HTML Standard for Developers is not meant to be a reference for everything related to HTML and HTML technologies, but just a view of the HTML Standard which subsets to the developer-applicable information. MDN is better for the former role.

[carmacleod]

Hi @domenic

If the HTML spec for an element simply included a Reference to the relevant table row in the ARIA in HTML spec, I think that would be useful to developers, and a nice little reminder at point of use to think about accessibility. For example, button element could link to https://www.w3.org/TR/html-aria/#button

[annevk]

I think it would be too confusing to only link the conformance requirements and not the implementer requirements. Linking both might be reasonable though and would further the goal of having accessibility considered as a core part of the element's definition.

[carmacleod]

@annevk
So, do you mean that button element would link to both:

• https://www.w3.org/TR/html-aria/#button and
• http://w3c.github.io/aria/#button ?

If so, I think that would be awesome.

What names would you choose for the concept titles? Perhaps something like:

• "Implied ARIA Role" and
• "Allowed ARIA Attributes" ?

Or would a single concept be preferred, such as perhaps:

• "ARIA Semantics", which would contain both links ?

[annevk]

I was thinking about https://www.w3.org/TR/html-aam-1.0/#details-id-16 (hard to locate these IDs unfortunately and potentially they are not stable given the numbering) in particular for implementers of the button element. And something along the lines of "ARIA for authors" and "ARIA for implementers" to make the distinction clear.

[carmacleod]

@annevk
The unstable ID problem is fixed in the latest editor's draft of the HTML-AAM spec.
The link for button (in the draft) is https://w3c.github.io/html-aam/#el-button

So (after the fixed HTML-AAM links are released in a Recommendation version) could we add something like the following code to the concept table for button?

<dt><a href="dom.html#concept-element-aria-for-authors" id="the-button-element:concept-element-aria-for-authors">ARIA for Authors</a>:</dt>
<dd><a href="https://www.w3.org/TR/html-aria/#button">button in the ARIA in HTML specification</a>.</dd>
<dt><a href="dom.html#concept-element-aria-for-implementers" id="the-button-element:concept-element-aria-for-implementers">ARIA for Implementers</a>:</dt>
<dd><a href="https://w3c.github.io/html-aam/#el-button">button in the HTML Accessibility API Mappings specification</a>.</dd>

I think it would go after the "Content attributes" list (?), and so would look something like this:

Of course, we would need to add definitions of the "ARIA for Authors" and "ARIA for Implementers" concepts in dom.html#concept-element-aria-for-authors and dom.html#concept-element-aria-for-implementers. If you think that this is a good direction to go in, I can try to come up with some words for these definitions, and if we are good with the definitions, then I can create a draft PR for more elements.

[domenic]

Bikeshedding, I would prefer a single dt, maybe "Accessibility considerations", which two dds, e.g. "For authors" and "For implementers".

[annevk]

With @domenic's nit taken into account I think that's great. Maybe "button accessibility for authors" and "button accessibility for implementers" so that the link text is reasonably unique throughout the standard. And also, I suspect we need something like that anyway to cover the more complicated elements, such as input.

[domenic]

Although I'd prefer not to repeat the element name inside the dl personally---we don't do it so far, instead using the heading to govern all the context---you raise a good point about the more complicated scenarios. Could we pick one or two of those and come up with a concrete proposal for the linking text?

[annevk]

Inspired by html-aam:

input (type attribute in the Date state) accessibility for implementers

[carmacleod]

Ok, tried to come up with some example screen snaps covering the 2 styles discussed.
Please let me know which style (or combination of styles) is preferred.

Style 1: Without repeating the element name or input type state

- the button element:

- input type="date" (part 1 of 2 theinput element):

- input type="date" (part 2 of 2 theDate state):

---

Style 2: Using the element name and the input type state in the link text

- the button element:

- input type="date" option 1... add all of the links to theinput element:

- input type="date" option 2... where input would just say something like "Depends on the state of the type attribute", and then each state would have the links:

[annevk]

Wow, thanks for all that work @carmacleod! I think we'll have to wait a bit for @domenic to get back from vacation to make a decision here. I’m personally happy with all of these though prefer putting it all in the green box.

[zcorpan]

I think having two separate lines for each type is a bit verbose, but a variant might work:

input (type attribute in the Date state) for authors; for implementers.

[domenic]

Thanks so much @carmacleod for these explorations, and I'm sorry to have disappeared on vacation just as you were getting into the swing of things.

My conclusion looking at your examples is that we're not going to be able to have a one-size-fits-all rule. In particular, while I think we should list the different variations for each element in the green domintro block most of the time, for <input> it's just too overwhelming.

So my preference would be "style 1", although for other tags with variations (such as a, form, th, etc.) we should do it more like style style 2 option 1.

Similarly, on specific typography, I think your For Authors.\nFor Implementers. is best in the general case, but when there are variations, we'll want something more like @zcorpan states. The precedent based on input's Categories <dt> would be something like Represents a hyperlink: for authors; for implementers.\nOtherwise: for authors; for implementers.

---

Now, there is an alternative that I'll throw out there, which I'm unsure about, but I should mention. Which is to just have two links per element, going to the "topmost" ARIA/HTML-AAM mapping. So e.g. input would go to input (type attribute in the Button state) in HTML-AAM and input type=button for HTML-ARIA. Then we would expect people to scroll down to see all the variants.

This is a bit semantically unsound, although it could be made better if the target specs inserted specific anchor IDs for those sections. E.g. we could link to #input-mapping or similar and guarantee that, through any refactorings, that would point to something that allows you to scroll through all the different input mappings.

Is this variant worth pursuing, or should we continue refining the version discussed above, which links to all HTML-AAM/HTML-ARIA mapping variants from HTML directly?

[stevefaulkner]

@domenic

although it could be made better if the target specs inserted specific anchor IDs for those sections

this can be done if you indicate what you need

[carmacleod]

@domenic Hope you had an awesome vacation, and sorry to take so long to get back to you! :)

Your "link to #input-mapping" alternative is an excellent compromise for input, but first, please have a look at this screen snap of "@zcorpan's input variant" with all of the types listed in the domintro block.
It may not be as overwhelming as it originally seemed, and it allows for consistency across all elements, including input (and others with variants, using the typography you suggested above).

My thinking is that, if at all possible, I would prefer to list (and link to) the input types separately because many authors may not realize that every input type has unique accessibility considerations.

[domenic]

@carmacleod that looks reasonable to me, although I don't think we need to list the tag name redundantly. So I'd suggest something like

type attribute in the Hidden state: for authors; for implementers.

At this point it might be best to start working on a pull request :). Perhaps it'd be good to start with input (the big one), a (a tiny bit of complications), and then something simple like button?

[carmacleod]

Agreed. Please assign this to me. Thanks!