From 0e28ff15d7f659df722618625246c8b4990b6601 Mon Sep 17 00:00:00 2001 From: Scott O'Hara Date: Wed, 24 Nov 2021 10:43:10 -0500 Subject: [PATCH 1/3] Editorial: clarify expectations for name/desc verbosity closes #1649 These editorial changes attempt to clarify that a description _doesn't have to be verbose_. It also adjusts some wording so when talking about an accessible name, the spec is saying that, and not using the term "label" This update touches `aria-labelledby` and `aria-describedby` - because they share the same paragraph between the two. It also touches `aria-description` which also was semi-reusing the paragraph that was repeated between `aria-labelledby` and `aria-describedby` - but it also needed a few wording changes. Happy for others to add onto this or make further wording adjustments as need be. --- index.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.html b/index.html index 3f86a4406..a3e53d478 100644 --- a/index.html +++ b/index.html @@ -11217,7 +11217,7 @@

Definitions of States and Properties (all aria-* attributes)

aria-describedby

Identifies the element (or elements) that describes the object. See related aria-labelledby and aria-description.

-

The aria-labelledby attribute is similar to aria-describedby in that both reference other elements to calculate a text alternative, but a label should be concise, where a description is intended to provide more verbose information.

+

The aria-labelledby attribute is similar to aria-describedby in that both reference other elements to calculate a text alternative. While a concise accessible name is preferrable, a description can either be concise, or provide more verbose information.

The element or elements referenced by the aria-describedby comprise the entire description. Include ID references to multiple elements if necessary, or enclose a set of elements (e.g., paragraphs) with the element referenced by the ID.

@@ -11259,7 +11259,7 @@

Definitions of States and Properties (all aria-* attributes)

aria-description

Defines a string value that describes or annotates the current element. See related aria-describedby.

-

The aria-description attribute is similar to aria-label in that both provide a flat string to associate with the element, but a label should be concise, whereas a description is intended to provide more verbose information.

+

The aria-description attribute is similar to aria-label in that both provide a flat string to associate with the element (an accessible description, and name, respectively). Unlike an accessible name, which is generally preferred to be concise, a description can provide more verbose information, as necessary.

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. However, if the description text is available in the DOM, authors SHOULD NOT use aria-description, but should use one of the following instead:

From 6122cd4cf15136ea7a964da7b10de13bb7b7e2e3 Mon Sep 17 00:00:00 2001 From: Scott O'Hara Date: Fri, 26 Nov 2021 13:12:36 -0500 Subject: [PATCH 2/3] Update index.html --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index a3e53d478..aeb3093de 100644 --- a/index.html +++ b/index.html @@ -11217,7 +11217,7 @@

Definitions of States and Properties (all aria-* attributes)

aria-describedby

Identifies the element (or elements) that describes the object. See related aria-labelledby and aria-description.

-

The aria-labelledby attribute is similar to aria-describedby in that both reference other elements to calculate a text alternative. While a concise accessible name is preferrable, a description can either be concise, or provide more verbose information.

+

The aria-labelledby attribute is similar to aria-describedby in that both reference other elements to calculate a text alternative (an accessible name, and description, respectively). While a concise accessible name is preferable, a description can either be concise, or provide more verbose information.

The element or elements referenced by the aria-describedby comprise the entire description. Include ID references to multiple elements if necessary, or enclose a set of elements (e.g., paragraphs) with the element referenced by the ID.

From f5edd04f0f43f4c0440cf91b532001d804b54b28 Mon Sep 17 00:00:00 2001 From: Scott O'Hara Date: Fri, 26 Nov 2021 13:12:42 -0500 Subject: [PATCH 3/3] Update index.html --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index aeb3093de..da7b45a58 100644 --- a/index.html +++ b/index.html @@ -12000,7 +12000,7 @@

Definitions of States and Properties (all aria-* attributes)

Identifies the element (or elements) that labels the current element. See related aria-label and aria-describedby.

The purpose of aria-labelledby is the same as that of aria-label. It provides the user with a recognizable name of the object. The most common accessibility API mapping for a label is the accessible name property.

If the interface is such that it is not possible to have a visible label on the screen, authors SHOULD use aria-label and SHOULD NOT use 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.

-

The aria-labelledby attribute is similar to aria-describedby in that both reference other elements to calculate a text alternative (an accessible name, and description, respectively). While a concise accessible name is preferrable, a description can either be concise, or provide more verbose information.

+

The aria-labelledby attribute is similar to aria-describedby in that both reference other elements to calculate a text alternative (an accessible name, and description, respectively). While a concise accessible name is preferable, a description can either be concise, or provide more verbose information.

The expected spelling of this property in U.S. English is "labeledby." However, the accessibility API features to which this property is mapped have established the "labelledby" spelling. This property is spelled that way to match the convention and minimize the difficulty for developers.