Aria-practices: Feedback on draft section 5: Providing Accessible Names and Descriptions

[mcking65]

This issue is for collecting initial feedback on the first broadly distributed draft of a new section titled Providing Accessible Names and Descriptions. This section is planned for publication in release 4 of Authoring Practices 1.1 in late July 2019.

PR for revisions

Feedback from this issue and other channels is being incorporated into a revised version of the naming and describing section.
Pull request #1062 will merge the revisions to master on July 10 in preparation for the APG call for consensus to publish that will be made to the ARIA working group at that time.

[jessebeach]

I'm having a difficult time understanding the behavior of the caption element in tables, specifically how its behavior changes when a label is applied to the containing table.

http://w3c.github.io/aria-practices/#describing_with_captions

Is it true that the caption is cast to help text in the case that the table has a label?

[jongund]

@mcking65 Matt,
I think this is very good. One thing I would like to see added is in Section 5.1 one or to sentences about what a screen reader does with the information. Something like:

Screen readers typically speak the role of the element (e.g. link, image, textbox, table, switch..) and then the accessible name for the element. If there is an accessible description, by default screen readers usually speak that information last. Accessible names therefore should not include role information and should be the same content as the visible labels provided people who can see the content. Names should be short and if more detailed explanation is needed on the purposed of the named element an accessible description can be added to the element.

[LJWatson]

There is a lot of really good information in this section. Just a few comments...

The language sometimes feels a bit too complicated. For example the duplication in "fundamental and important"; the re-enforcement of "effective and reliable"; very emotive words like "devistating"; and superfluous words like "cardinal".

The rules look good, but suggest they would be better placed in the Using ARIA specification, which is already a known reference for the rules of using ARIA (ping @stevefaulkner). The AP is already enormous (with nearly 300 headings and 1,000+ links).

On a similar note, it seems that the accessible name and description calculations should be normatively referenced from their origin specs, instead of duplicated in the AP.

[LJWatson]

In 5.3.1.3 it says:

In HTML documents, whenever possible, rely on HTML naming techniques, such as the HTML label element, alt attribute for images, caption element for tables, etc. While less flexible, their simplicity and reliance on visible text help ensure robust accessible experiences.>

The alt attribute doesn't rely on visible text, so it seems out of place in the opening sentence of the paragraph.

[jongund]

@mcking65
I think this section 5..4.1 on aria-details needs more work, since aria-details is poorly implemented by screen reader and apparently by looking at the Core AAM the AX API (macOS) has no mapping at all for aria-details, so not going to be available on macOS. The spec says that some accessibility APIs may only provide one if both are present, but states that aria-details will take precedence. Looking at Core AAM it doesn't seem there is any conflict in providing both, other than it will be an advantage to do so macOS, since AX API it can still provide information on aria-describedby.

[jongund]

@mcking65 The section 4.1.4 Descriptions Derived from Titles
also seems to include aria-details in the discussion of accessible description calculation, is this really true that aria-details will trump other description techniques?

[TestPartners]

I agree with Léonie regarding referencing the accessible name computation rather than duplicating it. There is already an issue whereby the github.w3c and w3.org websites contain different versions of the accessible name computation (one includes placeholder and the other doesn't) even though both documents have the same version number. The last thing we need is a third version.

[mfairchild365]

I'll echo the concerns that @jongund mentioned around how aria-details affects the accessible description computation.

[mcking65]

@jessebeach wrote:

I'm having a difficult time understanding the behavior of the caption element in tables, specifically how its behavior changes when a label is applied to the containing table.

http://w3c.github.io/aria-practices/#describing_with_captions

Is it true that the caption is cast to help text in the case that the table has a label?

Yes, if you use aria-label or aria-labelledby to name a table, and if that table has a caption, then the caption becomes the description in the a11y tree.

Do you think we should revise the first paragraph of that section to make this point more clearly?

[mcking65]

@LJWatson wrote:

In 5.3.1.3 it says:

In HTML documents, whenever possible, rely on HTML naming techniques, such as the HTML label element, alt attribute for images, caption element for tables, etc. While less flexible, their simplicity and reliance on visible text help ensure robust accessible experiences.>

The alt attribute doesn't rely on visible text, so it seems out of place in the opening sentence of the paragraph.

I revised rule 3 text in cd7111e to remove mention of alt. The paragraph now reads:

In HTML documents, whenever possible, rely on HTML naming techniques, such as the HTML label element for form elements and caption element for tables. While less flexible, their simplicity and reliance on visible text help ensure robust accessible experiences. Several of the naming techniques highlight specific accessibility advantages of using HTML features instead of ARIA attributes.

View the branch with revisions.

[jessebeach]

Do you think we should revise the first paragraph of that section to make this point more clearly?

@mcking65 yes, if only to call out this magical behavior. It's analogical to way that aria-haspopup on a button changes the semantics to menubutton. The behavior is non-obvious and magical.

[mcking65]

Léonie, thank you very much for taking the time to review and provide feedback!

@LJWatson wrote:

The language sometimes feels a bit too complicated. For example the duplication in "fundamental and important"; the re-enforcement of "effective and reliable"; very emotive words like "devistating"; and superfluous words like "cardinal".

After a928ddb and 1c22510, the opening paragraph now reads:

Providing elements with accessible names, and where appropriate, accessible descriptions is one of the most important responsibilities authors have when developing accessible web experiences. While doing so is straightforward for most elements, technical mistakes that can completely block users of assistive technologies are easy to make and unfortunately common. To help authors effectively provide accessible names and descriptions, this section explains their purpose, when authors need to provide them, how browsers assemble them, and rules for coding and composing them. It also guides authors in the use of the following naming and describing techniques and WAI-ARIA properties:

View the complete revised name and description section.

@LJWatson wrote:

The rules look good, but suggest they would be better placed in the Using ARIA specification, which is already a known reference for the rules of using ARIA (ping @stevefaulkner).

I'm unclear why the rules would better fit in Using ARIA, which is scoped specifically to HTML. If the rules were moved there, wouldn't the entire section need to go there? The rules are designed to highlight and emphasize some critical points in the subsequent techniques sections.

One thing to consider is that we designed the information architecture of this section with the ARIA 1.2 scope of HTML role parity in mind. Right after we publish, it will be further revised to include techniques in support of the ARIA label and legend roles as well as provide guidance for all the new structural roles. Thus, we will have several more situations where referencing these rules will be particularly helpful.

@LJWatson wrote:

The AP is already enormous (with nearly 300 headings and 1,000+ links).

Indeed, it is a beast rapidly getting more beastly! This is a serious concern that the task force has discussed, and I hope we can aggressively pursue transforming from a Note into some other type of W3C resource after APG 1.2 is published along with the ARIA 1.2 Recommendation. By that time, we plan to have 100% coverage of the ARIA specification and will be in a much better position to focus on other matters like improving usability.

@LJWatson wrote:

On a similar note, it seems that the accessible name and description calculations should be normatively referenced from their origin specs, instead of duplicated in the AP.

Section 5.3.5Accessible name calculation does reference the specification. That section is meant to be explanitory, not duplicative in the same way that the entire APG is explanitory. Same is true for section 5.4.2 Accessible description calculation.

Today, the task force discussed whether to keep these sections. The consensus is that they provide real value for people who do not have the time or ability to synthesize this type of information from the accname and html-aam specs.

[mcking65]

@TestPartners wrote:

There is an anomaly whereby a data table constructed using ARIA (role="table") MUST have an accessible name, but neither the HTML specification nor WCAG 2.1 require elements to have an accessible name. This means that a table built using ARIA must have an accessible name and a table built with a element does not need one. What is the rationale for that?

Fabulous question! This is a mystery we hope to resolve with w3c/aria#1005. My hope is that the requirement for a name on table will be removed in ARIA 1.2. If so, that would drive several changes to APG.

[mcking65]

@TestPartners wrote:

There is already an issue whereby the github.w3c and w3.org websites contain different versions of the accessible name computation (one includes placeholder and the other doesn't) even though both documents have the same version number. The last thing we need is a third version.

GitHub and w3.org contain different versions of all W3C publications managed in GitHub. Those are the differences between the latest work in progress verses the published version of a document. The top of every document contains information about its status that is easily overlooked but can be quite important.

[mcking65]

@jongund wrote:

One thing I would like to see added is in Section 5.1 one or to sentences about what a screen reader does with the information. Something like:

Screen readers typically speak the role of the element (e.g. link, image, textbox, table, switch..) and then the accessible name for the element. If there is an accessible description, by default screen readers usually speak that information last. Accessible names therefore should not include role information and should be the same content as the visible labels provided people who can see the content. Names should be short and if more detailed explanation is needed on the purposed of the named element an accessible description can be added to the element.

Section 5.1 includes the following paragraph:

An accessible description is also an author-provided string that is rendered by assistive technologies. Authors supply a description when there is a need to associate additional information with an element, such as instructions or format requirements for an input field. Because they are usually significantly longer than names, assistive technologies present descriptions differently from names and other element attributes. For instance, a screen reader may announce a description of an element after its name, role, value (if any), and relevant states or properties.

We do not include information about how to compose a name in 5.1, e.g., tips like keep it brief and do not include the role name in the accessible name. That information is in section 5.3.3 (Composing Effective and User-friendly Accessible Names) and emphasized by rule 5.

So, it seems like we already have what you are suggesting. Or, am I not understanding?

[mcking65]

@mfairchild365 and @jongund, the aria-details guidance is based on the spec, but we didn't do significant research on its actual utility in current implementations. While the guidance needs to support the specification, as discussed in today's APG TF meeting, we will investigate further and discuss whether we need to modify the language to caution against unrealistic expectations.

[mcking65]

@jessebeach wrote:

Do you think we should revise the first paragraph of that section to make this point more clearly?

@mcking65 yes, if only to call out this magical behavior. It's analogical to way that aria-haspopup on a button changes the semantics to menubutton. The behavior is non-obvious and magical.

In 34fa2e5 I revised sections:

• 5.3.2.6 Naming Tables and Figures with Captions
• 5.4.1.3 Describing Tables and Figures with Captions

I hope the magic is more obvious now. you can view the full text of the revised version here.

[jongund]

@mcking65 and @mfairchild365 Just like the ARIA spec, aria-details should have its own section that discusses the various issues with using it in practice, just like in the ARIA spec itself. Since aria-details is not part of the accessible name or description algorithm it should not even be mentioned as part of creating an accessible name or description. The ARIA practices should provide more clarity, not contribute to the confusion people have about using aria-details. The current draft actually makes the use of aria-details as more useful than using aria-describedby and I am not sure anyone who understands the current implementation of aria-details would make that recommendation.

[jongund]

@mcking65 The information about screen readers to me at least should be first in the paragraph, since that provides context for what the accessible name is about. Putting the information at the end of the paragraph makes the information less important or discover able to me, given that people tend to skim first lines of paragraphs to see if they want to read the whole thing. So I suggest moving the last sentence to be the first.

[aardrian]

@mcking65

Indeed, it is a beast rapidly getting more beastly! This is a serious concern that the task force has discussed, and I hope we can aggressively pursue transforming from a Note into some other type of W3C resource after APG 1.2 is published along with the ARIA 1.2 Recommendation. By that time, we plan to have 100% coverage of the ARIA specification and will be in a much better position to focus on other matters like improving usability.

Why? What purpose does that serve?

This reads as scope creep.

With dozens of open issues noting bugs in patterns that impact users _today_, I think a better use of time would be filling those gaps. Otherwise you are overlapping with existing standards documents or other notes.

I recognize the value in having an overview of how to use ARIA (some of which is addressed in other documents) as well as providing patterns against which we can test AT, but when the patterns have known issues we cannot even effectively test support in AT.

Take the good bits and percolate them to the relevant reference materials and continue to let this document exist as an (ostensibly) accessible pattern library.

As it stands today, I have to _actively_ discourage users from some of the patterns because if they copy paste the code as-is, they get broken patterns. Focusing on fixing the patterns will make this document more trusted should it ever try to broaden its scope.

[mcking65]

@jongund wrote:

@mcking65 The information about screen readers to me at least should be first in the paragraph, since that provides context for what the accessible name is about. Putting the information at the end of the paragraph makes the information less important or discover able to me, given that people tend to skim first lines of paragraphs to see if they want to read the whole thing. So I suggest moving the last sentence to be the first.

Jon, I agree that the information about screen reader presentation is an important topic. But, we also need a paragraph that focuses on what an accessible description is. So, I broke that paragraph into two separate paragraphs; one that defines accessible description and another that explains screen reader presentation. With changes in commit e912af4, the last two paragraphs of section 5.1 now read as follows.

An accessible description is also an author-provided string that is rendered by assistive technologies. Authors supply a description when there is a need to associate additional information with an element, such as instructions or format requirements for an input field.

assistive technologies present names differently from descriptions. For instance, screen readers typically announce the name and role of an element first, e.g., a button named "Mute Conversation"could be spoken as "Mute Conversation button". If an element has a state, it could be announced either before or after the name and role; after name and role is the typical default. For example, a switch button named "Mute Conversation" in the "off" state could be announced as "Mute Conversation switch button off". Because descriptions are optional strings that are usually significantly longer than names, they are presented last, sometimes after a slight delay. For example, "Mute Conversation Switch button off, Silences alerts and notifications about activity in this conversation." To reduce verbosity, some screen readers do not announce descriptions by default but instead inform users of their presence so that users can press a key that will announce the description.

You can view the full text of revised section 5.1 here.

Does this resolve your concern about that section?

[accdc]

Hi Matt,
I read through the revised text, and it looks good to me. As the spec evolves and things are added or removed, we can always revisit some of this guidance if needed later on.

[mcking65]

@jongund, @mfairchild365,

Based on our discussion in the July 9, 2019 APG teleconference about whether to keep guidance on aria-details in the naming and describing section, I have removed all information related to aria-details with commit 6d815d5. I have preserved the comment in a branch that I will surface in issue #70, which we will postpone until APG 1.2.

[mcking65]

@aardrian wrote:

@mcking65:

Indeed, it is a beast rapidly getting more beastly! This is a serious concern that the task force has discussed, and I hope we can aggressively pursue transforming from a Note into some other type of W3C resource after APG 1.2 is published along with the ARIA 1.2 Recommendation. By that time, we plan to have 100% coverage of the ARIA specification and will be in a much better position to focus on other matters like improving usability.

Why? What purpose does that serve?

This reads as scope creep.

We are not intending to increase the scope at all, just make the information architecture and presentation of the existing content more usable.

With dozens of open issues noting bugs in patterns that impact users _today_, I think a better use of time would be filling those gaps. Otherwise you are overlapping with existing standards documents or other notes.

For sure, fixing bugs is a higher priority. That goes along with first covering the complete ARIA spec.

Better coordination with other working group resources is also an issue that has been on our radar, and the ARIA WG has been meeting with other WGs, such asWAI Education and Outreach to work on that as well.

I recognize the value in having an overview of how to use ARIA (some of which is addressed in other documents) as well as providing patterns against which we can test AT, but when the patterns have known issues we cannot even effectively test support in AT.

Please keep in mind, as explained in the Read Me First section, APG patterns are not designed to work with AT that do not correctly support the ARIA specification. Many of the "known issues" are actually AT issues. the aria-at project and community group are going to build an AT compatibility and support database that will help drive consistency in how AT support ARIA.

As it stands today, I have to _actively_ discourage users from some of the patterns because if they copy paste the code as-is, they get broken patterns. Focusing on fixing the patterns will make this document more trusted should it ever try to broaden its scope.

As explained in the Read Me First, APG code is not designed to be production-ready. So, please advise everyone against copy/pasting and using as-is!

And, as i mentioned above, there is quite a bit of ARIA that is not yet well supported. Thus, as we describe in the Read Me First section, it is essential to test with targetted assistive technologies and browsers.

ARIA is still a bit like CSS was 5 years after it became a standard in 1996. Things were still pretty messy in 2001. One big difference -- polyfilling isn't feasible; there is no way to adjust your UI for specific assistive technologies. The primary goal of the aria-at community group, which is still in early stages, is to accelerate cleaning up the mess.

[mcking65]

Thank you @jessebeach, @tatermelon, @jongund, @LJWatson, @TestPartners, @mfairchild365, @aardrian, and @accdc for your reviews and feedback.

Hopefully it is all adequately addressed by commit fb18db7, which is now in master and will get published on w3.org in APG 1.1 release 4 during the week of July 22. Of course, keep the feedback coming. There will be more added to this section for the many changes coming to this topic in ARIA 1.2 at the end of the year.