Html: Adding accessible labels (and descriptions) to sections is laborious and error-prone

[jimmyfrasche]

Per aria recommendations, I'd rather not use aria. The most common place I do have to use aria is for aria-label, aria-labelledby, and, to a lesser extent, aria-describedby. This is also where I run into the most problems. They all have workarounds but they can be a bit tedious and hard to get right.

When this comes up, the label and/or description is almost always contained in the element so aria-labelledby makes more sense than aria-label, but this means giving that element a unique id.

That's not really an issue with form elements, in my experience, since they're less likely to show up on a page more than once without some javascript that can generate unique ids, they have a dedicated label element and if I want to add a description I can use something like id="{{the-form-elements-id}}-description.

Coming up with ids for things like an article can be difficult in CMSes since they can occasionally be shown on the page more than once. Consider reading a page that has recent posts in the sidebar and related pages below the current article. The same article may be in both and without care taken to handle passing the differing contexts into the article teaser template the ids will be duplicated. That example is unlikely to cause issue in practice since the duplicate ids would refer to duplicate content so even if the "wrong" one is used to look up the label the correct label is still applied, by happenstance.

Another way around this would be to do something like

<h2>Related content</h2>
<article aria-label="{{ title }}">
  <span>{{ title }}</span>
  image, blurb, link, etc.

but something about that makes me uneasy, in addition to the current(?) bug where an aria-label does not get translated with the rest of a document. ( https://github.com/w3c/aria/issues/899 proposes using a heading element to deduce the name but I generally don't want teasers like this to have headers since I don't think it really adds much to the navigability here, and it makes it harder to nest them in arbitrary places in the document without passing the parent heading level to the template which can be difficult to set up in some CMSes).

Still, it would be nice if no ids and no aria attributes had to come into play at all and I think it would be better to have the label and description specified more clearly and concisely in the document source, somehow.

I know I'm not suppose to propose solutions at this point but I think I can best illustrate what I want to do by an example:

<article>
  <title>Probably can't use this tag!</title>
  <desc hidden>a description</desc>
  other stuff
</article>

which would be equivalent to

<article aria-labelledby=a-label-id aria-describedby=a-description-id>
  <div id=a-label-id>Probably can't use this tag!</div>
  <div id=a-description-id hidden>a description</div>
  other stuff
</article>

Something like that would avoid duplicating content or coming up with a lot of unique identifiers, while making it simple and obvious to create and see the relation between the label/description and what is being labelled/described.

(I don't require a screen reader, though I have used screen readers before; my primary concern is making the correct thing easier to do and understand).

[annevk]

Welcome, sounds like you're familiar with https://whatwg.org/faq#adding-new-features. An initial step here that might be interesting is to experiment with this using custom elements. This is a bit cumbersome today as you'll have to add the attributes directly, but in the future some of it should be exposed on ElementInternals, so you can emulate built-in elements in a way. Then if those custom elements see wide adoption, that would be a good sign that perhaps they should be added natively to the web platform.

cc @whatwg/a11y

[jimmyfrasche]

I wasn't proposing a specific thing so much as trying to demonstrate how easy I think I should it be.

Nevertheless: https://github.com/jimmyfrasche/titledesc and https://jimmyfrasche.github.io/titledesc/

That was interesting. Never written a custom element before. In this case, it was kind of annoying that disconnectedCallback doesn't pass the element from which one was disconnected since I had to change its attributes, though I can understand why that would be a niche use case.

[alice]

I'm trying to understand the issue. Is there some reason an <h[1-6]> element wouldn't fulfill the need you're describing here?

[jimmyfrasche]

• headings don't set the aria-label of the containing element (pending some proposed exceptions https://github.com/w3c/aria/issues/899 )
• it can be useful to use a non-heading for the label
• headings can't be used for descriptions
• dedicated elements seem like they'd read best from all the various solutions, actual and proposed, I've seen and there's precedent in svg's desc element

Descriptions are not as common an issue. It seemed natural to bundle the two, though, and I got the idea from desc.

[alice]

I previously wrote:

_I guess I'm not clear on why you need a label for the containing element if it contains a heading. Users are more likely to navigate by heading than by landmark. Can you help me understand the user need in this case?_

_Descriptions are another matter, but again, I'm not clear on the user need there._

[Edit] I had a read through the ARIA issue you linked, and that provided some more context - thanks for that!

So I guess then my question is better phrased as: what gap (other than descriptions) would be left if, as proposed, certain landmark roles had their accessible name computed from the first descendant heading?

When would you need to use something other than a heading element?

[jimmyfrasche]

I specifically decided to file an issue at all after having to do a lot of work fixing dozens of templates that tried to use aria-labelledby and aria-describedby but were riddled with errors from duplicate ids and non-existent ids.

It wasn't that the original devs were incompetent and they clearly meant to do well; it's just easy to get this stuff wrong without an undue amount of care, especially when using templates where things can get included on the same page more than once and the label/heading/title can come from a different template.

The other thing I needed to fix was headings that were coming out at essentially random levels, for the same reason as the aria-labelledby ids—how individually correct templates get combined and reused.

Sometimes I had to use a span styled as a heading to avoid using the wrong heading level in templates that got reused in multiple contexts. I could have added some kind of context tracking mechanism or a global counter or something but there wasn't the budget to tack something like that on. Ideally, that kind of thing wouldn't be necessary anyway. It should be largely possible to write html that is clear and works regardless of context.

It's possible that the previously linked issue and getting the document outline restored would be sufficient for most cases, but the latter seems to have stagnated for some time. I'd be happy with whatever.

[alice]

Thanks so much for the extra context.

I definitely agree that IDs are extremely error prone, and the heading issue as you said has gone nowhere for a long time.

[LJWatson]

@Alice commented:

So I guess then my question is better phrased as: what gap (other than descriptions) would be left if, as proposed, certain landmark roles had their accessible
name computed from the first descendant heading?>

We might need to think about <section> elements because they only become landmarks when they have an accessible name. It's possible the presence of a first child heading is enough to make the case for the accessible name being assigned, and the element becoming a navigable landmark, but I'm not sure it can be guaranteed?