fix(aria-label): Improve page for clarity #32688

dipikabh · 2024-03-14T22:09:10Z

Description

Glossary page: Accessible name

Fixes subject-verb mismatches
Edits for clarity

Attribute: aria-label

Replaces link for "accessible name" to our glossary page
Adds a description for the example code
Reorganizes multi-para content in "Description" into bullets for better scanning of info
Collates repeated info in text and note
Adds missing period to note text
Other general edits for clarity and readability

Motivation

To improve readability, clarity, and organization

Related issues and pull requests

Update: Partially addresses #31739

github-actions · 2024-03-14T22:10:36Z

Preview URLs

External URLs (1)

URL: /en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label
Title: aria-label

https://www.youtube.com/watch?v=9xXBYcWgCHA (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2024-03-27 18:53:42)

estelle

several very minor suggestions

estelle · 2024-03-21T19:16:35Z

files/en-us/glossary/accessible_name/index.md

@@ -12,11 +12,11 @@ Accessible names convey the purpose or intent of the element. This helps users u

 Depending on the element and the HTML markup, the value of the accessible name may be derived from visible (e.g., the text within {{HTMLElement("figcaption")}}) or invisible (e.g., the `aria-label` attribute set on an element) content, or a combination of both. How an element's accessible name is determined is based on the [accessible name calculation](https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/#name_calculation), which is different for different elements.

-It is best to use visible text as the accessible names. Many elements, including {{HTMLElement("a")}}, {{HTMLElement("td")}} and {{HTMLElement("button")}}, get their name from their contents. For example, given `<a href="foo.html">Bar</a>`, the accessible name is "Bar."
+It is best to use visible text as the accessible name. Many elements, including {{HTMLElement("a")}}, {{HTMLElement("td")}} and {{HTMLElement("button")}}, get their accessible names from their contents. For example, given `<a href="foo.html">Bar</a>`, the accessible name of this `<a>` element is "Bar."


Suggested change

It is best to use visible text as the accessible name. Many elements, including {{HTMLElement("a")}}, {{HTMLElement("td")}} and {{HTMLElement("button")}}, get their accessible names from their contents. For example, given `<a href="foo.html">Bar</a>`, the accessible name of this `<a>` element is "Bar."

It is best to use visible text as the accessible name. Many elements, including {{HTMLElement("a")}}, {{HTMLElement("td")}} and {{HTMLElement("button")}}, get their accessible name from their contents. For example, given `<a href="foo.html">Bar</a>`, the accessible name of this `<a>` element is "Bar."

the plural made it sound like an element can have more than one accessible name. It is correct to use "names", but "name" is also ok, and less likely to create confusion.

thank you estelle. i was feeling very iffy about these updates - so i'm glad you share my concern

probably the right fix here would be to also make "content" singular:

It is best to use visible text as the accessible name. Many elements, including {{HTMLElement("a")}}, {{HTMLElement("td")}} and {{HTMLElement("button")}}, get their accessible name from their content.

estelle · 2024-03-21T19:18:40Z

files/en-us/glossary/accessible_name/index.md


-Other elements get their accessible name from the content of associated elements. For some parent elements, like {{HTMLElement("fieldset")}}, {{HTMLElement("table")}}, and {{HTMLElement("figure")}}, if those elements contain a descendant {{HTMLElement("fieldset")}}, {{HTMLElement("caption")}}, or {{HTMLElement("figcaption")}}, respectively, the association is automatic. For some other elements, like {{HTMLElement("textarea")}} and {{HTMLElement("input")}}, the accessible name also comes from an associated element, the {{HTMLElement("label")}} element, but that association has to explicitly set with a `for` attribute value on the `<label>` that matches the form control's `id`.
+Other elements get their accessible names from the content of associated elements. If some parent elements such as {{HTMLElement("fieldset")}}, {{HTMLElement("table")}}, and {{HTMLElement("figure")}} contain a descendant {{HTMLElement("fieldset")}}, {{HTMLElement("caption")}}, or {{HTMLElement("figcaption")}} element, respectively, the association is automatic. For form elements like {{HTMLElement("textarea")}} and {{HTMLElement("input")}}, the accessible name comes from the associated {{HTMLElement("label")}} element; the association in this case has to be explicitly defined by setting the `for` attribute in the `<label>` element to match the `id` of the form control.


Suggested change

Other elements get their accessible names from the content of associated elements. If some parent elements such as {{HTMLElement("fieldset")}}, {{HTMLElement("table")}}, and {{HTMLElement("figure")}} contain a descendant {{HTMLElement("fieldset")}}, {{HTMLElement("caption")}}, or {{HTMLElement("figcaption")}} element, respectively, the association is automatic. For form elements like {{HTMLElement("textarea")}} and {{HTMLElement("input")}}, the accessible name comes from the associated {{HTMLElement("label")}} element; the association in this case has to be explicitly defined by setting the `for` attribute in the `<label>` element to match the `id` of the form control.

Other elements get their accessible name from the content of associated elements. If some parent elements such as {{HTMLElement("fieldset")}}, {{HTMLElement("table")}}, and {{HTMLElement("figure")}} contain a descendant {{HTMLElement("fieldset")}}, {{HTMLElement("caption")}}, or {{HTMLElement("figcaption")}} element, respectively, the association is automatic. For form elements like {{HTMLElement("textarea")}} and {{HTMLElement("input")}}, the accessible name comes from the associated {{HTMLElement("label")}} element; the association in this case has to be explicitly defined by setting the `for` attribute in the `<label>` element to match the `id` of the form control, unless the association is implicit as is the case when the form control is nested within the `<label>`.

i would remove the example of figure > figcaption. since (though this is taking a while to get full implementation) figcaption will not provide a name to figure in the future. this was generally considered too noisy and redundant, especially since figcaptions can contain structured content which would not have their semantics communicated in the flattened text string that becomes the name.

Thanks, both!

Fixing the last sentence as:

The association needs to be explicitly defined by setting the for attribute in the <label> element to match the form element's id. Alternatively, an implicit association is created when the form control is directly nested within the <label> element.

@scottaohara thanks for the insights into the future direction of figure > figcaption regarding accessible name. I've removed their mention.

files/en-us/glossary/accessible_name/index.md

files/en-us/web/accessibility/aria/attributes/aria-label/index.md

estelle · 2024-03-21T19:31:58Z

files/en-us/web/accessibility/aria/attributes/aria-label/index.md


-> **Note:** The `aria-label` is only "visible" to assistive technologies. If the information is important enough to add for AT users, consider making it visible for all users.
+- Not all elements can be given an accessible name. Neither `aria-label` nor `aria-labelledby` should be used with non-interactive elements, inline structural roles such as with `code`, `term`, and `emphasis`, and roles not be mapped to the accessibility API, including `presentation`, `none`, and `hidden`. The `aria-label` attribute is intended for interactive elements only, including links, videos, form controls, and those with [landmark roles](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) or [widget roles](/en-US/docs/Web/Accessibility/ARIA/Roles#2._widget_roles); `aria-label` provides an accessible name when no visible label exists in the DOM.


Suggested change

- Not all elements can be given an accessible name. Neither `aria-label` nor `aria-labelledby` should be used with non-interactive elements, inline structural roles such as with `code`, `term`, and `emphasis`, and roles not be mapped to the accessibility API, including `presentation`, `none`, and `hidden`. The `aria-label` attribute is intended for interactive elements only, including links, videos, form controls, and those with [landmark roles](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) or [widget roles](/en-US/docs/Web/Accessibility/ARIA/Roles#2._widget_roles); `aria-label` provides an accessible name when no visible label exists in the DOM.

- Not all elements can be given an accessible name. Neither `aria-label` nor `aria-labelledby` should be used with non-interactive elements, inline structural roles such as with `code`, `term`, and `emphasis`, and roles not mapped to the accessibility API, including `presentation`, `none`, and `hidden`. The `aria-label` attribute is intended for interactive elements only, including links, videos, form controls, and those with [landmark roles](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) or [widget roles](/en-US/docs/Web/Accessibility/ARIA/Roles#2._widget_roles); `aria-label` provides an accessible name when no visible label exists in the DOM.

this isn't entirely true. it's not just interactive elements that aria-label or aria-labelledby can be used with. I realize this wasn't a change made in this PR, but since this PR is open, this information should be corrected. There are various non-interactive elemetns which can benefit from having an aria-label/labelledby name, if one can't use the native features to provide one (e.g., tables, fieldsets)

@scottaohara I'm glad you mentioned this because I started looking at this page precisely because of this issue raised here: The documentation for aria-label mentions that this is for interactive elements only, but this doesn't seem right #31739

There are two instances on the page that mention that aria-label should be used for interactive elements only.

I'm removing this note in the Associated roles section:

Note: The aria-label attribute is intended for interactive elements only. When placed on non-interactive elements, such as those listed above, it may not be read or may confuse your users as a non-interactive element that acts like an interactive one.

I'm updating the above point as follows (removing reference to non-interactive elements, removing hidden):

Not all elements can be given an accessible name. Neither aria-label nor aria-labelledby should be used with inline structural roles such as code, term, and emphasis, and roles not mapped to the accessibility API, including none. The aria-label attribute is intended for elements including links, videos, form controls, and those with landmark roles or widget roles; aria-label provides an accessible name when no visible label exists in the DOM.

Updating the list in the Associated roles section as per https://w3c.github.io/aria/#namefromprohibited. definition was missing.

files/en-us/web/accessibility/aria/attributes/aria-label/index.md

files/en-us/glossary/accessible_name/index.md

scottaohara · 2024-03-21T21:16:14Z

files/en-us/glossary/accessible_name/index.md

@@ -12,11 +12,11 @@ Accessible names convey the purpose or intent of the element. This helps users u

 Depending on the element and the HTML markup, the value of the accessible name may be derived from visible (e.g., the text within {{HTMLElement("figcaption")}}) or invisible (e.g., the `aria-label` attribute set on an element) content, or a combination of both. How an element's accessible name is determined is based on the [accessible name calculation](https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/#name_calculation), which is different for different elements.

-It is best to use visible text as the accessible names. Many elements, including {{HTMLElement("a")}}, {{HTMLElement("td")}} and {{HTMLElement("button")}}, get their name from their contents. For example, given `<a href="foo.html">Bar</a>`, the accessible name is "Bar."
+It is best to use visible text as the accessible name. Many elements, including {{HTMLElement("a")}}, {{HTMLElement("td")}} and {{HTMLElement("button")}}, get their accessible names from their contents. For example, given `<a href="foo.html">Bar</a>`, the accessible name of this `<a>` element is "Bar."


thank you estelle. i was feeling very iffy about these updates - so i'm glad you share my concern

scottaohara · 2024-03-21T21:18:21Z

files/en-us/glossary/accessible_name/index.md


-Other elements get their accessible name from the content of associated elements. For some parent elements, like {{HTMLElement("fieldset")}}, {{HTMLElement("table")}}, and {{HTMLElement("figure")}}, if those elements contain a descendant {{HTMLElement("fieldset")}}, {{HTMLElement("caption")}}, or {{HTMLElement("figcaption")}}, respectively, the association is automatic. For some other elements, like {{HTMLElement("textarea")}} and {{HTMLElement("input")}}, the accessible name also comes from an associated element, the {{HTMLElement("label")}} element, but that association has to explicitly set with a `for` attribute value on the `<label>` that matches the form control's `id`.
+Other elements get their accessible names from the content of associated elements. If some parent elements such as {{HTMLElement("fieldset")}}, {{HTMLElement("table")}}, and {{HTMLElement("figure")}} contain a descendant {{HTMLElement("fieldset")}}, {{HTMLElement("caption")}}, or {{HTMLElement("figcaption")}} element, respectively, the association is automatic. For form elements like {{HTMLElement("textarea")}} and {{HTMLElement("input")}}, the accessible name comes from the associated {{HTMLElement("label")}} element; the association in this case has to be explicitly defined by setting the `for` attribute in the `<label>` element to match the `id` of the form control.


i would remove the example of figure > figcaption. since (though this is taking a while to get full implementation) figcaption will not provide a name to figure in the future. this was generally considered too noisy and redundant, especially since figcaptions can contain structured content which would not have their semantics communicated in the flattened text string that becomes the name.

scottaohara · 2024-03-21T21:23:57Z

files/en-us/web/accessibility/aria/attributes/aria-label/index.md


-> **Note:** The `aria-label` is only "visible" to assistive technologies. If the information is important enough to add for AT users, consider making it visible for all users.
+- Not all elements can be given an accessible name. Neither `aria-label` nor `aria-labelledby` should be used with non-interactive elements, inline structural roles such as with `code`, `term`, and `emphasis`, and roles not be mapped to the accessibility API, including `presentation`, `none`, and `hidden`. The `aria-label` attribute is intended for interactive elements only, including links, videos, form controls, and those with [landmark roles](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) or [widget roles](/en-US/docs/Web/Accessibility/ARIA/Roles#2._widget_roles); `aria-label` provides an accessible name when no visible label exists in the DOM.


this isn't entirely true. it's not just interactive elements that aria-label or aria-labelledby can be used with. I realize this wasn't a change made in this PR, but since this PR is open, this information should be corrected. There are various non-interactive elemetns which can benefit from having an aria-label/labelledby name, if one can't use the native features to provide one (e.g., tables, fieldsets)

dipikabh · 2024-03-22T20:33:43Z

Thank you, @estelle and @scottaohara, for your insightful reviews and suggestions! I've addressed all your comments. I'd appreciate if you could take another look.

Scott, your feedback about the use of aria-label and aria-labelledby for both interactive and non-interactive elements was particularly helpful. I have updated the text (and there is scope to add more details to address the linked issue).

(I've updated the PR description to include a reference to the issue that initiated this PR.)

estelle

Just some text simplification suggestions

files/en-us/glossary/accessible_name/index.md

files/en-us/web/accessibility/aria/attributes/aria-label/index.md

dipikabh · 2024-03-27T18:54:31Z

Thanks @estelle and @scottaohara for the reviews!

dipikabh added 2 commits March 14, 2024 17:54

edits for clarity

4636eaa

updates See also

7e8502c

dipikabh requested review from a team as code owners March 14, 2024 22:09

dipikabh requested review from scottaohara and Elchi3 and removed request for a team March 14, 2024 22:09

github-actions bot added Content:Accessibility Accessibility docs Content:Glossary Glossary entries size/s 6-50 LoC changed labels Mar 14, 2024

fixes typo

b11985f

estelle requested changes Mar 21, 2024

View reviewed changes

scottaohara reviewed Mar 21, 2024

View reviewed changes

fixes review comments

bf2e103

dipikabh requested review from scottaohara and estelle March 24, 2024 17:13

estelle approved these changes Mar 27, 2024

View reviewed changes

fixes review comments

66d7c8a

dipikabh merged commit d9c3dac into mdn:main Mar 27, 2024
9 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(aria-label): Improve page for clarity #32688

fix(aria-label): Improve page for clarity #32688

dipikabh commented Mar 14, 2024 •

edited

github-actions bot commented Mar 14, 2024 •

edited

estelle left a comment

estelle Mar 21, 2024

scottaohara Mar 21, 2024

dipikabh Mar 22, 2024

estelle Mar 21, 2024

scottaohara Mar 21, 2024

dipikabh Mar 22, 2024

estelle Mar 21, 2024

scottaohara Mar 21, 2024

dipikabh Mar 22, 2024 •

edited

scottaohara Mar 21, 2024

scottaohara Mar 21, 2024

scottaohara Mar 21, 2024

dipikabh commented Mar 22, 2024

estelle left a comment

dipikabh commented Mar 27, 2024

	It is best to use visible text as the accessible name. Many elements, including {{HTMLElement("a")}}, {{HTMLElement("td")}} and {{HTMLElement("button")}}, get their accessible names from their contents. For example, given `<a href="foo.html">Bar</a>`, the accessible name of this `<a>` element is "Bar."
	It is best to use visible text as the accessible name. Many elements, including {{HTMLElement("a")}}, {{HTMLElement("td")}} and {{HTMLElement("button")}}, get their accessible name from their contents. For example, given `<a href="foo.html">Bar</a>`, the accessible name of this `<a>` element is "Bar."


		Other elements get their accessible name from the content of associated elements. For some parent elements, like {{HTMLElement("fieldset")}}, {{HTMLElement("table")}}, and {{HTMLElement("figure")}}, if those elements contain a descendant {{HTMLElement("fieldset")}}, {{HTMLElement("caption")}}, or {{HTMLElement("figcaption")}}, respectively, the association is automatic. For some other elements, like {{HTMLElement("textarea")}} and {{HTMLElement("input")}}, the accessible name also comes from an associated element, the {{HTMLElement("label")}} element, but that association has to explicitly set with a `for` attribute value on the `<label>` that matches the form control's `id`.
		Other elements get their accessible names from the content of associated elements. If some parent elements such as {{HTMLElement("fieldset")}}, {{HTMLElement("table")}}, and {{HTMLElement("figure")}} contain a descendant {{HTMLElement("fieldset")}}, {{HTMLElement("caption")}}, or {{HTMLElement("figcaption")}} element, respectively, the association is automatic. For form elements like {{HTMLElement("textarea")}} and {{HTMLElement("input")}}, the accessible name comes from the associated {{HTMLElement("label")}} element; the association in this case has to be explicitly defined by setting the `for` attribute in the `<label>` element to match the `id` of the form control.


		> Note: The `aria-label` is only "visible" to assistive technologies. If the information is important enough to add for AT users, consider making it visible for all users.
		- Not all elements can be given an accessible name. Neither `aria-label` nor `aria-labelledby` should be used with non-interactive elements, inline structural roles such as with `code`, `term`, and `emphasis`, and roles not be mapped to the accessibility API, including `presentation`, `none`, and `hidden`. The `aria-label` attribute is intended for interactive elements only, including links, videos, form controls, and those with [landmark roles](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles) or [widget roles](/en-US/docs/Web/Accessibility/ARIA/Roles#2._widget_roles); `aria-label` provides an accessible name when no visible label exists in the DOM.

fix(aria-label): Improve page for clarity #32688

fix(aria-label): Improve page for clarity #32688

Conversation

dipikabh commented Mar 14, 2024 • edited

Description

Motivation

Related issues and pull requests

github-actions bot commented Mar 14, 2024 • edited

estelle left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dipikabh Mar 22, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dipikabh commented Mar 22, 2024

estelle left a comment

Choose a reason for hiding this comment

dipikabh commented Mar 27, 2024

dipikabh commented Mar 14, 2024 •

edited

github-actions bot commented Mar 14, 2024 •

edited

dipikabh Mar 22, 2024 •

edited