fix(aria-label): Improve page for clarity

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")}}, can get their accessible name from their content. For example, given `<a href="foo.html">Bar</a>`, the accessible name of this hyperlink 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 name from the content of associated elements. If some parent elements such as {{HTMLElement("fieldset")}} and {{HTMLElement("table")}} contain a descendant {{HTMLElement("fieldset")}} or {{HTMLElement("caption")}} 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 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.
 
-With some elements, like {{HTMLElement("img")}}, the accessible name comes from its attributes, in this case, the `alt` attribute value. Given `<img src="grape.jpg" alt="banana"/>`, the image's accessible name is "banana."
+For some elements like {{HTMLElement("img")}}, the accessible name comes from their attributes; for example, the `alt` attribute in the case of {{HTMLElement("img")}}. Given `<img src="grape.jpg" alt="banana"/>`, the image's accessible name is "banana."
 
 To create an association between visible content and an element or multiple text nodes and an element, the [`aria-labeledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) attribute can be used. If there is no visible text to associate with a UI element needing an accessible name, the [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute can be used. Names should not be added to elements marking up inline text, like {{HTMLElement("code")}}, {{HTMLElement("del")}}, and {{HTMLElement("mark")}}.
 

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

@@ -9,9 +9,11 @@ The `aria-label` attribute defines a string value that labels an interactive ele
 
 ## Description
 
-Sometimes the default [accessible name](https://w3c.github.io/accname/#dfn-accessible-name) of an element is missing, or does not accurately describe its contents, and there is no content visible in the DOM that can be associated with the object to give it meaning. A common example is a button containing an SVG or [icon font (which you shouldn't be using)](https://www.youtube.com/watch?v=9xXBYcWgCHA) without any text.
+Sometimes, the default {{Glossary("accessible_name", "accessible name")}} of an element is missing or the accessible name does not accurately describe the contents of the element and there is no content visible in the DOM that can be associated with the object to give it meaning. A common example of such an element is a button containing an SVG or an icon font without any text. (Check out this [video about you shouldn't use icon fonts](https://www.youtube.com/watch?v=9xXBYcWgCHA).)
 
-In cases where an interactive element has no accessible name, or an accessible name that isn't accurate, and there is no content visible in the DOM that can be referenced via the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) attribute, the `aria-label` attribute can be used to define a string that labels the interactive element on which it is set. This provides the element with its accessible name.
+In cases where an interactive element has no accessible name or an accessible name is not accurate and there is no content visible in the DOM that can be referenced via the [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) attribute, the `aria-label` attribute can be used to define a string that labels the interactive element on which it is set. This provides the interactive element with its accessible name.
+
+The code below shows an example of how to use the `aria-label` attribute to provide an accessible name for a `<button>` element. The button in this example contains an SVG graphic and lacks textual content, making the `aria-label` essential for screen reader users to understand its function, which in this case is indicated as "Close".
 
 ```html
 <button aria-label="Close" onclick="myDialog.close()">
@@ -28,29 +30,30 @@ In cases where an interactive element has no accessible name, or an accessible n
 </button>
 ```
 
-> **Note:** `aria-label` is intended for use on interactive elements, or elements made to be interactive via other ARIA declarations, when there is no appropriate text visible in the DOM that could be referenced as a label
+> **Note:** `aria-label` is intended for interactive elements or for elements made interactive via other ARIA declarations when there's no visible text in the DOM to serve as a label.
 
 Most content has an accessible name generated from its immediate wrapping element's text content. Accessible names can also be created by certain attributes or associated elements.
 
 By default, a button's accessible name is the content between the opening and closing {{HTMLElement('button')}} tags, an image's accessible name is the content of its [`alt`](/en-US/docs/Web/HTML/Element/img#alt) attribute, and a form input's accessible name is the content of the associated {{HTMLElement('label')}} element.
 
-If none of these options are available, or if the default accessible name is not appropriate, use the `aria-label` attribute to define the accessible name of an element.
-
-`aria-label` can be used in cases where text that could label the element is _not_ visible. If there is visible text that labels an element, use [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby) instead.
+If none of these options are available or if the default accessible name is not appropriate, use the `aria-label` attribute to define the accessible name of an element.
 
-The purpose of `aria-label` is the same as `aria-labelledby`. Both provide an accessible name for an element. If there is no visible name for the element you can reference, use `aria-label` to provide the user with a recognizable accessible name. If the label text is available in the DOM, and referencing the DOM content and acceptable user experience, prefer to use `aria-labelledby`. Don't include both. If both are present on the same element, `aria-labelledby` will take precedence over `aria-label`.
+> **Note:** While `aria-label` can be used on any element that can have an accessible name, in practice however, it is supported only on interactive elements, [widgets](/en-US/docs/Web/Accessibility/ARIA/Roles#2._widget_roles), [landmarks](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles), images, and iframes.
 
-> **Note:** While `aria-label` is allowed on any element that can have an accessible name, in practice, `aria-label` is only supported on interactive elements, widgets, landmarks, images and iframes.
+When using `aria-label`, you also need to consider [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby):
 
-The `aria-label` attribute can be used with regular, semantic HTML elements; it is not limited to elements that have an [ARIA `role`](/en-US/docs/Web/Accessibility/ARIA/Roles) assigned.
+- `aria-label` can be used in cases where text that could label the element is _not_ visible. If there is visible text that labels an element, use `aria-labelledby` instead.
+- The purpose of `aria-label` is the same as `aria-labelledby`. Both provide an accessible name for an element. If there is no visible name for the element you can reference, use `aria-label` to provide the user with a recognizable accessible name. If label text is available in the DOM and it's possible to reference it for an acceptable user experience, prefer to use `aria-labelledby`. Don't use both on the same element because `aria-labelledby` will take precedence over `aria-label` if both are applied.
 
-Don't "overuse" `aria-label`. For example, use visible text with `aria-describedby` or `aria-description`, not `aria-label`, to provide additional instructions or clarify the UI. Always remember, you don't need to target instructions to screen readers only; if instructions are needed, provide them to everyone (or, preferably, make your UI more intuitive).
+Keep the following additional guidelines in mind when using `aria-label`:
 
-Not all elements can be given an accessible name. Neither `aria-label` nor `aria-labelledby` should be used with non-interactive elements or inline structural role such as with `code`, `term`, or `emphasis` nor roles whose semantics will not be mapped to the accessibility API, including `presentation`, `none`, and `hidden`. The `aria-label` attribute is intended for interactive elements only. Use `aria-label` to ensure an accessible name is provided when none is visible in the DOM for all interactive elements, like links, videos, form controls, [landmark roles](/en-US/docs/Web/Accessibility/ARIA/Roles#3._landmark_roles), and [widget roles](/en-US/docs/Web/Accessibility/ARIA/Roles#2._widget_roles).
+- The `aria-label` attribute can be used with regular, semantic HTML elements; it is not limited to elements that have an [ARIA `role`](/en-US/docs/Web/Accessibility/ARIA/Roles) assigned.
+- Don't "overuse" `aria-label`. Remember that it's primarily for assistive technology. To provide additional instructions or to clarify the UI, use visible text with `aria-describedby` or [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-description), not `aria-label`. Instructions should be accessible to all users, not just to those with screen readers (or preferably, make your UI more intuitive).
 
-If you give your {{HTMLElement('iframe')}}s a `title`, your images an `alt` attributes, and your input's associated {{HTMLElement('label')}}s, `aria-label` is not necessary. But, if present, the `aria-label` will take precedence over the `title`, `alt` and `<label>` as your `iframe`, image, or input's accessible name, respectively.
+  > **Note:** Since `aria-label` content isn't displayed outside assistive technologies, consider making important information visible for all users.
 
-> **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 inline structural roles such as with `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](/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.
+- If you assign a `title` to an {{HTMLElement('iframe')}}, define an `alt` attribute for an {{HTMLElement('img')}}, or add {{HTMLElement('label')}} for an {{HTMLElement('input')}}, `aria-label` is not necessary. However, if an `aria-label` attribute is present, it will take precedence over the iframe's `title`, the image's `alt`, or the input's `<label>` text as the accessible name for that element.
 
 ## Values
 
@@ -66,12 +69,13 @@ If you give your {{HTMLElement('iframe')}}s a `title`, your images an `alt` attr
 
 ## Associated roles
 
-Used in almost all roles **except** roles that can not be provided an accessible name by the author.
+Used in almost all roles **except** roles that cannot be provided an accessible name by the author.
 
 The `aria-label` attribute is **NOT** supported in:
 
 - [`code`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles)
 - [`caption`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles)
+- [`definition`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles)
 - [`deletion`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles)
 - [`emphasis`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles)
 - [`generic`](/en-US/docs/Web/Accessibility/ARIA/Roles/generic_role)
@@ -86,15 +90,14 @@ The `aria-label` attribute is **NOT** supported in:
 - [`term`](/en-US/docs/Web/Accessibility/ARIA/Roles/term_role)
 - [`time`](/en-US/docs/Web/Accessibility/ARIA/Roles/structural_roles)
 
-> **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.
-
 ## Specifications
 
 {{Specifications}}
 
 ## See also
 
 - {{HTMLElement('label')}} element
+- [`aria-description`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-description)
 - [`aria-labelledby`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-labelledby)
 - [Using HTML landmark roles to improve accessibility](/en-US/blog/aria-accessibility-html-landmark-roles/) on MDN blog (2023)