Add aria-description

[aleventhal]

Closes issue #891

---

Preview | Diff

[backwardok]

So excited to see this being added!

[joanmarie]

In addition to my inline comments, I think it would be good to add a statement indicating which takes precedence when both aria-describedby and aria-description are used. There's a similar statement in this spec for aria-labelledby:

As required by the accessible name and description computation, user agents give precedence to aria-labelledby over aria-label when computing the accessible name property.

I'm not sure how we want to deal with adding mention of an ARIA 1.3 property in AccName 1.2. Maybe that's a non-issue. OR we could add a statement that doesn't mention AccName, but instead has a "user agents MUST" statement regarding what should happen when authors use both aria-describedby and aria-description.

[carmacleod]

Should aria-description be prohibited on generic role?

[scottaohara]

Should aria-description be prohibited on generic role?

if so, then likely so should aria-describedby and aria-details but that's not the case now. I think this warrants discussion though, but presently I'd think it's reasonable to continue to allow it (as it could be situationally useful).

[aleventhal]

Should aria-description be prohibited on generic role?

I'm leaning against it as an unnecessary restriction and I'm not sure what the benefit would be Consider that not everything that has an annotation will be necessarily highlighted, and thus won't have a mark role. There is the possibility that something will have an annotation on a passage of text that only becomes obvious to visual users after you click on it. IMO it could be on a span, etc.

With aria-label/name etc. I think the benefit of prohibiting it on some roles was that it would be possible to accidentally hide the inner contents from the AT. But that's not an issue here.

[carmacleod]

Other than "similar to aria-label", nothing really says "this is invisible". Perhaps that should be explicit.

[carmacleod]

After merging this, need to open an issue to update https://w3c.github.io/accname/ to say that aria-describedby overrides aria-description.

[carmacleod]

@aleventhal Sorry for the back-and-forth, but I think your original phrase before c7113b6 was better, i.e:

If the description text is available in the DOM, ...

(In fact, I think I'll provide a PR for aria-label to say "available in the DOM" as well... Edit: PR #1149. :)

What I had in mind for visible was adding something like the following (paraphrased from aria-label):

In cases where providing a visible description is not the desired user experience, authors MAY set the accessible description of the element using aria-description.

---

Here are 2 possible places where that sentence could fit in (there may be others):
1.

The purpose of aria-description is the same as that of aria-describedby. It provides the user with additional descriptive text for the object. In cases where providing a visible description is not the desired user experience, authors MAY set the accessible description of the element using aria-description. The most common accessibility API mapping for a description is the accessible description property. User agents MUST give precedence to aria-describedby over aria-description when computing the accessible description property.

If the description text is available in the DOM, authors SHOULD NOT use aria-description, but should use one of the following instead:

---

2.

The purpose of aria-description is the same as that of aria-describedby. It provides the user with additional descriptive text for the object. The most common accessibility API mapping for a description is the accessible description property. User agents MUST give precedence to aria-describedby over aria-description when computing the accessible description property.

In cases where providing a visible description is not the desired user experience, authors MAY set the accessible description of the element using aria-description. If the description text is available in the DOM, authors SHOULD NOT use aria-description, but should use one of the following instead:

[aleventhal]

Ok, makes sense. I used the second option, but I added a "However, " to help things flow. What do you think?

[aleventhal]

In addition to my inline comments, I think it would be good to add a statement indicating which takes precedence when both aria-describedby and aria-description are used.
This is done:
"User agents MUST give precedence to aria-describedby over aria-description when computing the accessible description property."

[joanmarie]

This version LGTM. Thanks for all your work on this!

[carmacleod]

I used the second option, but I added a "However, " to help things flow. What do you think?

Looks good!

[carmacleod]

+1

Thanks!