From de49b6102d87213d84ae17be65c5b54cd76af3cc Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Thu, 28 Feb 2019 14:42:26 +0100 Subject: [PATCH 001/131] Guideline for labeling and describing Fixes #70, fixes #74. --- draft-labelling-describing.md | 105 ++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 draft-labelling-describing.md diff --git a/draft-labelling-describing.md b/draft-labelling-describing.md new file mode 100644 index 0000000000..b2dd89a489 --- /dev/null +++ b/draft-labelling-describing.md @@ -0,0 +1,105 @@ +Labeling and Describing + +## Labels + +A label is used as the accessible name for an element. + +For elements with certain roles, the label is taken from the element’s contents by default. This can be overridden with a label from the author by using the aria-labelledby or aria-label attributes. If the label from the element’s contents is appropriate, then it should not be overridden with those attributes. + +In the following example, a link (with default role "link") gets its label from the element’s contents. + +``` +Home +``` + + +The following roles get the label from the contents by default: + +* button + +* cell + +* checkbox + +* columnheader + +* gridcell + +* heading + +* link + +* menuitem + +* menuitemcheckbox + +* menuitemradio + +* option + +* radio + +* row + +* rowgroup + +* rowheader + +* sectionhead + +* switch + +* tab + +* tooltip + +* treeitem + +If the element’s contents is not appropriate as a label, but there is an element that can be used as the label, then authors should use the aria-labelledby attribute. + +In the following example, an element with the "switch" role is labelled by a previous sibling element. + +``` +Night mode + +``` + + +In some cases the combination of the element’s contents and another element would be appropriate as a label. In such situations, the aria-labelledby should be used and reference both the element itself and the other element. + +In the following example, a "read more" link is labelled by the element itself and the article’s heading, resulting in “Read more… 7 ways you can help save the bees”. + +``` +

7 ways you can help save the bees

+

Bees are disappearing rapidly. +Here are seven things you can do to help.

+

Read more...

+``` + + +If there is no visible label that is appropriate, authors should use the aria-label attribute to set the label for the element. + +In the following example, a close button contains an "X" and is given the label “Close” using the aria-label attribute. + +``` + +``` + + +### Accessible name calculation + +aria-label vs aria-labelledby + +aria-placeholder, placeholder, title + +## Descriptions + +aria-describedby + +aria-details + +aria-roledescription + +### Accessible description calculation + +aria-describedby, aria-details, aria-placeholder?, placeholder, title From 713aa1feae522bac2b340efce0a39361d55b7a3d Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 4 Mar 2019 16:29:51 +0100 Subject: [PATCH 002/131] Write about roles that don't get name from content Also remove sectionhead as it is an abstract role, and include an early draft of accessible name calculation. --- draft-labelling-describing.md | 48 ++++++++++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 4 deletions(-) diff --git a/draft-labelling-describing.md b/draft-labelling-describing.md index b2dd89a489..3955a3a0a4 100644 --- a/draft-labelling-describing.md +++ b/draft-labelling-describing.md @@ -45,8 +45,6 @@ The following roles get the label from the contents by default: * rowheader -* sectionhead - * switch * tab @@ -86,11 +84,53 @@ In the following example, a close button contains an "X" and is given the label ``` +Other roles do not get the label from the contents of the element. In these cases, an author-provided label does not override the element’s contents, but augments it. Examples of such roles are (note that this is not a complete list): + +* alertdialog + +* application + +* article + +* banner + +* complementary + +* navigation + +* radiogroup + +* search + +* status + +For example, the navigation landmark could be labeled with the purpose of the landmark. In the following snippet, a breadcrumbs navigation is labeled using the aria-label attribute. + +``` +
+ You are here: + Home > + Books > + Children's books +
+``` + + ### Accessible name calculation -aria-label vs aria-labelledby +User agents follow the accessible name calculation algorithm to get the label for an element. + +The following attributes are considered when calculating the accessible name, in this order: + +1. aria-labelledby + +2. aria-label (with some exceptions) + +3. Host-language specific attributes or elements (e.g. the title attribute in HTML) + +4. In some cases, for widgets that have a value, that value. -aria-placeholder, placeholder, title +5. If the element’s role allows name from content, the element’s contents. ## Descriptions From ae9a5edf510c7aff73e7e11df669986e2079a83d Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Thu, 7 Mar 2019 14:59:55 +0100 Subject: [PATCH 003/131] Say accessible name instead of label; flesh out accessible name calculation --- draft-labelling-describing.md | 104 +++++++++++++++++++++++++++------- 1 file changed, 83 insertions(+), 21 deletions(-) diff --git a/draft-labelling-describing.md b/draft-labelling-describing.md index 3955a3a0a4..9ba8530c6a 100644 --- a/draft-labelling-describing.md +++ b/draft-labelling-describing.md @@ -1,19 +1,25 @@ Labeling and Describing -## Labels +## Introduction -A label is used as the accessible name for an element. +An accessible name is a name or a label used to identify the element for users of assistive technology. For example, a button’s accessible name can be "OK". -For elements with certain roles, the label is taken from the element’s contents by default. This can be overridden with a label from the author by using the aria-labelledby or aria-label attributes. If the label from the element’s contents is appropriate, then it should not be overridden with those attributes. +An accessible description complements the accessible name with a description. An accessible description is always optional, and if present it does not need to be as brief as an accessible name. -In the following example, a link (with default role "link") gets its label from the element’s contents. +## Accessible name + +### Name from content by default + +For elements with certain roles, the accessible name is taken from the element’s contents by default. In the following example, a link (with default role "link") gets its accessible name from the element’s contents (“Home”). ``` Home ``` -The following roles get the label from the contents by default: +The accessible name can be set explicitly by using the aria-labelledby or aria-label attributes. If the accessible name from the element’s contents is already good, then don’t use the aria-labelledby or aria-label attributes. + +The following roles get the accessible name from the contents by default: * button @@ -53,9 +59,9 @@ The following roles get the label from the contents by default: * treeitem -If the element’s contents is not appropriate as a label, but there is an element that can be used as the label, then authors should use the aria-labelledby attribute. +If the element’s contents is not appropriate as a label, but there is an element that can be used as the label, then use the aria-labelledby attribute. -In the following example, an element with the "switch" role is labelled by a previous sibling element. +In the following example, an element with the "switch" role is labeled by a previous sibling element. ``` Night mode @@ -63,28 +69,40 @@ In the following example, an element with the "switch" role is labelled by a pre ``` -In some cases the combination of the element’s contents and another element would be appropriate as a label. In such situations, the aria-labelledby should be used and reference both the element itself and the other element. +Because a span element is used for the switch control, the HTML label element cannot be used to label it, since it only works with HTML elements that are form controls. However, the switch role can be used on an input element with type="checkbox”, and then HTML label can be used. + +``` + + +``` + + +In some cases, the combination of the element’s contents and another element would be appropriate as an accessible name. In such situations, use the aria-labelledby and reference both the element itself and the other element. -In the following example, a "read more" link is labelled by the element itself and the article’s heading, resulting in “Read more… 7 ways you can help save the bees”. +In the following example, a "read more" link is labeled by the element itself and the article’s heading, resulting in “Read more… 7 ways you can help save the bees”. ```

7 ways you can help save the bees

Bees are disappearing rapidly. Here are seven things you can do to help.

-

Read more...

+

Read more...

``` -If there is no visible label that is appropriate, authors should use the aria-label attribute to set the label for the element. +If there is no content that is appropriate to use as the accessible name, use the aria-label attribute to set the label for the element directly. -In the following example, a close button contains an "X" and is given the label “Close” using the aria-label attribute. +In the following example, a close button contains an "X" and is given the accessible name “Close” using the aria-label attribute. ``` ``` -Other roles do not get the label from the contents of the element. In these cases, an author-provided label does not override the element’s contents, but augments it. Examples of such roles are (note that this is not a complete list): +### Name from author only + +Some roles do not get the accessible name from the contents of the element. An accessible name set with the aria-labelledby or aria-label attributes does not override the contents of such elements. + +Examples of such roles are (note that this is not a complete list): * alertdialog @@ -104,7 +122,7 @@ Other roles do not get the label from the contents of the element. In these case * status -For example, the navigation landmark could be labeled with the purpose of the landmark. In the following snippet, a breadcrumbs navigation is labeled using the aria-label attribute. +For example, the navigation landmark could be labeled with the purpose of the landmark. In the following snippet, a breadcrumbs navigation region is labeled using the aria-label attribute. ```
@@ -116,21 +134,65 @@ For example, the navigation landmark could be labeled with the purpose of the la ``` +Alternatively, this can use the HTML nav element, which has the "navigation" role by default: + +``` + +``` + + ### Accessible name calculation -User agents follow the accessible name calculation algorithm to get the label for an element. +User agents follow the accessible name calculation algorithm to get the label for an element. This is defined in [https://w3c.github.io/accname/](https://w3c.github.io/accname/) and [https://w3c.github.io/html-aam/](https://w3c.github.io/html-aam/) for HTML. -The following attributes are considered when calculating the accessible name, in this order: +The aria-labelledby attribute is used first, then the aria-label attribute, then host-language-specific attributes or elements (e.g., the alt attribute on HTML img) or, for roles that can take the name from content, the element’s contents. -1. aria-labelledby +For example, an img element with just a src attribute has no accessible name (don’t do this): -2. aria-label (with some exceptions) +``` + +``` + + +If there is a title attribute, then that is used as the accessible name: + +``` + +``` + + +If there is also an alt attribute, then that is used as the accessible name, and the title attribute is instead used as the accessible description: -3. Host-language specific attributes or elements (e.g. the title attribute in HTML) +``` +The Queen, holding a pigeon. +``` -4. In some cases, for widgets that have a value, that value. -5. If the element’s role allows name from content, the element’s contents. +If there is also an aria-label attribute, then that overrides the alt attribute: + +``` +Sorry, this image failed to load. +``` + + +If there is also an aria-labelledby attribute, that wins over the other attributes (don’t do this): + +``` +Sorry, this image failed to load. +The Queen, holding a pigeon. +``` + ## Descriptions From ce15b81ccd3f67f69cdac2947a7a42cd21eea103 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Tue, 12 Mar 2019 17:06:39 -0400 Subject: [PATCH 004/131] Rewrite and expand on labels - Use "explicit label" and "implicit label" instead of "name from author" and "name from content". - Expand on accessible name calculation. --- draft-labelling-describing.md | 171 ++++++++++++++++++++-------------- 1 file changed, 99 insertions(+), 72 deletions(-) diff --git a/draft-labelling-describing.md b/draft-labelling-describing.md index 9ba8530c6a..375bc68b0c 100644 --- a/draft-labelling-describing.md +++ b/draft-labelling-describing.md @@ -2,64 +2,70 @@ Labeling and Describing ## Introduction -An accessible name is a name or a label used to identify the element for users of assistive technology. For example, a button’s accessible name can be "OK". +A label, also known as accessible name, is a name or a label used to identify the element for users of assistive technology. For example, a button’s label can be "OK". -An accessible description complements the accessible name with a description. An accessible description is always optional, and if present it does not need to be as brief as an accessible name. +An accessible description complements the label with a description. An accessible description is always optional, and if present it does not need to be as brief as a label. -## Accessible name +## Labels -### Name from content by default +There are two different ways to get the label for an element, depending on the element’s role. -For elements with certain roles, the accessible name is taken from the element’s contents by default. In the following example, a link (with default role "link") gets its accessible name from the element’s contents (“Home”). +* Implicit label by default + +* Explicit label only + +### Implicit label by default + +For elements with certain roles, the label is taken from the element’s contents by default. In the following example, a link (with default role `link`) gets its label from the element’s contents ("Home"). ``` Home ``` -The accessible name can be set explicitly by using the aria-labelledby or aria-label attributes. If the accessible name from the element’s contents is already good, then don’t use the aria-labelledby or aria-label attributes. +The label also can be set explicitly by using the `aria-labelledby` or `aria-label` attributes. If the implicit label (from the element’s contents) is already good, then don’t use the `aria-labelledby` or `aria-label` attributes. -The following roles get the accessible name from the contents by default: +The following roles get the label from the contents by default: -* button +* `button` -* cell +* `cell` -* checkbox +* `checkbox` -* columnheader +* `columnheader` -* gridcell +* `gridcell` -* heading +* `heading` -* link +* `link` -* menuitem +* `menuitem` -* menuitemcheckbox +* `menuitemcheckbox` -* menuitemradio +* `menuitemradio` -* option +* `option` -* radio +* `radio` -* row +* `row` -* rowgroup +* `rowgroup` -* rowheader +* `rowheader` -* switch +* `switch` -* tab +* `tab` -* tooltip +* `tooltip` -* treeitem +* `treeitem` -If the element’s contents is not appropriate as a label, but there is an element that can be used as the label, then use the aria-labelledby attribute. +If the element’s contents are not appropriate as a label, but there is an element that can be used as the label, then use the `aria-labelledby` attribute. In the following example, an element with the "switch" role is labeled by a previous sibling element. @@ -69,7 +75,7 @@ In the following example, an element with the "switch" role is labeled by a prev ``` -Because a span element is used for the switch control, the HTML label element cannot be used to label it, since it only works with HTML elements that are form controls. However, the switch role can be used on an input element with type="checkbox”, and then HTML label can be used. +Because a `span` element is used for the switch control, the HTML `label` element cannot be used to label it, since it only works with HTML elements that are form controls. However, the `switch` role can be used on an `input` element with `type="checkbox”`, and then HTML `label` can be used. ``` @@ -77,7 +83,7 @@ Because a span element is used for the switch control, the HTML label element ca ``` -In some cases, the combination of the element’s contents and another element would be appropriate as an accessible name. In such situations, use the aria-labelledby and reference both the element itself and the other element. +In some cases, the combination of the element’s contents and another element would be appropriate as a label. In such situations, use the `aria-labelledby` and reference both the element itself and the other element. In the following example, a "read more" link is labeled by the element itself and the article’s heading, resulting in “Read more… 7 ways you can help save the bees”. @@ -89,56 +95,44 @@ Here are seven things you can do to help.

``` -If there is no content that is appropriate to use as the accessible name, use the aria-label attribute to set the label for the element directly. +If there is no content that is appropriate to use as the label, then use the `aria-label` attribute to set the label for the element directly. -In the following example, a close button contains an "X" and is given the accessible name “Close” using the aria-label attribute. +In the following example, a close button contains an "X" and is given the label “Close” using the `aria-label` attribute. ``` ``` -### Name from author only +### Explicit label only -Some roles do not get the accessible name from the contents of the element. An accessible name set with the aria-labelledby or aria-label attributes does not override the contents of such elements. +Some roles do not get the label from the contents of the element; a label can only be set explicitly using the `aria-labelledby` or `aria-label` attributes. An explicit label does not override the contents of such elements. Examples of such roles are (note that this is not a complete list): -* alertdialog +* `alertdialog` -* application +* `application` -* article +* `article` -* banner +* `banner` -* complementary +* `complementary` -* navigation +* `navigation` -* radiogroup +* `radiogroup` -* search +* `search` -* status +* `status` -For example, the navigation landmark could be labeled with the purpose of the landmark. In the following snippet, a breadcrumbs navigation region is labeled using the aria-label attribute. +For example, the `navigation` landmark could be labeled with the purpose of the landmark. In the following snippet, a "breadcrumbs" navigation region is labeled explicitly using the `aria-labelledby` attribute. The HTML `nav` element has the `navigation` role by default. ``` -
- You are here: - Home > - Books > - Children's books -
-``` - - -Alternatively, this can use the HTML nav element, which has the "navigation" role by default: - -``` -
``` +It is also possible to reference an element using `aria-labelledby` even if that element is hidden. In the following example, the `span` element could be styled with CSS `display: none` and the `nav` element would still have the label "You are here:". + +``` + +``` + ## Descriptions An element can be given an accessible description using the `aria-describedby` attribute or the `aria-details` attribute. @@ -238,7 +249,9 @@ will be permanently removed after 30 days.

This description will be presented to the user as plain text. For example, if the description contains an HTML `img` element, a text equivalent of the image is computed. ``` - + ...

Items in the trash will be permanently removed after 30 days.

@@ -267,6 +280,19 @@ If both `aria-details` and `aria-describedby` are specified on an element, only ### Accessible description calculation -Like the accessible name calculation, the accessible description calculation produces a plain text string for an element. This algorithm is not used for the `aria-details` attribute. +Like the accessible name calculation (see the earlier section), the accessible description calculation produces a plain text string for an element. This algorithm is not used for the `aria-details` attribute. + +The accessible description calculation algorithm is the same algorithm as the accessible name calculation algorithm, but it branches off in some places depending on whether a name or a description is being calculated. In particular, when collecting an accessible description, the algorithm uses `aria-describedby` instead of `aria-labelledby`. -TODO ... +As with `aria-labelledby`, it is possible to reference an element using `aria-describedby` even if that element is hidden. + +For example, a text field in a form could have a description that is hidden by default, but can be revealed on request using a disclosure widget. The description could also be referenced from the text field directly with `aria-describedby`. The accessible description for the `input` element is "Your username is the name that you use to log in to this service.". + +``` + + + + +``` From 801539f77b45765dbfc600dd8a1eaba1f6d214b9 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Thu, 25 Apr 2019 16:35:32 +0200 Subject: [PATCH 007/131] Try to address Matt's comments --- draft-labelling-describing.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/draft-labelling-describing.md b/draft-labelling-describing.md index 29f069a3ff..cc5475e9b2 100644 --- a/draft-labelling-describing.md +++ b/draft-labelling-describing.md @@ -8,22 +8,24 @@ An accessible description complements the label with a description. An accessibl ## Labels -There are two different ways to get the label for an element, depending on the element’s role. +There are two different kinds of labels, depending on the element’s role. The difference is both in how the label is computed for the element, and how the element is represented to assistive technologies. -* Implicit label by default +* Label that represents the element. The label is taken from the element's contents, unless `aria-labelledby` or `aria-label` attributes are used. Only the label is represented to users of assistive tecnologies. -* Explicit label only +* Label that augments the element. The label is not taken from the element's contents (by default). A label can be set using `aria-labelledby` or `aria-label`. The label will augment the element; both the label and the element's contents are exposed to users of assistive technology. -### Implicit label by default -For elements with certain roles, the label is taken from the element’s contents by default. In the following example, a link (with default role `link`) gets its label from the element’s contents ("Home"). +### Label that represents the element + +For elements with certain roles, the label is taken from the element’s contents by default, and the label will represent the element when communicated to assistive technologies. In the following example, a link (with default role `link`) gets its label from the element’s contents ("Home"). ``` Home ``` +This could be rendered to assistive technology as "link, Home"; the role and the label, not not repeating the content ("link, Home, Home"). -The label also can be set explicitly by using the `aria-labelledby` or `aria-label` attributes. If the implicit label (from the element’s contents) is already good, then don’t use the `aria-labelledby` or `aria-label` attributes. +The label also can be set explicitly by using the `aria-labelledby` or `aria-label` attributes. If the label from the element’s contents is already good, then don’t use the `aria-labelledby` or `aria-label` attributes. The following roles get the label from the contents by default: @@ -104,9 +106,9 @@ In the following example, a close button contains an "X" and is given the label ``` -### Explicit label only +### Label that augments the element -Some roles do not get the label from the contents of the element; a label can only be set explicitly using the `aria-labelledby` or `aria-label` attributes. An explicit label does not override the contents of such elements. +Some roles do not get the label from the contents of the element; a label can only be set explicitly using the `aria-labelledby` or `aria-label` attributes. For elements with these roles, a label augments the element, but does not override the contents. Examples of such roles are (note that this is not a complete list): @@ -152,11 +154,11 @@ User agents attempt to formulate labels for elements by walking through a list o 3. If the label is still empty, then host-language-specific attributes or elements (e.g., the `alt` attribute on HTML `img`) are used if present. -4. If the label is still empty, then for roles that can take implicit label by default, the element’s contents. +4. If the label is still empty, then for roles that can take label from the element's content, the element’s contents. 5. Finally, if the label is still empty, then host-langauge-specific tooltip attributes or elements (e.g., the `title` attribute in HTML) are used if present. -Steps 1-2 are explicit label, and steps 3-5 are implicit label. The final step is a fallback mechanism. Generally when labelling an element, use one of the non-fallback mechanisms. +The final step is a fallback mechanism. Generally when labelling an element, use one of the non-fallback mechanisms. For example, for the HTML `input` element, the `placeholder` attribute is used as a fallback labeling mechanism if nothing else results in a label. For an `input` element, it is better to use a `label` element, since it does not disappear visually when the user focuses the form control. @@ -264,7 +266,7 @@ In some cases, a plain text description is insufficient. The `aria-details` attr
Passenger 1 (adult) From 61f20ae26c4bce4d13c95c5ef91a9ad7001834bc Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Thu, 28 Feb 2019 14:42:26 +0100 Subject: [PATCH 008/131] Guideline for labeling and describing Fixes #70, fixes #74. --- draft-labelling-describing.md | 105 ++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 draft-labelling-describing.md diff --git a/draft-labelling-describing.md b/draft-labelling-describing.md new file mode 100644 index 0000000000..b2dd89a489 --- /dev/null +++ b/draft-labelling-describing.md @@ -0,0 +1,105 @@ +Labeling and Describing + +## Labels + +A label is used as the accessible name for an element. + +For elements with certain roles, the label is taken from the element’s contents by default. This can be overridden with a label from the author by using the aria-labelledby or aria-label attributes. If the label from the element’s contents is appropriate, then it should not be overridden with those attributes. + +In the following example, a link (with default role "link") gets its label from the element’s contents. + +``` +Home +``` + + +The following roles get the label from the contents by default: + +* button + +* cell + +* checkbox + +* columnheader + +* gridcell + +* heading + +* link + +* menuitem + +* menuitemcheckbox + +* menuitemradio + +* option + +* radio + +* row + +* rowgroup + +* rowheader + +* sectionhead + +* switch + +* tab + +* tooltip + +* treeitem + +If the element’s contents is not appropriate as a label, but there is an element that can be used as the label, then authors should use the aria-labelledby attribute. + +In the following example, an element with the "switch" role is labelled by a previous sibling element. + +``` +Night mode + +``` + + +In some cases the combination of the element’s contents and another element would be appropriate as a label. In such situations, the aria-labelledby should be used and reference both the element itself and the other element. + +In the following example, a "read more" link is labelled by the element itself and the article’s heading, resulting in “Read more… 7 ways you can help save the bees”. + +``` +

7 ways you can help save the bees

+

Bees are disappearing rapidly. +Here are seven things you can do to help.

+

Read more...

+``` + + +If there is no visible label that is appropriate, authors should use the aria-label attribute to set the label for the element. + +In the following example, a close button contains an "X" and is given the label “Close” using the aria-label attribute. + +``` + +``` + + +### Accessible name calculation + +aria-label vs aria-labelledby + +aria-placeholder, placeholder, title + +## Descriptions + +aria-describedby + +aria-details + +aria-roledescription + +### Accessible description calculation + +aria-describedby, aria-details, aria-placeholder?, placeholder, title From 879287127d16e7343547b645fb7a78051e7a3763 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 4 Mar 2019 16:29:51 +0100 Subject: [PATCH 009/131] Write about roles that don't get name from content Also remove sectionhead as it is an abstract role, and include an early draft of accessible name calculation. --- draft-labelling-describing.md | 48 ++++++++++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 4 deletions(-) diff --git a/draft-labelling-describing.md b/draft-labelling-describing.md index b2dd89a489..3955a3a0a4 100644 --- a/draft-labelling-describing.md +++ b/draft-labelling-describing.md @@ -45,8 +45,6 @@ The following roles get the label from the contents by default: * rowheader -* sectionhead - * switch * tab @@ -86,11 +84,53 @@ In the following example, a close button contains an "X" and is given the label ``` +Other roles do not get the label from the contents of the element. In these cases, an author-provided label does not override the element’s contents, but augments it. Examples of such roles are (note that this is not a complete list): + +* alertdialog + +* application + +* article + +* banner + +* complementary + +* navigation + +* radiogroup + +* search + +* status + +For example, the navigation landmark could be labeled with the purpose of the landmark. In the following snippet, a breadcrumbs navigation is labeled using the aria-label attribute. + +``` +
+ You are here: + Home > + Books > + Children's books +
+``` + + ### Accessible name calculation -aria-label vs aria-labelledby +User agents follow the accessible name calculation algorithm to get the label for an element. + +The following attributes are considered when calculating the accessible name, in this order: + +1. aria-labelledby + +2. aria-label (with some exceptions) + +3. Host-language specific attributes or elements (e.g. the title attribute in HTML) + +4. In some cases, for widgets that have a value, that value. -aria-placeholder, placeholder, title +5. If the element’s role allows name from content, the element’s contents. ## Descriptions From c3ec1e9ced6189a2b6b7a85a9e09e376c45a48eb Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Thu, 7 Mar 2019 14:59:55 +0100 Subject: [PATCH 010/131] Say accessible name instead of label; flesh out accessible name calculation --- draft-labelling-describing.md | 104 +++++++++++++++++++++++++++------- 1 file changed, 83 insertions(+), 21 deletions(-) diff --git a/draft-labelling-describing.md b/draft-labelling-describing.md index 3955a3a0a4..9ba8530c6a 100644 --- a/draft-labelling-describing.md +++ b/draft-labelling-describing.md @@ -1,19 +1,25 @@ Labeling and Describing -## Labels +## Introduction -A label is used as the accessible name for an element. +An accessible name is a name or a label used to identify the element for users of assistive technology. For example, a button’s accessible name can be "OK". -For elements with certain roles, the label is taken from the element’s contents by default. This can be overridden with a label from the author by using the aria-labelledby or aria-label attributes. If the label from the element’s contents is appropriate, then it should not be overridden with those attributes. +An accessible description complements the accessible name with a description. An accessible description is always optional, and if present it does not need to be as brief as an accessible name. -In the following example, a link (with default role "link") gets its label from the element’s contents. +## Accessible name + +### Name from content by default + +For elements with certain roles, the accessible name is taken from the element’s contents by default. In the following example, a link (with default role "link") gets its accessible name from the element’s contents (“Home”). ``` Home ``` -The following roles get the label from the contents by default: +The accessible name can be set explicitly by using the aria-labelledby or aria-label attributes. If the accessible name from the element’s contents is already good, then don’t use the aria-labelledby or aria-label attributes. + +The following roles get the accessible name from the contents by default: * button @@ -53,9 +59,9 @@ The following roles get the label from the contents by default: * treeitem -If the element’s contents is not appropriate as a label, but there is an element that can be used as the label, then authors should use the aria-labelledby attribute. +If the element’s contents is not appropriate as a label, but there is an element that can be used as the label, then use the aria-labelledby attribute. -In the following example, an element with the "switch" role is labelled by a previous sibling element. +In the following example, an element with the "switch" role is labeled by a previous sibling element. ``` Night mode @@ -63,28 +69,40 @@ In the following example, an element with the "switch" role is labelled by a pre ``` -In some cases the combination of the element’s contents and another element would be appropriate as a label. In such situations, the aria-labelledby should be used and reference both the element itself and the other element. +Because a span element is used for the switch control, the HTML label element cannot be used to label it, since it only works with HTML elements that are form controls. However, the switch role can be used on an input element with type="checkbox”, and then HTML label can be used. + +``` + + +``` + + +In some cases, the combination of the element’s contents and another element would be appropriate as an accessible name. In such situations, use the aria-labelledby and reference both the element itself and the other element. -In the following example, a "read more" link is labelled by the element itself and the article’s heading, resulting in “Read more… 7 ways you can help save the bees”. +In the following example, a "read more" link is labeled by the element itself and the article’s heading, resulting in “Read more… 7 ways you can help save the bees”. ```

7 ways you can help save the bees

Bees are disappearing rapidly. Here are seven things you can do to help.

-

Read more...

+

Read more...

``` -If there is no visible label that is appropriate, authors should use the aria-label attribute to set the label for the element. +If there is no content that is appropriate to use as the accessible name, use the aria-label attribute to set the label for the element directly. -In the following example, a close button contains an "X" and is given the label “Close” using the aria-label attribute. +In the following example, a close button contains an "X" and is given the accessible name “Close” using the aria-label attribute. ``` ``` -Other roles do not get the label from the contents of the element. In these cases, an author-provided label does not override the element’s contents, but augments it. Examples of such roles are (note that this is not a complete list): +### Name from author only + +Some roles do not get the accessible name from the contents of the element. An accessible name set with the aria-labelledby or aria-label attributes does not override the contents of such elements. + +Examples of such roles are (note that this is not a complete list): * alertdialog @@ -104,7 +122,7 @@ Other roles do not get the label from the contents of the element. In these case * status -For example, the navigation landmark could be labeled with the purpose of the landmark. In the following snippet, a breadcrumbs navigation is labeled using the aria-label attribute. +For example, the navigation landmark could be labeled with the purpose of the landmark. In the following snippet, a breadcrumbs navigation region is labeled using the aria-label attribute. ```
@@ -116,21 +134,65 @@ For example, the navigation landmark could be labeled with the purpose of the la ``` +Alternatively, this can use the HTML nav element, which has the "navigation" role by default: + +``` + +``` + + ### Accessible name calculation -User agents follow the accessible name calculation algorithm to get the label for an element. +User agents follow the accessible name calculation algorithm to get the label for an element. This is defined in [https://w3c.github.io/accname/](https://w3c.github.io/accname/) and [https://w3c.github.io/html-aam/](https://w3c.github.io/html-aam/) for HTML. -The following attributes are considered when calculating the accessible name, in this order: +The aria-labelledby attribute is used first, then the aria-label attribute, then host-language-specific attributes or elements (e.g., the alt attribute on HTML img) or, for roles that can take the name from content, the element’s contents. -1. aria-labelledby +For example, an img element with just a src attribute has no accessible name (don’t do this): -2. aria-label (with some exceptions) +``` + +``` + + +If there is a title attribute, then that is used as the accessible name: + +``` + +``` + + +If there is also an alt attribute, then that is used as the accessible name, and the title attribute is instead used as the accessible description: -3. Host-language specific attributes or elements (e.g. the title attribute in HTML) +``` +The Queen, holding a pigeon. +``` -4. In some cases, for widgets that have a value, that value. -5. If the element’s role allows name from content, the element’s contents. +If there is also an aria-label attribute, then that overrides the alt attribute: + +``` +Sorry, this image failed to load. +``` + + +If there is also an aria-labelledby attribute, that wins over the other attributes (don’t do this): + +``` +Sorry, this image failed to load. +The Queen, holding a pigeon. +``` + ## Descriptions From 6b4549288c1fdc71878da4afb29ece5b74e7de3e Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Tue, 12 Mar 2019 17:06:39 -0400 Subject: [PATCH 011/131] Rewrite and expand on labels - Use "explicit label" and "implicit label" instead of "name from author" and "name from content". - Expand on accessible name calculation. --- draft-labelling-describing.md | 171 ++++++++++++++++++++-------------- 1 file changed, 99 insertions(+), 72 deletions(-) diff --git a/draft-labelling-describing.md b/draft-labelling-describing.md index 9ba8530c6a..375bc68b0c 100644 --- a/draft-labelling-describing.md +++ b/draft-labelling-describing.md @@ -2,64 +2,70 @@ Labeling and Describing ## Introduction -An accessible name is a name or a label used to identify the element for users of assistive technology. For example, a button’s accessible name can be "OK". +A label, also known as accessible name, is a name or a label used to identify the element for users of assistive technology. For example, a button’s label can be "OK". -An accessible description complements the accessible name with a description. An accessible description is always optional, and if present it does not need to be as brief as an accessible name. +An accessible description complements the label with a description. An accessible description is always optional, and if present it does not need to be as brief as a label. -## Accessible name +## Labels -### Name from content by default +There are two different ways to get the label for an element, depending on the element’s role. -For elements with certain roles, the accessible name is taken from the element’s contents by default. In the following example, a link (with default role "link") gets its accessible name from the element’s contents (“Home”). +* Implicit label by default + +* Explicit label only + +### Implicit label by default + +For elements with certain roles, the label is taken from the element’s contents by default. In the following example, a link (with default role `link`) gets its label from the element’s contents ("Home"). ``` Home ``` -The accessible name can be set explicitly by using the aria-labelledby or aria-label attributes. If the accessible name from the element’s contents is already good, then don’t use the aria-labelledby or aria-label attributes. +The label also can be set explicitly by using the `aria-labelledby` or `aria-label` attributes. If the implicit label (from the element’s contents) is already good, then don’t use the `aria-labelledby` or `aria-label` attributes. -The following roles get the accessible name from the contents by default: +The following roles get the label from the contents by default: -* button +* `button` -* cell +* `cell` -* checkbox +* `checkbox` -* columnheader +* `columnheader` -* gridcell +* `gridcell` -* heading +* `heading` -* link +* `link` -* menuitem +* `menuitem` -* menuitemcheckbox +* `menuitemcheckbox` -* menuitemradio +* `menuitemradio` -* option +* `option` -* radio +* `radio` -* row +* `row` -* rowgroup +* `rowgroup` -* rowheader +* `rowheader` -* switch +* `switch` -* tab +* `tab` -* tooltip +* `tooltip` -* treeitem +* `treeitem` -If the element’s contents is not appropriate as a label, but there is an element that can be used as the label, then use the aria-labelledby attribute. +If the element’s contents are not appropriate as a label, but there is an element that can be used as the label, then use the `aria-labelledby` attribute. In the following example, an element with the "switch" role is labeled by a previous sibling element. @@ -69,7 +75,7 @@ In the following example, an element with the "switch" role is labeled by a prev ``` -Because a span element is used for the switch control, the HTML label element cannot be used to label it, since it only works with HTML elements that are form controls. However, the switch role can be used on an input element with type="checkbox”, and then HTML label can be used. +Because a `span` element is used for the switch control, the HTML `label` element cannot be used to label it, since it only works with HTML elements that are form controls. However, the `switch` role can be used on an `input` element with `type="checkbox”`, and then HTML `label` can be used. ``` @@ -77,7 +83,7 @@ Because a span element is used for the switch control, the HTML label element ca ``` -In some cases, the combination of the element’s contents and another element would be appropriate as an accessible name. In such situations, use the aria-labelledby and reference both the element itself and the other element. +In some cases, the combination of the element’s contents and another element would be appropriate as a label. In such situations, use the `aria-labelledby` and reference both the element itself and the other element. In the following example, a "read more" link is labeled by the element itself and the article’s heading, resulting in “Read more… 7 ways you can help save the bees”. @@ -89,56 +95,44 @@ Here are seven things you can do to help.

``` -If there is no content that is appropriate to use as the accessible name, use the aria-label attribute to set the label for the element directly. +If there is no content that is appropriate to use as the label, then use the `aria-label` attribute to set the label for the element directly. -In the following example, a close button contains an "X" and is given the accessible name “Close” using the aria-label attribute. +In the following example, a close button contains an "X" and is given the label “Close” using the `aria-label` attribute. ``` ``` -### Name from author only +### Explicit label only -Some roles do not get the accessible name from the contents of the element. An accessible name set with the aria-labelledby or aria-label attributes does not override the contents of such elements. +Some roles do not get the label from the contents of the element; a label can only be set explicitly using the `aria-labelledby` or `aria-label` attributes. An explicit label does not override the contents of such elements. Examples of such roles are (note that this is not a complete list): -* alertdialog +* `alertdialog` -* application +* `application` -* article +* `article` -* banner +* `banner` -* complementary +* `complementary` -* navigation +* `navigation` -* radiogroup +* `radiogroup` -* search +* `search` -* status +* `status` -For example, the navigation landmark could be labeled with the purpose of the landmark. In the following snippet, a breadcrumbs navigation region is labeled using the aria-label attribute. +For example, the `navigation` landmark could be labeled with the purpose of the landmark. In the following snippet, a "breadcrumbs" navigation region is labeled explicitly using the `aria-labelledby` attribute. The HTML `nav` element has the `navigation` role by default. ``` -
- You are here: - Home > - Books > - Children's books -
-``` - - -Alternatively, this can use the HTML nav element, which has the "navigation" role by default: - -``` -
``` +It is also possible to reference an element using `aria-labelledby` even if that element is hidden. In the following example, the `span` element could be styled with CSS `display: none` and the `nav` element would still have the label "You are here:". + +``` + +``` + ## Descriptions An element can be given an accessible description using the `aria-describedby` attribute or the `aria-details` attribute. @@ -238,7 +249,9 @@ will be permanently removed after 30 days.

This description will be presented to the user as plain text. For example, if the description contains an HTML `img` element, a text equivalent of the image is computed. ``` - + ...

Items in the trash will be permanently removed after 30 days.

@@ -267,6 +280,19 @@ If both `aria-details` and `aria-describedby` are specified on an element, only ### Accessible description calculation -Like the accessible name calculation, the accessible description calculation produces a plain text string for an element. This algorithm is not used for the `aria-details` attribute. +Like the accessible name calculation (see the earlier section), the accessible description calculation produces a plain text string for an element. This algorithm is not used for the `aria-details` attribute. + +The accessible description calculation algorithm is the same algorithm as the accessible name calculation algorithm, but it branches off in some places depending on whether a name or a description is being calculated. In particular, when collecting an accessible description, the algorithm uses `aria-describedby` instead of `aria-labelledby`. -TODO ... +As with `aria-labelledby`, it is possible to reference an element using `aria-describedby` even if that element is hidden. + +For example, a text field in a form could have a description that is hidden by default, but can be revealed on request using a disclosure widget. The description could also be referenced from the text field directly with `aria-describedby`. The accessible description for the `input` element is "Your username is the name that you use to log in to this service.". + +``` + + + + +``` From 78e912cafa714c75505a744a1c4dfc9f5fb71f53 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Thu, 25 Apr 2019 16:35:32 +0200 Subject: [PATCH 014/131] Try to address Matt's comments --- draft-labelling-describing.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/draft-labelling-describing.md b/draft-labelling-describing.md index 29f069a3ff..cc5475e9b2 100644 --- a/draft-labelling-describing.md +++ b/draft-labelling-describing.md @@ -8,22 +8,24 @@ An accessible description complements the label with a description. An accessibl ## Labels -There are two different ways to get the label for an element, depending on the element’s role. +There are two different kinds of labels, depending on the element’s role. The difference is both in how the label is computed for the element, and how the element is represented to assistive technologies. -* Implicit label by default +* Label that represents the element. The label is taken from the element's contents, unless `aria-labelledby` or `aria-label` attributes are used. Only the label is represented to users of assistive tecnologies. -* Explicit label only +* Label that augments the element. The label is not taken from the element's contents (by default). A label can be set using `aria-labelledby` or `aria-label`. The label will augment the element; both the label and the element's contents are exposed to users of assistive technology. -### Implicit label by default -For elements with certain roles, the label is taken from the element’s contents by default. In the following example, a link (with default role `link`) gets its label from the element’s contents ("Home"). +### Label that represents the element + +For elements with certain roles, the label is taken from the element’s contents by default, and the label will represent the element when communicated to assistive technologies. In the following example, a link (with default role `link`) gets its label from the element’s contents ("Home"). ``` Home ``` +This could be rendered to assistive technology as "link, Home"; the role and the label, not not repeating the content ("link, Home, Home"). -The label also can be set explicitly by using the `aria-labelledby` or `aria-label` attributes. If the implicit label (from the element’s contents) is already good, then don’t use the `aria-labelledby` or `aria-label` attributes. +The label also can be set explicitly by using the `aria-labelledby` or `aria-label` attributes. If the label from the element’s contents is already good, then don’t use the `aria-labelledby` or `aria-label` attributes. The following roles get the label from the contents by default: @@ -104,9 +106,9 @@ In the following example, a close button contains an "X" and is given the label ``` -### Explicit label only +### Label that augments the element -Some roles do not get the label from the contents of the element; a label can only be set explicitly using the `aria-labelledby` or `aria-label` attributes. An explicit label does not override the contents of such elements. +Some roles do not get the label from the contents of the element; a label can only be set explicitly using the `aria-labelledby` or `aria-label` attributes. For elements with these roles, a label augments the element, but does not override the contents. Examples of such roles are (note that this is not a complete list): @@ -152,11 +154,11 @@ User agents attempt to formulate labels for elements by walking through a list o 3. If the label is still empty, then host-language-specific attributes or elements (e.g., the `alt` attribute on HTML `img`) are used if present. -4. If the label is still empty, then for roles that can take implicit label by default, the element’s contents. +4. If the label is still empty, then for roles that can take label from the element's content, the element’s contents. 5. Finally, if the label is still empty, then host-langauge-specific tooltip attributes or elements (e.g., the `title` attribute in HTML) are used if present. -Steps 1-2 are explicit label, and steps 3-5 are implicit label. The final step is a fallback mechanism. Generally when labelling an element, use one of the non-fallback mechanisms. +The final step is a fallback mechanism. Generally when labelling an element, use one of the non-fallback mechanisms. For example, for the HTML `input` element, the `placeholder` attribute is used as a fallback labeling mechanism if nothing else results in a label. For an `input` element, it is better to use a `label` element, since it does not disappear visually when the user focuses the form control. @@ -264,7 +266,7 @@ In some cases, a plain text description is insufficient. The `aria-details` attr
Passenger 1 (adult) From a8651d18866d16464b782df5eafd687e0b2b10f3 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 29 Apr 2019 19:52:02 +0200 Subject: [PATCH 015/131] Move draft into aria-practices.html --- aria-practices.html | 268 +++++++++++++++++++++++++++++- draft-labelling-describing.md | 300 ---------------------------------- 2 files changed, 261 insertions(+), 307 deletions(-) delete mode 100644 draft-labelling-describing.md diff --git a/aria-practices.html b/aria-practices.html index ea9a5acbee..222a1f53a7 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -477,7 +477,7 @@

WAI-ARIA Roles, States, and Properties

- + - +

Checkbox

WAI-ARIA supports two types of checkbox widgets:

@@ -2179,7 +2179,7 @@
For Radio Groups Not Contained in a Toolbar
  • Tab and Shift + Tab: - Move focus into and out of the radio group. + Move focus into and out of the radio group. When focus moves into a radio group :
    • If a radio button is checked, focus is set on the checked button.
      • @@ -3697,6 +3697,260 @@
      Examples
+
+

Labeling and describing

+ +
+

Introduction

+ +

A label, also known as accessible name, is a name or a label used to identify the element for users of assistive technology. For example, a button’s label can be "OK".

+ +

An accessible description complements the label with a description. An accessible description is always optional, and if present it does not need to be as brief as a label.

+
+ +
+

Labels

+ +

There are two different kinds of labels, depending on the element’s role. The difference is both in how the label is computed for the element, and how the element is represented to assistive technologies.

+ +
    +
  • Label that represents the element. The label is taken from the element's contents, unless `aria-labelledby` or `aria-label` attributes are used. Only the label is represented to users of assistive tecnologies.
    • + +
  • Label that augments the element. The label is not taken from the element's contents (by default). A label can be set using `aria-labelledby` or `aria-label`. The label will augment the element; both the label and the element's contents are exposed to users of assistive technology.
    • +
+ +
+

Label that represents the element

+ +

For elements with certain roles, the label is taken from the element’s contents by default, and the label will represent the element when communicated to assistive technologies. In the following example, a link (with default role `link`) gets its label from the element’s contents ("Home").

+ + 
<a href="/">Home</a>
+ +

This could be rendered to assistive technology as "link, Home"; the role and the label, not not repeating the content ("link, Home, Home").

+ +

The label also can be set explicitly by using the `aria-labelledby` or `aria-label` attributes. If the label from the element’s contents is already good, then don’t use the `aria-labelledby` or `aria-label` attributes.

+ +

The following roles get the label from the contents by default:

+ +
    +
  • `button`
    • +
  • `cell`
    • +
  • `checkbox`
    • +
  • `columnheader`
    • +
  • `gridcell`
    • +
  • `heading`
    • +
  • `link`
    • +
  • `menuitem`
    • +
  • `menuitemcheckbox`
    • +
  • `menuitemradio`
    • +
  • `option`
    • +
  • `radio`
    • +
  • `row`
    • +
  • `rowgroup`
    • +
  • `rowheader`
    • +
  • `switch`
    • +
  • `tab`
    • +
  • `tooltip`
    • +
  • `treeitem`
    • +
+ +

If the element’s contents are not appropriate as a label, but there is an element that can be used as the label, then use the `aria-labelledby` attribute.

+ +

In the following example, an element with the "switch" role is labeled by a previous sibling element.

+ + 
<span id="night-mode-label">Night mode</span>
+<span role="switch" aria-checked="false" tabindex="0" aria-labelledby="night-mode-label"></span>
+ + +

Because a `span` element is used for the switch control, the HTML `label` element cannot be used to label it, since it only works with HTML elements that are form controls. However, the `switch` role can be used on an `input` element with `type="checkbox”`, and then HTML `label` can be used.

+ + 
<label for="night-mode">Night mode</label>
+<input type="checkbox" role="switch" id="night-mode">
+ + +

In some cases, the combination of the element’s contents and another element would be appropriate as a label. In such situations, use the `aria-labelledby` and reference both the element itself and the other element.

+ +

In the following example, a "read more" link is labeled by the element itself and the article’s heading, resulting in “Read more… 7 ways you can help save the bees”.

+ + 
<h2 id="bees-heading">7 ways you can help save the bees</h2>
+<p>Bees are disappearing rapidly.
+Here are seven things you can do to help.</p>
+<p><a id="bees-read-more" aria-labelledby="bees-read-more bees-heading">Read more...</a></p>
+ +

If there is no content that is appropriate to use as the label, then use the `aria-label` attribute to set the label for the element directly.

+ +

In the following example, a close button contains an "X" and is given the label “Close” using the `aria-label` attribute.

+ + 
<button type="button" aria-label="Close">X</button>
+ +
+ +
+

Label that augments the element

+ +

Some roles do not get the label from the contents of the element; a label can only be set explicitly using the `aria-labelledby` or `aria-label` attributes. For elements with these roles, a label augments the element, but does not override the contents.

+ +

Examples of such roles are (note that this is not a complete list):

+ +
    +
  • `alertdialog`
    • +
  • `application`
    • +
  • `article`
    • +
  • `banner`
    • +
  • `complementary`
    • +
  • `navigation`
    • +
  • `radiogroup`
    • +
  • `search`
    • +
  • `status`
    • +
+ +

For example, the `navigation` landmark could be labeled with the purpose of the landmark. In the following snippet, a "breadcrumbs" + navigation region is labeled explicitly using the `aria-labelledby` attribute. The HTML `nav` element has the `navigation` role by default.

+ + 
<nav aria-labelledby="breadcrumbs-label">
+ <span id="breadcrumbs-label">You are here:</span>
+ <a href="/">Home</a> &gt;
+ <a href="/books/">Books</a> &gt;
+ <a>Children's books</a>
+</nav>
+
+ +
+

Accessible name calculation

+ +

User agents follow the accessible name calculation algorithm to get the label for an element. This is defined in [https://w3c.github.io/accname/](https://w3c.github.io/accname/) and [https://w3c.github.io/html-aam/](https://w3c.github.io/html-aam/) for HTML.

+ +

User agents attempt to formulate labels for elements by walking through a list of potential naming methods and use the first that generates a name. The algorithm is roughly like this:

+ +
    +
  1. First, the `aria-labelledby` attribute is used if present.
    2. +
  2. If the label is still empty, the `aria-label` attribute is used if present.
    3. +
  3. If the label is still empty, then host-language-specific attributes or elements (e.g., the `alt` attribute on HTML `img`) are used if present.
    4. +
  4. If the label is still empty, then for roles that can take label from the element's content, the element’s contents.
    5. +
  5. Finally, if the label is still empty, then host-langauge-specific tooltip attributes or elements (e.g., the `title` attribute in HTML) are used if present.
    6. +
+ +

The final step is a fallback mechanism. Generally when labelling an element, use one of the non-fallback mechanisms.

+ +

For example, for the HTML `input` element, the `placeholder` attribute is used as a fallback labeling mechanism if nothing else results in a label. For an `input` element, it is better to use a `label` element, since it does not disappear visually when the user focuses the form control.

+ +
+

Examples of non-recursive accessible name calculation

+ +

For example, an img element with just a src attribute has no label (don’t do this):

+ + 
<img src="photo.jpg">
+ +

If there is a `title` attribute, then that is used as the label (fallback mechanism; generally avoid doing this):

+ + 
<img src="photo.jpg" title="The Queen, holding a pigeon.">
+ +

If there is also an `alt` attribute (using `alt` for images is recommended), then that is used as the label, and the `title` attribute is instead used as the accessible description:

+ + 
<img src="photo.jpg" alt="The Queen, holding a pigeon." title="Photo: Rex Features">
+ +

If there is also an `aria-label` attribute, then that overrides the `alt` attribute:

+ + 
<img src="photo.jpg" aria-label="The Queen, holding a pigeon." title="Photo: Rex Features"
+     alt="Sorry, this image failed to load.">
+ +

If there is also an `aria-labelledby` attribute, that wins over the other attributes (the `aria-label` attribute ought to be removed if it is not used):

+ + 
<img src="photo.jpg" aria-label="This is ignored." title="Photo: Established Depiction"
+     alt="Sorry, this image failed to load." aria-labelledby="the-queen">
+<span id="the-queen">The Queen, holding a pigeon.</span>
+
+ +
+
Examples of recursive accessible name calculation
+ +

The accessible name calculation algorithm will be invoked recursively when necessary. An `aria-labelledby` reference causes the algorithm to be invoked recursively, and when computing an accessible name from content the algorithm is invoked recursively for each child node.

+ +

In this example, the label for the button is computed by recursing into each child node, resulting in "Move to trash".

+ + 
<button>Move to <img src="bin.svg" alt="trash"></button>
+ +

When following an `aria-labelledby` reference, the algorithm avoids following the same reference twice in order to not end up in infinite loops.

+ +

In this example, the label for the button is computed by first following the `aria-labelledby` reference to the parent element, and then computing the label for that element from the child nodes, first visiting the `button` element again but ignoring the `aria-labelledby` reference and instead using the `aria-label` attribute, and then visiting the next child (the text node). The resulting label is "Remove meeting: Daily status report".

+ + 
<div id="meeting-1">
+ <button aria-labelledby="meeting-1"
+         aria-label="Remove meeting:">X</button>
+  Daily status report
+</div>
+ +

It is also possible to reference an element using `aria-labelledby` even if that element is hidden. In the following example, the `span` element could be styled with CSS `display: none` and the `nav` element would still have the label "You are here:".

+ + 
<nav aria-labelledby="breadcrumbs-label">
+ <span id="breadcrumbs-label">You are here:</span>
+ <a href="/">Home</a> &gt;
+ <a href="/books/">Books</a> &gt;
+ <a>Children's books</a>
+</nav>
+
+
+
+ +
+

Descriptions

+ +

An element can be given an accessible description using the `aria-describedby` attribute or the `aria-details` attribute.

+ +

The `aria-describedby` attribute works similarly to the `aria-labelledby` attribute. For example, a button could be described by a later paragraph.

+ + 
<button aria-describedby="trash-desc">Move to trash</button>
+...
+<p id="trash-desc">Items in the trash
+will be permanently removed after 30 days.</p>
+ +

This description will be presented to the user as plain text. For example, if the description contains an HTML `img` element, a text equivalent of the image is computed.

+ + 
<button aria-describedby="trash-desc">
+ Move to <img src="bin.svg" alt="trash">
+</button>
+...
+<p id="trash-desc">Items in <img src="bin.svg" alt="the trash">
+will be permanently removed after 30 days.</p>
+ +

In some cases, a plain text description is insufficient. The `aria-details` attribute can be used in such situations. In this example, a text field for a passenger’s name (when booking a flight) has a description that is a list of three items, and contains a link to an external document with further details.

+ + 
<ul id="full-name-desc">
+ <li>The passenger's name must match the name in their passport.</li>
+ <li>The name must consist of only characters in the A-Z range.</li>
+ <li><a href="faq.html#name">What if the name in the passport contains other characters?</a></li>
+</ul>
+<fieldset>
+ <legend>Passenger 1 (adult)</legend>
+ <p><label>Full name
+  <input name="full-name" aria-details="full-name-desc">
+ </label></p>
+ ...
+</fieldset>
+ +

If both `aria-details` and `aria-describedby` are specified on an element, only the `aria-details` attribute is used. This can be useful in order to provide a fallback for user agents that don’t support `aria-details`.

+ +
+

Accessible description calculation

+ +

Like the accessible name calculation (see the earlier section), the accessible description calculation produces a plain text string for an element. This algorithm is not used for the `aria-details` attribute.

+ +

The accessible description calculation algorithm is the same algorithm as the accessible name calculation algorithm, but it branches off in some places depending on whether a name or a description is being calculated. In particular, when collecting an accessible description, the algorithm uses `aria-describedby` instead of `aria-labelledby`.

+ +

As with `aria-labelledby`, it is possible to reference an element using `aria-describedby` even if that element is hidden.

+ +

For example, a text field in a form could have a description that is hidden by default, but can be revealed on request using a disclosure widget. The description could also be referenced from the text field directly with `aria-describedby`. The accessible description for the `input` element is "Your username is the name that you use to log in to this service.".

+ + 
<label for="username">Username</label>
+<input id="username" name="username" aria-describedby="username-desc">
+<button aria-expanded="false" aria-controls="username-desc" aria-label="Help about username">?</button>
+<p id="username-desc" hidden>
+ Your username is the name that you use to log in to this service.
+</p>
+
+
+
+

Developing a Keyboard Interface

@@ -4988,7 +5242,7 @@

Indexes

Change History

Change history is maintained in a separate version-specific branch.

- +

Acknowledgements

diff --git a/draft-labelling-describing.md b/draft-labelling-describing.md deleted file mode 100644 index cc5475e9b2..0000000000 --- a/draft-labelling-describing.md +++ /dev/null @@ -1,300 +0,0 @@ -Labeling and Describing - -## Introduction - -A label, also known as accessible name, is a name or a label used to identify the element for users of assistive technology. For example, a button’s label can be "OK". - -An accessible description complements the label with a description. An accessible description is always optional, and if present it does not need to be as brief as a label. - -## Labels - -There are two different kinds of labels, depending on the element’s role. The difference is both in how the label is computed for the element, and how the element is represented to assistive technologies. - -* Label that represents the element. The label is taken from the element's contents, unless `aria-labelledby` or `aria-label` attributes are used. Only the label is represented to users of assistive tecnologies. - -* Label that augments the element. The label is not taken from the element's contents (by default). A label can be set using `aria-labelledby` or `aria-label`. The label will augment the element; both the label and the element's contents are exposed to users of assistive technology. - - -### Label that represents the element - -For elements with certain roles, the label is taken from the element’s contents by default, and the label will represent the element when communicated to assistive technologies. In the following example, a link (with default role `link`) gets its label from the element’s contents ("Home"). - -``` -Home -``` - -This could be rendered to assistive technology as "link, Home"; the role and the label, not not repeating the content ("link, Home, Home"). - -The label also can be set explicitly by using the `aria-labelledby` or `aria-label` attributes. If the label from the element’s contents is already good, then don’t use the `aria-labelledby` or `aria-label` attributes. - -The following roles get the label from the contents by default: - -* `button` - -* `cell` - -* `checkbox` - -* `columnheader` - -* `gridcell` - -* `heading` - -* `link` - -* `menuitem` - -* `menuitemcheckbox` - -* `menuitemradio` - -* `option` - -* `radio` - -* `row` - -* `rowgroup` - -* `rowheader` - -* `switch` - -* `tab` - -* `tooltip` - -* `treeitem` - -If the element’s contents are not appropriate as a label, but there is an element that can be used as the label, then use the `aria-labelledby` attribute. - -In the following example, an element with the "switch" role is labeled by a previous sibling element. - -``` -Night mode - -``` - - -Because a `span` element is used for the switch control, the HTML `label` element cannot be used to label it, since it only works with HTML elements that are form controls. However, the `switch` role can be used on an `input` element with `type="checkbox”`, and then HTML `label` can be used. - -``` - - -``` - - -In some cases, the combination of the element’s contents and another element would be appropriate as a label. In such situations, use the `aria-labelledby` and reference both the element itself and the other element. - -In the following example, a "read more" link is labeled by the element itself and the article’s heading, resulting in “Read more… 7 ways you can help save the bees”. - -``` -

7 ways you can help save the bees

-

Bees are disappearing rapidly. -Here are seven things you can do to help.

-

Read more...

-``` - - -If there is no content that is appropriate to use as the label, then use the `aria-label` attribute to set the label for the element directly. - -In the following example, a close button contains an "X" and is given the label “Close” using the `aria-label` attribute. - -``` - -``` - - -### Label that augments the element - -Some roles do not get the label from the contents of the element; a label can only be set explicitly using the `aria-labelledby` or `aria-label` attributes. For elements with these roles, a label augments the element, but does not override the contents. - -Examples of such roles are (note that this is not a complete list): - -* `alertdialog` - -* `application` - -* `article` - -* `banner` - -* `complementary` - -* `navigation` - -* `radiogroup` - -* `search` - -* `status` - -For example, the `navigation` landmark could be labeled with the purpose of the landmark. In the following snippet, a "breadcrumbs" navigation region is labeled explicitly using the `aria-labelledby` attribute. The HTML `nav` element has the `navigation` role by default. - -``` - -``` - - -### Accessible name calculation - -User agents follow the accessible name calculation algorithm to get the label for an element. This is defined in [https://w3c.github.io/accname/](https://w3c.github.io/accname/) and [https://w3c.github.io/html-aam/](https://w3c.github.io/html-aam/) for HTML. - -User agents attempt to formulate labels for elements by walking through a list of potential naming methods and use the first that generates a name. The algorithm is roughly like this: - -1. First, the `aria-labelledby` attribute is used if present. - -2. If the label is still empty, the `aria-label` attribute is used if present. - -3. If the label is still empty, then host-language-specific attributes or elements (e.g., the `alt` attribute on HTML `img`) are used if present. - -4. If the label is still empty, then for roles that can take label from the element's content, the element’s contents. - -5. Finally, if the label is still empty, then host-langauge-specific tooltip attributes or elements (e.g., the `title` attribute in HTML) are used if present. - -The final step is a fallback mechanism. Generally when labelling an element, use one of the non-fallback mechanisms. - -For example, for the HTML `input` element, the `placeholder` attribute is used as a fallback labeling mechanism if nothing else results in a label. For an `input` element, it is better to use a `label` element, since it does not disappear visually when the user focuses the form control. - -#### Examples of non-recursive accessible name calculation - -For example, an img element with just a src attribute has no label (don’t do this): - -``` - -``` - - -If there is a `title` attribute, then that is used as the label (fallback mechanism; generally avoid doing this): - -``` - -``` - - -If there is also an `alt` attribute (using `alt` for images is recommended), then that is used as the label, and the `title` attribute is instead used as the accessible description: - -``` -The Queen, holding a pigeon. -``` - - -If there is also an `aria-label` attribute, then that overrides the `alt` attribute: - -``` -Sorry, this image failed to load. -``` - - -If there is also an `aria-labelledby` attribute, that wins over the other attributes (the `aria-label` attribute ought to be removed if it is not used): - -``` -Sorry, this image failed to load. -The Queen, holding a pigeon. -``` - - -#### Examples of recursive accessible name calculation - -The accessible name calculation algorithm will be invoked recursively when necessary. An `aria-labelledby` reference causes the algorithm to be invoked recursively, and when computing an accessible name from content the algorithm is invoked recursively for each child node. - -In this example, the label for the button is computed by recursing into each child node, resulting in "Move to trash". - -``` - -``` - - -When following an `aria-labelledby` reference, the algorithm avoids following the same reference twice in order to not end up in infinite loops. - -In this example, the label for the button is computed by first following the `aria-labelledby` reference to the parent element, and then computing the label for that element from the child nodes, first visiting the `button` element again but ignoring the `aria-labelledby` reference and instead using the `aria-label` attribute, and then visiting the next child (the text node). The resulting label is "Remove meeting: Daily status report". - -``` -
- - Daily status report -
-``` - -It is also possible to reference an element using `aria-labelledby` even if that element is hidden. In the following example, the `span` element could be styled with CSS `display: none` and the `nav` element would still have the label "You are here:". - -``` - -``` - -## Descriptions - -An element can be given an accessible description using the `aria-describedby` attribute or the `aria-details` attribute. - -The `aria-describedby` attribute works similarly to the `aria-labelledby` attribute. For example, a button could be described by a later paragraph. - -``` - -... -

Items in the trash -will be permanently removed after 30 days.

-``` - - -This description will be presented to the user as plain text. For example, if the description contains an HTML `img` element, a text equivalent of the image is computed. - -``` - -... -

Items in the trash -will be permanently removed after 30 days.

-``` - - -In some cases, a plain text description is insufficient. The `aria-details` attribute can be used in such situations. In this example, a text field for a passenger’s name (when booking a flight) has a description that is a list of three items, and contains a link to an external document with further details. - -``` - -
- Passenger 1 (adult) -

- ... -
-``` - - -If both `aria-details` and `aria-describedby` are specified on an element, only the `aria-details` attribute is used. This can be useful in order to provide a fallback for user agents that don’t support `aria-details`. - -### Accessible description calculation - -Like the accessible name calculation (see the earlier section), the accessible description calculation produces a plain text string for an element. This algorithm is not used for the `aria-details` attribute. - -The accessible description calculation algorithm is the same algorithm as the accessible name calculation algorithm, but it branches off in some places depending on whether a name or a description is being calculated. In particular, when collecting an accessible description, the algorithm uses `aria-describedby` instead of `aria-labelledby`. - -As with `aria-labelledby`, it is possible to reference an element using `aria-describedby` even if that element is hidden. - -For example, a text field in a form could have a description that is hidden by default, but can be revealed on request using a disclosure widget. The description could also be referenced from the text field directly with `aria-describedby`. The accessible description for the `input` element is "Your username is the name that you use to log in to this service.". - -``` - - - - -``` From 7773aae5c534af0976f60e52a5aff9d70d34b16a Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 29 Apr 2019 20:00:47 +0200 Subject: [PATCH 016/131] Fix typo --- aria-practices.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aria-practices.html b/aria-practices.html index 222a1f53a7..c8e47318b6 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3714,7 +3714,7 @@

Labels

There are two different kinds of labels, depending on the element’s role. The difference is both in how the label is computed for the element, and how the element is represented to assistive technologies.

    -
  • Label that represents the element. The label is taken from the element's contents, unless `aria-labelledby` or `aria-label` attributes are used. Only the label is represented to users of assistive tecnologies.
    • +
  • Label that represents the element. The label is taken from the element's contents, unless `aria-labelledby` or `aria-label` attributes are used. Only the label is represented to users of assistive technologies.
  • Label that augments the element. The label is not taken from the element's contents (by default). A label can be set using `aria-labelledby` or `aria-label`. The label will augment the element; both the label and the element's contents are exposed to users of assistive technology.
From 1bf0f40b4b0368d7a4a83d569b6d86ab9cdbc745 Mon Sep 17 00:00:00 2001 From: Matt King Date: Mon, 6 May 2019 10:59:41 -0700 Subject: [PATCH 017/131] Incomplete and rough draft of revised outline --- aria-practices.html | 367 +++++++++++++++++++++------------- draft-labelling-describing.md | 2 +- 2 files changed, 234 insertions(+), 135 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index c8e47318b6..9ebfae5dc6 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3697,41 +3697,121 @@
Examples
-
-

Labeling and describing

- -
-

Introduction

- -

A label, also known as accessible name, is a name or a label used to identify the element for users of assistive technology. For example, a button’s label can be "OK".

+
+

Providing Accessible Names and Descriptions

+

+ Providing elements with accessible names, and where appropriate, accessible descriptions is one of the most fundamental and important responsibilities authors have when developing accessible web experiences. + While doing so is straight forward for most elements, technical mistakes that can have devistating impacts on users of assistive technologies are easy to make and unfortunately common. + To help authors provide effective and reliable 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 then provides guidance for effectively employing the following naming and describing techniques and WAI-ARIA properties: +

+
    +
  • Naming with child content.
    • +
  • Naming by encapsulation with a label.
    • +
  • Naming with a String Attribute Via aria-label.
    • +
  • Naming by Referencing Content with aria-labelledby.
    • +
  • Naming with Legends and Captions.
    • +
  • Fallback Names Derived from Titles and Placeholders.
    • +
  • Describing by referencing content with aria-describedby.
    • +
  • Describing by referencing content with aria-details.
    • +
  • Fallback descriptions Derived from Titles and Placeholders.
    • +
-

An accessible description complements the label with a description. An accessible description is always optional, and if present it does not need to be as brief as a label.

+
+

What ARE Accessible Names and Descriptions?

+

+ An accessible name is a short string, typically 1 to 3 words, that authors associate with an element to provide users of assistive technologies with a label for the element. + For example, an input field might have an accessible name of "User ID" or a button might be named "Submit". +

+

An accessible name serves two primary purposes:

+
    +
  1. Convey the purpose or intent of the element.
    2. +
  2. Distinguish it from other elements on the page.
    3. +
+

+ Both the WAI-ARIA specification and WCAG require all focusable, interactive elements to have an accessible name. + In addition dialogs and some structural containers, such as tables and regions, are required to have a name. + Many other elements can be named, but whether a name will enhance the accessible experience is determined by various characteristics of the surrounding context. + Finally, there are some elements where providing an accessible name is technically possible but not advisable. + The Accessible Name Guidance by Role section lists naming requirements and guidelines for every ARIA role. +

+

+ 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 it is an input), and any relevant states or properties. +

- -
-

Labels

- + +
+

How Are Name and Description Strings Derived?

+

+ Because there are several elements and attributes for specifying text to include in an accessible name or description string, and because they can be combined in a practically endless number of ways, browsers have to implement a fairly complex algorithm for assembling the strings. +The section on accessible name calculation provides a detailed explanation of the algorithm. +However, most authors do not need a detailed understanding of the algorithm since nearly all elements can be named or described by implementing the coding patterns described in the naming techniques section and following the guidance provided by the cardinal rules for naming. +

+
+ +
+

Cardinal Rules of Naming

+ +
+

Rule 1: Heed Warnings and Test Thoroughly

+

+ because the aria-label and aria-labelledby attributes override content contained in some elementss, they can block assistive technology access to some on-screen text. + Thus + , to both serve an optimal experience and avoid potentially disasterous mistakes, it is essential to understand when and how these two attributes override element text. +

There are two different kinds of labels, depending on the element’s role. The difference is both in how the label is computed for the element, and how the element is represented to assistive technologies.

-
  • Label that represents the element. The label is taken from the element's contents, unless `aria-labelledby` or `aria-label` attributes are used. Only the label is represented to users of assistive technologies.
    • -
  • Label that augments the element. The label is not taken from the element's contents (by default). A label can be set using `aria-labelledby` or `aria-label`. The label will augment the element; both the label and the element's contents are exposed to users of assistive technology.
- + +
+
-

Label that represents the element

- +

Rule 2: Prefer Visible Text

+

+ When a user interface includes visible text that could be used to provide an appropriate accessible name, using the visible text for the accessible name simplifies maintenance, prevents bugs, and reduces language translation requirements, which leads to a more robust accessible experience. + The naming techniques described in the sections below emphasize techniques for utilizing on-screen text. +

+
+ +
+

Rule 3: Prefer Native Techniques

+

That is, in HTML documents, prefer HTML naming techniques, such as the HTML label element.

+
+
+

Rule 4: Avoid Browser Fallback

+

+ Talk about how fallbacks can be less robust because of potential implementation inconsistency. + title and placeholder +

+
+ +
+

Rule 5: Compose Brief, Useful Names

+

+ Mention some good properties of names, such as uniqueness, brevity, and clarity. + Refer user to section on best practices for composing effective accessible names. + Example practice: Do NOT include a WAI-ARIA role name in the accessible name. For example, do not include the word "button" in the name of a button or the word "navigation" in the name of a navigation region. +

+
+
+ +
+

Naming Techniques

+ +
+

Naming with Child Content

For elements with certain roles, the label is taken from the element’s contents by default, and the label will represent the element when communicated to assistive technologies. In the following example, a link (with default role `link`) gets its label from the element’s contents ("Home").

<a href="/">Home</a>

This could be rendered to assistive technology as "link, Home"; the role and the label, not not repeating the content ("link, Home, Home").

- -

The label also can be set explicitly by using the `aria-labelledby` or `aria-label` attributes. If the label from the element’s contents is already good, then don’t use the `aria-labelledby` or `aria-label` attributes.

- +

The following roles get the label from the contents by default:

-
  • `button`
  • `cell`
    • @@ -3753,7 +3833,18 @@

    Label that represents the element

  • `tooltip`
  • `treeitem`
+
+ +
+

Naming with a String Attribute Via aria-label

+

If there is no content that is appropriate to use as the label, then use the `aria-label` attribute to set the label for the element directly.

+

In the following example, a close button contains an "X" and is given the label “Close” using the `aria-label` attribute.

+ + 
<button type="button" aria-label="Close">X</button>
+
+
+

Naming with Referenced Content Via aria-labeledby

If the element’s contents are not appropriate as a label, but there is an element that can be used as the label, then use the `aria-labelledby` attribute.

In the following example, an element with the "switch" role is labeled by a previous sibling element.

@@ -3761,13 +3852,11 @@

Label that represents the element

<span id="night-mode-label">Night mode</span>
 <span role="switch" aria-checked="false" tabindex="0" aria-labelledby="night-mode-label"></span>
-

Because a `span` element is used for the switch control, the HTML `label` element cannot be used to label it, since it only works with HTML elements that are form controls. However, the `switch` role can be used on an `input` element with `type="checkbox”`, and then HTML `label` can be used.

<label for="night-mode">Night mode</label>
 <input type="checkbox" role="switch" id="night-mode">
-

In some cases, the combination of the element’s contents and another element would be appropriate as a label. In such situations, use the `aria-labelledby` and reference both the element itself and the other element.

In the following example, a "read more" link is labeled by the element itself and the article’s heading, resulting in “Read more… 7 ways you can help save the bees”.

@@ -3776,13 +3865,6 @@

Label that represents the element

<p>Bees are disappearing rapidly. Here are seven things you can do to help.</p> <p><a id="bees-read-more" aria-labelledby="bees-read-more bees-heading">Read more...</a></p> - -

If there is no content that is appropriate to use as the label, then use the `aria-label` attribute to set the label for the element directly.

- -

In the following example, a close button contains an "X" and is given the label “Close” using the `aria-label` attribute.

- - 
<button type="button" aria-label="Close">X</button>
-
@@ -3814,140 +3896,157 @@

Label that augments the element

<a>Children's books</a> </nav>
+
+ +
+

Composing Effective and User-friendly Accessible Names

+

Todo: Write a section that describes how to make good names, i.e., brief, descriptive, unique, front-loaded, no role names, etc.

+
+ +
+

Accessible Name Guidance by Role

+

Todo: build a table with every concrete role with columns for:

+
    +
  • role
    • +
  • Name Required?: with values of always, sometimes, or never
    • +
  • Named by Content?: values of Yes or No
    • +
  • Guidance: Explains sometimes and never for name required. Provides warning if named from content.
    • +
+
+ +
+

Accessible name calculation

+

User agents follow the accessible name calculation algorithm to get the label for an element. This is defined in [https://w3c.github.io/accname/](https://w3c.github.io/accname/) and [https://w3c.github.io/html-aam/](https://w3c.github.io/html-aam/) for HTML.

+

User agents attempt to formulate labels for elements by walking through a list of potential naming methods and use the first that generates a name. The algorithm is roughly like this:

+
    +
  1. First, the `aria-labelledby` attribute is used if present.
    2. +
  2. If the label is still empty, the `aria-label` attribute is used if present.
    3. +
  3. If the label is still empty, then host-language-specific attributes or elements (e.g., the `alt` attribute on HTML `img`) are used if present.
    4. +
  4. If the label is still empty, then for roles that can take label from the element's content, the element’s contents.
    5. +
  5. Finally, if the label is still empty, then host-langauge-specific tooltip attributes or elements (e.g., the `title` attribute in HTML) are used if present.
    6. +
-
-

Accessible name calculation

- -

User agents follow the accessible name calculation algorithm to get the label for an element. This is defined in [https://w3c.github.io/accname/](https://w3c.github.io/accname/) and [https://w3c.github.io/html-aam/](https://w3c.github.io/html-aam/) for HTML.

- -

User agents attempt to formulate labels for elements by walking through a list of potential naming methods and use the first that generates a name. The algorithm is roughly like this:

- -
    -
  1. First, the `aria-labelledby` attribute is used if present.
    2. -
  2. If the label is still empty, the `aria-label` attribute is used if present.
    3. -
  3. If the label is still empty, then host-language-specific attributes or elements (e.g., the `alt` attribute on HTML `img`) are used if present.
    4. -
  4. If the label is still empty, then for roles that can take label from the element's content, the element’s contents.
    5. -
  5. Finally, if the label is still empty, then host-langauge-specific tooltip attributes or elements (e.g., the `title` attribute in HTML) are used if present.
    6. -
- -

The final step is a fallback mechanism. Generally when labelling an element, use one of the non-fallback mechanisms.

+

The final step is a fallback mechanism. Generally when labelling an element, use one of the non-fallback mechanisms.

-

For example, for the HTML `input` element, the `placeholder` attribute is used as a fallback labeling mechanism if nothing else results in a label. For an `input` element, it is better to use a `label` element, since it does not disappear visually when the user focuses the form control.

+

For example, for the HTML `input` element, the `placeholder` attribute is used as a fallback labeling mechanism if nothing else results in a label. For an `input` element, it is better to use a `label` element, since it does not disappear visually when the user focuses the form control.

-
-

Examples of non-recursive accessible name calculation

+
+

Examples of non-recursive accessible name calculation

-

For example, an img element with just a src attribute has no label (don’t do this):

+

For example, an img element with just a src attribute has no label (don’t do this):

- 
<img src="photo.jpg">
+ 
<img src="photo.jpg">
-

If there is a `title` attribute, then that is used as the label (fallback mechanism; generally avoid doing this):

+

If there is a `title` attribute, then that is used as the label (fallback mechanism; generally avoid doing this):

- 
<img src="photo.jpg" title="The Queen, holding a pigeon.">
+ 
<img src="photo.jpg" title="The Queen, holding a pigeon.">
-

If there is also an `alt` attribute (using `alt` for images is recommended), then that is used as the label, and the `title` attribute is instead used as the accessible description:

+

If there is also an `alt` attribute (using `alt` for images is recommended), then that is used as the label, and the `title` attribute is instead used as the accessible description:

- 
<img src="photo.jpg" alt="The Queen, holding a pigeon." title="Photo: Rex Features">
+ 
<img src="photo.jpg" alt="The Queen, holding a pigeon." title="Photo: Rex Features">
-

If there is also an `aria-label` attribute, then that overrides the `alt` attribute:

+

If there is also an `aria-label` attribute, then that overrides the `alt` attribute:

- 
<img src="photo.jpg" aria-label="The Queen, holding a pigeon." title="Photo: Rex Features"
-     alt="Sorry, this image failed to load.">
+ 
<img src="photo.jpg" aria-label="The Queen, holding a pigeon." title="Photo: Rex Features"
+   alt="Sorry, this image failed to load.">
-

If there is also an `aria-labelledby` attribute, that wins over the other attributes (the `aria-label` attribute ought to be removed if it is not used):

+

If there is also an `aria-labelledby` attribute, that wins over the other attributes (the `aria-label` attribute ought to be removed if it is not used):

- 
<img src="photo.jpg" aria-label="This is ignored." title="Photo: Established Depiction"
-     alt="Sorry, this image failed to load." aria-labelledby="the-queen">
-<span id="the-queen">The Queen, holding a pigeon.</span>
-
+ 
<img src="photo.jpg" aria-label="This is ignored." title="Photo: Established Depiction"
+   alt="Sorry, this image failed to load." aria-labelledby="the-queen">
+  <span id="the-queen">The Queen, holding a pigeon.</span>
+
-
-
Examples of recursive accessible name calculation
+
+

Examples of recursive accessible name calculation

-

The accessible name calculation algorithm will be invoked recursively when necessary. An `aria-labelledby` reference causes the algorithm to be invoked recursively, and when computing an accessible name from content the algorithm is invoked recursively for each child node.

+

The accessible name calculation algorithm will be invoked recursively when necessary. An `aria-labelledby` reference causes the algorithm to be invoked recursively, and when computing an accessible name from content the algorithm is invoked recursively for each child node.

-

In this example, the label for the button is computed by recursing into each child node, resulting in "Move to trash".

+

In this example, the label for the button is computed by recursing into each child node, resulting in "Move to trash".

- 
<button>Move to <img src="bin.svg" alt="trash"></button>
+ 
<button>Move to <img src="bin.svg" alt="trash"></button>
-

When following an `aria-labelledby` reference, the algorithm avoids following the same reference twice in order to not end up in infinite loops.

+

When following an `aria-labelledby` reference, the algorithm avoids following the same reference twice in order to not end up in infinite loops.

-

In this example, the label for the button is computed by first following the `aria-labelledby` reference to the parent element, and then computing the label for that element from the child nodes, first visiting the `button` element again but ignoring the `aria-labelledby` reference and instead using the `aria-label` attribute, and then visiting the next child (the text node). The resulting label is "Remove meeting: Daily status report".

+

In this example, the label for the button is computed by first following the `aria-labelledby` reference to the parent element, and then computing the label for that element from the child nodes, first visiting the `button` element again but ignoring the `aria-labelledby` reference and instead using the `aria-label` attribute, and then visiting the next child (the text node). The resulting label is "Remove meeting: Daily status report".

- 
<div id="meeting-1">
- <button aria-labelledby="meeting-1"
-         aria-label="Remove meeting:">X</button>
-  Daily status report
-</div>
+ 
<div id="meeting-1">
+  <button aria-labelledby="meeting-1"
+      aria-label="Remove meeting:">X</button>
+      Daily status report
+  </div>
-

It is also possible to reference an element using `aria-labelledby` even if that element is hidden. In the following example, the `span` element could be styled with CSS `display: none` and the `nav` element would still have the label "You are here:".

+

It is also possible to reference an element using `aria-labelledby` even if that element is hidden. In the following example, the `span` element could be styled with CSS `display: none` and the `nav` element would still have the label "You are here:".

- 
<nav aria-labelledby="breadcrumbs-label">
- <span id="breadcrumbs-label">You are here:</span>
- <a href="/">Home</a> &gt;
- <a href="/books/">Books</a> &gt;
- <a>Children's books</a>
-</nav>
-
+ 
<nav aria-labelledby="breadcrumbs-label">
+  <span id="breadcrumbs-label">You are here:</span>
+    <a href="/">Home</a> &gt;
+    <a href="/books/">Books</a> &gt;
+    <a>Children's books</a>
+  </nav>
- -
-

Descriptions

- -

An element can be given an accessible description using the `aria-describedby` attribute or the `aria-details` attribute.

- -

The `aria-describedby` attribute works similarly to the `aria-labelledby` attribute. For example, a button could be described by a later paragraph.

- - 
<button aria-describedby="trash-desc">Move to trash</button>
-...
-<p id="trash-desc">Items in the trash
-will be permanently removed after 30 days.</p>
- -

This description will be presented to the user as plain text. For example, if the description contains an HTML `img` element, a text equivalent of the image is computed.

- - 
<button aria-describedby="trash-desc">
- Move to <img src="bin.svg" alt="trash">
-</button>
-...
-<p id="trash-desc">Items in <img src="bin.svg" alt="the trash">
-will be permanently removed after 30 days.</p>
- -

In some cases, a plain text description is insufficient. The `aria-details` attribute can be used in such situations. In this example, a text field for a passenger’s name (when booking a flight) has a description that is a list of three items, and contains a link to an external document with further details.

- - 
<ul id="full-name-desc">
- <li>The passenger's name must match the name in their passport.</li>
- <li>The name must consist of only characters in the A-Z range.</li>
- <li><a href="faq.html#name">What if the name in the passport contains other characters?</a></li>
-</ul>
-<fieldset>
- <legend>Passenger 1 (adult)</legend>
- <p><label>Full name
-  <input name="full-name" aria-details="full-name-desc">
- </label></p>
- ...
-</fieldset>
- -

If both `aria-details` and `aria-describedby` are specified on an element, only the `aria-details` attribute is used. This can be useful in order to provide a fallback for user agents that don’t support `aria-details`.

- + +
+

Describing Techniques

+
-

Accessible description calculation

+

Describing by referencing content with aria-describedby

+

The `aria-describedby` attribute works similarly to the `aria-labelledby` attribute. For example, a button could be described by a later paragraph.

+ + 
<button aria-describedby="trash-desc">Move to trash</button>
+          ...
+          <p id="trash-desc">Items in the trash
+          will be permanently removed after 30 days.</p>
+ +

This description will be presented to the user as plain text. For example, if the description contains an HTML `img` element, a text equivalent of the image is computed.

+ + 
<button aria-describedby="trash-desc">
+          Move to <img src="bin.svg" alt="trash">
+          </button>
+          ...
+          <p id="trash-desc">Items in <img src="bin.svg" alt="the trash">
+          will be permanently removed after 30 days.</p>
+
+ +
+

Describing by referencing content with aria-details>

+

In some cases, a plain text description is insufficient. The `aria-details` attribute can be used in such situations. In this example, a text field for a passenger’s name (when booking a flight) has a description that is a list of three items, and contains a link to an external document with further details.

+ + 
<ul id="full-name-desc">
+          <li>The passenger's name must match the name in their passport.</li>
+          <li>The name must consist of only characters in the A-Z range.</li>
+          <li><a href="faq.html#name">What if the name in the passport contains other characters?</a></li>
+          </ul>
+          <fieldset>
+          <legend>Passenger 1 (adult)</legend>
+          <p><label>Full name
+          <input name="full-name" aria-details="full-name-desc">
+          </label></p>
+          ...
+          </fieldset>
+ +

If both `aria-details` and `aria-describedby` are specified on an element, only the `aria-details` attribute is used. This can be useful in order to provide a fallback for user agents that don’t support `aria-details`.

+
+
-

Like the accessible name calculation (see the earlier section), the accessible description calculation produces a plain text string for an element. This algorithm is not used for the `aria-details` attribute.

+
+

Accessible description calculation

-

The accessible description calculation algorithm is the same algorithm as the accessible name calculation algorithm, but it branches off in some places depending on whether a name or a description is being calculated. In particular, when collecting an accessible description, the algorithm uses `aria-describedby` instead of `aria-labelledby`.

+

Like the accessible name calculation (see the earlier section), the accessible description calculation produces a plain text string for an element. This algorithm is not used for the `aria-details` attribute.

-

As with `aria-labelledby`, it is possible to reference an element using `aria-describedby` even if that element is hidden.

+

The accessible description calculation algorithm is the same algorithm as the accessible name calculation algorithm, but it branches off in some places depending on whether a name or a description is being calculated. In particular, when collecting an accessible description, the algorithm uses `aria-describedby` instead of `aria-labelledby`.

-

For example, a text field in a form could have a description that is hidden by default, but can be revealed on request using a disclosure widget. The description could also be referenced from the text field directly with `aria-describedby`. The accessible description for the `input` element is "Your username is the name that you use to log in to this service.".

+

As with `aria-labelledby`, it is possible to reference an element using `aria-describedby` even if that element is hidden.

- 
<label for="username">Username</label>
-<input id="username" name="username" aria-describedby="username-desc">
-<button aria-expanded="false" aria-controls="username-desc" aria-label="Help about username">?</button>
-<p id="username-desc" hidden>
- Your username is the name that you use to log in to this service.
-</p>
-
+

For example, a text field in a form could have a description that is hidden by default, but can be revealed on request using a disclosure widget. The description could also be referenced from the text field directly with `aria-describedby`. The accessible description for the `input` element is "Your username is the name that you use to log in to this service.".

+ + 
<label for="username">Username</label>
+        <input id="username" name="username" aria-describedby="username-desc">
+        <button aria-expanded="false" aria-controls="username-desc" aria-label="Help about username">?</button>
+        <p id="username-desc" hidden>
+        Your username is the name that you use to log in to this service.
+        </p>
diff --git a/draft-labelling-describing.md b/draft-labelling-describing.md index 4b9713e14b..1b59826826 100644 --- a/draft-labelling-describing.md +++ b/draft-labelling-describing.md @@ -2,7 +2,7 @@ ## Providing Accessible Names and Descriptions -Providing elements with accessible names, and where appropriate, accessible descriptions is one of the most fundamental and important responsibilities authors have when developing accessible web experiences. While doing it well is not typically difficult, technical mistakes that have devistating impact are common. After providing some basic information about accessible names and descriptions, this section provides guidance for using the following ARIA properties: +Providing elements with accessible names, and where appropriate, accessible descriptions is one of the most fundamental and important responsibilities authors have when developing accessible web experiences. While doing it well is not typically difficult, technical mistakes that can have devistating impacts are unfortunately common. After providing some basic information about accessible names and descriptions, this section provides guidance for using the following ARIA attributes: ### Accessible Name and Description Basics From 16008f5c6484b87734ede1e2da4f270077278297 Mon Sep 17 00:00:00 2001 From: Matt King Date: Tue, 7 May 2019 10:22:50 -0700 Subject: [PATCH 018/131] more rough draft work on intro content and overall structure --- aria-practices.html | 54 +++++++++++++++++++++++++++------------------ 1 file changed, 33 insertions(+), 21 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 9ebfae5dc6..1282b228e7 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3746,9 +3746,9 @@

What ARE Accessible Names and Descriptions?

How Are Name and Description Strings Derived?

- Because there are several elements and attributes for specifying text to include in an accessible name or description string, and because they can be combined in a practically endless number of ways, browsers have to implement a fairly complex algorithm for assembling the strings. -The section on accessible name calculation provides a detailed explanation of the algorithm. -However, most authors do not need a detailed understanding of the algorithm since nearly all elements can be named or described by implementing the coding patterns described in the naming techniques section and following the guidance provided by the cardinal rules for naming. + Because there are several elements and attributes for specifying text to include in an accessible name or description string, and because they can be combined in a practically endless number of ways, browsers implement fairly complex algorithms for assembling the strings. +The sections on accessible name calculation and accessible description calculation provide detailed explanations of the algorithms. +However, most authors do not need detailed understanding of the algorithms since nearly all circumstances where a name or description is useful are supported by the coding patterns described in the naming techniques and describing techniques sections.

@@ -3758,44 +3758,46 @@

Cardinal Rules of Naming

Rule 1: Heed Warnings and Test Thoroughly

- because the aria-label and aria-labelledby attributes override content contained in some elementss, they can block assistive technology access to some on-screen text. - Thus - , to both serve an optimal experience and avoid potentially disasterous mistakes, it is essential to understand when and how these two attributes override element text. + Several of the naming techniques include notes that warn against coding patterns that may appear logical at first glance but are either prohibitted by the ARIA specification or fall into gray space that is not yet fully specified. + These patterns may even yield desired names in some browsers. + However, it is unlikely they will provide consistent results across browsers, especially over time as work to improve the consistency of name calculation across browsers progresses. +

+

+ In addition to heeding the warnings provided in the naming techniques, it is difficult to over emphasize the importance of testing to ensure that names browsers calculate match expectations.

-

There are two different kinds of labels, depending on the element’s role. The difference is both in how the label is computed for the element, and how the element is represented to assistive technologies.

-
    -
  • Label that represents the element. The label is taken from the element's contents, unless `aria-labelledby` or `aria-label` attributes are used. Only the label is represented to users of assistive technologies.
    • -
  • Label that augments the element. The label is not taken from the element's contents (by default). A label can be set using `aria-labelledby` or `aria-label`. The label will augment the element; both the label and the element's contents are exposed to users of assistive technology.
    • -
-

Rule 2: Prefer Visible Text

- When a user interface includes visible text that could be used to provide an appropriate accessible name, using the visible text for the accessible name simplifies maintenance, prevents bugs, and reduces language translation requirements, which leads to a more robust accessible experience. - The naming techniques described in the sections below emphasize techniques for utilizing on-screen text. + When a user interface includes visible text that could be used to provide an appropriate accessible name, using the visible text for the accessible name simplifies maintenance, prevents bugs, and reduces language translation requirements. + When names are generated from text that exists only in markup and is never displayed visually, there is a greater likelihood that accessible names are not updated when the user interface design or content are changed.

Rule 3: Prefer Native Techniques

-

That is, in HTML documents, prefer HTML naming techniques, such as the HTML label element.

+

+ In HTML documents, whenever possible, rely on HTML naming techniques, such as the HTML label element. + While less flexible, their simplicity and reliance on visible text help ensure robust accessible experiences. +

+

Rule 4: Avoid Browser Fallback

- Talk about how fallbacks can be less robust because of potential implementation inconsistency. - title and placeholder + When authors do not specify an accessible name using an element or attribute that is intended for naming, browsers attempt to help assistive technology users by resorting to fall back methods for generating a name. + For example, the HTML title and placeholder attributes are used as last resort sources for accessible names. + Because the purpose of these attributes is not naming, their content typically yields low quality accessible names that are not effective.

Rule 5: Compose Brief, Useful Names

- Mention some good properties of names, such as uniqueness, brevity, and clarity. - Refer user to section on best practices for composing effective accessible names. - Example practice: Do NOT include a WAI-ARIA role name in the accessible name. For example, do not include the word "button" in the name of a button or the word "navigation" in the name of a navigation region. + In the same way that visually crowded screens reduce usability, excessively long or insufficiently distinct and descriptive accessible names can make a user interface very difficult, or even impossible, to use for someone who relies on a non-visual form of the user interface. + In other words, for a web experience to accessible, the names must be effective. + Composing Effective and User-friendly Accessible Names

@@ -3837,6 +3839,15 @@

Naming with Child Content

Naming with a String Attribute Via aria-label

+

+ because the aria-label and aria-labelledby attributes override content contained in some elementss, they can block assistive technology access to some on-screen text. + Thus, to both serve an optimal experience and avoid potentially disasterous mistakes, it is essential to understand when and how these two attributes override element text. +

+

There are two different kinds of labels, depending on the element’s role. The difference is both in how the label is computed for the element, and how the element is represented to assistive technologies.

+
    +
  • Label that represents the element. The label is taken from the element's contents, unless `aria-labelledby` or `aria-label` attributes are used. Only the label is represented to users of assistive technologies.
    • +
  • Label that augments the element. The label is not taken from the element's contents (by default). A label can be set using `aria-labelledby` or `aria-label`. The label will augment the element; both the label and the element's contents are exposed to users of assistive technology.
    • +

If there is no content that is appropriate to use as the label, then use the `aria-label` attribute to set the label for the element directly.

In the following example, a close button contains an "X" and is given the label “Close” using the `aria-label` attribute.

@@ -3898,9 +3909,10 @@

Label that augments the element

-
+

Composing Effective and User-friendly Accessible Names

Todo: Write a section that describes how to make good names, i.e., brief, descriptive, unique, front-loaded, no role names, etc.

+

Example practice: Do NOT include a WAI-ARIA role name in the accessible name. For example, do not include the word "button" in the name of a button or the word "navigation" in the name of a navigation region.

From 0f0524ff2ea694cb59b4ffb9c40f5e8478c65e53 Mon Sep 17 00:00:00 2001 From: Matt King Date: Thu, 9 May 2019 16:38:02 -0700 Subject: [PATCH 019/131] edits to cardinal rules --- aria-practices.html | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 1282b228e7..e39cba3007 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3723,10 +3723,10 @@

What ARE Accessible Names and Descriptions?

An accessible name is a short string, typically 1 to 3 words, that authors associate with an element to provide users of assistive technologies with a label for the element. For example, an input field might have an accessible name of "User ID" or a button might be named "Submit".

-

An accessible name serves two primary purposes:

+

An accessible name serves two primary purposes for users of assistive technologies, such as screen readers:

  1. Convey the purpose or intent of the element.
    2. -
  2. Distinguish it from other elements on the page.
    3. +
  3. Distinguishes an element from other elements on the page.

Both the WAI-ARIA specification and WCAG require all focusable, interactive elements to have an accessible name. @@ -3758,8 +3758,8 @@

Cardinal Rules of Naming

Rule 1: Heed Warnings and Test Thoroughly

- Several of the naming techniques include notes that warn against coding patterns that may appear logical at first glance but are either prohibitted by the ARIA specification or fall into gray space that is not yet fully specified. - These patterns may even yield desired names in some browsers. + Several of the below naming techniques include notes that warn against specific coding patterns that are either prohibitted by the ARIA specification or fall into gray space that is not yet fully specified. + Some of these prohibitted or ambiguous patterns may appear logical and even yield desired names in some browsers. However, it is unlikely they will provide consistent results across browsers, especially over time as work to improve the consistency of name calculation across browsers progresses.

@@ -3787,7 +3787,7 @@

Rule 3: Prefer Native Techniques

Rule 4: Avoid Browser Fallback

When authors do not specify an accessible name using an element or attribute that is intended for naming, browsers attempt to help assistive technology users by resorting to fall back methods for generating a name. - For example, the HTML title and placeholder attributes are used as last resort sources for accessible names. + For example, the HTML title and placeholder attributes are used as last resort sources of content for accessible names. Because the purpose of these attributes is not naming, their content typically yields low quality accessible names that are not effective.

@@ -3797,7 +3797,7 @@

Rule 5: Compose Brief, Useful Names

In the same way that visually crowded screens reduce usability, excessively long or insufficiently distinct and descriptive accessible names can make a user interface very difficult, or even impossible, to use for someone who relies on a non-visual form of the user interface. In other words, for a web experience to accessible, the names must be effective. - Composing Effective and User-friendly Accessible Names + The below section on Composing Effective and User-friendly Accessible Names provides guidance for striking an effective balance between brevity and descriptiveness.

@@ -3813,7 +3813,7 @@

Naming with Child Content

This could be rendered to assistive technology as "link, Home"; the role and the label, not not repeating the content ("link, Home, Home").

-

The following roles get the label from the contents by default:

+

Elements having one of the following roles are, by default, named by the content they contain:

  • `button`
  • `cell`
    • @@ -3828,7 +3828,6 @@

    Naming with Child Content

  • `option`
  • `radio`
  • `row`
    • -
  • `rowgroup`
  • `rowheader`
  • `switch`
  • `tab`
    • From e131ba5df38ddeed413fbfcee9baea56a4a2e4d9 Mon Sep 17 00:00:00 2001 From: Matt King Date: Sat, 11 May 2019 14:03:33 -0700 Subject: [PATCH 020/131] Adjust IA --- aria-practices.html | 574 ++++++++++++++++++++++---------------------- 1 file changed, 288 insertions(+), 286 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index e39cba3007..f394ad8bcd 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3746,319 +3746,321 @@

    What ARE Accessible Names and Descriptions?

    How Are Name and Description Strings Derived?

    - Because there are several elements and attributes for specifying text to include in an accessible name or description string, and because they can be combined in a practically endless number of ways, browsers implement fairly complex algorithms for assembling the strings. + Because there are several elements and attributes for specifying text to include in an accessible name or description string, and because authors can combine them in a practically endless number of ways, browsers implement fairly complex algorithms for assembling the strings. The sections on accessible name calculation and accessible description calculation provide detailed explanations of the algorithms. However, most authors do not need detailed understanding of the algorithms since nearly all circumstances where a name or description is useful are supported by the coding patterns described in the naming techniques and describing techniques sections.

    -
    -

    Cardinal Rules of Naming

    - -
    -

    Rule 1: Heed Warnings and Test Thoroughly

    -

    - Several of the below naming techniques include notes that warn against specific coding patterns that are either prohibitted by the ARIA specification or fall into gray space that is not yet fully specified. - Some of these prohibitted or ambiguous patterns may appear logical and even yield desired names in some browsers. - However, it is unlikely they will provide consistent results across browsers, especially over time as work to improve the consistency of name calculation across browsers progresses. -

    -

    - In addition to heeding the warnings provided in the naming techniques, it is difficult to over emphasize the importance of testing to ensure that names browsers calculate match expectations. -

    -
    - -
    -

    Rule 2: Prefer Visible Text

    -

    - When a user interface includes visible text that could be used to provide an appropriate accessible name, using the visible text for the accessible name simplifies maintenance, prevents bugs, and reduces language translation requirements. - When names are generated from text that exists only in markup and is never displayed visually, there is a greater likelihood that accessible names are not updated when the user interface design or content are changed. -

    -
    - -
    -

    Rule 3: Prefer Native Techniques

    -

    - In HTML documents, whenever possible, rely on HTML naming techniques, such as the HTML label element. - While less flexible, their simplicity and reliance on visible text help ensure robust accessible experiences. -

    -
    - -
    -

    Rule 4: Avoid Browser Fallback

    -

    - When authors do not specify an accessible name using an element or attribute that is intended for naming, browsers attempt to help assistive technology users by resorting to fall back methods for generating a name. - For example, the HTML title and placeholder attributes are used as last resort sources of content for accessible names. - Because the purpose of these attributes is not naming, their content typically yields low quality accessible names that are not effective. -

    -
    - -
    -

    Rule 5: Compose Brief, Useful Names

    -

    - In the same way that visually crowded screens reduce usability, excessively long or insufficiently distinct and descriptive accessible names can make a user interface very difficult, or even impossible, to use for someone who relies on a non-visual form of the user interface. - In other words, for a web experience to accessible, the names must be effective. - The below section on Composing Effective and User-friendly Accessible Names provides guidance for striking an effective balance between brevity and descriptiveness. -

    +
    +

    Accessible Names

    +
    +

    Cardinal Rules of Naming

    + +
    +
    Rule 1: Heed Warnings and Test Thoroughly
    +

    + Several of the below naming techniques include notes that warn against specific coding patterns that are either prohibitted by the ARIA specification or fall into gray space that is not yet fully specified. + Some of these prohibitted or ambiguous patterns may appear logical and even yield desired names in some browsers. + However, it is unlikely they will provide consistent results across browsers, especially over time as work to improve the consistency of name calculation across browsers progresses. +

    +

    + In addition to heeding the warnings provided in the naming techniques, it is difficult to over emphasize the importance of testing to ensure that names browsers calculate match expectations. +

    +
    + +
    +
    Rule 2: Prefer Visible Text
    +

    + When a user interface includes visible text that could be used to provide an appropriate accessible name, using the visible text for the accessible name simplifies maintenance, prevents bugs, and reduces language translation requirements. + When names are generated from text that exists only in markup and is never displayed visually, there is a greater likelihood that accessible names are not updated when the user interface design or content are changed. +

    +
    + +
    +
    Rule 3: Prefer Native Techniques
    +

    + In HTML documents, whenever possible, rely on HTML naming techniques, such as the HTML label element. + While less flexible, their simplicity and reliance on visible text help ensure robust accessible experiences. +

    +
    + +
    +
    Rule 4: Avoid Browser Fallback
    +

    + When authors do not specify an accessible name using an element or attribute that is intended for naming, browsers attempt to help assistive technology users by resorting to fall back methods for generating a name. + For example, the HTML title and placeholder attributes are used as last resort sources of content for accessible names. + Because the purpose of these attributes is not naming, their content typically yields low quality accessible names that are not effective. +

    +
    + +
    +
    Rule 5: Compose Brief, Useful Names
    +

    + In the same way that visually crowded screens reduce usability, excessively long or insufficiently distinct and descriptive accessible names can make a user interface very difficult, or even impossible, to use for someone who relies on a non-visual form of the user interface. + In other words, for a web experience to accessible, the names must be effective. + The below section on Composing Effective and User-friendly Accessible Names provides guidance for striking an effective balance between brevity and descriptiveness. +

    +
    -
    - -
    -

    Naming Techniques

    - -
    -

    Naming with Child Content

    -

    For elements with certain roles, the label is taken from the element’s contents by default, and the label will represent the element when communicated to assistive technologies. In the following example, a link (with default role `link`) gets its label from the element’s contents ("Home").

    - - 
    <a href="/">Home</a>
    - -

    This could be rendered to assistive technology as "link, Home"; the role and the label, not not repeating the content ("link, Home, Home").

    -

    Elements having one of the following roles are, by default, named by the content they contain:

    +
    +

    Naming Techniques

    + +
    +
    Naming with Child Content
    +

    For elements with certain roles, the label is taken from the element’s contents by default, and the label will represent the element when communicated to assistive technologies. In the following example, a link (with default role `link`) gets its label from the element’s contents ("Home").

    + + 
    <a href="/">Home</a>
    + +

    This could be rendered to assistive technology as "link, Home"; the role and the label, not not repeating the content ("link, Home, Home").

    + +

    Elements having one of the following roles are, by default, named by the content they contain:

    +
      +
    • `button`
      • +
    • `cell`
      • +
    • `checkbox`
      • +
    • `columnheader`
      • +
    • `gridcell`
      • +
    • `heading`
      • +
    • `link`
      • +
    • `menuitem`
      • +
    • `menuitemcheckbox`
      • +
    • `menuitemradio`
      • +
    • `option`
      • +
    • `radio`
      • +
    • `row`
      • +
    • `rowheader`
      • +
    • `switch`
      • +
    • `tab`
      • +
    • `tooltip`
      • +
    • `treeitem`
      • +
    +
    + +
    +
    Naming with a String Attribute Via aria-label
    +

    + because the aria-label and aria-labelledby attributes override content contained in some elementss, they can block assistive technology access to some on-screen text. + Thus, to both serve an optimal experience and avoid potentially disasterous mistakes, it is essential to understand when and how these two attributes override element text. +

    +

    There are two different kinds of labels, depending on the element’s role. The difference is both in how the label is computed for the element, and how the element is represented to assistive technologies.

      -
    • `button`
      • -
    • `cell`
      • -
    • `checkbox`
      • -
    • `columnheader`
      • -
    • `gridcell`
      • -
    • `heading`
      • -
    • `link`
      • -
    • `menuitem`
      • -
    • `menuitemcheckbox`
      • -
    • `menuitemradio`
      • -
    • `option`
      • -
    • `radio`
      • -
    • `row`
      • -
    • `rowheader`
      • -
    • `switch`
      • -
    • `tab`
      • -
    • `tooltip`
      • -
    • `treeitem`
      • +
    • Label that represents the element. The label is taken from the element's contents, unless `aria-labelledby` or `aria-label` attributes are used. Only the label is represented to users of assistive technologies.
      • +
    • Label that augments the element. The label is not taken from the element's contents (by default). A label can be set using `aria-labelledby` or `aria-label`. The label will augment the element; both the label and the element's contents are exposed to users of assistive technology.
    +

    If there is no content that is appropriate to use as the label, then use the `aria-label` attribute to set the label for the element directly.

    + +

    In the following example, a close button contains an "X" and is given the label “Close” using the `aria-label` attribute.

    + + 
    <button type="button" aria-label="Close">X</button>
    +
    +
    +
    Naming with Referenced Content Via aria-labeledby
    +

    If the element’s contents are not appropriate as a label, but there is an element that can be used as the label, then use the `aria-labelledby` attribute.

    + +

    In the following example, an element with the "switch" role is labeled by a previous sibling element.

    + + 
    <span id="night-mode-label">Night mode</span>
+  <span role="switch" aria-checked="false" tabindex="0" aria-labelledby="night-mode-label"></span>
    + +

    Because a `span` element is used for the switch control, the HTML `label` element cannot be used to label it, since it only works with HTML elements that are form controls. However, the `switch` role can be used on an `input` element with `type="checkbox”`, and then HTML `label` can be used.

    + + 
    <label for="night-mode">Night mode</label>
+  <input type="checkbox" role="switch" id="night-mode">
    + +

    In some cases, the combination of the element’s contents and another element would be appropriate as a label. In such situations, use the `aria-labelledby` and reference both the element itself and the other element.

    + +

    In the following example, a "read more" link is labeled by the element itself and the article’s heading, resulting in “Read more… 7 ways you can help save the bees”.

    + + 
    <h2 id="bees-heading">7 ways you can help save the bees</h2>
+  <p>Bees are disappearing rapidly.
+  Here are seven things you can do to help.</p>
+  <p><a id="bees-read-more" aria-labelledby="bees-read-more bees-heading">Read more...</a></p>
    +
    + +
    +
    Label that augments the element
    + +

    Some roles do not get the label from the contents of the element; a label can only be set explicitly using the `aria-labelledby` or `aria-label` attributes. For elements with these roles, a label augments the element, but does not override the contents.

    + +

    Examples of such roles are (note that this is not a complete list):

    + +
      +
    • `alertdialog`
      • +
    • `application`
      • +
    • `article`
      • +
    • `banner`
      • +
    • `complementary`
      • +
    • `navigation`
      • +
    • `radiogroup`
      • +
    • `search`
      • +
    • `status`
      • +
    + +

    For example, the `navigation` landmark could be labeled with the purpose of the landmark. In the following snippet, a "breadcrumbs" + navigation region is labeled explicitly using the `aria-labelledby` attribute. The HTML `nav` element has the `navigation` role by default.

    + + 
    <nav aria-labelledby="breadcrumbs-label">
+   <span id="breadcrumbs-label">You are here:</span>
+   <a href="/">Home</a> &gt;
+   <a href="/books/">Books</a> &gt;
+   <a>Children's books</a>
+  </nav>
    +
    -
    -

    Naming with a String Attribute Via aria-label

    -

    - because the aria-label and aria-labelledby attributes override content contained in some elementss, they can block assistive technology access to some on-screen text. - Thus, to both serve an optimal experience and avoid potentially disasterous mistakes, it is essential to understand when and how these two attributes override element text. -

    -

    There are two different kinds of labels, depending on the element’s role. The difference is both in how the label is computed for the element, and how the element is represented to assistive technologies.

    -
      -
    • Label that represents the element. The label is taken from the element's contents, unless `aria-labelledby` or `aria-label` attributes are used. Only the label is represented to users of assistive technologies.
      • -
    • Label that augments the element. The label is not taken from the element's contents (by default). A label can be set using `aria-labelledby` or `aria-label`. The label will augment the element; both the label and the element's contents are exposed to users of assistive technology.
      • -
    -

    If there is no content that is appropriate to use as the label, then use the `aria-label` attribute to set the label for the element directly.

    - -

    In the following example, a close button contains an "X" and is given the label “Close” using the `aria-label` attribute.

    - - 
    <button type="button" aria-label="Close">X</button>
    +
    +

    Composing Effective and User-friendly Accessible Names

    +

    Todo: Write a section that describes how to make good names, i.e., brief, descriptive, unique, front-loaded, no role names, etc.

    +

    Example practice: Do NOT include a WAI-ARIA role name in the accessible name. For example, do not include the word "button" in the name of a button or the word "navigation" in the name of a navigation region.

    -
    -

    Naming with Referenced Content Via aria-labeledby

    -

    If the element’s contents are not appropriate as a label, but there is an element that can be used as the label, then use the `aria-labelledby` attribute.

    - -

    In the following example, an element with the "switch" role is labeled by a previous sibling element.

    - - 
    <span id="night-mode-label">Night mode</span>
-<span role="switch" aria-checked="false" tabindex="0" aria-labelledby="night-mode-label"></span>
    - -

    Because a `span` element is used for the switch control, the HTML `label` element cannot be used to label it, since it only works with HTML elements that are form controls. However, the `switch` role can be used on an `input` element with `type="checkbox”`, and then HTML `label` can be used.

    - - 
    <label for="night-mode">Night mode</label>
-<input type="checkbox" role="switch" id="night-mode">
    - -

    In some cases, the combination of the element’s contents and another element would be appropriate as a label. In such situations, use the `aria-labelledby` and reference both the element itself and the other element.

    - -

    In the following example, a "read more" link is labeled by the element itself and the article’s heading, resulting in “Read more… 7 ways you can help save the bees”.

    - - 
    <h2 id="bees-heading">7 ways you can help save the bees</h2>
-<p>Bees are disappearing rapidly.
-Here are seven things you can do to help.</p>
-<p><a id="bees-read-more" aria-labelledby="bees-read-more bees-heading">Read more...</a></p>
    -
    - -
    -

    Label that augments the element

    - -

    Some roles do not get the label from the contents of the element; a label can only be set explicitly using the `aria-labelledby` or `aria-label` attributes. For elements with these roles, a label augments the element, but does not override the contents.

    - -

    Examples of such roles are (note that this is not a complete list):

    - + +
    +

    Accessible Name Guidance by Role

    +

    Todo: build a table with every concrete role with columns for:

      -
    • `alertdialog`
      • -
    • `application`
      • -
    • `article`
      • -
    • `banner`
      • -
    • `complementary`
      • -
    • `navigation`
      • -
    • `radiogroup`
      • -
    • `search`
      • -
    • `status`
      • +
    • role
      • +
    • Name Required?: with values of always, sometimes, or never
      • +
    • Named by Content?: values of Yes or No
      • +
    • Guidance: Explains sometimes and never for name required. Provides warning if named from content.
    - -

    For example, the `navigation` landmark could be labeled with the purpose of the landmark. In the following snippet, a "breadcrumbs" - navigation region is labeled explicitly using the `aria-labelledby` attribute. The HTML `nav` element has the `navigation` role by default.

    - - 
    <nav aria-labelledby="breadcrumbs-label">
- <span id="breadcrumbs-label">You are here:</span>
- <a href="/">Home</a> &gt;
- <a href="/books/">Books</a> &gt;
- <a>Children's books</a>
-</nav>
    +
    + +
    +

    Accessible name calculation

    +

    User agents follow the accessible name calculation algorithm to get the label for an element. This is defined in [https://w3c.github.io/accname/](https://w3c.github.io/accname/) and [https://w3c.github.io/html-aam/](https://w3c.github.io/html-aam/) for HTML.

    +

    User agents attempt to formulate labels for elements by walking through a list of potential naming methods and use the first that generates a name. The algorithm is roughly like this:

    +
      +
    1. First, the `aria-labelledby` attribute is used if present.
      2. +
    2. If the label is still empty, the `aria-label` attribute is used if present.
      3. +
    3. If the label is still empty, then host-language-specific attributes or elements (e.g., the `alt` attribute on HTML `img`) are used if present.
      4. +
    4. If the label is still empty, then for roles that can take label from the element's content, the element’s contents.
      5. +
    5. Finally, if the label is still empty, then host-langauge-specific tooltip attributes or elements (e.g., the `title` attribute in HTML) are used if present.
      6. +
    + +

    The final step is a fallback mechanism. Generally when labelling an element, use one of the non-fallback mechanisms.

    + +

    For example, for the HTML `input` element, the `placeholder` attribute is used as a fallback labeling mechanism if nothing else results in a label. For an `input` element, it is better to use a `label` element, since it does not disappear visually when the user focuses the form control.

    + +
    +
    Examples of non-recursive accessible name calculation
    + +

    For example, an img element with just a src attribute has no label (don’t do this):

    + + 
    <img src="photo.jpg">
    + +

    If there is a `title` attribute, then that is used as the label (fallback mechanism; generally avoid doing this):

    + + 
    <img src="photo.jpg" title="The Queen, holding a pigeon.">
    + +

    If there is also an `alt` attribute (using `alt` for images is recommended), then that is used as the label, and the `title` attribute is instead used as the accessible description:

    + + 
    <img src="photo.jpg" alt="The Queen, holding a pigeon." title="Photo: Rex Features">
    + +

    If there is also an `aria-label` attribute, then that overrides the `alt` attribute:

    + + 
    <img src="photo.jpg" aria-label="The Queen, holding a pigeon." title="Photo: Rex Features"
+     alt="Sorry, this image failed to load.">
    + +

    If there is also an `aria-labelledby` attribute, that wins over the other attributes (the `aria-label` attribute ought to be removed if it is not used):

    + + 
    <img src="photo.jpg" aria-label="This is ignored." title="Photo: Established Depiction"
+     alt="Sorry, this image failed to load." aria-labelledby="the-queen">
+    <span id="the-queen">The Queen, holding a pigeon.</span>
    +
    + +
    +
    Examples of recursive accessible name calculation
    + +

    The accessible name calculation algorithm will be invoked recursively when necessary. An `aria-labelledby` reference causes the algorithm to be invoked recursively, and when computing an accessible name from content the algorithm is invoked recursively for each child node.

    + +

    In this example, the label for the button is computed by recursing into each child node, resulting in "Move to trash".

    + + 
    <button>Move to <img src="bin.svg" alt="trash"></button>
    + +

    When following an `aria-labelledby` reference, the algorithm avoids following the same reference twice in order to not end up in infinite loops.

    + +

    In this example, the label for the button is computed by first following the `aria-labelledby` reference to the parent element, and then computing the label for that element from the child nodes, first visiting the `button` element again but ignoring the `aria-labelledby` reference and instead using the `aria-label` attribute, and then visiting the next child (the text node). The resulting label is "Remove meeting: Daily status report".

    + + 
    <div id="meeting-1">
+    <button aria-labelledby="meeting-1"
+        aria-label="Remove meeting:">X</button>
+        Daily status report
+    </div>
    + +

    It is also possible to reference an element using `aria-labelledby` even if that element is hidden. In the following example, the `span` element could be styled with CSS `display: none` and the `nav` element would still have the label "You are here:".

    + + 
    <nav aria-labelledby="breadcrumbs-label">
+    <span id="breadcrumbs-label">You are here:</span>
+      <a href="/">Home</a> &gt;
+      <a href="/books/">Books</a> &gt;
+      <a>Children's books</a>
+    </nav>
    +
    -
    -

    Composing Effective and User-friendly Accessible Names

    -

    Todo: Write a section that describes how to make good names, i.e., brief, descriptive, unique, front-loaded, no role names, etc.

    -

    Example practice: Do NOT include a WAI-ARIA role name in the accessible name. For example, do not include the word "button" in the name of a button or the word "navigation" in the name of a navigation region.

    -
    +
    +

    Accessible Descriptions

    +
    +

    Describing Techniques

    + +
    +
    Describing by referencing content with aria-describedby
    +

    The `aria-describedby` attribute works similarly to the `aria-labelledby` attribute. For example, a button could be described by a later paragraph.

    -
    -

    Accessible Name Guidance by Role

    -

    Todo: build a table with every concrete role with columns for:

    -
      -
    • role
      • -
    • Name Required?: with values of always, sometimes, or never
      • -
    • Named by Content?: values of Yes or No
      • -
    • Guidance: Explains sometimes and never for name required. Provides warning if named from content.
      • -
    -
    + 
    <button aria-describedby="trash-desc">Move to trash</button>
+            ...
+            <p id="trash-desc">Items in the trash
+            will be permanently removed after 30 days.</p>
    -
    -

    Accessible name calculation

    -

    User agents follow the accessible name calculation algorithm to get the label for an element. This is defined in [https://w3c.github.io/accname/](https://w3c.github.io/accname/) and [https://w3c.github.io/html-aam/](https://w3c.github.io/html-aam/) for HTML.

    -

    User agents attempt to formulate labels for elements by walking through a list of potential naming methods and use the first that generates a name. The algorithm is roughly like this:

    -
      -
    1. First, the `aria-labelledby` attribute is used if present.
      2. -
    2. If the label is still empty, the `aria-label` attribute is used if present.
      3. -
    3. If the label is still empty, then host-language-specific attributes or elements (e.g., the `alt` attribute on HTML `img`) are used if present.
      4. -
    4. If the label is still empty, then for roles that can take label from the element's content, the element’s contents.
      5. -
    5. Finally, if the label is still empty, then host-langauge-specific tooltip attributes or elements (e.g., the `title` attribute in HTML) are used if present.
      6. -
    - -

    The final step is a fallback mechanism. Generally when labelling an element, use one of the non-fallback mechanisms.

    - -

    For example, for the HTML `input` element, the `placeholder` attribute is used as a fallback labeling mechanism if nothing else results in a label. For an `input` element, it is better to use a `label` element, since it does not disappear visually when the user focuses the form control.

    - -
    -

    Examples of non-recursive accessible name calculation

    - -

    For example, an img element with just a src attribute has no label (don’t do this):

    - - 
    <img src="photo.jpg">
    - -

    If there is a `title` attribute, then that is used as the label (fallback mechanism; generally avoid doing this):

    - - 
    <img src="photo.jpg" title="The Queen, holding a pigeon.">
    - -

    If there is also an `alt` attribute (using `alt` for images is recommended), then that is used as the label, and the `title` attribute is instead used as the accessible description:

    - - 
    <img src="photo.jpg" alt="The Queen, holding a pigeon." title="Photo: Rex Features">
    - -

    If there is also an `aria-label` attribute, then that overrides the `alt` attribute:

    - - 
    <img src="photo.jpg" aria-label="The Queen, holding a pigeon." title="Photo: Rex Features"
-   alt="Sorry, this image failed to load.">
    - -

    If there is also an `aria-labelledby` attribute, that wins over the other attributes (the `aria-label` attribute ought to be removed if it is not used):

    - - 
    <img src="photo.jpg" aria-label="This is ignored." title="Photo: Established Depiction"
-   alt="Sorry, this image failed to load." aria-labelledby="the-queen">
-  <span id="the-queen">The Queen, holding a pigeon.</span>
    +

    This description will be presented to the user as plain text. For example, if the description contains an HTML `img` element, a text equivalent of the image is computed.

    + + 
    <button aria-describedby="trash-desc">
+            Move to <img src="bin.svg" alt="trash">
+            </button>
+            ...
+            <p id="trash-desc">Items in <img src="bin.svg" alt="the trash">
+            will be permanently removed after 30 days.</p>
    - +
    -

    Examples of recursive accessible name calculation

    - -

    The accessible name calculation algorithm will be invoked recursively when necessary. An `aria-labelledby` reference causes the algorithm to be invoked recursively, and when computing an accessible name from content the algorithm is invoked recursively for each child node.

    - -

    In this example, the label for the button is computed by recursing into each child node, resulting in "Move to trash".

    - - 
    <button>Move to <img src="bin.svg" alt="trash"></button>
    - -

    When following an `aria-labelledby` reference, the algorithm avoids following the same reference twice in order to not end up in infinite loops.

    - -

    In this example, the label for the button is computed by first following the `aria-labelledby` reference to the parent element, and then computing the label for that element from the child nodes, first visiting the `button` element again but ignoring the `aria-labelledby` reference and instead using the `aria-label` attribute, and then visiting the next child (the text node). The resulting label is "Remove meeting: Daily status report".

    - - 
    <div id="meeting-1">
-  <button aria-labelledby="meeting-1"
-      aria-label="Remove meeting:">X</button>
-      Daily status report
-  </div>
    - -

    It is also possible to reference an element using `aria-labelledby` even if that element is hidden. In the following example, the `span` element could be styled with CSS `display: none` and the `nav` element would still have the label "You are here:".

    - - 
    <nav aria-labelledby="breadcrumbs-label">
-  <span id="breadcrumbs-label">You are here:</span>
-    <a href="/">Home</a> &gt;
-    <a href="/books/">Books</a> &gt;
-    <a>Children's books</a>
-  </nav>
    -
    -
    +
    Describing by referencing content with aria-details
    +

    In some cases, a plain text description is insufficient. The `aria-details` attribute can be used in such situations. In this example, a text field for a passenger’s name (when booking a flight) has a description that is a list of three items, and contains a link to an external document with further details.

    -
    -

    Describing Techniques

    - -
    -

    Describing by referencing content with aria-describedby

    -

    The `aria-describedby` attribute works similarly to the `aria-labelledby` attribute. For example, a button could be described by a later paragraph.

    - - 
    <button aria-describedby="trash-desc">Move to trash</button>
-          ...
-          <p id="trash-desc">Items in the trash
-          will be permanently removed after 30 days.</p>
    - -

    This description will be presented to the user as plain text. For example, if the description contains an HTML `img` element, a text equivalent of the image is computed.

    - - 
    <button aria-describedby="trash-desc">
-          Move to <img src="bin.svg" alt="trash">
-          </button>
-          ...
-          <p id="trash-desc">Items in <img src="bin.svg" alt="the trash">
-          will be permanently removed after 30 days.</p>
    -
    + 
    <ul id="full-name-desc">
+            <li>The passenger's name must match the name in their passport.</li>
+            <li>The name must consist of only characters in the A-Z range.</li>
+            <li><a href="faq.html#name">What if the name in the passport contains other characters?</a></li>
+            </ul>
+            <fieldset>
+            <legend>Passenger 1 (adult)</legend>
+            <p><label>Full name
+            <input name="full-name" aria-details="full-name-desc">
+            </label></p>
+            ...
+            </fieldset>
    -
    -

    Describing by referencing content with aria-details>

    -

    In some cases, a plain text description is insufficient. The `aria-details` attribute can be used in such situations. In this example, a text field for a passenger’s name (when booking a flight) has a description that is a list of three items, and contains a link to an external document with further details.

    +

    If both `aria-details` and `aria-describedby` are specified on an element, only the `aria-details` attribute is used. This can be useful in order to provide a fallback for user agents that don’t support `aria-details`.

    +
    +
    - 
    <ul id="full-name-desc">
-          <li>The passenger's name must match the name in their passport.</li>
-          <li>The name must consist of only characters in the A-Z range.</li>
-          <li><a href="faq.html#name">What if the name in the passport contains other characters?</a></li>
-          </ul>
-          <fieldset>
-          <legend>Passenger 1 (adult)</legend>
-          <p><label>Full name
-          <input name="full-name" aria-details="full-name-desc">
-          </label></p>
-          ...
-          </fieldset>
    +
    +

    Accessible description calculation

    +

    Like the accessible name calculation (see the earlier section), the accessible description calculation produces a plain text string for an element. This algorithm is not used for the `aria-details` attribute.

    +

    The accessible description calculation algorithm is the same algorithm as the accessible name calculation algorithm, but it branches off in some places depending on whether a name or a description is being calculated. In particular, when collecting an accessible description, the algorithm uses `aria-describedby` instead of `aria-labelledby`.

    +

    As with `aria-labelledby`, it is possible to reference an element using `aria-describedby` even if that element is hidden.

    +

    For example, a text field in a form could have a description that is hidden by default, but can be revealed on request using a disclosure widget. The description could also be referenced from the text field directly with `aria-describedby`. The accessible description for the `input` element is "Your username is the name that you use to log in to this service.".

    -

    If both `aria-details` and `aria-describedby` are specified on an element, only the `aria-details` attribute is used. This can be useful in order to provide a fallback for user agents that don’t support `aria-details`.

    + 
    <label for="username">Username</label>
+          <input id="username" name="username" aria-describedby="username-desc">
+          <button aria-expanded="false" aria-controls="username-desc" aria-label="Help about username">?</button>
+          <p id="username-desc" hidden>
+          Your username is the name that you use to log in to this service.
+          </p>
    - -
    -

    Accessible description calculation

    - -

    Like the accessible name calculation (see the earlier section), the accessible description calculation produces a plain text string for an element. This algorithm is not used for the `aria-details` attribute.

    - -

    The accessible description calculation algorithm is the same algorithm as the accessible name calculation algorithm, but it branches off in some places depending on whether a name or a description is being calculated. In particular, when collecting an accessible description, the algorithm uses `aria-describedby` instead of `aria-labelledby`.

    - -

    As with `aria-labelledby`, it is possible to reference an element using `aria-describedby` even if that element is hidden.

    - -

    For example, a text field in a form could have a description that is hidden by default, but can be revealed on request using a disclosure widget. The description could also be referenced from the text field directly with `aria-describedby`. The accessible description for the `input` element is "Your username is the name that you use to log in to this service.".

    - - 
    <label for="username">Username</label>
-        <input id="username" name="username" aria-describedby="username-desc">
-        <button aria-expanded="false" aria-controls="username-desc" aria-label="Help about username">?</button>
-        <p id="username-desc" hidden>
-        Your username is the name that you use to log in to this service.
-        </p>
    -
    From a40f81b940a0f27e115162f6b0e8dc735b66718e Mon Sep 17 00:00:00 2001 From: Matt King Date: Sat, 11 May 2019 17:08:36 -0700 Subject: [PATCH 021/131] Editorial revisions to name from content --- aria-practices.html | 57 +++++++++++++++++++++++++++------------------ 1 file changed, 34 insertions(+), 23 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index f394ad8bcd..908a10c97d 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3809,33 +3809,44 @@

    Naming Techniques

    Naming with Child Content
    -

    For elements with certain roles, the label is taken from the element’s contents by default, and the label will represent the element when communicated to assistive technologies. In the following example, a link (with default role `link`) gets its label from the element’s contents ("Home").

    - +

    + There are certain elements that get their name from the content they contain. + For example, the following link is named "Home". +

    + 
    <a href="/">Home</a>
    -

    This could be rendered to assistive technology as "link, Home"; the role and the label, not not repeating the content ("link, Home, Home").

    - -

    Elements having one of the following roles are, by default, named by the content they contain:

    +

    + When assistive technologies render an element, such as a link or button, that gets its accessible name from its content, the accessible name is the only content the user can perceive for that element. + This is in contrast to other elements, such as text fields or tables, where the accessible name is a label that is presented along with the value or content of the element. + For instance, the accessible name of a table can be derived from a caption element, and assistive technologies render both the caption and all other content contained inside the table. +

    +

    Elements having one of the following roles are, by default, named by a string calculated from all their descendant content:

      -
    • `button`
      • -
    • `cell`
      • -
    • `checkbox`
      • -
    • `columnheader`
      • -
    • `gridcell`
      • -
    • `heading`
      • -
    • `link`
      • -
    • `menuitem`
      • -
    • `menuitemcheckbox`
      • -
    • `menuitemradio`
      • -
    • `option`
      • -
    • `radio`
      • -
    • `row`
      • -
    • `rowheader`
      • -
    • `switch`
      • -
    • `tab`
      • -
    • `tooltip`
      • -
    • `treeitem`
      • +
    • button
      • +
    • cell
      • +
    • checkbox
      • +
    • columnheader
      • +
    • gridcell
      • +
    • heading
      • +
    • link
      • +
    • menuitem
      • +
    • menuitemcheckbox
      • +
    • menuitemradio
      • +
    • option
      • +
    • radio
      • +
    • row
      • +
    • rowheader
      • +
    • switch
      • +
    • tab
      • +
    • tooltip
      • +
    • treeitem
    +

    + WARNING! If an element with one of the above roles is named by using aria-label or aria-labelledby, text content contained in the element and its descendants is hidden from assistive technology users unless the descendant content is referenced by aria-labelledby. + It is strongly recommended to avoid using either of these attributes to override content of one of the above elements except in rare circumstances where hiding content from assistive technology users is beneficial. + In addition, in situations where visible content is hidden from assistive technology users by use of one of these attributes, thorough testing with assistive technologies is particularly important. +

    From 93c9ec7f6ee65fdb2259f2a85376be360381d093 Mon Sep 17 00:00:00 2001 From: Matt King Date: Sun, 12 May 2019 10:06:43 -0700 Subject: [PATCH 022/131] Editorial revisions to aria-label section --- aria-practices.html | 51 ++++++++++++++++++++++++++++++++------------- 1 file changed, 36 insertions(+), 15 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 908a10c97d..ff9f3719b3 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3807,7 +3807,7 @@
    Rule 5: Compose Brief, Useful Names

    Naming Techniques

    -
    +
    Naming with Child Content

    There are certain elements that get their name from the content they contain. @@ -3849,24 +3849,45 @@

    Naming with Child Content

    -
    +
    Naming with a String Attribute Via aria-label

    - because the aria-label and aria-labelledby attributes override content contained in some elementss, they can block assistive technology access to some on-screen text. - Thus, to both serve an optimal experience and avoid potentially disasterous mistakes, it is essential to understand when and how these two attributes override element text. + The aria-label attribute enables authors to specify a string that will name an element. + For example, the name of the following button is "Close".

    -

    There are two different kinds of labels, depending on the element’s role. The difference is both in how the label is computed for the element, and how the element is represented to assistive technologies.

    -
      -
    • Label that represents the element. The label is taken from the element's contents, unless `aria-labelledby` or `aria-label` attributes are used. Only the label is represented to users of assistive technologies.
      • -
    • Label that augments the element. The label is not taken from the element's contents (by default). A label can be set using `aria-labelledby` or `aria-label`. The label will augment the element; both the label and the element's contents are exposed to users of assistive technology.
      • -
    -

    If there is no content that is appropriate to use as the label, then use the `aria-label` attribute to set the label for the element directly.

    - -

    In the following example, a close button contains an "X" and is given the label “Close” using the `aria-label` attribute.

    - 
    <button type="button" aria-label="Close">X</button>
    +

    + The aria-label attribute is useful when there is no visible text content that will serve as an appropriate accessible name. +

    +

    + The aria-label attribute effects assistive technology users in one of two different ways, depending on the role of the element to which it is applied. + When applied to an element with one of the roles that supports naming from child content, aria-label hides descendant content from assistive technology users and replaces the content with the value of aria-label. + However, when applied to nearly any other type of element, assistive technologies will render both the value of aria-label and the content of the element. + For example, the name of the following navigation region is "Product". +

    + 
    
+          <nav aria-label="Product">
+            <!-- list of navigation links to product pages -->
+          </nav>
+
    +

    + When encountering this navigation region, a screen reader user will hear the name and role of the element, e.g., "Product navigation region", and then be able to read through the links contained in the region. +

    +
    +

    Warnings!

    +
      +
    1. There are certain types of elements that should not be named with aria-label. They are identified in the table in section Accessible Name Guidance by Role.
      2. +
    2. + If aria-label is applied to an element with one of the roles that supports naming from child content, text content contained in the element and its descendants is hidden from assistive technology users. + It is strongly recommended to avoid using this attribute to override content of one of these elements except in rare circumstances where hiding content from assistive technology users is beneficial. +
      3. +
    3. Because the value of aria-label is not rendered visually, testing with assistive technologies to ensure the expected name is presented to users is particularly important.
      4. +
    4. When a user interface is translated into multiple languages, ensure that aria-lable values are translated.
      5. +
    +
    -
    + +
    Naming with Referenced Content Via aria-labeledby

    If the element’s contents are not appropriate as a label, but there is an element that can be used as the label, then use the `aria-labelledby` attribute.

    @@ -3889,7 +3910,7 @@
    Naming with Referenced Content Via aria-labeledby
    Here are seven things you can do to help.</p> <p><a id="bees-read-more" aria-labelledby="bees-read-more bees-heading">Read more...</a></p>
    - +
    Label that augments the element
    From 9276759ee0d054d99c7fd8a0ef3695c4c99b040d Mon Sep 17 00:00:00 2001 From: Matt King Date: Sun, 12 May 2019 14:25:45 -0700 Subject: [PATCH 023/131] Editorial revision to aria-labelledby section --- aria-practices.html | 133 ++++++++++++++++++++++---------------------- 1 file changed, 66 insertions(+), 67 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index ff9f3719b3..ce20749ee1 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3726,7 +3726,7 @@

    What ARE Accessible Names and Descriptions?

    An accessible name serves two primary purposes for users of assistive technologies, such as screen readers:

    1. Convey the purpose or intent of the element.
      2. -
    2. Distinguishes an element from other elements on the page.
      3. +
    3. Distinguish the element from other elements on the page.

    Both the WAI-ARIA specification and WCAG require all focusable, interactive elements to have an accessible name. @@ -3842,8 +3842,8 @@

    Naming with Child Content
  • tooltip
  • treeitem
-

- WARNING! If an element with one of the above roles is named by using aria-label or aria-labelledby, text content contained in the element and its descendants is hidden from assistive technology users unless the descendant content is referenced by aria-labelledby. +

+ If an element with one of the above roles is named by using aria-label or aria-labelledby, text content contained in the element and its descendants is hidden from assistive technology users unless the descendant content is referenced by aria-labelledby. It is strongly recommended to avoid using either of these attributes to override content of one of the above elements except in rare circumstances where hiding content from assistive technology users is beneficial. In addition, in situations where visible content is hidden from assistive technology users by use of one of these attributes, thorough testing with assistive technologies is particularly important.

@@ -3873,72 +3873,71 @@
Naming with a String Attribute Via aria-label

When encountering this navigation region, a screen reader user will hear the name and role of the element, e.g., "Product navigation region", and then be able to read through the links contained in the region.

-
-

Warnings!

-
    -
  1. There are certain types of elements that should not be named with aria-label. They are identified in the table in section Accessible Name Guidance by Role.
    2. -
  2. - If aria-label is applied to an element with one of the roles that supports naming from child content, text content contained in the element and its descendants is hidden from assistive technology users. - It is strongly recommended to avoid using this attribute to override content of one of these elements except in rare circumstances where hiding content from assistive technology users is beneficial. -
    3. -
  3. Because the value of aria-label is not rendered visually, testing with assistive technologies to ensure the expected name is presented to users is particularly important.
    4. -
  4. When a user interface is translated into multiple languages, ensure that aria-lable values are translated.
    5. -
-
+
    +
  1. + If aria-label is applied to an element with one of the roles that supports naming from child content, text content contained in the element and its descendants is hidden from assistive technology users. + It is strongly recommended to avoid using this attribute to override content of one of these elements except in rare circumstances where hiding content from assistive technology users is beneficial. +
    2. +
  2. There are certain types of elements, such as paragraphs and list items, that should not be named with aria-label. They are identified in the table in section Accessible Name Guidance by Role.
    3. +
  3. Because the value of aria-label is not rendered visually, testing with assistive technologies to ensure the expected name is presented to users is particularly important.
    4. +
  4. When a user interface is translated into multiple languages, ensure that aria-lable values are translated.
    5. +
Naming with Referenced Content Via aria-labeledby
-

If the element’s contents are not appropriate as a label, but there is an element that can be used as the label, then use the `aria-labelledby` attribute.

- -

In the following example, an element with the "switch" role is labeled by a previous sibling element.

- - 
<span id="night-mode-label">Night mode</span>
-  <span role="switch" aria-checked="false" tabindex="0" aria-labelledby="night-mode-label"></span>
- -

Because a `span` element is used for the switch control, the HTML `label` element cannot be used to label it, since it only works with HTML elements that are form controls. However, the `switch` role can be used on an `input` element with `type="checkbox”`, and then HTML `label` can be used.

- - 
<label for="night-mode">Night mode</label>
-  <input type="checkbox" role="switch" id="night-mode">
- -

In some cases, the combination of the element’s contents and another element would be appropriate as a label. In such situations, use the `aria-labelledby` and reference both the element itself and the other element.

- -

In the following example, a "read more" link is labeled by the element itself and the article’s heading, resulting in “Read more… 7 ways you can help save the bees”.

- - 
<h2 id="bees-heading">7 ways you can help save the bees</h2>
-  <p>Bees are disappearing rapidly.
-  Here are seven things you can do to help.</p>
-  <p><a id="bees-read-more" aria-labelledby="bees-read-more bees-heading">Read more...</a></p>
-
- -
-
Label that augments the element
- -

Some roles do not get the label from the contents of the element; a label can only be set explicitly using the `aria-labelledby` or `aria-label` attributes. For elements with these roles, a label augments the element, but does not override the contents.

- -

Examples of such roles are (note that this is not a complete list):

- -
    -
  • `alertdialog`
    • -
  • `application`
    • -
  • `article`
    • -
  • `banner`
    • -
  • `complementary`
    • -
  • `navigation`
    • -
  • `radiogroup`
    • -
  • `search`
    • -
  • `status`
    • -
- -

For example, the `navigation` landmark could be labeled with the purpose of the landmark. In the following snippet, a "breadcrumbs" - navigation region is labeled explicitly using the `aria-labelledby` attribute. The HTML `nav` element has the `navigation` role by default.

- - 
<nav aria-labelledby="breadcrumbs-label">
-   <span id="breadcrumbs-label">You are here:</span>
-   <a href="/">Home</a> &gt;
-   <a href="/books/">Books</a> &gt;
-   <a>Children's books</a>
-  </nav>
+

+ The aria-labelledby property enables authors to reference other elements on the page to define an accessible name. + For example, the following switch is named by the text content of a previous sibling element. +

+ 

+  <span id="night-mode-label">Night mode</span>
+  <span role="switch" aria-checked="false" tabindex="0" aria-labelledby="night-mode-label"></span>
+
+

+ Note that while using aria-labelledby is similar in this situation to using an HTML label element with the for attribute, one significant difference is that browsers do not automatically make clicking on the label activate the element; that is an author responsibility. + However, HTML label cannot be used to label a span element. + Fortunately, an HTML inputtype="checkbox" allows the ARIA switch role, so when feasible, using the following approach creates a more robust solution. +

+ 

+  <label for="night-mode">Night mode</label>
+  <input type="checkbox" role="switch" id="night-mode">
+
+

The aria-labelledby property is useful in a wide variety of situations because:

+
    +
  • It has the highest precedence when browsers calculate accessible names, i.e., it overrides names from child content and all other naming attributes, such as aria-label.
    • +
  • It can concatenate content from multiple elements into a single name string.
    • +
  • It incorporates content from elements regardless of their visibility, i.e., it even includes content from elements with display:none or visibility:hidden in the calculated name string.
    • +
  • It incorporates the value of input elements, i.e., if it references a textbox, the value of the textbox is included in the calculated name string.
    • +
+

+ In some cases, the most effective name for an element is its own content combined with the content of another element. + Because aria-labelledby has highest precedence in name calculation, in those situations, it is possible to use aria-labelledby to reference both the element itself and the other element. + In the following example, the "read more" link is named by the element itself and the article’s heading, resulting in a name of "Read more... 7 ways you can help save the bees". +

+ 

+  <h2 id="bees-heading">7 ways you can help save the bees</h2>
+  <p>Bees are disappearing rapidly. Here are seven things you can do to help.</p>
+  <p><a id="bees-read-more" aria-labelledby="bees-read-more bees-heading">Read more...</a></p>
+
+

+ When multiple elements are referenced, the text content of the referenced elements will be concatenated in the order they are listed in the attribute value. + In addition, browsers will trim leading and trailing white space and separate the content from each element with a single space. +

+

+ To-do: add one or two more simple but realistic examples to show reference to hidden elements and inputs, perhaps also highlighting how browsers handle spacing. + Short examples, 3 lines of code or less, are preferrable. +

+
    +
  1. The aria-labelledby property cannot be chained, i.e., if an element with aria-labelled by references another element that also has aria-labelledby, the aria-labelledby attribute on the referenced element will be ignored.
    2. +
  2. The aria-labelledby property cannot be applied to the descendant of an element that supports naming from content. For example, most browsers will ignore the aria-labelledby attribute in this link: <a href="/"><span aria-labelledby="elem1"></span><a>.
    3. +
  3. There are certain types of elements, such as paragraphs and list items, that should not be named with aria-labelledby. They are identified in the table in section Accessible Name Guidance by Role.
    4. +
  4. + If aria-labelledby is applied to an element with one of the roles that supports naming from child content, text content contained in the element and its descendants is hidden from assistive technology users unless it is also referenced by aria-labelledby. + It is strongly recommended to avoid using this attribute to override content of one of these elements except in rare circumstances where hiding content from assistive technology users is beneficial. +
    5. +
  5. Because calculating the name of an element with aria-labelledby can be complex and reference hidden content, testing with assistive technologies to ensure the expected name is presented to users is particularly important.
    6. +
@@ -3953,9 +3952,9 @@

Accessible Name Guidance by Role

Todo: build a table with every concrete role with columns for:

  • role
    • -
  • Name Required?: with values of always, sometimes, or never
    • +
  • Name Required?: with values of always, usually, sometimes, or never
  • Named by Content?: values of Yes or No
    • -
  • Guidance: Explains sometimes and never for name required. Provides warning if named from content.
    • +
  • Guidance: Explains usually, sometimes and never for name required. Provides warning if named from content.
From 0f48fdb636ce545655e4faf026f7db6cb8f5c2f5 Mon Sep 17 00:00:00 2001 From: Matt King Date: Sun, 12 May 2019 21:18:52 -0700 Subject: [PATCH 024/131] complete outline for naming techniques --- aria-practices.html | 29 ++++++++++++++++++++++------- 1 file changed, 22 insertions(+), 7 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index ce20749ee1..0ddb87ba89 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3707,9 +3707,9 @@

Providing Accessible Names and Descriptions

  • Naming with child content.
    • -
  • Naming by encapsulation with a label.
  • Naming with a String Attribute Via aria-label.
  • Naming by Referencing Content with aria-labelledby.
    • +
  • Naming by encapsulation with a label.
  • Naming with Legends and Captions.
  • Fallback Names Derived from Titles and Placeholders.
  • Describing by referencing content with aria-describedby.
    • @@ -3757,7 +3757,7 @@

    Accessible Names

    Cardinal Rules of Naming

    -
    +
    Rule 1: Heed Warnings and Test Thoroughly

    Several of the below naming techniques include notes that warn against specific coding patterns that are either prohibitted by the ARIA specification or fall into gray space that is not yet fully specified. @@ -3769,7 +3769,7 @@

    Rule 1: Heed Warnings and Test Thoroughly

    -
    +
    Rule 2: Prefer Visible Text

    When a user interface includes visible text that could be used to provide an appropriate accessible name, using the visible text for the accessible name simplifies maintenance, prevents bugs, and reduces language translation requirements. @@ -3777,7 +3777,7 @@

    Rule 2: Prefer Visible Text

    -
    +
    Rule 3: Prefer Native Techniques

    In HTML documents, whenever possible, rely on HTML naming techniques, such as the HTML label element. @@ -3785,7 +3785,7 @@

    Rule 3: Prefer Native Techniques

    -
    +
    Rule 4: Avoid Browser Fallback

    When authors do not specify an accessible name using an element or attribute that is intended for naming, browsers attempt to help assistive technology users by resorting to fall back methods for generating a name. @@ -3794,11 +3794,11 @@

    Rule 4: Avoid Browser Fallback

    -
    +
    Rule 5: Compose Brief, Useful Names

    In the same way that visually crowded screens reduce usability, excessively long or insufficiently distinct and descriptive accessible names can make a user interface very difficult, or even impossible, to use for someone who relies on a non-visual form of the user interface. - In other words, for a web experience to accessible, the names must be effective. + In other words, for a web experience to be accessible, the names must be effective. The below section on Composing Effective and User-friendly Accessible Names provides guidance for striking an effective balance between brevity and descriptiveness.

    @@ -3939,6 +3939,21 @@
    Naming with Referenced Content Via aria-labeledby
  • Because calculating the name of an element with aria-labelledby can be complex and reference hidden content, testing with assistive technologies to ensure the expected name is presented to users is particularly important.
    • + +
    +
    Naming by Encapsulation with a Label
    +

    Todo: write this section. Note that we could describe the ARIA label role, but state that it is not supported until ARIA 1.2 is a recommendation So, in this version, we should talk about the HTML technique first.

    +
    + +
    +
    Naming with Legends and Captions
    +

    Todo: write this section. Note that we could describe the ARIA legend role, but state that it is not supported until ARIA 1.2 is a recommendation So, in this version, we should talk about the HTML technique first.

    +
    + +
    +
    Fallback Names Derived from Titles and Placeholders
    +

    Todo: write this section. Needs to cover title, placeholder, and aria-placeholder.

    +
    From c686c11bbfe469e9eac568efa6691df6b7f7d37d Mon Sep 17 00:00:00 2001 From: Matt King Date: Sun, 12 May 2019 23:55:44 -0700 Subject: [PATCH 025/131] Partial revision of name calculation section --- aria-practices.html | 60 ++++++++++++++++++++++----------------------- 1 file changed, 29 insertions(+), 31 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 0ddb87ba89..dfb2c726b3 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3952,7 +3952,10 @@
    Naming with Legends and Captions
    Fallback Names Derived from Titles and Placeholders
    -

    Todo: write this section. Needs to cover title, placeholder, and aria-placeholder.

    +

    Todo: finish writing this section. Needs to cover title, placeholder, and aria-placeholder.

    +

    + For the HTML `input` element, the `placeholder` attribute is used as a fallback labeling mechanism if nothing else results in a label. For an `input` element, it is better to use a `label` element, since it does not disappear visually when the user focuses the form control. +

    @@ -3975,29 +3978,34 @@

    Accessible Name Guidance by Role

    Accessible name calculation

    -

    User agents follow the accessible name calculation algorithm to get the label for an element. This is defined in [https://w3c.github.io/accname/](https://w3c.github.io/accname/) and [https://w3c.github.io/html-aam/](https://w3c.github.io/html-aam/) for HTML.

    -

    User agents attempt to formulate labels for elements by walking through a list of potential naming methods and use the first that generates a name. The algorithm is roughly like this:

    +

    + User agents formulate an accessible name string for an element by walking through a list of potential naming methods and using the first that generates a name. + The algorithm they follow is defined in the accessible name specification. + It is roughly like the following: +

    +

    Todo: make the steps related to HTML elements and attributes in the following list more specific so readers can see the precedence of any specific element or attribute.

      -
    1. First, the `aria-labelledby` attribute is used if present.
      2. -
    2. If the label is still empty, the `aria-label` attribute is used if present.
      3. -
    3. If the label is still empty, then host-language-specific attributes or elements (e.g., the `alt` attribute on HTML `img`) are used if present.
      4. -
    4. If the label is still empty, then for roles that can take label from the element's content, the element’s contents.
      5. -
    5. Finally, if the label is still empty, then host-langauge-specific tooltip attributes or elements (e.g., the `title` attribute in HTML) are used if present.
      6. +
    6. The aria-labelledby attribute is used if present.
      7. +
    7. If the name is still empty, the aria-label attribute is used if present.
      8. +
    8. If the name is still empty, then host-language-specific attributes or elements (e.g., alt attribute on HTML img) are used if present.
      9. +
    9. If the name is still empty, then for elements with a role that supports naming from child content, the content of the element is used.
      10. +
    10. Finally, if the name is still empty, then other fallback host-language-specific tooltip attributes or elements (e.g., the title attribute in HTML) are used if present.
    - -

    The final step is a fallback mechanism. Generally when labelling an element, use one of the non-fallback mechanisms.

    - -

    For example, for the HTML `input` element, the `placeholder` attribute is used as a fallback labeling mechanism if nothing else results in a label. For an `input` element, it is better to use a `label` element, since it does not disappear visually when the user focuses the form control.

    - -
    +

    + The final step is a fallback mechanism. Generally when labelling an element, use one of the non-fallback mechanisms. +

    +

    + When calculating a name from content, the user agent walks through all descendant nodes. + And, when following aria-labelledby references, it similarly walks the tree of each referenced element. + Thus, the naming algorithm is recursive. + The following two sections provide non-recursive and recursive examples of how the algorithm works. +

    + +
    Examples of non-recursive accessible name calculation
    - -

    For example, an img element with just a src attribute has no label (don’t do this):

    - +

    Consider an img element that has only an src attribute and so does not have an accessible name (do not do this):

    <img src="photo.jpg">
    - -

    If there is a `title` attribute, then that is used as the label (fallback mechanism; generally avoid doing this):

    - +

    If there is a title attribute, then it serves as a naming falback mechanism (avoid doing this):

    <img src="photo.jpg" title="The Queen, holding a pigeon.">

    If there is also an `alt` attribute (using `alt` for images is recommended), then that is used as the label, and the `title` attribute is instead used as the accessible description:

    @@ -4016,9 +4024,8 @@
    Examples of non-recursive accessible name calculation
    <span id="the-queen">The Queen, holding a pigeon.</span>
    -
    +
    Examples of recursive accessible name calculation
    -

    The accessible name calculation algorithm will be invoked recursively when necessary. An `aria-labelledby` reference causes the algorithm to be invoked recursively, and when computing an accessible name from content the algorithm is invoked recursively for each child node.

    In this example, the label for the button is computed by recursing into each child node, resulting in "Move to trash".

    @@ -4034,15 +4041,6 @@
    Examples of recursive accessible name calculation
    aria-label="Remove meeting:">X</button> Daily status report </div> - -

    It is also possible to reference an element using `aria-labelledby` even if that element is hidden. In the following example, the `span` element could be styled with CSS `display: none` and the `nav` element would still have the label "You are here:".

    - - 
    <nav aria-labelledby="breadcrumbs-label">
-    <span id="breadcrumbs-label">You are here:</span>
-      <a href="/">Home</a> &gt;
-      <a href="/books/">Books</a> &gt;
-      <a>Children's books</a>
-    </nav>
    From 746b200c0e569781b7429ae1a0c53cde15efde7e Mon Sep 17 00:00:00 2001 From: JaEun Jemma Ku Date: Thu, 16 May 2019 20:03:41 -0500 Subject: [PATCH 026/131] fix/change with feedback --- aria-practices.html | 128 ++++++++++++++++++++++---------------------- 1 file changed, 64 insertions(+), 64 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index dfb2c726b3..407720df25 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3701,7 +3701,7 @@
    Examples

    Providing Accessible Names and Descriptions

    Providing elements with accessible names, and where appropriate, accessible descriptions is one of the most fundamental and important responsibilities authors have when developing accessible web experiences. - While doing so is straight forward for most elements, technical mistakes that can have devistating impacts on users of assistive technologies are easy to make and unfortunately common. + While doing so is straight forward for most elements, technical mistakes that can have devastating impacts on users of assistive technologies are easy to make and unfortunately common. To help authors provide effective and reliable 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 then provides guidance for effectively employing the following naming and describing techniques and WAI-ARIA properties:

    @@ -3730,10 +3730,10 @@

    What ARE Accessible Names and Descriptions?

    Both the WAI-ARIA specification and WCAG require all focusable, interactive elements to have an accessible name. - In addition dialogs and some structural containers, such as tables and regions, are required to have a name. + In addition dialogs and some structural containers, such as tables and regions, are required to have a name. Many other elements can be named, but whether a name will enhance the accessible experience is determined by various characteristics of the surrounding context. Finally, there are some elements where providing an accessible name is technically possible but not advisable. - The Accessible Name Guidance by Role section lists naming requirements and guidelines for every ARIA role. + The Accessible Name Guidance by Role section lists naming requirements and guidelines for every ARIA role.

    An accessible description is also an author-provided string that is rendered by assistive technologies. @@ -3742,7 +3742,7 @@

    What ARE Accessible Names and Descriptions?

    For instance, a screen reader may announce a description of an element after its name, role, value (if it is an input), and any relevant states or properties.

    - +

    How Are Name and Description Strings Derived?

    @@ -3751,12 +3751,12 @@

    How Are Name and Description Strings Derived?

    However, most authors do not need detailed understanding of the algorithms since nearly all circumstances where a name or description is useful are supported by the coding patterns described in the naming techniques and describing techniques sections.

    - +

    Accessible Names

    Cardinal Rules of Naming

    - +
    Rule 1: Heed Warnings and Test Thoroughly

    @@ -3768,23 +3768,23 @@

    Rule 1: Heed Warnings and Test Thoroughly
    In addition to heeding the warnings provided in the naming techniques, it is difficult to over emphasize the importance of testing to ensure that names browsers calculate match expectations.

    - +
    Rule 2: Prefer Visible Text

    When a user interface includes visible text that could be used to provide an appropriate accessible name, using the visible text for the accessible name simplifies maintenance, prevents bugs, and reduces language translation requirements. - When names are generated from text that exists only in markup and is never displayed visually, there is a greater likelihood that accessible names are not updated when the user interface design or content are changed. + When names are generated from text that exists only in markup and is never displayed visually, there is a greater likelihood that accessible names are not updated when the user interface design or content are changed.

    - +
    Rule 3: Prefer Native Techniques

    In HTML documents, whenever possible, rely on HTML naming techniques, such as the HTML label element. - While less flexible, their simplicity and reliance on visible text help ensure robust accessible experiences. + While less flexible, their simplicity and reliance on visible text help ensure robust accessible experiences.

    - +
    Rule 4: Avoid Browser Fallback

    @@ -3793,31 +3793,31 @@

    Rule 4: Avoid Browser Fallback
    Because the purpose of these attributes is not naming, their content typically yields low quality accessible names that are not effective.

    - +
    Rule 5: Compose Brief, Useful Names

    - In the same way that visually crowded screens reduce usability, excessively long or insufficiently distinct and descriptive accessible names can make a user interface very difficult, or even impossible, to use for someone who relies on a non-visual form of the user interface. - In other words, for a web experience to be accessible, the names must be effective. - The below section on Composing Effective and User-friendly Accessible Names provides guidance for striking an effective balance between brevity and descriptiveness. + In the same way that visually crowded screens reduce usability, excessively long or insufficiently distinct accessible names can make a user interface very difficult, or even impossible, to use for someone who relies on a non-visual form of the user interface. + In other words, for a web experience to be accessible, the names must be effective. + The below section on Composing Effective and User-friendly Accessible Names provides guidance for striking an effective balance between brevity and duplication.

    - +

    Naming Techniques

    - +
    Naming with Child Content

    - There are certain elements that get their name from the content they contain. + Certain elements get their name from the content they contain. For example, the following link is named "Home".

    - + 
    <a href="/">Home</a>
    - +

    - When assistive technologies render an element, such as a link or button, that gets its accessible name from its content, the accessible name is the only content the user can perceive for that element. + When assistive technologies render an element, such as a link or button, that gets its accessible name from its content, the accessible name is the only content the user can perceive for that element. This is in contrast to other elements, such as text fields or tables, where the accessible name is a label that is presented along with the value or content of the element. For instance, the accessible name of a table can be derived from a caption element, and assistive technologies render both the caption and all other content contained inside the table.

    @@ -3848,7 +3848,7 @@
    Naming with Child Content
    In addition, in situations where visible content is hidden from assistive technology users by use of one of these attributes, thorough testing with assistive technologies is particularly important.

    - +
    Naming with a String Attribute Via aria-label

    @@ -3860,7 +3860,7 @@

    Naming with a String Attribute Via aria-label
    The aria-label attribute is useful when there is no visible text content that will serve as an appropriate accessible name.

    - The aria-label attribute effects assistive technology users in one of two different ways, depending on the role of the element to which it is applied. + The aria-label attribute affects assistive technology users in one of two different ways, depending on the role of the element to which it is applied. When applied to an element with one of the roles that supports naming from child content, aria-label hides descendant content from assistive technology users and replaces the content with the value of aria-label. However, when applied to nearly any other type of element, assistive technologies will render both the value of aria-label and the content of the element. For example, the name of the following navigation region is "Product". @@ -3883,9 +3883,9 @@

    Naming with a String Attribute Via aria-label
  • When a user interface is translated into multiple languages, ensure that aria-lable values are translated.
    • - +
    -
    Naming with Referenced Content Via aria-labeledby
    +
    Naming with Referenced Content Via aria-labelledby

    The aria-labelledby property enables authors to reference other elements on the page to define an accessible name. For example, the following switch is named by the text content of a previous sibling element. @@ -3895,9 +3895,9 @@

    Naming with Referenced Content Via aria-labeledby
    <span role="switch" aria-checked="false" tabindex="0" aria-labelledby="night-mode-label"></span>

    - Note that while using aria-labelledby is similar in this situation to using an HTML label element with the for attribute, one significant difference is that browsers do not automatically make clicking on the label activate the element; that is an author responsibility. + Note that while using aria-labelledby is similar in this situation to using an HTML label element with the for attribute, one significant difference is that browsers do not automatically make clicking on the labelling element activate the labelled element; that is an author responsibility. However, HTML label cannot be used to label a span element. - Fortunately, an HTML inputtype="checkbox" allows the ARIA switch role, so when feasible, using the following approach creates a more robust solution. + Fortunately, an HTML input with type="checkbox" allows the ARIA switch role, so when feasible, using the following approach creates a more robust solution. 

    
   <label for="night-mode">Night mode</label>
@@ -3905,7 +3905,7 @@ 
    Naming with Referenced Content Via aria-labeledby

    The aria-labelledby property is useful in a wide variety of situations because:

      -
    • It has the highest precedence when browsers calculate accessible names, i.e., it overrides names from child content and all other naming attributes, such as aria-label.
      • +
    • It has the highest precedence when browsers calculate accessible names, i.e., it overrides names from child content and all other naming attributes, including aria-label.
    • It can concatenate content from multiple elements into a single name string.
    • It incorporates content from elements regardless of their visibility, i.e., it even includes content from elements with display:none or visibility:hidden in the calculated name string.
    • It incorporates the value of input elements, i.e., if it references a textbox, the value of the textbox is included in the calculated name string.
      • @@ -3939,43 +3939,43 @@
      Naming with Referenced Content Via aria-labeledby
    • Because calculating the name of an element with aria-labelledby can be complex and reference hidden content, testing with assistive technologies to ensure the expected name is presented to users is particularly important.
    - +
    Naming by Encapsulation with a Label
    -

    Todo: write this section. Note that we could describe the ARIA label role, but state that it is not supported until ARIA 1.2 is a recommendation So, in this version, we should talk about the HTML technique first.

    +

    To-do: write this section. Note that we could describe the ARIA label role, but state that it is not supported until ARIA 1.2 is a recommendation So, in this version, we should talk about the HTML technique first.(suggestion - specifically mention Form element, and refer back to caridinal rule 2: prefer visible text, and rule 3: prefer native techniques

    - +
    Naming with Legends and Captions
    -

    Todo: write this section. Note that we could describe the ARIA legend role, but state that it is not supported until ARIA 1.2 is a recommendation So, in this version, we should talk about the HTML technique first.

    +

    To-do: write this section. Note that we could describe the ARIA legend role, but state that it is not supported until ARIA 1.2 is a recommendation So, in this version, we should talk about the HTML technique first.

    - +
    Fallback Names Derived from Titles and Placeholders
    -

    Todo: finish writing this section. Needs to cover title, placeholder, and aria-placeholder.

    +

    To-do: finish writing this section. Needs to cover title, placeholder, and aria-placeholder.

    For the HTML `input` element, the `placeholder` attribute is used as a fallback labeling mechanism if nothing else results in a label. For an `input` element, it is better to use a `label` element, since it does not disappear visually when the user focuses the form control.

    - +

    Composing Effective and User-friendly Accessible Names

    -

    Todo: Write a section that describes how to make good names, i.e., brief, descriptive, unique, front-loaded, no role names, etc.

    +

    To-do: Write a section that describes how to make good names, i.e., brief, descriptive, unique, front-loaded, no role names, etc.

    Example practice: Do NOT include a WAI-ARIA role name in the accessible name. For example, do not include the word "button" in the name of a button or the word "navigation" in the name of a navigation region.

    - +

    Accessible Name Guidance by Role

    -

    Todo: build a table with every concrete role with columns for:

    +

    To-do: build a table with every concrete role with columns for:

    • role
    • Name Required?: with values of always, usually, sometimes, or never
    • Named by Content?: values of Yes or No
      • -
    • Guidance: Explains usually, sometimes and never for name required. Provides warning if named from content.
      • +
    • Guidance: Explains usually, sometimes and never for name required. Provides warning if named from content.
    - +

    Accessible name calculation

    @@ -3983,7 +3983,7 @@

    Accessible name calculation

    The algorithm they follow is defined in the accessible name specification. It is roughly like the following:

    -

    Todo: make the steps related to HTML elements and attributes in the following list more specific so readers can see the precedence of any specific element or attribute.

    +

    To-do: make the steps related to HTML elements and attributes in the following list more specific so readers can see the precedence of any specific element or attribute.

    1. The aria-labelledby attribute is used if present.
    2. If the name is still empty, the aria-label attribute is used if present.
      3. @@ -4000,42 +4000,42 @@

      Accessible name calculation

      Thus, the naming algorithm is recursive. The following two sections provide non-recursive and recursive examples of how the algorithm works.

      - +
      Examples of non-recursive accessible name calculation

      Consider an img element that has only an src attribute and so does not have an accessible name (do not do this):

      <img src="photo.jpg">

      If there is a title attribute, then it serves as a naming falback mechanism (avoid doing this):

      <img src="photo.jpg" title="The Queen, holding a pigeon.">
      - +

      If there is also an `alt` attribute (using `alt` for images is recommended), then that is used as the label, and the `title` attribute is instead used as the accessible description:

      - + 
      <img src="photo.jpg" alt="The Queen, holding a pigeon." title="Photo: Rex Features">
      - +

      If there is also an `aria-label` attribute, then that overrides the `alt` attribute:

      - + 
      <img src="photo.jpg" aria-label="The Queen, holding a pigeon." title="Photo: Rex Features"
      alt="Sorry, this image failed to load.">
      - +

      If there is also an `aria-labelledby` attribute, that wins over the other attributes (the `aria-label` attribute ought to be removed if it is not used):

      - + 
      <img src="photo.jpg" aria-label="This is ignored." title="Photo: Established Depiction"
      alt="Sorry, this image failed to load." aria-labelledby="the-queen">
     <span id="the-queen">The Queen, holding a pigeon.</span>
      - +
      Examples of recursive accessible name calculation

      The accessible name calculation algorithm will be invoked recursively when necessary. An `aria-labelledby` reference causes the algorithm to be invoked recursively, and when computing an accessible name from content the algorithm is invoked recursively for each child node.

      - +

      In this example, the label for the button is computed by recursing into each child node, resulting in "Move to trash".

      - + 
      <button>Move to <img src="bin.svg" alt="trash"></button>
      - +

      When following an `aria-labelledby` reference, the algorithm avoids following the same reference twice in order to not end up in infinite loops.

      - +

      In this example, the label for the button is computed by first following the `aria-labelledby` reference to the parent element, and then computing the label for that element from the child nodes, first visiting the `button` element again but ignoring the `aria-labelledby` reference and instead using the `aria-label` attribute, and then visiting the next child (the text node). The resulting label is "Remove meeting: Daily status report".

      - + 
      <div id="meeting-1">
     <button aria-labelledby="meeting-1"
         aria-label="Remove meeting:">X</button>
@@ -4044,23 +4044,23 @@ 
      Examples of recursive accessible name calculation
    - +

    Accessible Descriptions

    Describing Techniques

    - +
    Describing by referencing content with aria-describedby

    The `aria-describedby` attribute works similarly to the `aria-labelledby` attribute. For example, a button could be described by a later paragraph.

    - + 
    <button aria-describedby="trash-desc">Move to trash</button>
             ...
             <p id="trash-desc">Items in the trash
             will be permanently removed after 30 days.</p>
    - +

    This description will be presented to the user as plain text. For example, if the description contains an HTML `img` element, a text equivalent of the image is computed.

    - + 
    <button aria-describedby="trash-desc">
             Move to <img src="bin.svg" alt="trash">
             </button>
@@ -4068,11 +4068,11 @@ 
    Describing by referencing content with aria-describedby
    
             <p id="trash-desc">Items in <img src="bin.svg" alt="the trash">
             will be permanently removed after 30 days.</p>
    - +
    Describing by referencing content with aria-details

    In some cases, a plain text description is insufficient. The `aria-details` attribute can be used in such situations. In this example, a text field for a passenger’s name (when booking a flight) has a description that is a list of three items, and contains a link to an external document with further details.

    - + 
    <ul id="full-name-desc">
             <li>The passenger's name must match the name in their passport.</li>
             <li>The name must consist of only characters in the A-Z range.</li>
@@ -4085,18 +4085,18 @@ 
    Describing by referencing content with aria-details
    
             </label></p>
             ...
             </fieldset>
    - +

    If both `aria-details` and `aria-describedby` are specified on an element, only the `aria-details` attribute is used. This can be useful in order to provide a fallback for user agents that don’t support `aria-details`.

    - +

    Accessible description calculation

    Like the accessible name calculation (see the earlier section), the accessible description calculation produces a plain text string for an element. This algorithm is not used for the `aria-details` attribute.

    The accessible description calculation algorithm is the same algorithm as the accessible name calculation algorithm, but it branches off in some places depending on whether a name or a description is being calculated. In particular, when collecting an accessible description, the algorithm uses `aria-describedby` instead of `aria-labelledby`.

    As with `aria-labelledby`, it is possible to reference an element using `aria-describedby` even if that element is hidden.

    For example, a text field in a form could have a description that is hidden by default, but can be revealed on request using a disclosure widget. The description could also be referenced from the text field directly with `aria-describedby`. The accessible description for the `input` element is "Your username is the name that you use to log in to this service.".

    - + 
    <label for="username">Username</label>
           <input id="username" name="username" aria-describedby="username-desc">
           <button aria-expanded="false" aria-controls="username-desc" aria-label="Help about username">?</button>

From 490eaed602ee093996df11ba1156a18803e12493 Mon Sep 17 00:00:00 2001
From: JaEun Jemma Ku 
Date: Thu, 16 May 2019 20:51:38 -0500
Subject: [PATCH 027/131] lint testing and one typo fix

---
 aria-practices.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/aria-practices.html b/aria-practices.html
index 407720df25..a72cce742f 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -3707,7 +3707,7 @@ 
    Providing Accessible Names and Descriptions
    
     
    
     
      
       
    • Naming with child content.
      • 
-      
    • Naming with a String Attribute Via aria-label.
      • 
+      
    • Naming with a String Attribute Via aria-lable.
      • 
       
    • Naming by Referencing Content with aria-labelledby.
      • 
       
    • Naming by encapsulation with a label.
      • 
       
    • Naming with Legends and Captions.
      • 

From 0536ec86dc5e70277b921290022ce9a9b93190d5 Mon Sep 17 00:00:00 2001
From: JaEun Jemma Ku 
Date: Thu, 16 May 2019 20:56:23 -0500
Subject: [PATCH 028/131] fix typo

---
 aria-practices.html | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/aria-practices.html b/aria-practices.html
index a72cce742f..c625fad548 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -3707,7 +3707,7 @@ 
      Providing Accessible Names and Descriptions
      
     
      
     
        
       
      • Naming with child content.
        • 
-      
      • Naming with a String Attribute Via aria-lable.
        • 
+      
      • Naming with a String Attribute Via aria-label.
        • 
       
      • Naming by Referencing Content with aria-labelledby.
        • 
       
      • Naming by encapsulation with a label.
        • 
       
      • Naming with Legends and Captions.
        • 
@@ -3880,7 +3880,7 @@ 
        Naming with a String Attribute Via aria-label
        
         
         
      • There are certain types of elements, such as paragraphs and list items, that should not be named with aria-label. They are identified in the table in section Accessible Name Guidance by Role.
        • 
             
      • Because the value of aria-label is not rendered visually, testing with assistive technologies to ensure the expected name is presented to users is particularly important.
        • 
-            
      • When a user interface is translated into multiple languages, ensure that aria-lable values are translated.
        • 
+            
      • When a user interface is translated into multiple languages, ensure that aria-label values are translated.
        •
    From b4a87d838014407d905659e469ef1b981f11b2b4 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 20 May 2019 08:53:05 +0200 Subject: [PATCH 029/131] Remove outdated markdown file --- draft-labelling-describing.md | 308 ---------------------------------- 1 file changed, 308 deletions(-) delete mode 100644 draft-labelling-describing.md diff --git a/draft-labelling-describing.md b/draft-labelling-describing.md deleted file mode 100644 index 1b59826826..0000000000 --- a/draft-labelling-describing.md +++ /dev/null @@ -1,308 +0,0 @@ -Labeling and Describing - -## Providing Accessible Names and Descriptions - -Providing elements with accessible names, and where appropriate, accessible descriptions is one of the most fundamental and important responsibilities authors have when developing accessible web experiences. While doing it well is not typically difficult, technical mistakes that can have devistating impacts are unfortunately common. After providing some basic information about accessible names and descriptions, this section provides guidance for using the following ARIA attributes: - - -### Accessible Name and Description Basics - -An accessible name is a short string, typically 1 to 3 words, associated with an element that provides users of assistive technologies with a label for the element. For example, a button’s label may be "OK". The label serves two primary purposes: -1. Convey the purpose or intent of the element. -2. Distinguish it from other elements on the page. - -An accessible description is also a string provided to assistive technologies that complements the label. For example, it might describe format and length requirements for an input field. Assistive technologies present descriptions differently from labels. For instance, a screen reader may announce a description of an element last after the label, role, value (if it is an input), and any relevant states or properties. - -## Labels - -There are two different kinds of labels, depending on the element’s role. The difference is both in how the label is computed for the element, and how the element is represented to assistive technologies. - -* Label that represents the element. The label is taken from the element's contents, unless `aria-labelledby` or `aria-label` attributes are used. Only the label is represented to users of assistive tecnologies. - -* Label that augments the element. The label is not taken from the element's contents (by default). A label can be set using `aria-labelledby` or `aria-label`. The label will augment the element; both the label and the element's contents are exposed to users of assistive technology. - - -### Label that represents the element - -For elements with certain roles, the label is taken from the element’s contents by default, and the label will represent the element when communicated to assistive technologies. In the following example, a link (with default role `link`) gets its label from the element’s contents ("Home"). - -``` -Home -``` - -This could be rendered to assistive technology as "link, Home"; the role and the label, not not repeating the content ("link, Home, Home"). - -The label also can be set explicitly by using the `aria-labelledby` or `aria-label` attributes. If the label from the element’s contents is already good, then don’t use the `aria-labelledby` or `aria-label` attributes. - -The following roles get the label from the contents by default: - -* `button` - -* `cell` - -* `checkbox` - -* `columnheader` - -* `gridcell` - -* `heading` - -* `link` - -* `menuitem` - -* `menuitemcheckbox` - -* `menuitemradio` - -* `option` - -* `radio` - -* `row` - -* `rowgroup` - -* `rowheader` - -* `switch` - -* `tab` - -* `tooltip` - -* `treeitem` - -If the element’s contents are not appropriate as a label, but there is an element that can be used as the label, then use the `aria-labelledby` attribute. - -In the following example, an element with the "switch" role is labeled by a previous sibling element. - -``` -Night mode - -``` - - -Because a `span` element is used for the switch control, the HTML `label` element cannot be used to label it, since it only works with HTML elements that are form controls. However, the `switch` role can be used on an `input` element with `type="checkbox”`, and then HTML `label` can be used. - -``` - - -``` - - -In some cases, the combination of the element’s contents and another element would be appropriate as a label. In such situations, use the `aria-labelledby` and reference both the element itself and the other element. - -In the following example, a "read more" link is labeled by the element itself and the article’s heading, resulting in “Read more… 7 ways you can help save the bees”. - -``` -

    7 ways you can help save the bees

    -

    Bees are disappearing rapidly. -Here are seven things you can do to help.

    -

    Read more...

    -``` - - -If there is no content that is appropriate to use as the label, then use the `aria-label` attribute to set the label for the element directly. - -In the following example, a close button contains an "X" and is given the label “Close” using the `aria-label` attribute. - -``` - -``` - - -### Label that augments the element - -Some roles do not get the label from the contents of the element; a label can only be set explicitly using the `aria-labelledby` or `aria-label` attributes. For elements with these roles, a label augments the element, but does not override the contents. - -Examples of such roles are (note that this is not a complete list): - -* `alertdialog` - -* `application` - -* `article` - -* `banner` - -* `complementary` - -* `navigation` - -* `radiogroup` - -* `search` - -* `status` - -For example, the `navigation` landmark could be labeled with the purpose of the landmark. In the following snippet, a "breadcrumbs" navigation region is labeled explicitly using the `aria-labelledby` attribute. The HTML `nav` element has the `navigation` role by default. - -``` - -``` - - -### Accessible name calculation - -Because authors have so many different ways of specifying accessible names and descriptions, browsers implement a fairly complex algorithm for calculating the name and description of an element. -User agents follow the accessible name calculation algorithm to get the label for an element. This is defined in [https://w3c.github.io/accname/](https://w3c.github.io/accname/) and [https://w3c.github.io/html-aam/](https://w3c.github.io/html-aam/) for HTML. - -User agents attempt to formulate labels for elements by walking through a list of potential naming methods and use the first that generates a name. The algorithm is roughly like this: - -1. First, the `aria-labelledby` attribute is used if present. - -2. If the label is still empty, the `aria-label` attribute is used if present. - -3. If the label is still empty, then host-language-specific attributes or elements (e.g., the `alt` attribute on HTML `img`) are used if present. - -4. If the label is still empty, then for roles that can take label from the element's content, the element’s contents. - -5. Finally, if the label is still empty, then host-langauge-specific tooltip attributes or elements (e.g., the `title` attribute in HTML) are used if present. - -The final step is a fallback mechanism. Generally when labelling an element, use one of the non-fallback mechanisms. - -For example, for the HTML `input` element, the `placeholder` attribute is used as a fallback labeling mechanism if nothing else results in a label. For an `input` element, it is better to use a `label` element, since it does not disappear visually when the user focuses the form control. - -#### Examples of non-recursive accessible name calculation - -For example, an img element with just a src attribute has no label (don’t do this): - -``` - -``` - - -If there is a `title` attribute, then that is used as the label (fallback mechanism; generally avoid doing this): - -``` - -``` - - -If there is also an `alt` attribute (using `alt` for images is recommended), then that is used as the label, and the `title` attribute is instead used as the accessible description: - -``` -The Queen, holding a pigeon. -``` - - -If there is also an `aria-label` attribute, then that overrides the `alt` attribute: - -``` -Sorry, this image failed to load. -``` - - -If there is also an `aria-labelledby` attribute, that wins over the other attributes (the `aria-label` attribute ought to be removed if it is not used): - -``` -Sorry, this image failed to load. -The Queen, holding a pigeon. -``` - - -#### Examples of recursive accessible name calculation - -The accessible name calculation algorithm will be invoked recursively when necessary. An `aria-labelledby` reference causes the algorithm to be invoked recursively, and when computing an accessible name from content the algorithm is invoked recursively for each child node. - -In this example, the label for the button is computed by recursing into each child node, resulting in "Move to trash". - -``` - -``` - - -When following an `aria-labelledby` reference, the algorithm avoids following the same reference twice in order to not end up in infinite loops. - -In this example, the label for the button is computed by first following the `aria-labelledby` reference to the parent element, and then computing the label for that element from the child nodes, first visiting the `button` element again but ignoring the `aria-labelledby` reference and instead using the `aria-label` attribute, and then visiting the next child (the text node). The resulting label is "Remove meeting: Daily status report". - -``` -
    - - Daily status report -
    -``` - -It is also possible to reference an element using `aria-labelledby` even if that element is hidden. In the following example, the `span` element could be styled with CSS `display: none` and the `nav` element would still have the label "You are here:". - -``` - -``` - -## Descriptions - -An element can be given an accessible description using the `aria-describedby` attribute or the `aria-details` attribute. - -The `aria-describedby` attribute works similarly to the `aria-labelledby` attribute. For example, a button could be described by a later paragraph. - -``` - -... -

    Items in the trash -will be permanently removed after 30 days.

    -``` - - -This description will be presented to the user as plain text. For example, if the description contains an HTML `img` element, a text equivalent of the image is computed. - -``` - -... -

    Items in the trash -will be permanently removed after 30 days.

    -``` - - -In some cases, a plain text description is insufficient. The `aria-details` attribute can be used in such situations. In this example, a text field for a passenger’s name (when booking a flight) has a description that is a list of three items, and contains a link to an external document with further details. - -``` - -
    - Passenger 1 (adult) -

    - ... -
    -``` - - -If both `aria-details` and `aria-describedby` are specified on an element, only the `aria-details` attribute is used. This can be useful in order to provide a fallback for user agents that don’t support `aria-details`. - -### Accessible description calculation - -Like the accessible name calculation (see the earlier section), the accessible description calculation produces a plain text string for an element. This algorithm is not used for the `aria-details` attribute. - -The accessible description calculation algorithm is the same algorithm as the accessible name calculation algorithm, but it branches off in some places depending on whether a name or a description is being calculated. In particular, when collecting an accessible description, the algorithm uses `aria-describedby` instead of `aria-labelledby`. - -As with `aria-labelledby`, it is possible to reference an element using `aria-describedby` even if that element is hidden. - -For example, a text field in a form could have a description that is hidden by default, but can be revealed on request using a disclosure widget. The description could also be referenced from the text field directly with `aria-describedby`. The accessible description for the `input` element is "Your username is the name that you use to log in to this service.". - -``` - - - - -``` From b596c6817d420ca30bd2b4678d13e12a0a34afdb Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 20 May 2019 09:17:29 +0200 Subject: [PATCH 030/131] Skeleton table for all concrete roles --- aria-practices.html | 423 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 417 insertions(+), 6 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index c625fad548..5d21eb8fa1 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3968,12 +3968,423 @@

    Composing Effective and User-friendly Accessible Names

    Accessible Name Guidance by Role

    To-do: build a table with every concrete role with columns for:

    -
      -
    • role
      • -
    • Name Required?: with values of always, usually, sometimes, or never
      • -
    • Named by Content?: values of Yes or No
      • -
    • Guidance: Explains usually, sometimes and never for name required. Provides warning if named from content.
      • -
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    roleName RequiredNamed by ContentGuidance
    alertnamerequiredfromcontentguidance
    alertdialognamerequiredfromcontentguidance
    applicationnamerequiredfromcontentguidance
    articlenamerequiredfromcontentguidance
    bannernamerequiredfromcontentguidance
    buttonnamerequiredfromcontentguidance
    cellnamerequiredfromcontentguidance
    checkboxnamerequiredfromcontentguidance
    columnheadernamerequiredfromcontentguidance
    comboboxnamerequiredfromcontentguidance
    complementarynamerequiredfromcontentguidance
    contentinfonamerequiredfromcontentguidance
    definitionnamerequiredfromcontentguidance
    dialognamerequiredfromcontentguidance
    directorynamerequiredfromcontentguidance
    documentnamerequiredfromcontentguidance
    feednamerequiredfromcontentguidance
    figurenamerequiredfromcontentguidance
    formnamerequiredfromcontentguidance
    gridnamerequiredfromcontentguidance
    gridcellnamerequiredfromcontentguidance
    groupnamerequiredfromcontentguidance
    headingnamerequiredfromcontentguidance
    imgnamerequiredfromcontentguidance
    linknamerequiredfromcontentguidance
    listnamerequiredfromcontentguidance
    listboxnamerequiredfromcontentguidance
    listitemnamerequiredfromcontentguidance
    lognamerequiredfromcontentguidance
    mainnamerequiredfromcontentguidance
    marqueenamerequiredfromcontentguidance
    mathnamerequiredfromcontentguidance
    menunamerequiredfromcontentguidance
    menubarnamerequiredfromcontentguidance
    menuitemnamerequiredfromcontentguidance
    menuitemcheckboxnamerequiredfromcontentguidance
    menuitemradionamerequiredfromcontentguidance
    navigationnamerequiredfromcontentguidance
    none, presentationnamerequiredfromcontentguidance
    notenamerequiredfromcontentguidance
    optionnamerequiredfromcontentguidance
    progressbarnamerequiredfromcontentguidance
    radionamerequiredfromcontentguidance
    radiogroupnamerequiredfromcontentguidance
    regionnamerequiredfromcontentguidance
    rownamerequiredfromcontentguidance
    rowgroupnamerequiredfromcontentguidance
    rowheadernamerequiredfromcontentguidance
    scrollbarnamerequiredfromcontentguidance
    searchnamerequiredfromcontentguidance
    searchboxnamerequiredfromcontentguidance
    separatornamerequiredfromcontentguidance
    slidernamerequiredfromcontentguidance
    spinbuttonnamerequiredfromcontentguidance
    statusnamerequiredfromcontentguidance
    switchnamerequiredfromcontentguidance
    tabnamerequiredfromcontentguidance
    tablenamerequiredfromcontentguidance
    tablistnamerequiredfromcontentguidance
    tabpanelnamerequiredfromcontentguidance
    termnamerequiredfromcontentguidance
    textboxnamerequiredfromcontentguidance
    timernamerequiredfromcontentguidance
    toolbarnamerequiredfromcontentguidance
    tooltipnamerequiredfromcontentguidance
    treenamerequiredfromcontentguidance
    treegridnamerequiredfromcontentguidance
    treeitemnamerequiredfromcontentguidance
    From edf4be5eaf9f800bc79a65d68a2c814b211d4af1 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 20 May 2019 09:22:00 +0200 Subject: [PATCH 031/131] Fill out name from content in the table --- aria-practices.html | 136 ++++++++++++++++++++++---------------------- 1 file changed, 68 insertions(+), 68 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 5d21eb8fa1..fee5d991f4 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3978,409 +3978,409 @@

    Accessible Name Guidance by Role

    alert namerequired - fromcontent + No guidance alertdialog namerequired - fromcontent + No guidance application namerequired - fromcontent + No guidance article namerequired - fromcontent + No guidance banner namerequired - fromcontent + No guidance button namerequired - fromcontent + Yes guidance cell namerequired - fromcontent + Yes guidance checkbox namerequired - fromcontent + Yes guidance columnheader namerequired - fromcontent + Yes guidance combobox namerequired - fromcontent + No guidance complementary namerequired - fromcontent + No guidance contentinfo namerequired - fromcontent + No guidance definition namerequired - fromcontent + No guidance dialog namerequired - fromcontent + No guidance directory namerequired - fromcontent + No guidance document namerequired - fromcontent + No guidance feed namerequired - fromcontent + No guidance figure namerequired - fromcontent + No guidance form namerequired - fromcontent + No guidance grid namerequired - fromcontent + No guidance gridcell namerequired - fromcontent + Yes guidance group namerequired - fromcontent + No guidance heading namerequired - fromcontent + Yes guidance img namerequired - fromcontent + No guidance link namerequired - fromcontent + Yes guidance list namerequired - fromcontent + No guidance listbox namerequired - fromcontent + No guidance listitem namerequired - fromcontent + No guidance log namerequired - fromcontent + No guidance main namerequired - fromcontent + No guidance marquee namerequired - fromcontent + No guidance math namerequired - fromcontent + No guidance menu namerequired - fromcontent + No guidance menubar namerequired - fromcontent + No guidance menuitem namerequired - fromcontent + Yes guidance menuitemcheckbox namerequired - fromcontent + Yes guidance menuitemradio namerequired - fromcontent + Yes guidance navigation namerequired - fromcontent + No guidance none, presentation namerequired - fromcontent + No guidance note namerequired - fromcontent + No guidance option namerequired - fromcontent + Yes guidance progressbar namerequired - fromcontent + No guidance radio namerequired - fromcontent + Yes guidance radiogroup namerequired - fromcontent + No guidance region namerequired - fromcontent + No guidance row namerequired - fromcontent + Yes guidance rowgroup namerequired - fromcontent + Yes guidance rowheader namerequired - fromcontent + Yes guidance scrollbar namerequired - fromcontent + No guidance search namerequired - fromcontent + No guidance searchbox namerequired - fromcontent + No guidance separator namerequired - fromcontent + No guidance slider namerequired - fromcontent + No guidance spinbutton namerequired - fromcontent + No guidance status namerequired - fromcontent + No guidance switch namerequired - fromcontent + Yes guidance tab namerequired - fromcontent + Yes guidance table namerequired - fromcontent + No guidance tablist namerequired - fromcontent + No guidance tabpanel namerequired - fromcontent + No guidance term namerequired - fromcontent + No guidance textbox namerequired - fromcontent + No guidance timer namerequired - fromcontent + No guidance toolbar namerequired - fromcontent + No guidance tooltip namerequired - fromcontent + Yes guidance tree namerequired - fromcontent + Yes guidance treegrid namerequired - fromcontent + No guidance treeitem namerequired - fromcontent + Yes guidance From 7eb5d5df92e58e22e88a86011d93092a347e5c88 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 20 May 2019 09:56:34 +0200 Subject: [PATCH 032/131] Fill in parts of the table --- aria-practices.html | 82 ++++++++++++++++++++++----------------------- 1 file changed, 41 insertions(+), 41 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index fee5d991f4..8a3d48b8ef 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3977,19 +3977,19 @@

    Accessible Name Guidance by Role

    alert - namerequired + Sometimes No - guidance + A name can sometimes be useful to know what kind of alert it is. alertdialog - namerequired + Always No guidance application - namerequired + Always No guidance @@ -4007,7 +4007,7 @@

    Accessible Name Guidance by Role

    button - namerequired + Always Yes guidance @@ -4019,19 +4019,19 @@

    Accessible Name Guidance by Role

    checkbox - namerequired + Always Yes guidance columnheader - namerequired + Always Yes guidance combobox - namerequired + Always No guidance @@ -4055,7 +4055,7 @@

    Accessible Name Guidance by Role

    dialog - namerequired + Always No guidance @@ -4091,13 +4091,13 @@

    Accessible Name Guidance by Role

    grid - namerequired + Always No guidance gridcell - namerequired + Always Yes guidance @@ -4109,19 +4109,19 @@

    Accessible Name Guidance by Role

    heading - namerequired + Always Yes guidance img - namerequired + Always No guidance link - namerequired + Always Yes guidance @@ -4133,7 +4133,7 @@

    Accessible Name Guidance by Role

    listbox - namerequired + Always No guidance @@ -4145,7 +4145,7 @@

    Accessible Name Guidance by Role

    log - namerequired + Always No guidance @@ -4157,7 +4157,7 @@

    Accessible Name Guidance by Role

    marquee - namerequired + Always No guidance @@ -4181,19 +4181,19 @@

    Accessible Name Guidance by Role

    menuitem - namerequired + Always Yes guidance menuitemcheckbox - namerequired + Always Yes guidance menuitemradio - namerequired + Always Yes guidance @@ -4205,9 +4205,9 @@

    Accessible Name Guidance by Role

    none, presentation - namerequired + Never No - guidance + note @@ -4217,31 +4217,31 @@

    Accessible Name Guidance by Role

    option - namerequired + Always Yes guidance progressbar - namerequired + Always No guidance radio - namerequired + Always Yes guidance radiogroup - namerequired + Always No guidance region - namerequired + Always No guidance @@ -4259,13 +4259,13 @@

    Accessible Name Guidance by Role

    rowheader - namerequired + Always Yes guidance scrollbar - namerequired + Always No guidance @@ -4277,7 +4277,7 @@

    Accessible Name Guidance by Role

    searchbox - namerequired + Always No guidance @@ -4289,13 +4289,13 @@

    Accessible Name Guidance by Role

    slider - namerequired + Always No guidance spinbutton - namerequired + Always No guidance @@ -4307,7 +4307,7 @@

    Accessible Name Guidance by Role

    switch - namerequired + Always Yes guidance @@ -4319,7 +4319,7 @@

    Accessible Name Guidance by Role

    table - namerequired + Always No guidance @@ -4331,7 +4331,7 @@

    Accessible Name Guidance by Role

    tabpanel - namerequired + Always No guidance @@ -4343,13 +4343,13 @@

    Accessible Name Guidance by Role

    textbox - namerequired + Always No guidance timer - namerequired + Always No guidance @@ -4361,25 +4361,25 @@

    Accessible Name Guidance by Role

    tooltip - namerequired + Always Yes guidance tree - namerequired + Always Yes guidance treegrid - namerequired + Always No guidance treeitem - namerequired + Always Yes guidance From bdb67d63f737c03f0e2a4c1a7c3944b9ce0cfbf2 Mon Sep 17 00:00:00 2001 From: Matt King Date: Mon, 27 May 2019 22:39:55 -0700 Subject: [PATCH 033/131] Fix capitalization and structure of intro list --- aria-practices.html | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 8a3d48b8ef..787f44dfe8 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3703,18 +3703,26 @@

    Providing Accessible Names and Descriptions

    Providing elements with accessible names, and where appropriate, accessible descriptions is one of the most fundamental and important responsibilities authors have when developing accessible web experiences. While doing so is straight forward for most elements, technical mistakes that can have devastating impacts on users of assistive technologies are easy to make and unfortunately common. To help authors provide effective and reliable 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 then provides guidance for effectively employing the following naming and describing techniques and WAI-ARIA properties: + It also provides guidance for effectively employing the following naming and describing techniques and WAI-ARIA properties:

      -
    • Naming with child content.
      • -
    • Naming with a String Attribute Via aria-label.
      • -
    • Naming by Referencing Content with aria-labelledby.
      • -
    • Naming by encapsulation with a label.
      • -
    • Naming with Legends and Captions.
      • -
    • Fallback Names Derived from Titles and Placeholders.
      • -
    • Describing by referencing content with aria-describedby.
      • -
    • Describing by referencing content with aria-details.
      • -
    • Fallback descriptions Derived from Titles and Placeholders.
      • +
    • Naming: +
        +
      • Naming with child content.
        • +
      • Naming with a string attribute via aria-label.
        • +
      • Naming by referencing content with aria-labelledby.
        • +
      • Naming by encapsulation with a label.
        • +
      • Naming with legends and captions.
        • +
      • Fallback names derived from titles and placeholders.
        • +
      +
      • +
    • Describing: +
        +
      • Describing by referencing content with aria-describedby.
        • +
      • Describing by referencing content with aria-details.
        • +
      • Fallback descriptions derived from titles and placeholders.
        • +
      +
    From fb4f995a9e9f822e5919a85c0ec9111e83ce889f Mon Sep 17 00:00:00 2001 From: Matt King Date: Mon, 27 May 2019 22:52:31 -0700 Subject: [PATCH 034/131] Editorial revisions to clarity in naming rule 5 --- aria-practices.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 787f44dfe8..6b742b9dad 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3805,9 +3805,9 @@
    Rule 4: Avoid Browser Fallback
    Rule 5: Compose Brief, Useful Names

    - In the same way that visually crowded screens reduce usability, excessively long or insufficiently distinct accessible names can make a user interface very difficult, or even impossible, to use for someone who relies on a non-visual form of the user interface. - In other words, for a web experience to be accessible, the names must be effective. - The below section on Composing Effective and User-friendly Accessible Names provides guidance for striking an effective balance between brevity and duplication. + Similar to how visually crowded screens and ambiguous icons reduce usability, excessively long, insufficiently distinct, or unclear accessible names can make a user interface very difficult, or even impossible, to use for someone who relies on a non-visual form of the user interface. + In other words, for a web experience to be accessible, its accessible names must be effective. + The below section on Composing Effective and User-friendly Accessible Names provides guidance for balancing brevity and clarity.

    From 82a8e821668505053e6cfcf5c4565b4e6cdcb816 Mon Sep 17 00:00:00 2001 From: Matt King Date: Mon, 27 May 2019 23:13:15 -0700 Subject: [PATCH 035/131] fix typo in aria-labelledby guidance section --- aria-practices.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 6b742b9dad..49c076603e 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3803,7 +3803,7 @@
    Rule 4: Avoid Browser Fallback
    -
    Rule 5: Compose Brief, Useful Names
    +
    Rule 5: Compose Brief, Useful Names

    Similar to how visually crowded screens and ambiguous icons reduce usability, excessively long, insufficiently distinct, or unclear accessible names can make a user interface very difficult, or even impossible, to use for someone who relies on a non-visual form of the user interface. In other words, for a web experience to be accessible, its accessible names must be effective. @@ -3937,7 +3937,7 @@

    Naming with Referenced Content Via aria-labelledby
    Short examples, 3 lines of code or less, are preferrable.

      -
    1. The aria-labelledby property cannot be chained, i.e., if an element with aria-labelled by references another element that also has aria-labelledby, the aria-labelledby attribute on the referenced element will be ignored.
      2. +
    2. The aria-labelledby property cannot be chained, i.e., if an element with aria-labelledby references another element that also has aria-labelledby, the aria-labelledby attribute on the referenced element will be ignored.
    3. The aria-labelledby property cannot be applied to the descendant of an element that supports naming from content. For example, most browsers will ignore the aria-labelledby attribute in this link: <a href="/"><span aria-labelledby="elem1"></span><a>.
    4. There are certain types of elements, such as paragraphs and list items, that should not be named with aria-labelledby. They are identified in the table in section Accessible Name Guidance by Role.
    5. From 702837aed64f53a3c54ac0d1891357f7557ff667 Mon Sep 17 00:00:00 2001 From: Matt King Date: Mon, 27 May 2019 23:37:11 -0700 Subject: [PATCH 036/131] remove explicit URIs from name and role guidance table --- aria-practices.html | 142 ++++++++++++++++++++++---------------------- 1 file changed, 71 insertions(+), 71 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 49c076603e..a3cd49aa20 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3974,9 +3974,9 @@

      Composing Effective and User-friendly Accessible Names

    -

    Accessible Name Guidance by Role

    -

    To-do: build a table with every concrete role with columns for:

    - +

    Accessible Name Guidance by Role

    +

    The following table

    +
    @@ -3984,409 +3984,409 @@

    Accessible Name Guidance by Role

    - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + From 6c6449138627e3c72056c50390153341b9d17874 Mon Sep 17 00:00:00 2001 From: Matt King Date: Tue, 28 May 2019 00:32:51 -0700 Subject: [PATCH 037/131] Provide intro to guidance by role table --- aria-practices.html | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/aria-practices.html b/aria-practices.html index a3cd49aa20..07fac24b34 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3975,7 +3975,10 @@

    Composing Effective and User-friendly Accessible Names

    Accessible Name Guidance by Role

    -

    The following table

    +

    + Certain elements always require a name, others may usually or sometimes require a name, and still others should never be named. + The following table provides requirements, allowed techniques, and guidance for each ARIA role. +

    role Name Required Guidance
    alertalert Sometimes No A name can sometimes be useful to know what kind of alert it is.
    alertdialogalertdialog Always No guidance
    applicationapplication Always No guidance
    articlearticle namerequired No guidance
    bannerbanner namerequired No guidance
    buttonbutton Always Yes guidance
    cellcell namerequired Yes guidance
    checkboxcheckbox Always Yes guidance
    columnheadercolumnheader Always Yes guidance
    comboboxcombobox Always No guidance
    complementarycomplementary namerequired No guidance
    contentinfocontentinfo namerequired No guidance
    definitiondefinition namerequired No guidance
    dialogdialog Always No guidance
    directorydirectory namerequired No guidance
    documentdocument namerequired No guidance
    feedfeed namerequired No guidance
    figurefigure namerequired No guidance
    formform namerequired No guidance
    gridgrid Always No guidance
    gridcellgridcell Always Yes guidance
    groupgroup namerequired No guidance
    headingheading Always Yes guidance
    imgimg Always No guidance
    linklink Always Yes guidance
    listlist namerequired No guidance
    listboxlistbox Always No guidance
    listitemlistitem namerequired No guidance
    loglog Always No guidance
    mainmain namerequired No guidance
    marqueemarquee Always No guidance
    mathmath namerequired No guidance
    menumenu namerequired No guidance
    menubarmenubar namerequired No guidance
    menuitemmenuitem Always Yes guidance
    menuitemcheckboxmenuitemcheckbox Always Yes guidance
    menuitemradiomenuitemradio Always Yes guidance
    navigationnavigation namerequired No guidance
    none, presentationnone, presentation Never No
    notenote namerequired No guidance
    optionoption Always Yes guidance
    progressbarprogressbar Always No guidance
    radioradio Always Yes guidance
    radiogroupradiogroup Always No guidance
    regionregion Always No guidance
    rowrow namerequired Yes guidance
    rowgrouprowgroup namerequired Yes guidance
    rowheaderrowheader Always Yes guidance
    scrollbarscrollbar Always No guidance
    searchsearch namerequired No guidance
    searchboxsearchbox Always No guidance
    separatorseparator namerequired No guidance
    sliderslider Always No guidance
    spinbuttonspinbutton Always No guidance
    statusstatus namerequired No guidance
    switchswitch Always Yes guidance
    tabtab namerequired Yes guidance
    tabletable Always No guidance
    tablisttablist namerequired No guidance
    tabpaneltabpanel Always No guidance
    termterm namerequired No guidance
    textboxtextbox Always No guidance
    timertimer Always No guidance
    toolbartoolbar namerequired No guidance
    tooltiptooltip Always Yes guidance
    treetree Always Yes guidance
    treegridtreegrid Always No guidance
    treeitemtreeitem Always Yes guidance
    From 0612ba8bbc158b2f8a4d9b4020011fbc52ecdcff Mon Sep 17 00:00:00 2001 From: Matt King Date: Tue, 28 May 2019 00:37:05 -0700 Subject: [PATCH 038/131] Add class role-reference to role links in guidance by role table --- aria-practices.html | 136 ++++++++++++++++++++++---------------------- 1 file changed, 68 insertions(+), 68 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 07fac24b34..bd2c25845d 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3987,409 +3987,409 @@

    Accessible Name Guidance by Role

     - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + From 1fd6368f54ac6136a5a020b34ac7b844d21d82d2 Mon Sep 17 00:00:00 2001 From: Matt King Date: Sat, 1 Jun 2019 14:44:08 -0700 Subject: [PATCH 039/131] Revise name guidance by role table --- aria-practices.html | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index bd2c25845d..c884407072 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3990,37 +3990,37 @@

    Accessible Name Guidance by Role

     - + - - + + - + - + - + - + - + - + From b2e2067c3224fad61568d36388a5f173d7ad8e69 Mon Sep 17 00:00:00 2001 From: Matt King Date: Sat, 1 Jun 2019 15:05:21 -0700 Subject: [PATCH 040/131] Fix name on name guidance by role table --- aria-practices.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aria-practices.html b/aria-practices.html index c884407072..85109af9d6 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3974,7 +3974,7 @@

    Composing Effective and User-friendly Accessible Names

    -

    Accessible Name Guidance by Role

    +

    Accessible Name Guidance by Role

    Certain elements always require a name, others may usually or sometimes require a name, and still others should never be named. The following table provides requirements, allowed techniques, and guidance for each ARIA role. From c229c7670437c9fdc4de66ec2b54a47ebeeb6e7d Mon Sep 17 00:00:00 2001 From: Matt King Date: Sat, 1 Jun 2019 15:27:41 -0700 Subject: [PATCH 041/131] More name guidance by role --- aria-practices.html | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 85109af9d6..3519879989 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3982,13 +3982,13 @@

    Accessible Name Guidance by Role

    - - - + + + - + @@ -4002,19 +4002,19 @@

    Accessible Name Guidance by Roleapplication

    - + - + - + - + @@ -4044,11 +4044,11 @@

    Accessible Name Guidance by Rolecombobox

    - + - + From 8e8ec74211085a6b2e8dd532df5e4b9c02103490 Mon Sep 17 00:00:00 2001 From: Matt King Date: Mon, 3 Jun 2019 09:41:22 -0700 Subject: [PATCH 042/131] Update to-do description for label encapsulation --- aria-practices.html | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/aria-practices.html b/aria-practices.html index 3519879989..1b31f841a9 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3950,7 +3950,12 @@
    Naming with Referenced Content Via aria-labelledby
    Naming by Encapsulation with a Label
    -

    To-do: write this section. Note that we could describe the ARIA label role, but state that it is not supported until ARIA 1.2 is a recommendation So, in this version, we should talk about the HTML technique first.(suggestion - specifically mention Form element, and refer back to caridinal rule 2: prefer visible text, and rule 3: prefer native techniques

    +

    + To-do: write this section. This version WILL NOT include the new ARIA 1.2 label role. + The 1.2 label role will be added after the July release of APG 1.1 R4. + So, in this version, we should talk about the HTML technique. + Specifically illustrate Form element labeling, and refer back to caridinal rule 2: prefer visible text, and rule 3: prefer native techniques. +

    From 6451e9168aac5f2d6c834043fcb8becd2fc3bced Mon Sep 17 00:00:00 2001 From: Matt King Date: Mon, 3 Jun 2019 09:48:57 -0700 Subject: [PATCH 043/131] Update to-do description for labeling with legend --- aria-practices.html | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 1b31f841a9..d10afcd8c5 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3954,13 +3954,17 @@
    Naming by Encapsulation with a Label
    To-do: write this section. This version WILL NOT include the new ARIA 1.2 label role. The 1.2 label role will be added after the July release of APG 1.1 R4. So, in this version, we should talk about the HTML technique. - Specifically illustrate Form element labeling, and refer back to caridinal rule 2: prefer visible text, and rule 3: prefer native techniques. + Specifically illustrate Form element labeling, and refer back to cardinal rule 2: prefer visible text, and rule 3: prefer native techniques.

    Naming with Legends and Captions
    -

    To-do: write this section. Note that we could describe the ARIA legend role, but state that it is not supported until ARIA 1.2 is a recommendation So, in this version, we should talk about the HTML technique first.

    +

    + To-do: write this section. + This version will not include the ARIA 1.2 legend role; it will be added in a version after the APG 1.1 R4 release in July. + Specifically illustrate Form element labeling, and refer back to cardinal rule 2: prefer visible text, and rule 3: prefer native techniques. +

    From ab90611691c7a1d4640d7b3f780aa3960803f126 Mon Sep 17 00:00:00 2001 From: Matt King Date: Mon, 3 Jun 2019 12:48:54 -0700 Subject: [PATCH 044/131] Introduce naming guidance by role table --- aria-practices.html | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index d10afcd8c5..5a71f83772 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3986,14 +3986,30 @@

    Composing Effective and User-friendly Accessible Names

    Accessible Name Guidance by Role

    Certain elements always require a name, others may usually or sometimes require a name, and still others should never be named. - The following table provides requirements, allowed techniques, and guidance for each ARIA role. + The table below lists all ARIA roles and provides the following information for each :

    +
    +
    When to Name:
    +
    + This column contains Always, Usually, Sometimes, or Never. + If the value is Always, the ARIA specification requires authors to provide a name, and a missing name will trigger accessibility validators to flag a violation. + The guidance column includes an explanation of the other values. +
    +
    Content Can Name
    +
    + This column contains Yes or No. + If the value is Yes, browsers will calculate a name for elements with that role from the text of all descendant content unless aria-label or aria-labelledby is used to override the content. + It is strongly recommended to avoid using aria-label or aria-labelledby on elements having one of the roles where this column contains Yes except in rare circumstances where hiding descendant content of the element from assistive technology users is beneficial. +
    +
    Guidance:
    +
    Provides information to help determine if providing a name is beneficial, and if so, identifies any recommended techniques.
    +
    roleGuidance
    alertalert Sometimes No A name can sometimes be useful to know what kind of alert it is.
    alertdialogalertdialog Always No guidance
    applicationapplication Always No guidance
    articlearticle namerequired No guidance
    bannerbanner namerequired No guidance
    buttonbutton Always Yes guidance
    cellcell namerequired Yes guidance
    checkboxcheckbox Always Yes guidance
    columnheadercolumnheader Always Yes guidance
    comboboxcombobox Always No guidance
    complementarycomplementary namerequired No guidance
    contentinfocontentinfo namerequired No guidance
    definitiondefinition namerequired No guidance
    dialogdialog Always No guidance
    directorydirectory namerequired No guidance
    documentdocument namerequired No guidance
    feedfeed namerequired No guidance
    figurefigure namerequired No guidance
    formform namerequired No guidance
    gridgrid Always No guidance
    gridcellgridcell Always Yes guidance
    groupgroup namerequired No guidance
    headingheading Always Yes guidance
    imgimg Always No guidance
    linklink Always Yes guidance
    listlist namerequired No guidance
    listboxlistbox Always No guidance
    listitemlistitem namerequired No guidance
    loglog Always No guidance
    mainmain namerequired No guidance
    marqueemarquee Always No guidance
    mathmath namerequired No guidance
    menumenu namerequired No guidance
    menubarmenubar namerequired No guidance
    menuitemmenuitem Always Yes guidance
    menuitemcheckboxmenuitemcheckbox Always Yes guidance
    menuitemradiomenuitemradio Always Yes guidance
    navigationnavigation namerequired No guidance
    none, presentationnone, presentation Never No
    notenote namerequired No guidance
    optionoption Always Yes guidance
    progressbarprogressbar Always No guidance
    radioradio Always Yes guidance
    radiogroupradiogroup Always No guidance
    regionregion Always No guidance
    rowrow namerequired Yes guidance
    rowgrouprowgroup namerequired Yes guidance
    rowheaderrowheader Always Yes guidance
    scrollbarscrollbar Always No guidance
    searchsearch namerequired No guidance
    searchboxsearchbox Always No guidance
    separatorseparator namerequired No guidance
    sliderslider Always No guidance
    spinbuttonspinbutton Always No guidance
    statusstatus namerequired No guidance
    switchswitch Always Yes guidance
    tabtab namerequired Yes guidance
    tabletable Always No guidance
    tablisttablist namerequired No guidance
    tabpaneltabpanel Always No guidance
    termterm namerequired No guidance
    textboxtextbox Always No guidance
    timertimer Always No guidance
    toolbartoolbar namerequired No guidance
    tooltiptooltip Always Yes guidance
    treetree Always Yes guidance
    treegridtreegrid Always No guidance
    treeitemtreeitem Always Yes guidancealert Sometimes NoA name can sometimes be useful to know what kind of alert it is.To-do: can we think of a circumstance where naming an alert would serve a useful purpose? Are there any assistive technologies that would render the boundaries of an alert container or have a way to render the name?
    alertdialog Always Noguidance
    Named using aria-labelledby if a visible title is present, otherwise with aria-label.
    application Always Noguidance
    articlenamerequiredUsually NoguidanceNamed using aria-labelledby if a visible title is present, otherwise with aria-label
    bannernamerequiredSometimes NoguidanceOnly necessary in the rare circumstances where two banner landmark regions are present on the same page. It is otherwise optional.
    button Always Yesguidance
    cell
    roleName RequiredNamed by ContentGuidanceProvide Name?Content Can NameGuidance
    alertSometimesOptional No To-do: can we think of a circumstance where naming an alert would serve a useful purpose? Are there any assistive technologies that would render the boundaries of an alert container or have a way to render the name?
    Always NoNamed using aria-labelledby if a visible title is present, otherwise with aria-label.
    articleUsuallyRecommended No Named using aria-labelledby if a visible title is present, otherwise with aria-label
    bannerSometimesOptional NoOnly necessary in the rare circumstances where two banner landmark regions are present on the same page. It is otherwise optional.Necessary in the uncommon circumstance where two banner landmark regions are present on the same page. It is otherwise optional.
    buttonAlways NoguidanceNamed using aria-labelledby if a visible title is present, otherwise with aria-label.
    complementarynamerequiredOptional No guidance
    - - - + + + From e2138b99a410c3d6b5ae1545bb02396451b66a7b Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Tue, 4 Jun 2019 16:08:25 +0200 Subject: [PATCH 045/131] The label element --- aria-practices.html | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 5a71f83772..6d9cdf0995 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3711,7 +3711,7 @@

    Providing Accessible Names and Descriptions

  • Naming with child content.
  • Naming with a string attribute via aria-label.
  • Naming by referencing content with aria-labelledby.
    • -
  • Naming by encapsulation with a label.
    • +
  • Naming with the label element.
  • Naming with legends and captions.
  • Fallback names derived from titles and placeholders.
    • @@ -3949,19 +3949,24 @@
    Naming with Referenced Content Via aria-labelledby
    -
    Naming by Encapsulation with a Label
    -

    - To-do: write this section. This version WILL NOT include the new ARIA 1.2 label role. - The 1.2 label role will be added after the July release of APG 1.1 R4. - So, in this version, we should talk about the HTML technique. - Specifically illustrate Form element labeling, and refer back to cardinal rule 2: prefer visible text, and rule 3: prefer native techniques. -

    +
    Naming with the Label Element
    +

    The HTML label element allows authors to give a form control a label, and have the two be programmatically associated so that assistive technologies can render the label when the user interacts with the form control.

    +

    For example, the purpose of a checkbox without a label would be unclear. If there's text next to the checkbox, visual users can understand the purpose, but users of assistive technology will only experience a checkbox without a label when interacting with the checkbox. Using the label element gives the checkbox a label and allows all users to access the label easily.

    + 
    <label>
+ <input type="checkbox" name="subscribe">
+ subscribe to our newsletter
+</label>
    +

    The form control can also be associated with the label by using the `for` attribute on the `label` element. This allows the label and the form control to have different parents in the DOM, but requires adding an `id` attribute to the form control, which can be error-prone. When possible, use encapsulation instead of the `for` attribute.

    + 
    <input type="checkbox" name="subscribe" id="subscribe_checkbox">
+<label for="subscribe_checkbox">subscribe to our newsletter</label>
    +

    Using the label element satisfies Rule 2: Prefer Visible Text and Rule 3: Prefer Native Techniques.

    +

    Another advantage of the label element is that clicking the label focuses or activates the associated form control, as if the form control had been clicked. This increases the hit area for the form control.

    Naming with Legends and Captions

    - To-do: write this section. + To-do: write this section. This version will not include the ARIA 1.2 legend role; it will be added in a version after the APG 1.1 R4 release in July. Specifically illustrate Form element labeling, and refer back to cardinal rule 2: prefer visible text, and rule 3: prefer native techniques.

    @@ -3985,7 +3990,7 @@

    Composing Effective and User-friendly Accessible Names

    Accessible Name Guidance by Role

    - Certain elements always require a name, others may usually or sometimes require a name, and still others should never be named. + Certain elements always require a name, others may usually or sometimes require a name, and still others should never be named. The table below lists all ARIA roles and provides the following information for each :

    @@ -3998,7 +4003,7 @@

    Accessible Name Guidance by RoleContent Can Name
    This column contains Yes or No. - If the value is Yes, browsers will calculate a name for elements with that role from the text of all descendant content unless aria-label or aria-labelledby is used to override the content. + If the value is Yes, browsers will calculate a name for elements with that role from the text of all descendant content unless aria-label or aria-labelledby is used to override the content. It is strongly recommended to avoid using aria-label or aria-labelledby on elements having one of the roles where this column contains Yes except in rare circumstances where hiding descendant content of the element from assistive technology users is beneficial.
    Guidance:
    From aa068f6e479a20bf38bd4aad1506967e68d9c67f Mon Sep 17 00:00:00 2001 From: Matt King Date: Tue, 4 Jun 2019 08:52:24 -0700 Subject: [PATCH 046/131] Draft effective naming guidance section --- aria-practices.html | 39 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 2 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 6d9cdf0995..953dc53d18 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3983,8 +3983,43 @@
    Fallback Names Derived from Titles and Placeholders

    Composing Effective and User-friendly Accessible Names

    -

    To-do: Write a section that describes how to make good names, i.e., brief, descriptive, unique, front-loaded, no role names, etc.

    -

    Example practice: Do NOT include a WAI-ARIA role name in the accessible name. For example, do not include the word "button" in the name of a button or the word "navigation" in the name of a navigation region.

    +

    + For assistive technology users, especially screen reader users, the quality of accessible names is one of the most significant contributors to usability. + Names that do not provide enough information reduce users' effectiveness while names that are too long reduce efficiency. + And, names that are difficult to understand reduce effectiveness, efficiency, and enjoyment. +

    +

    The following guidelines provide a starting point for crafting user friendly names.

    +
      +
    • + Convey function or purpose, not form. + For example, if an icon that looks like the letter X closes a dialog, name it Close, not X. + Similarly, if a set of navigation links in the left side bar navigate among the product pages in a shopping site, name the navigation region Product, not Left. +
      • +
    • + Put the most distinguishing and important words first. + Often, for interactive elements that perform an action, this means a verb is the first word. + For instance, if a list of contacts displays a separate set of edit, delete, and more actions buttons for each contact, Actions for John Doe is better than John Doe actions because it distinguishes the actions menu button from the other buttons as well from the element that opens John Doe's contact card. +
      • +
    • + Be concise. For many elements, one to three words is sufficient. + Only add more words when necessary. + +
      • +
    • + Do NOT include a WAI-ARIA role name in the accessible name. + For example, do not include the word "button" in the name of a button or the word "navigation" in the name of a navigation region. + Doing so would create duplicate screen reader output since screen readers convey the role of an element in addition to its name. +
      • +
    • + Create unique names for elements with the same role unless the elements are actually identical. + For example, ensure every link on a page has a different name except in cases where multiple links have the same target. + Similarly, give every navigation region on a page a different name unless there are regions with exactly identical content that perform exactly identical navigation functions. +
      • +
    • + Start names with a capital letter; it helps some screen readers speak them with appropriate inflection. + And, do nott end names with a period; they are not sentences. +
      • +
    From 5046495f3069246cd3f562cd52fb3c54dda07199 Mon Sep 17 00:00:00 2001 From: Matt King Date: Tue, 4 Jun 2019 09:03:42 -0700 Subject: [PATCH 047/131] Revise intro to naming guidance by role table --- aria-practices.html | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/aria-practices.html b/aria-practices.html index 953dc53d18..48869548a0 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4033,7 +4033,9 @@

    Accessible Name Guidance by Role This column contains Always, Usually, Sometimes, or Never. If the value is Always, the ARIA specification requires authors to provide a name, and a missing name will trigger accessibility validators to flag a violation. - The guidance column includes an explanation of the other values. + If the value is Usually, providing a name is strongly recommended. + If the value is Sometimes, naming is optional and may even be discouraged; the guidance column may provide additional explanation. + And, if the value is Never, naming is strongly discouraged even if it is technically permitted. This generally means that assistive technologies are unlikely to present a name even if provided.
    Content Can Name
    From b977ba5a8f17fefdfe8e418b90f95254a359b636 Mon Sep 17 00:00:00 2001 From: Matt King Date: Tue, 4 Jun 2019 09:37:06 -0700 Subject: [PATCH 048/131] More updates to naming guidance by role --- aria-practices.html | 71 ++++++++++++++++++++++++++++++++++++--------- 1 file changed, 57 insertions(+), 14 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 48869548a0..7f1ba42633 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4055,7 +4055,7 @@

    Accessible Name Guidance by Role

    - + @@ -4073,39 +4073,71 @@

    Accessible Name Guidance by Role

    - + - + - + - + - + - + - + - + - + @@ -4115,15 +4147,26 @@

    Accessible Name Guidance by Role

    - + - + - + - + From cccb053133599ac5c2f451fd0ddb51ed6a24cf87 Mon Sep 17 00:00:00 2001 From: Matt King Date: Tue, 4 Jun 2019 14:29:07 -0700 Subject: [PATCH 049/131] Revise aria-labelledby guidance --- aria-practices.html | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 7f1ba42633..3dfa6f4835 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3921,7 +3921,7 @@
    Naming with Referenced Content Via aria-labelledby

    In some cases, the most effective name for an element is its own content combined with the content of another element. Because aria-labelledby has highest precedence in name calculation, in those situations, it is possible to use aria-labelledby to reference both the element itself and the other element. - In the following example, the "read more" link is named by the element itself and the article’s heading, resulting in a name of "Read more... 7 ways you can help save the bees". + In the following example, the "read more" link is named by the element itself and the article’s heading, resulting in a name for the link of "Read more... 7 ways you can help save the bees". 

    
   <h2 id="bees-heading">7 ways you can help save the bees</h2>
@@ -3929,16 +3929,16 @@ 
    Naming with Referenced Content Via aria-labelledby
    
   <p><a id="bees-read-more" aria-labelledby="bees-read-more bees-heading">Read more...</a></p>

    - When multiple elements are referenced, the text content of the referenced elements will be concatenated in the order they are listed in the attribute value. - In addition, browsers will trim leading and trailing white space and separate the content from each element with a single space. + When multiple elements are referenced by aria-labelledby, text content from each referenced element is concatenated in the order specified in the aria-labeledby value. + If an element is referenced more than one time, only the first reference is processed. + When concatenating content from multiple elements, browsers trim leading and trailing white space and separate content from each element with a single space.

    - To-do: add one or two more simple but realistic examples to show reference to hidden elements and inputs, perhaps also highlighting how browsers handle spacing. - Short examples, 3 lines of code or less, are preferrable. + To-do: add example to show reference to hidden elements and an input that demonstrates spacing between strings from referenced elements.

    1. The aria-labelledby property cannot be chained, i.e., if an element with aria-labelledby references another element that also has aria-labelledby, the aria-labelledby attribute on the referenced element will be ignored.
      2. -
    2. The aria-labelledby property cannot be applied to the descendant of an element that supports naming from content. For example, most browsers will ignore the aria-labelledby attribute in this link: <a href="/"><span aria-labelledby="elem1"></span><a>.
      3. +
    3. If an element is referenced by aria-labelledby more than one time during a name calculation, the second and any subsequent references will be ignored.
    4. There are certain types of elements, such as paragraphs and list items, that should not be named with aria-labelledby. They are identified in the table in section Accessible Name Guidance by Role.
    5. If aria-labelledby is applied to an element with one of the roles that supports naming from child content, text content contained in the element and its descendants is hidden from assistive technology users unless it is also referenced by aria-labelledby. From 87179dc563710b2322b22a3dab8fcb472e8f22bf Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Wed, 5 Jun 2019 16:36:43 +0200 Subject: [PATCH 050/131] Fieldset and legend --- aria-practices.html | 43 +++++++++++++++++++++++++++++++++---------- 1 file changed, 33 insertions(+), 10 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 3dfa6f4835..cc2095ba53 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3711,8 +3711,9 @@

      Providing Accessible Names and Descriptions

    6. Naming with child content.
    7. Naming with a string attribute via aria-label.
    8. Naming by referencing content with aria-labelledby.
      9. -
    9. Naming with the label element.
      10. -
    10. Naming with legends and captions.
      11. +
    11. Naming form controls with the label element.
      12. +
    12. Naming fieldsets with the legend element.
      13. +
    13. Naming tables and figures with captions.
    14. Fallback names derived from titles and placeholders.
      15. @@ -3949,7 +3950,7 @@
      Naming with Referenced Content Via aria-labelledby
      -
      Naming with the Label Element
      +
      Naming Form Controls with the Label Element

      The HTML label element allows authors to give a form control a label, and have the two be programmatically associated so that assistive technologies can render the label when the user interacts with the form control.

      For example, the purpose of a checkbox without a label would be unclear. If there's text next to the checkbox, visual users can understand the purpose, but users of assistive technology will only experience a checkbox without a label when interacting with the checkbox. Using the label element gives the checkbox a label and allows all users to access the label easily.

      <label>
@@ -3963,13 +3964,35 @@ 
      Naming with the Label Element
      
           
      Another advantage of the label element is that clicking the label focuses or activates the associated form control, as if the form control had been clicked. This increases the hit area for the form control.
      -
      -
      Naming with Legends and Captions
      -

      - To-do: write this section. - This version will not include the ARIA 1.2 legend role; it will be added in a version after the APG 1.1 R4 release in July. - Specifically illustrate Form element labeling, and refer back to cardinal rule 2: prefer visible text, and rule 3: prefer native techniques. -

      +
      +
      Naming Fieldsets with the Legend Element
      +

      Multiple form controls can be grouped together to make the form easier to navigate. The HTML fieldset element can be used to group form controls, and the legend element gives the group a name.

      +

      This is particularly useful for questions with multiple choices; without associating the question with the options with markup, users of assistive technology might only access the answers and miss out on the question.

      +

      For example, a group of radio buttons can be grouped together in a fieldset, where the legend element labels the group for the radio buttons.

      + 
      <fieldset>
+ <legend>Select your starter class</legend>
+ <label><input name="starter-class" value="green"> Green</label>
+ <label><input name="starter-class" value="red"> Red</label>
+ <label><input name="starter-class" value="blue"> Blue</label>
+</fieldset>
      +

      Related form fields can also be grouped using fieldset and legend even when they are not multiple choices for one question. This is useful for users to be able to navigate the form group-by-group.

      + 
      <fieldset>
+ <legend>Shipping address</legend>
+ <p><label>Full name <input name="name" required></label></p>
+ <p><label>Address line 1 <input name="address-1" required></label></p>
+ <p><label>Address line 2 <input name="address-2"></label></p>
+ ...
+</fieldset>
+<fieldset>
+ <legend>Billing address</legend>
+ ...
+</fieldset>
      +

      Using the legend element to name a fieldset element satisfies Rule 2: Prefer Visible Text and Rule 3: Prefer Native Techniques.

      +
      + +
      +
      Naming Tables and Figures with Captions
      +

      To-do: write this section.

      From 1743094b42b20adf1f95f3629da968fb9facc72c Mon Sep 17 00:00:00 2001 From: Matt King Date: Sun, 9 Jun 2019 14:52:10 -0700 Subject: [PATCH 051/131] Fix everything raised in review by @carmacleod on June 4 --- aria-practices.html | 191 +++++++++++++++++++++++++------------------- 1 file changed, 110 insertions(+), 81 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index cc2095ba53..14a0bf044f 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3701,7 +3701,7 @@
      Examples

      Providing Accessible Names and Descriptions

      Providing elements with accessible names, and where appropriate, accessible descriptions is one of the most fundamental and important responsibilities authors have when developing accessible web experiences. - While doing so is straight forward for most elements, technical mistakes that can have devastating impacts on users of assistive technologies are easy to make and unfortunately common. + While doing so is straightforward for most elements, technical mistakes that can have devastating impacts on users of assistive technologies are easy to make and unfortunately common. To help authors provide effective and reliable 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 provides guidance for effectively employing the following naming and describing techniques and WAI-ARIA properties:

      @@ -3748,7 +3748,7 @@

      What ARE Accessible Names and Descriptions?

      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 it is an input), and any relevant states or properties. + For instance, a screen reader may announce a description of an element after its name, role, value (if any), and relevant states or properties.

      @@ -3769,8 +3769,8 @@

      Cardinal Rules of Naming

      Rule 1: Heed Warnings and Test Thoroughly

      - Several of the below naming techniques include notes that warn against specific coding patterns that are either prohibitted by the ARIA specification or fall into gray space that is not yet fully specified. - Some of these prohibitted or ambiguous patterns may appear logical and even yield desired names in some browsers. + Several of the naming techniques below include notes that warn against specific coding patterns that are either prohibited by the ARIA specification or fall into gray space that is not yet fully specified. + Some of these prohibited or ambiguous patterns may appear logical and even yield desired names in some browsers. However, it is unlikely they will provide consistent results across browsers, especially over time as work to improve the consistency of name calculation across browsers progresses.

      @@ -3782,14 +3782,19 @@

      Rule 1: Heed Warnings and Test Thoroughly
      Rule 2: Prefer Visible Text

      When a user interface includes visible text that could be used to provide an appropriate accessible name, using the visible text for the accessible name simplifies maintenance, prevents bugs, and reduces language translation requirements. - When names are generated from text that exists only in markup and is never displayed visually, there is a greater likelihood that accessible names are not updated when the user interface design or content are changed. + When names are generated from text that exists only in markup and is never displayed visually, there is a greater likelihood that accessible names will not be updated when the user interface design or content are changed. +

      +

      + If an interactive element, such as an input field or button , does not have a visually persistent text label, consider adjusting the design to include one. + In addition to serving as a more robust source for an accessible name, visible text labels enhance accessibility for many people with disabilities who do not use assistive technologies that present invisible accessible names. + In most circumstances, visible text labels also make the user interface easier to understand for all users.

      Rule 3: Prefer Native Techniques

      - In HTML documents, whenever possible, rely on HTML naming techniques, such as the HTML label element. + 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.

      @@ -3797,7 +3802,7 @@
      Rule 3: Prefer Native Techniques
      Rule 4: Avoid Browser Fallback

      - When authors do not specify an accessible name using an element or attribute that is intended for naming, browsers attempt to help assistive technology users by resorting to fall back methods for generating a name. + When authors do not specify an accessible name using an element or attribute that is intended for naming, browsers attempt to help assistive technology users by resorting to fallback methods for generating a name. For example, the HTML title and placeholder attributes are used as last resort sources of content for accessible names. Because the purpose of these attributes is not naming, their content typically yields low quality accessible names that are not effective.

      @@ -3808,7 +3813,7 @@
      Rule 5: Compose Brief, Useful Names

      Similar to how visually crowded screens and ambiguous icons reduce usability, excessively long, insufficiently distinct, or unclear accessible names can make a user interface very difficult, or even impossible, to use for someone who relies on a non-visual form of the user interface. In other words, for a web experience to be accessible, its accessible names must be effective. - The below section on Composing Effective and User-friendly Accessible Names provides guidance for balancing brevity and clarity. + The section on Composing Effective and User-friendly Accessible Names provides guidance for balancing brevity and clarity.

      @@ -3826,8 +3831,8 @@
      Naming with Child Content
      <a href="/">Home</a>

      - When assistive technologies render an element, such as a link or button, that gets its accessible name from its content, the accessible name is the only content the user can perceive for that element. - This is in contrast to other elements, such as text fields or tables, where the accessible name is a label that is presented along with the value or content of the element. + When assistive technologies render an element that gets its accessible name from its content, such as a link or button, the accessible name is the only content the user can perceive for that element. + This is in contrast to other elements, such as text fields or tables, where the accessible name is a label that is presented in addition to the value or content of the element. For instance, the accessible name of a table can be derived from a caption element, and assistive technologies render both the caption and all other content contained inside the table.

      Elements having one of the following roles are, by default, named by a string calculated from all their descendant content:

      @@ -3852,7 +3857,7 @@
      Naming with Child Content
    15. treeitem

      16. - If an element with one of the above roles is named by using aria-label or aria-labelledby, text content contained in the element and its descendants is hidden from assistive technology users unless the descendant content is referenced by aria-labelledby. + If an element with one of the above roles is named by using aria-label or aria-labelledby, content contained in the element and its descendants is hidden from assistive technology users unless the descendant content is referenced by aria-labelledby. It is strongly recommended to avoid using either of these attributes to override content of one of the above elements except in rare circumstances where hiding content from assistive technology users is beneficial. In addition, in situations where visible content is hidden from assistive technology users by use of one of these attributes, thorough testing with assistive technologies is particularly important.

      @@ -3861,33 +3866,33 @@
      Naming with Child Content
      Naming with a String Attribute Via aria-label

      - The aria-label attribute enables authors to specify a string that will name an element. + The aria-label property enables authors to specify a string that will name an element. For example, the name of the following button is "Close". 

      <button type="button" aria-label="Close">X</button>

      - The aria-label attribute is useful when there is no visible text content that will serve as an appropriate accessible name. + The aria-label property is useful when there is no visible text content that will serve as an appropriate accessible name.

      - The aria-label attribute affects assistive technology users in one of two different ways, depending on the role of the element to which it is applied. - When applied to an element with one of the roles that supports naming from child content, aria-label hides descendant content from assistive technology users and replaces the content with the value of aria-label. - However, when applied to nearly any other type of element, assistive technologies will render both the value of aria-label and the content of the element. + The aria-label property affects assistive technology users in one of two different ways, depending on the role of the element to which it is applied. + When applied to an element with one of the roles that supports naming from child content, aria-label hides descendant content from assistive technology users and replaces it with the value of aria-label. + However, when applied to nearly any other type of element, assistive technologies will render both the value of aria-label and the content of the element. For example, the name of the following navigation region is "Product". 

      
-          <nav aria-label="Product">
-            <!-- list of navigation links to product pages -->
-          </nav>
+  <nav aria-label="Product">
+    <!-- list of navigation links to product pages -->
+  </nav>

      When encountering this navigation region, a screen reader user will hear the name and role of the element, e.g., "Product navigation region", and then be able to read through the links contained in the region.

      1. - If aria-label is applied to an element with one of the roles that supports naming from child content, text content contained in the element and its descendants is hidden from assistive technology users. - It is strongly recommended to avoid using this attribute to override content of one of these elements except in rare circumstances where hiding content from assistive technology users is beneficial. + If aria-label is applied to an element with one of the roles that supports naming from child content, content contained in the element and its descendants is hidden from assistive technology users. + It is strongly recommended to avoid using aria-label to override content of one of these elements except in rare circumstances where hiding content from assistive technology users is beneficial.
        2. -
      2. There are certain types of elements, such as paragraphs and list items, that should not be named with aria-label. They are identified in the table in section Accessible Name Guidance by Role.
        3. +
      3. There are certain types of elements, such as paragraphs and list items, that should not be named with aria-label. They are identified in the table in the Accessible Name Guidance by Role section.
      4. Because the value of aria-label is not rendered visually, testing with assistive technologies to ensure the expected name is presented to users is particularly important.
      5. When a user interface is translated into multiple languages, ensure that aria-label values are translated.
      @@ -3922,7 +3927,7 @@
      Naming with Referenced Content Via aria-labelledby

      In some cases, the most effective name for an element is its own content combined with the content of another element. Because aria-labelledby has highest precedence in name calculation, in those situations, it is possible to use aria-labelledby to reference both the element itself and the other element. - In the following example, the "read more" link is named by the element itself and the article’s heading, resulting in a name for the link of "Read more... 7 ways you can help save the bees". + In the following example, the "Read more..." link is named by the element itself and the article’s heading, resulting in a name for the link of "Read more... 7 ways you can help save the bees". 

      
   <h2 id="bees-heading">7 ways you can help save the bees</h2>
@@ -3940,9 +3945,9 @@ 
      Naming with Referenced Content Via aria-labelledby
      
           
        
             
      1. The aria-labelledby property cannot be chained, i.e., if an element with aria-labelledby references another element that also has aria-labelledby, the aria-labelledby attribute on the referenced element will be ignored.
        2. 
             
      2. If an element is referenced by aria-labelledby more than one time during a name calculation, the second and any subsequent references will be ignored.
        3. 
-            
      3. There are certain types of elements, such as paragraphs and list items,  that should not be named with aria-labelledby. They are identified in the table in section Accessible Name Guidance by Role.
        4. 
+            
      4. There are certain types of elements, such as paragraphs and list items,  that should not be named with aria-labelledby. They are identified in the table in the Accessible Name Guidance by Role section.
        5. 
             
      5. 
-          If aria-labelledby is applied to an element with one of the roles that supports naming from child content, text content contained in the element and its descendants is hidden from assistive technology users unless it is also referenced by aria-labelledby.
+          If aria-labelledby is applied to an element with one of the roles that supports naming from child content, content contained in the element and its descendants is hidden from assistive technology users unless it is also referenced by aria-labelledby.
           It is strongly recommended to avoid using this attribute to override content of one of these elements except in rare circumstances where hiding content from assistive technology users is beneficial.
         
        6. 
             
      6. Because calculating the name of an element with aria-labelledby can be complex and reference hidden content, testing with assistive technologies to ensure the expected name is presented to users is particularly important.
        7. 
@@ -3999,7 +4004,7 @@ 
        Naming Tables and Figures with Captions
        
           
        Fallback Names Derived from Titles and Placeholders
        
           
        To-do: finish writing this section. Needs to cover title, placeholder, and aria-placeholder.
        
           
        
-            For the HTML `input` element, the `placeholder` attribute is used as a fallback labeling mechanism if nothing else results in a label. For an `input` element, it is better to use a `label` element, since it does not disappear visually when the user focuses the form control.
+            For the HTML input element, the placeholder attribute is used as a fallback labeling mechanism if nothing else results in a label. For an input element, it is better to use a label element, since it does not disappear visually when the user focuses the form control.
      @@ -4026,11 +4031,10 @@

      Composing Effective and User-friendly Accessible Names

    16. Be concise. For many elements, one to three words is sufficient. Only add more words when necessary. -
    17. Do NOT include a WAI-ARIA role name in the accessible name. - For example, do not include the word "button" in the name of a button or the word "navigation" in the name of a navigation region. + For example, do not include the word button in the name of a button, the word image in the name of an image, or the word navigation in the name of a navigation region. Doing so would create duplicate screen reader output since screen readers convey the role of an element in addition to its name.
    18. @@ -4540,8 +4544,8 @@

      Accessible name calculation

      To-do: make the steps related to HTML elements and attributes in the following list more specific so readers can see the precedence of any specific element or attribute.

        -
      1. The aria-labelledby attribute is used if present.
        2. -
      2. If the name is still empty, the aria-label attribute is used if present.
        3. +
      3. The aria-labelledby property is used if present.
        4. +
      4. If the name is still empty, the aria-label property is used if present.
      5. If the name is still empty, then host-language-specific attributes or elements (e.g., alt attribute on HTML img) are used if present.
      6. If the name is still empty, then for elements with a role that supports naming from child content, the content of the element is used.
      7. Finally, if the name is still empty, then other fallback host-language-specific tooltip attributes or elements (e.g., the title attribute in HTML) are used if present.
        8. @@ -4551,13 +4555,14 @@

        Accessible name calculation

        When calculating a name from content, the user agent walks through all descendant nodes. - And, when following aria-labelledby references, it similarly walks the tree of each referenced element. + And, when following aria-labelledby references, it similarly walks the tree of each referenced element. Thus, the naming algorithm is recursive. The following two sections provide non-recursive and recursive examples of how the algorithm works.

        Examples of non-recursive accessible name calculation
        +

        To-do: replace this img example with input type text example.

        Consider an img element that has only an src attribute and so does not have an accessible name (do not do this):

        <img src="photo.jpg">

        If there is a title attribute, then it serves as a naming falback mechanism (avoid doing this):

        @@ -4583,19 +4588,20 @@
        Examples of non-recursive accessible name calculation
        Examples of recursive accessible name calculation

        The accessible name calculation algorithm will be invoked recursively when necessary. An `aria-labelledby` reference causes the algorithm to be invoked recursively, and when computing an accessible name from content the algorithm is invoked recursively for each child node.

        -

        In this example, the label for the button is computed by recursing into each child node, resulting in "Move to trash".

        +

        In this example, the label for the button is computed by recursing into each child node, resulting in Move to trash.

        <button>Move to <img src="bin.svg" alt="trash"></button>
        -

        When following an `aria-labelledby` reference, the algorithm avoids following the same reference twice in order to not end up in infinite loops.

        +

        When following an aria-labelledby reference, the algorithm avoids following the same reference twice to avoid infinite loops.

        -

        In this example, the label for the button is computed by first following the `aria-labelledby` reference to the parent element, and then computing the label for that element from the child nodes, first visiting the `button` element again but ignoring the `aria-labelledby` reference and instead using the `aria-label` attribute, and then visiting the next child (the text node). The resulting label is "Remove meeting: Daily status report".

        +

        In this example, the label for the button is computed by first following the aria-labelledby reference to the parent element, and then computing the label for that element from the child nodes, first visiting the button element again but ignoring the aria-labelledby reference and instead using the aria-label, and then visiting the next child (the text node). The resulting label is Remove meeting: Daily status report.

        - 
        <div id="meeting-1">
-    <button aria-labelledby="meeting-1"
-        aria-label="Remove meeting:">X</button>
-        Daily status report
-    </div>
        + 
        
+  <div id="meeting-1">
+    <button aria-labelledby="meeting-1" aria-label="Remove meeting:">X</button>
+    Daily status report
+  </div>
+
        @@ -4604,60 +4610,83 @@
        Examples of recursive accessible name calculation

        Accessible Descriptions

        Describing Techniques

        - -
        +
        Describing by referencing content with aria-describedby
        -

        The `aria-describedby` attribute works similarly to the `aria-labelledby` attribute. For example, a button could be described by a later paragraph.

        +

        + The aria-describedby property works similarly to the aria-labelledby property. + For example, a button could be described by a sibling paragraph. +

        + + 
        
+  <button aria-describedby="trash-desc">Move to trash</button>
+  ...
+  <p id="trash-desc">Items in the trash will be permanently removed after 30 days.</p>
+
        - 
        <button aria-describedby="trash-desc">Move to trash</button>
-            ...
-            <p id="trash-desc">Items in the trash
-            will be permanently removed after 30 days.</p>
        +

        This description will be presented to the user as plain text. For example, if the description contains an HTML img element, a text equivalent of the image is computed.

        -

        This description will be presented to the user as plain text. For example, if the description contains an HTML `img` element, a text equivalent of the image is computed.

        + 
        
+  <button aria-describedby="trash-desc"> Move to <img src="bin.svg" alt="trash"></button>
+  ...
+  <p id="trash-desc">Items in <img src="bin.svg" alt="the trash"> will be permanently removed after 30 days.</p>
+
        +

        + As with aria-labelledby, it is possible to reference an element using aria-describedby even if that element is hidden. + For example, a text field in a form could have a description that is hidden by default, but can be revealed on request using a disclosure widget. + The description could also be referenced from the text field directly with aria-describedby. + In the following example, the accessible description for the input element is Your username is the name that you use to log in to this service. +

        - 
        <button aria-describedby="trash-desc">
-            Move to <img src="bin.svg" alt="trash">
-            </button>
-            ...
-            <p id="trash-desc">Items in <img src="bin.svg" alt="the trash">
-            will be permanently removed after 30 days.</p>
        + 
        
+  <label for="username">Username</label>
+  <input id="username" name="username" aria-describedby="username-desc">
+  <button aria-expanded="false" aria-controls="username-desc" aria-label="Help about username">?</button>
+  <p id="username-desc" hidden>
+    Your username is the name that you use to log in to this service.
+  </p>
+
        -
        +
        Describing by referencing content with aria-details
        -

        In some cases, a plain text description is insufficient. The `aria-details` attribute can be used in such situations. In this example, a text field for a passenger’s name (when booking a flight) has a description that is a list of three items, and contains a link to an external document with further details.

        - - 
        <ul id="full-name-desc">
-            <li>The passenger's name must match the name in their passport.</li>
-            <li>The name must consist of only characters in the A-Z range.</li>
-            <li><a href="faq.html#name">What if the name in the passport contains other characters?</a></li>
-            </ul>
-            <fieldset>
-            <legend>Passenger 1 (adult)</legend>
-            <p><label>Full name
-            <input name="full-name" aria-details="full-name-desc">
-            </label></p>
-            ...
-            </fieldset>
        - -

        If both `aria-details` and `aria-describedby` are specified on an element, only the `aria-details` attribute is used. This can be useful in order to provide a fallback for user agents that don’t support `aria-details`.

        +

        + In some cases, a plain text description is insufficient. + The aria-details property can be used in such situations. + In the following example, a text field for a passenger’s name (when booking a flight) has a description that is a list of three items, and contains a link to an external document with further details. +

        + + 
        
+  <ul id="full-name-desc">
+    <li>The passenger's name must match the name in their passport.</li>
+    <li>The name must consist of only characters in the A-Z range.</li>
+    <li><a href="faq.html#name">What if the name in the passport contains other characters?</a></li>
+  </ul>
+  <fieldset>
+    <legend>Passenger 1 (adult)</legend>
+    <p>
+      <label>Full name <input name="full-name" aria-details="full-name-desc"></label>
+    </p>
+    ...
+  </fieldset>
+
        + +

        + If both aria-details and aria-describedby are specified on an element, browsers ignore the aria-describedby value when calculating the accessible description. + Specifying both is potentially useful if there is a need to provide a fallback description for browsers and assistive technologies that do not yet support aria-details. +

        Accessible description calculation

        -

        Like the accessible name calculation (see the earlier section), the accessible description calculation produces a plain text string for an element. This algorithm is not used for the `aria-details` attribute.

        -

        The accessible description calculation algorithm is the same algorithm as the accessible name calculation algorithm, but it branches off in some places depending on whether a name or a description is being calculated. In particular, when collecting an accessible description, the algorithm uses `aria-describedby` instead of `aria-labelledby`.

        -

        As with `aria-labelledby`, it is possible to reference an element using `aria-describedby` even if that element is hidden.

        -

        For example, a text field in a form could have a description that is hidden by default, but can be revealed on request using a disclosure widget. The description could also be referenced from the text field directly with `aria-describedby`. The accessible description for the `input` element is "Your username is the name that you use to log in to this service.".

        - - 
        <label for="username">Username</label>
-          <input id="username" name="username" aria-describedby="username-desc">
-          <button aria-expanded="false" aria-controls="username-desc" aria-label="Help about username">?</button>
-          <p id="username-desc" hidden>
-          Your username is the name that you use to log in to this service.
-          </p>
        +

        + Like the accessible name calculation, the accessible description calculation produces a text string. + However, there is one exception: when an element is described using the aria-details/ property the assistive technology is provided with a reference. +

        +

        + The accessible description calculation algorithm is the same as the accessible name calculation algorithm except for a few branch points that depend on whether a name or description is being calculated. + In particular, when accumulating text for an accessible description, the algorithm uses aria-describedby instead of aria-labelledby. +

        From 7fb3244b88d62d924f679877b002957d6d4f9b20 Mon Sep 17 00:00:00 2001 From: Matt King Date: Sun, 9 Jun 2019 23:13:23 -0700 Subject: [PATCH 052/131] More minor revisions and to-do updates --- aria-practices.html | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 14a0bf044f..a348800dc1 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3935,7 +3935,7 @@
        Naming with Referenced Content Via aria-labelledby
        <p><a id="bees-read-more" aria-labelledby="bees-read-more bees-heading">Read more...</a></p>

        - When multiple elements are referenced by aria-labelledby, text content from each referenced element is concatenated in the order specified in the aria-labeledby value. + When multiple elements are referenced by aria-labelledby, text content from each referenced element is concatenated in the order specified in the aria-labelledby value. If an element is referenced more than one time, only the first reference is processed. When concatenating content from multiple elements, browsers trim leading and trailing white space and separate content from each element with a single space.

        @@ -4538,11 +4538,11 @@

        Accessible Name Guidance by Role

        Accessible name calculation

        - User agents formulate an accessible name string for an element by walking through a list of potential naming methods and using the first that generates a name. + User agents construct an accessible name string for an element by walking through a list of potential naming methods and using the first that generates a name. The algorithm they follow is defined in the accessible name specification. It is roughly like the following:

        -

        To-do: make the steps related to HTML elements and attributes in the following list more specific so readers can see the precedence of any specific element or attribute.

        +

        To-do: Add a specific step for each HTML element and attribute in the following list so readers can see the precedence of any specific element or attribute.

        1. The aria-labelledby property is used if present.
        2. If the name is still empty, the aria-label property is used if present.
          3. @@ -4623,13 +4623,14 @@
          Describing by referencing content with aria-describedby
          <p id="trash-desc">Items in the trash will be permanently removed after 30 days.</p>           -

          This description will be presented to the user as plain text. For example, if the description contains an HTML img element, a text equivalent of the image is computed.

          +

          Descriptions are reduced to text strings. For example, if the description contains an HTML img element, a text equivalent of the image is computed.

          
   <button aria-describedby="trash-desc"> Move to <img src="bin.svg" alt="trash"></button>
   ...
   <p id="trash-desc">Items in <img src="bin.svg" alt="the trash"> will be permanently removed after 30 days.</p>
          +

          As with aria-labelledby, it is possible to reference an element using aria-describedby even if that element is hidden. For example, a text field in a form could have a description that is hidden by default, but can be revealed on request using a disclosure widget. @@ -4647,7 +4648,7 @@

          Describing by referencing content with aria-describedby
          -
          +
          Describing by referencing content with aria-details

          In some cases, a plain text description is insufficient. @@ -4687,6 +4688,7 @@

          Accessible description calculation

          The accessible description calculation algorithm is the same as the accessible name calculation algorithm except for a few branch points that depend on whether a name or description is being calculated. In particular, when accumulating text for an accessible description, the algorithm uses aria-describedby instead of aria-labelledby.

          +

          To-do: Provide a step-by-step summary of the description calculation algorithm.

          From 32c5ca05ba34eaee1203931eb3bed1025d570d7f Mon Sep 17 00:00:00 2001 From: Matt King Date: Mon, 10 Jun 2019 00:11:17 -0700 Subject: [PATCH 053/131] Add stub section for fallback descriptions --- aria-practices.html | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/aria-practices.html b/aria-practices.html index a348800dc1..24c5d13191 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4676,6 +4676,11 @@
          Describing by referencing content with aria-details
          Specifying both is potentially useful if there is a need to provide a fallback description for browsers and assistive technologies that do not yet support aria-details.

          + +
          +
          Fallback Descriptions Derived from Titles and Placeholders
          +

          To-do: write this section.

          +
          From 7806b3ede8a83ac73d982afc7ff7d1ca1e179d26 Mon Sep 17 00:00:00 2001 From: Matt King Date: Mon, 10 Jun 2019 00:57:47 -0700 Subject: [PATCH 054/131] Editorial revisions to labeling form elements section --- aria-practices.html | 41 ++++++++++++++++++++++++++++++----------- 1 file changed, 30 insertions(+), 11 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 24c5d13191..4e6481e592 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3956,17 +3956,36 @@
          Naming with Referenced Content Via aria-labelledby
          Naming Form Controls with the Label Element
          -

          The HTML label element allows authors to give a form control a label, and have the two be programmatically associated so that assistive technologies can render the label when the user interacts with the form control.

          -

          For example, the purpose of a checkbox without a label would be unclear. If there's text next to the checkbox, visual users can understand the purpose, but users of assistive technology will only experience a checkbox without a label when interacting with the checkbox. Using the label element gives the checkbox a label and allows all users to access the label easily.

          - 
          <label>
- <input type="checkbox" name="subscribe">
- subscribe to our newsletter
-</label>
          -

          The form control can also be associated with the label by using the `for` attribute on the `label` element. This allows the label and the form control to have different parents in the DOM, but requires adding an `id` attribute to the form control, which can be error-prone. When possible, use encapsulation instead of the `for` attribute.

          - 
          <input type="checkbox" name="subscribe" id="subscribe_checkbox">
-<label for="subscribe_checkbox">subscribe to our newsletter</label>
          -

          Using the label element satisfies Rule 2: Prefer Visible Text and Rule 3: Prefer Native Techniques.

          -

          Another advantage of the label element is that clicking the label focuses or activates the associated form control, as if the form control had been clicked. This increases the hit area for the form control.

          +

          + The HTML label element enables authors to identify content that serves as a label and associate it with a form control. + When a label element is associated with a form control, Browsers calculate an accessible name for the form control from the label content. +

          +

          + For example, text displayed adjacent to a checkbox may be visually associated with the checkbox, so it is understood as the checkbox label by users who can perceive that visual association. + However, unless the text is programmatically associated with the checkbox, assistive technology users will experience a checkbox without a label. + Wrapping the checkbox and the labeling text in a label element as follows gives the checkbox an accessible name. +

          + 
          
+  <label>
+    <input type="checkbox" name="subscribe">
+    subscribe to our newsletter
+  </label>
+
          +

          + A form control can also be associated with a label by using the for attribute on the label element. + This allows the label and the form control to have different parents in the DOM, but requires adding an id attribute to the form control, which can be error-prone. + When possible, use the above encapsulation technique for association instead of the following for attribute technique. +

          + 
          
+  <input type="checkbox" name="subscribe" id="subscribe_checkbox">
+  <label for="subscribe_checkbox">subscribe to our newsletter</label>
+
          +

          + Using the label element is an effective technique for satisfying Rule 2: Prefer Visible Text. + It also satisfies Rule 3: Prefer Native Techniques. + Native HTML labels offer an important usability and accessibility advantage over ARIA labeling techniques: browsers automatically make clicking the label equivalent to clicking the form control. + This increases the hit area of the form control. +

          From b530fea5ba06b4ea688a37234a8a8764b763aab3 Mon Sep 17 00:00:00 2001 From: Matt King Date: Mon, 10 Jun 2019 01:15:29 -0700 Subject: [PATCH 055/131] Editorial revisions to labeling with legends section. --- aria-practices.html | 54 ++++++++++++++++++++++++++++----------------- 1 file changed, 34 insertions(+), 20 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 4e6481e592..f09e0f5dd8 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3990,27 +3990,41 @@
          Naming Form Controls with the Label Element
          Naming Fieldsets with the Legend Element
          -

          Multiple form controls can be grouped together to make the form easier to navigate. The HTML fieldset element can be used to group form controls, and the legend element gives the group a name.

          -

          This is particularly useful for questions with multiple choices; without associating the question with the options with markup, users of assistive technology might only access the answers and miss out on the question.

          +

          + The HTML fieldset element can be used to group form controls, which can make forms easier to navigate. + The legend element can be used to give the group a name. +

          +

          + This grouping technique is particularly useful for presenting multiple choice questions. + It enables authors to associate a question with a group of answers. + If a question is not programmatically associated with its answer options, assistive technology users could access the answers without being aware of the question. +

          For example, a group of radio buttons can be grouped together in a fieldset, where the legend element labels the group for the radio buttons.

          - 
          <fieldset>
- <legend>Select your starter class</legend>
- <label><input name="starter-class" value="green"> Green</label>
- <label><input name="starter-class" value="red"> Red</label>
- <label><input name="starter-class" value="blue"> Blue</label>
-</fieldset>
          -

          Related form fields can also be grouped using fieldset and legend even when they are not multiple choices for one question. This is useful for users to be able to navigate the form group-by-group.

          - 
          <fieldset>
- <legend>Shipping address</legend>
- <p><label>Full name <input name="name" required></label></p>
- <p><label>Address line 1 <input name="address-1" required></label></p>
- <p><label>Address line 2 <input name="address-2"></label></p>
- ...
-</fieldset>
-<fieldset>
- <legend>Billing address</legend>
- ...
-</fieldset>
          + 
          
+  <fieldset>
+    <legend>Select your starter class</legend>
+    <label><input name="starter-class" value="green"> Green</label>
+    <label><input name="starter-class" value="red"> Red</label>
+    <label><input name="starter-class" value="blue"> Blue</label>
+  </fieldset>
+
          +

          + Other types of related form fields can also be grouped using fieldset and legend. + This helps users navigate the form group-by-group. +

          + 
          
+  <fieldset>
+    <legend>Shipping address</legend>
+    <p><label>Full name <input name="name" required></label></p>
+    <p><label>Address line 1 <input name="address-1" required></label></p>
+    <p><label>Address line 2 <input name="address-2"></label></p>
+    ...
+  </fieldset>
+  <fieldset>
+    <legend>Billing address</legend>
+    ...
+  </fieldset>
+

          Using the legend element to name a fieldset element satisfies Rule 2: Prefer Visible Text and Rule 3: Prefer Native Techniques.

          From 16964ba912f5bcfdaadc7c72db7f67285ac1e6a5 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 10 Jun 2019 16:56:51 +0200 Subject: [PATCH 056/131] First draft of table and figure captions --- aria-practices.html | 42 +++++++++++++++++++++++++++++++++++------- common/biblio.js | 7 ++++++- 2 files changed, 41 insertions(+), 8 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index f09e0f5dd8..bce3c606bf 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4009,7 +4009,7 @@
          Naming Fieldsets with the Legend Element
          </fieldset>

          - Other types of related form fields can also be grouped using fieldset and legend. + Other types of related form fields can also be grouped using fieldset and legend. This helps users navigate the form group-by-group. 

          
@@ -4030,7 +4030,35 @@ 
          Naming Fieldsets with the Legend Element
          
 
         
          
           
          Naming Tables and Figures with Captions
          
-          
          To-do: write this section.
          
+          
          Tables and figures often have a caption to explain what the table of figure is about, how to read them, and sometimes giving them numbers to be able to refer to them in surrounding prose. This can help users navigate and understand the content better. This is generally useful for all users, but especially for users of assistive technologies.
          
+          
          In HTML, the table element marks up a data table, and can be provided with a caption using the caption element.
          
+          
          <table>
+ <caption>Special opening hours</caption>
+ <tr><td>30 May <td>Closed
+ <tr><td>6 June <td>11:00-16:00
+</table>
          
+          
          The following example gives the table a number ("Table 1") so it can be referenced. [[?CALORIC-RESTRICTION]]
          
+          
          <table>
+ <caption>Table 1. Traditional dietary intake of Okinawans and other Japanese circa 1950</caption>
+ <thead>
+  <tr>
+   <th>
+   <th>Okinawa, 1949
+   <th>Japan, 1950
+ <tbody>
+  <tr>
+   <th>Total calories
+   <td>1785
+   <td>2068
+
+  [...]
+
+</table>
          
+          
          Similarly, the HTML figure element can be given a caption using the figcaption element. The caption can appear before or after the figure, but it is more common for figures to have the caption after.
          
+          
          <figure>
+ <img alt="Painting of a person walking in a desert." src="Hole_JesusalDesierto.jpg">
+ <figcaption>Jesus entering the desert as imagined by William Hole, 1908</figcaption>
+</figure>
          
         
          
 
         
          
@@ -4093,9 +4121,9 @@ 
          Accessible Name Guidance by Role
             This column contains Always, Usually, Sometimes, or Never.
             If the value is Always, the ARIA specification requires authors to provide a name, and a missing name will trigger accessibility validators to flag a violation.
-            If the value is Usually, providing a name is strongly recommended. 
+            If the value is Usually, providing a name is strongly recommended.
             If the value is Sometimes, naming is optional and may even be discouraged; the guidance column may provide additional explanation.
-            And, if the value is Never, naming is strongly discouraged even if it is technically permitted. This generally means that assistive technologies are unlikely to present a name even if provided. 
+            And, if the value is Never, naming is strongly discouraged even if it is technically permitted. This generally means that assistive technologies are unlikely to present a name even if provided.
           
           
          Content Can Name
          
           
          
@@ -4137,7 +4165,7 @@ 
          Accessible Name Guidance by RoleNo

    @@ -4663,7 +4691,7 @@
    Describing by referencing content with aria-describedby
    ... <p id="trash-desc">Items in <img src="bin.svg" alt="the trash"> will be permanently removed after 30 days.</p>     - +

    As with aria-labelledby, it is possible to reference an element using aria-describedby even if that element is hidden. For example, a text field in a form could have a description that is hidden by default, but can be revealed on request using a disclosure widget. @@ -4709,7 +4737,7 @@

    Describing by referencing content with aria-details
    Specifying both is potentially useful if there is a need to provide a fallback description for browsers and assistive technologies that do not yet support aria-details.

    - +
    Fallback Descriptions Derived from Titles and Placeholders

    To-do: write this section.

    diff --git a/common/biblio.js b/common/biblio.js index 72e1618146..3658bae2fe 100644 --- a/common/biblio.js +++ b/common/biblio.js @@ -34,5 +34,10 @@ var biblio = { }, "WAI-ARIA": { "aliasOf": "WAI-ARIA-1.1", - } + }, + "CALORIC-RESTRICTION": { + "href": "https://www.ncbi.nlm.nih.gov/pubmed/17986602", + "title": "Caloric restriction, the traditional Okinawan diet, and healthy aging: the diet of the world's longest-lived people and its potential impact on morbidity and life span", + "publisher": "The National Center for Biotechnology Information" + } }; From 9fd5cb41cd4c1654f8257f272fd971f335cba657 Mon Sep 17 00:00:00 2001 From: Matt King Date: Mon, 10 Jun 2019 11:53:56 -0700 Subject: [PATCH 057/131] Add placeholder for section about describing with captions. --- aria-practices.html | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/aria-practices.html b/aria-practices.html index bce3c606bf..0f8b7b5fde 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3721,6 +3721,7 @@

    Providing Accessible Names and Descriptions

    • Describing by referencing content with aria-describedby.
    • Describing by referencing content with aria-details.
      • +
    • Describing tables and figures with captions.
    • Fallback descriptions derived from titles and placeholders.
    @@ -4737,6 +4738,11 @@
    Describing by referencing content with aria-details
    Specifying both is potentially useful if there is a need to provide a fallback description for browsers and assistive technologies that do not yet support aria-details.

    + +
    +
    Describing Tables and Figures with Captions
    +

    To-do: write this section. Include example of a table labeled by a heading via aria-labelledby so the caption becomes a description.

    +
    Fallback Descriptions Derived from Titles and Placeholders
    From 892ccff7c18ea5831edb9a2b1ac21848517e3396 Mon Sep 17 00:00:00 2001 From: Matt King Date: Mon, 10 Jun 2019 18:00:29 -0700 Subject: [PATCH 058/131] Revised based on June 10 review comments from @carmacleod. --- aria-practices.html | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 0f8b7b5fde..c92b02d205 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3974,7 +3974,7 @@
    Naming Form Controls with the Label Element

    A form control can also be associated with a label by using the for attribute on the label element. - This allows the label and the form control to have different parents in the DOM, but requires adding an id attribute to the form control, which can be error-prone. + This allows the label and the form control to be siblings or have different parents in the DOM, but requires adding an id attribute to the form control, which can be error-prone. When possible, use the above encapsulation technique for association instead of the following for attribute technique. 

    
@@ -4088,7 +4088,9 @@ 
    Composing Effective and User-friendly Accessible Names
    
           
  • 
             Put the most distinguishing and important words first.
             Often, for interactive elements that perform an action, this means a verb is the first word.
-            For instance, if a list of contacts displays a separate set of edit, delete, and more actions buttons for each contact, Actions for John Doe is better than John Doe actions because it distinguishes the actions menu button from the other buttons as well from the element that opens John Doe's contact card.
+            For instance, if a list of contacts displays Edit, Delete, and Actions buttons for each contact,
+            then Edit John Doe, Delete John Doe, and Actions for John Doe would be better accessible names than John Doe edit, John Doe delete, and John Doe actions.
+            By placing the verb first in the name, screen reader users can more easily and quickly distinguish the buttons from one another as well as from the element that opens the contact card for John Doe.
           
    • 
           
  • 
             Be concise. For many elements, one to three words is sufficient.
@@ -4101,12 +4103,12 @@ 
    Composing Effective and User-friendly Accessible Names
    
           
    • 
           
  • 
             Create unique names for elements with the same role unless the elements are actually identical.
-            For example, ensure every link on a page has a different name except in cases where multiple links have the same target.
-            Similarly, give every navigation region on a page a different name unless there are regions with exactly identical content that perform exactly identical navigation functions.
+            For example, ensure every link on a page has a different name except in cases where multiple links reference the same location.
+            Similarly, give every navigation region on a page a different name unless there are regions with identical content that performs identical navigation functions.
           
    • 
           
  • 
             Start names with a capital letter; it helps some screen readers speak them with appropriate inflection.
-            And, do nott end names with a period; they are not sentences.
+            Do not end names with a period; they are not sentences.
           
    •
    From 9f8aab40fb206b007769efd8291beb33443e3668 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Tue, 11 Jun 2019 16:48:33 +0200 Subject: [PATCH 059/131] Fallback names --- aria-practices.html | 26 +++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index c92b02d205..8ee8add2b4 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4031,6 +4031,7 @@
    Naming Fieldsets with the Legend Element
    Naming Tables and Figures with Captions
    +

    The accessible name for the HTML table and figure elements can be derived from a child caption or figcaption element, respectively.

    Tables and figures often have a caption to explain what the table of figure is about, how to read them, and sometimes giving them numbers to be able to refer to them in surrounding prose. This can help users navigate and understand the content better. This is generally useful for all users, but especially for users of assistive technologies.

    In HTML, the table element marks up a data table, and can be provided with a caption using the caption element.

    <table>
@@ -4064,10 +4065,25 @@ 
    Naming Tables and Figures with Captions
    
 
         
    
           
    Fallback Names Derived from Titles and Placeholders
    
-          
    To-do: finish writing this section. Needs to cover title, placeholder, and aria-placeholder.
    
-          
    
-            For the HTML input element, the placeholder attribute is used as a fallback labeling mechanism if nothing else results in a label. For an input element, it is better to use a label element, since it does not disappear visually when the user focuses the form control.
-          
    
+          
    When an accessible name is not provided using one of the primary techniques (e.g., the aria-label or aria-labelledby attributes), or native markup techniques (e.g., the HTML label element, or the alt attribute of the HTML img element), an accessible name can be derived from some other attributes as a fallback mechanism.
    
+
+          
    Any HTML element can have a title attribute specified. The title attribute is used as the element's fallback accessible name.
    
+
+          
    For example, a fieldset element without a legend element child, but with a title attribute, gets its accessible name from the title attribute.
    
+
+          
    <fieldset title="Select your starter class">
+    <label><input name="starter-class" value="green"> Green</label>
+    <label><input name="starter-class" value="red"> Red</label>
+    <label><input name="starter-class" value="blue"> Blue</label>
+   </fieldset>
    
+
+          
    For the HTML input and textarea elements, the placeholder attribute is used as a fallback labeling mechanism if nothing else (including the title attribute) results in a label. It is better to use a label element, since it does not disappear visually when the user focuses the form control.
    
+
+          
    <!-- Using a <label> is recommended -->
+<label>Search <input type=search name=q></label>
+
+<!-- A placeholder is used as fallback -->
+<input type=search name=q placeholder="Search">
    @@ -4740,7 +4756,7 @@
    Describing by referencing content with aria-details
    Specifying both is potentially useful if there is a need to provide a fallback description for browsers and assistive technologies that do not yet support aria-details.

    - +
    Describing Tables and Figures with Captions

    To-do: write this section. Include example of a table labeled by a heading via aria-labelledby so the caption becomes a description.

    From 9604f461668c0a97b6e24c4036e3940e08a4602b Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Tue, 11 Jun 2019 16:55:14 +0200 Subject: [PATCH 060/131] Mention that caption/figcaption satisfy rule 2 and 3 --- aria-practices.html | 2 ++ 1 file changed, 2 insertions(+) diff --git a/aria-practices.html b/aria-practices.html index 8ee8add2b4..1cab06c01a 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4061,6 +4061,8 @@
    Naming Tables and Figures with Captions
    <img alt="Painting of a person walking in a desert." src="Hole_JesusalDesierto.jpg"> <figcaption>Jesus entering the desert as imagined by William Hole, 1908</figcaption> </figure>     + +

    Using the caption element to name a table element, or a figcaption element to name a figure element, satisfies Rule 2: Prefer Visible Text and Rule 3: Prefer Native Techniques.

    From 5717568d176a8713cfb115cfbc685c6401169a51 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Tue, 11 Jun 2019 17:34:33 +0200 Subject: [PATCH 061/131] Add examples for aria-labelledby referencing a hidden element, and added spaces with aria-labelledby --- aria-practices.html | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 1cab06c01a..1b6c4b3f7a 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3920,10 +3920,14 @@
    Naming with Referenced Content Via aria-labelledby

    The aria-labelledby property is useful in a wide variety of situations because:

      -
    • It has the highest precedence when browsers calculate accessible names, i.e., it overrides names from child content and all other naming attributes, including aria-label.
      • -
    • It can concatenate content from multiple elements into a single name string.
      • -
    • It incorporates content from elements regardless of their visibility, i.e., it even includes content from elements with display:none or visibility:hidden in the calculated name string.
      • -
    • It incorporates the value of input elements, i.e., if it references a textbox, the value of the textbox is included in the calculated name string.
      • +

    • It has the highest precedence when browsers calculate accessible names, i.e., it overrides names from child content and all other naming attributes, including aria-label.

      • +

    • It can concatenate content from multiple elements into a single name string.

      • +
    • +

      It incorporates content from elements regardless of their visibility, i.e., it even includes content from elements with display:none or visibility:hidden in the calculated name string.

      + 
      <span id="night-mode-label" hidden>Night mode</span>
+  <input type="checkbox" role="switch" aria-labelledby="night-mode-label">
      +
      • +

    • It incorporates the value of input elements, i.e., if it references a textbox, the value of the textbox is included in the calculated name string.

    In some cases, the most effective name for an element is its own content combined with the content of another element. @@ -3940,9 +3944,12 @@

    Naming with Referenced Content Via aria-labelledby
    If an element is referenced more than one time, only the first reference is processed. When concatenating content from multiple elements, browsers trim leading and trailing white space and separate content from each element with a single space.

    -

    - To-do: add example to show reference to hidden elements and an input that demonstrates spacing between strings from referenced elements. -

    + 
    <section role="alert" aria-labelledby="alert-title alert-code">
+ <h2 id="alert-title">Alert</h2>
+ <p id="alert-code">code: red</p>
+ <p>We're out of peanuts.</p>
+</section>
    +

    In the above example, the accessible name of the alert will be "Alert code: red", with a space between "alert" and "code", and not "Alertcode: red".

    1. The aria-labelledby property cannot be chained, i.e., if an element with aria-labelledby references another element that also has aria-labelledby, the aria-labelledby attribute on the referenced element will be ignored.
    2. If an element is referenced by aria-labelledby more than one time during a name calculation, the second and any subsequent references will be ignored.
      3. From 06cc073b67908deb65b5fb9e0be252127febd471 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Wed, 12 Jun 2019 16:10:15 +0200 Subject: [PATCH 062/131] Replace img with input in Examples of non-recursive accessible name calculation --- aria-practices.html | 62 ++++++++++++++++++++++++++++++--------------- 1 file changed, 42 insertions(+), 20 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 1b6c4b3f7a..33b8a0ea4d 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4651,26 +4651,48 @@

      Accessible name calculation

      Examples of non-recursive accessible name calculation
      -

      To-do: replace this img example with input type text example.

      -

      Consider an img element that has only an src attribute and so does not have an accessible name (do not do this):

      - 
      <img src="photo.jpg">
      -

      If there is a title attribute, then it serves as a naming falback mechanism (avoid doing this):

      - 
      <img src="photo.jpg" title="The Queen, holding a pigeon.">
      - -

      If there is also an `alt` attribute (using `alt` for images is recommended), then that is used as the label, and the `title` attribute is instead used as the accessible description:

      - - 
      <img src="photo.jpg" alt="The Queen, holding a pigeon." title="Photo: Rex Features">
      - -

      If there is also an `aria-label` attribute, then that overrides the `alt` attribute:

      - - 
      <img src="photo.jpg" aria-label="The Queen, holding a pigeon." title="Photo: Rex Features"
-     alt="Sorry, this image failed to load.">
      - -

      If there is also an `aria-labelledby` attribute, that wins over the other attributes (the `aria-label` attribute ought to be removed if it is not used):

      - - 
      <img src="photo.jpg" aria-label="This is ignored." title="Photo: Established Depiction"
-     alt="Sorry, this image failed to load." aria-labelledby="the-queen">
-    <span id="the-queen">The Queen, holding a pigeon.</span>
      +

      Consider an input element that has no associated label element and only a name attribute and so does not have an accessible name (do not do this):

      + 
      <input name="code">
      +

      If there is a placeholder attribute, then it serves as a naming falback mechanism (avoid doing this):

      + + 
      <input name="code"
+       placeholder="One-time code">
      + +

      If there is also a title attribute, then it is used as the accessible name instead of placeholder, but it is still a fallback (avoid doing this):

      + + 
      <input name="code"
+       placeholder="123456"
+       title="One-time code">
      + +

      If there is also an label element (recommended), then that is used as the accessible name, and the title attribute is instead used as the accessible description:

      + + 
      <label>One-time code
+ <input name="code"
+        placeholder="123456"
+        title="Get your code from the app.">
+</label>
      + +

      If there is also an aria-label attribute, then that overrides the label element:

      + + 
      <label>Code
+ <input name="code"
+        aria-label="One-time code"
+        placeholder="123456"
+        title="Get your code from the app.">
+</label>
      + +

      If there is also an aria-labelledby attribute, that wins over the other elements and attributes (the aria-label attribute ought to be removed if it is not used):

      + + 
      <p>Please fill in your <span id="code-label">one-time code</span> to log in.</p>
+<p>
+ <label>Code
+  <input name="code"
+         aria-labelledby="code-label"
+         aria-label="This is ignored"
+         placeholder="123456"
+         title="Get your code from the app.">
+ </label>
+</p>
      From 03efdcce9be3215a762bfa13b7982fe0cb52dd94 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Wed, 12 Jun 2019 17:03:35 +0200 Subject: [PATCH 063/131] Expand on the accessible name calculation --- aria-practices.html | 57 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 52 insertions(+), 5 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 33b8a0ea4d..8ae5a191bd 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4633,11 +4633,58 @@

      Accessible name calculation

      To-do: Add a specific step for each HTML element and attribute in the following list so readers can see the precedence of any specific element or attribute.

        -
      1. The aria-labelledby property is used if present.
        2. -
      2. If the name is still empty, the aria-label property is used if present.
        3. -
      3. If the name is still empty, then host-language-specific attributes or elements (e.g., alt attribute on HTML img) are used if present.
        4. -
      4. If the name is still empty, then for elements with a role that supports naming from child content, the content of the element is used.
        5. -
      5. Finally, if the name is still empty, then other fallback host-language-specific tooltip attributes or elements (e.g., the title attribute in HTML) are used if present.
        6. +

      6. The aria-labelledby property is used if present.

        7. +

      7. If the name is still empty, the aria-label property is used if present.

        8. +
      8. +

        If the name is still empty, then host-language-specific attributes or elements are used if present. For HTML, these are, depending on the element:

        +
        +
        input whose type attribute is in the Button, Submit Button, or Reset Button state
        +
        The value attribute.
        + +
        input whose type attribute is in the Image Button state
        +
        img
        +
        The alt attribute.
        + +
        fieldset
        +
        The first child legend element.
        + +
        Other form elements (to-do: see html-aam issue 210)
        +
        The associated label element(s).
        + +
        figure
        +
        The first child figcaption element.
        + +
        table
        +
        The first child caption element.
        + +
        area
        +
        The alt attribute.
        +
        +
        9. +

      9. If the name is still empty, then for elements with a role that supports naming from child content, the content of the element is used.

        10. +
      10. +

        Finally, if the name is still empty, then other fallback host-language-specific attributes or elements are used if present. For HTML, these are, depending on the element:

        +
        +
        input whose type attribute is in the Text, Password, Search, Telephone, or URL states
        +
        textarea
        +
        The title attribute. Otherwise, the placeholder attribute.
        + +
        input whose type attribute is in the Submit Button state
        +
        A localized string of the word "submit".
        + +
        input whose type attribute is in the Reset Button state
        +
        A localized string of the word "reset".
        + +
        input whose type attribute is in the Image Button state
        +
        The title attribute. Otherwise, a localized string of the phrase "Submit Query". (To-do: see html-aam issue 211)
        + +
        summary
        +
        The word "Details". (To-do: see html-aam issue 212)
        + +
        Other elements
        +
        The title attribute.
        +
        +

      The final step is a fallback mechanism. Generally when labelling an element, use one of the non-fallback mechanisms. From ae90ce13f3d990299d37554cf5a5e397cf32944b Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Thu, 13 Jun 2019 16:05:27 +0200 Subject: [PATCH 064/131] Discourage the use of fallback naming techniques --- aria-practices.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 8ae5a191bd..73428a185e 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4074,9 +4074,9 @@

      Naming Tables and Figures with Captions
      Fallback Names Derived from Titles and Placeholders
      -

      When an accessible name is not provided using one of the primary techniques (e.g., the aria-label or aria-labelledby attributes), or native markup techniques (e.g., the HTML label element, or the alt attribute of the HTML img element), an accessible name can be derived from some other attributes as a fallback mechanism.

      +

      When an accessible name is not provided using one of the primary techniques (e.g., the aria-label or aria-labelledby attributes), or native markup techniques (e.g., the HTML label element, or the alt attribute of the HTML img element), an accessible name can be derived from some other attributes as a fallback mechanism. In general, prefer the explicit labeling techniques described above over fallback techniques described in this section.

      -

      Any HTML element can have a title attribute specified. The title attribute is used as the element's fallback accessible name.

      +

      Any HTML element can have a title attribute specified. The title attribute is used as the element's fallback accessible name. The title attribute is commonly presented visually as a tooltip when the user hovers over the element with a pointing device, which is not particularly discoverable, and is also not accessible to visual users without a pointing device.

      For example, a fieldset element without a legend element child, but with a title attribute, gets its accessible name from the title attribute.

      From 2cfd46e9d5df6952e4060344538d49fe27ce57c0 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Thu, 13 Jun 2019 16:14:30 +0200 Subject: [PATCH 065/131] Address some feedback --- aria-practices.html | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 73428a185e..432ed5f3c6 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4268,7 +4268,7 @@

      Accessible Name Guidance by Role
      • Naming is necessary when two complementary landmark regions are present on the same page.
        • -
      • naming is recommended even when one complementary region is present to help users understand the purpose of the region's content when navigating among landmark regions.
        • +
      • Naming is recommended even when one complementary region is present to help users understand the purpose of the region's content when navigating among landmark regions.
      • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
      @@ -4354,7 +4354,7 @@

      Accessible Name Guidance by Roleimg

    - + @@ -4388,7 +4388,7 @@

    Accessible Name Guidance by Role

    - + @@ -4436,7 +4436,7 @@

    Accessible Name Guidance by Role

    - + @@ -4550,7 +4550,7 @@

    Accessible Name Guidance by Role

    - + From df4bab3c262464c4e87d58885caae2e0d0c22a86 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Tue, 18 Jun 2019 16:59:02 +0200 Subject: [PATCH 066/131] Use a button instead of an alert in an example for aria-labelledby --- aria-practices.html | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 432ed5f3c6..c47ed540c9 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3944,12 +3944,9 @@
    Naming with Referenced Content Via aria-labelledby
    If an element is referenced more than one time, only the first reference is processed. When concatenating content from multiple elements, browsers trim leading and trailing white space and separate content from each element with a single space.

    - 
    <section role="alert" aria-labelledby="alert-title alert-code">
- <h2 id="alert-title">Alert</h2>
- <p id="alert-code">code: red</p>
- <p>We're out of peanuts.</p>
-</section>
    -

    In the above example, the accessible name of the alert will be "Alert code: red", with a space between "alert" and "code", and not "Alertcode: red".

    + 
    <button id="download-button" aria-labelledby="download-button download-details">Download</button>
+<span id="download-details">PDF, 2.4 MB</span>
    +

    In the above example, the accessible name of the alert will be "Download PDF, 2.4 MB", with a space between "Download" and "PDF", and not "DownloadPDF, 2.4 MB".

    1. The aria-labelledby property cannot be chained, i.e., if an element with aria-labelledby references another element that also has aria-labelledby, the aria-labelledby attribute on the referenced element will be ignored.
    2. If an element is referenced by aria-labelledby more than one time during a name calculation, the second and any subsequent references will be ignored.
      3. @@ -4631,7 +4628,6 @@

      Accessible name calculation

      The algorithm they follow is defined in the accessible name specification. It is roughly like the following:

      -

      To-do: Add a specific step for each HTML element and attribute in the following list so readers can see the precedence of any specific element or attribute.

      1. The aria-labelledby property is used if present.

      2. If the name is still empty, the aria-label property is used if present.

        3. From ac301c66cfd56a6c6fcb42067ed56a93e76f0bdb Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Tue, 18 Jun 2019 20:30:54 +0200 Subject: [PATCH 067/131] Write the accessible description algorithm --- aria-practices.html | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index c47ed540c9..f18f08740d 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4639,6 +4639,7 @@

        Accessible name calculation

        input whose type attribute is in the Image Button state
        img
        +
        area
        The alt attribute.
        fieldset
        @@ -4846,13 +4847,36 @@
        Fallback Descriptions Derived from Titles and Placeholders

        Accessible description calculation

        Like the accessible name calculation, the accessible description calculation produces a text string. - However, there is one exception: when an element is described using the aria-details/ property the assistive technology is provided with a reference. + However, there is one exception: when an element is described using the aria-details attribute the assistive technology is provided with a reference instead of constructing a flattened string.

        The accessible description calculation algorithm is the same as the accessible name calculation algorithm except for a few branch points that depend on whether a name or description is being calculated. In particular, when accumulating text for an accessible description, the algorithm uses aria-describedby instead of aria-labelledby.

        -

        To-do: Provide a step-by-step summary of the description calculation algorithm.

        +

        + When aria-details is not used, user agents construct an accessible description string for an element by walking through a list of potential description methods and using the first that generates a description. + The algorithm they follow is defined in the accessible name specification. + It is roughly like the following: +

        +
          +

        1. The aria-describedby property is used if present.

          2. +
        2. +

          If the description is still empty, then host-language-specific attributes or elements are used if present, if it wasn't already used as the accessible name. For HTML, these are, depending on the element:

          +
          +
          input whose type attribute is in the Button, Submit Button, or Reset Button state
          +
          The value attribute.
          + +
          summary
          +
          The element's subtree.
          + +
          table
          +
          The first child caption element.
          +
          +
          3. +
        3. +

          Finally, if the description is still empty, then other host-language-specific attributes or elements are used if present, if it wasn't already used for the accessible name. For HTML, this is the title attribute.

          +
          4. +
        From a1bd62f3ab098d6e2f4aff4c99f02aa6fc7918b0 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Tue, 18 Jun 2019 21:19:36 +0200 Subject: [PATCH 068/131] Describing Tables and Figures with Captions --- aria-practices.html | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index f18f08740d..c3e750bc36 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4834,8 +4834,33 @@
        Describing by referencing content with aria-details
        Describing Tables and Figures with Captions
        -

        To-do: write this section. Include example of a table labeled by a heading via aria-labelledby so the caption becomes a description.

        -
        +

        In HTML, a table element can get its accessible description from the child caption element, if that wasn't used as the accessible name.

        +

        For example, a preceding heading might be appropriate as an accessible name for a table, and the caption element can contain a longer description of the table and how the table is laid out. In such a situation, the aria-labelledby attribute can be used on the table to set the accessible name to that of the heading.

        + 
        <h2 id="events-heading">Upcoming events</h2>
+<table aria-labelledby="events-heading">
+ <caption>
+  Calendar of upcoming events, weeks 27 through 31, with each week starting with
+  Monday. The first column is the week number.
+ </caption>
+ <tr><th>Week<th>Monday<th>Tuesday<th>Wednesday<th>Thursday<th>Friday<Saturday<Sunday
+ <tr><td>27<td><td><td><td><td><td><td>
+ <tr><td>28<td><td><td><td><td><td><td><a href="/events/9856">Crown Princess's birthday</a>
+ <tr><td>29<td><td><td><td><td><td><td>
+ <tr><td>30<td><td><td><td><td><td><td>
+ <tr><td>31<td><td><td><td><td><td><td>
+</table>
        +

        The HTML figure element can get its accessible name from its figcaption element, but it will not be used as the accessible description, even if it was not used as the accessible name. If the figcaption element is appropriate as an accessible description, and the accessible name is set using aria-labelledby or aria-label, then the figcaption can be explicitly set as the accessible description using the aria-describedby attribute.

        + 
        <h2 id="neutron">Neutron</h2>
+<figure aria-labelledby="neutron" aria-describedby="neutron-caption">
+ <img src="neutron.svg" alt="Within the neutron are three quarks (blue 'u',
+ red 'd', green 'd') that are interconnected.">
+ <figcaption id="neutron-caption">
+  The quark content of the neutron. The color assignment of individual quarks is
+  arbitrary, but all three colors must be present. Forces between quarks are
+  mediated by gluons.
+ </figcaption>
+</figure>
        +
        Fallback Descriptions Derived from Titles and Placeholders
        From 1e56e16bab8b59b6fd18def1ab55ca1e0e29233e Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Tue, 18 Jun 2019 21:57:44 +0200 Subject: [PATCH 069/131] Descriptions Derived from Titles --- aria-practices.html | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index c3e750bc36..9d57f1a665 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3722,7 +3722,7 @@

        Providing Accessible Names and Descriptions

      3. Describing by referencing content with aria-describedby.
      4. Describing by referencing content with aria-details.
      5. Describing tables and figures with captions.
        6. -
      6. Fallback descriptions derived from titles and placeholders.
        7. +
      7. Descriptions derived from titles.
        8. @@ -4862,9 +4862,23 @@
        Describing Tables and Figures with Captions
        </figure>
        -
        -
        Fallback Descriptions Derived from Titles and Placeholders
        -

        To-do: write this section.

        +
        +
        Descriptions Derived from Titles
        +

        If the aria-details attribute is not used, and an accessible description was not provided using the aria-describedby attribute or one of the primary host-language-specific attributes or elements (e.g., the caption element for table), then, for HTML, if the element has a title attribute, that is used as the accessible description.

        +

        A visible description together with aria-describedby or aria-details is generally recommended. If a description that is not visible is desired, then the title attribute can be used, for any HTML element that can have an accessible description.

        +

        Note that the title attribute might not be accessible to some users, in particular sighted users not using a screen reader and not using a pointing device that supports hover (e.g., a mouse).

        +

        For example, an input element with input constrained using the pattern attribute can use the title attribute to describe what the expected input is.

        + 
        <label> Part number:
+ <input pattern="[0-9][A-Z]{3}" name="part"
+        title="A part number is a digit followed by three uppercase letters."/>
+</label>
        +

        The title attribute in this case can be shown to the user as a tooltip when the user hovers or focuses the control, but also as part of the error message when the user agent validates the form, if the input element's value doesn't match the pattern.

        +

        As another example, a link can use the title attribute to describe the link in more detail.

        + 
        <a href="http://twitter.com/W3C"
+   title="Follow W3C on Twitter">
+   <img src="/2008/site/images/Twitter_bird_logo_2012.svg"
+        alt="Twitter" class="social-icon" height="40" />
+  </a>
        From 26a4b1cb634f8ee8bf6edcb0783d916d0c7dd144 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Tue, 18 Jun 2019 22:35:55 +0200 Subject: [PATCH 070/131] Move to-dos that depend on resolution of other issues into github issues --- aria-practices.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 9d57f1a665..97403dcade 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4645,7 +4645,7 @@

        Accessible name calculation

        fieldset
        The first child legend element.
        -
        Other form elements (to-do: see html-aam issue 210)
        +
        Other form elements
        The associated label element(s).
        figure
        @@ -4673,10 +4673,10 @@

        Accessible name calculation

        A localized string of the word "reset".
        input whose type attribute is in the Image Button state
        -
        The title attribute. Otherwise, a localized string of the phrase "Submit Query". (To-do: see html-aam issue 211)
        +
        The title attribute. Otherwise, a localized string of the phrase "Submit Query".
        summary
        -
        The word "Details". (To-do: see html-aam issue 212)
        +
        The word "Details".
        Other elements
        The title attribute.
        From 7e9e68cf2451de2396dff274fa3b9ad0bc5ae739 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Thu, 20 Jun 2019 21:13:14 +0200 Subject: [PATCH 071/131] Remove the Content Can Name table column --- aria-practices.html | 846 ++++++++++++++++++++------------------------ 1 file changed, 388 insertions(+), 458 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 466f7df9b3..66cc39065f 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4160,464 +4160,394 @@

        Accessible Name Guidance by RoleProvides information to help determine if providing a name is beneficial, and if so, identifies any recommended techniques.

    roleProvide Name?Content Can NameGuidanceWhen to NameContent Can NameGuidance
    alert
    alertOptionalSometimes No To-do: can we think of a circumstance where naming an alert would serve a useful purpose? Are there any assistive technologies that would render the boundaries of an alert container or have a way to render the name?
    articleRecommendedUsually NoNamed using aria-labelledby if a visible title is present, otherwise with aria-label +
      +
    • Recommended to distinguish articles from one another; helps users when navigating among articles.
      • +
    • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
      • +
    +
    bannerOptionalSometimes NoNecessary in the uncommon circumstance where two banner landmark regions are present on the same page. It is otherwise optional. +
      +
    • Necessary in the uncommon circumstance where two banner landmark regions are present on the same page. It is otherwise optional.
      • +
    • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
      • +
    +
    button Always Yes +
      +
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • +
    • Ideally named by visible, descendant content.
      • +
    +
    cellnamerequiredAlways Yesguidance +
      +
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • +
    • Ideally named by visible, descendant content.
      • +
    • Note that associated row or column headers do not name a cell; a cell's name is its content. Headers are complementary information.
      • +
    +
    checkbox Always Yesguidance +
      +
    • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
      • +
    • If based on HTML type="checkbox", ideally named with a label element.
      • +
    • Otherwise, often named referencing visible content via aria-labelledby.
      • +
    +
    columnheader Always Yesguidance +
      +
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • +
    • Ideally named by visible, descendant content.
      • +
    +
    combobox
    complementaryOptionalUsually Noguidance +
      +
    • Naming is necessary when two complementary landmark regions are present on the same page.
      • +
    • naming is recommended even when one complementary region is present to help users understand the purpose of the region's content when navigating among landmark regions.
      • +
    • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
      • +
    +
    contentinfonamerequiredSometimes Noguidance +
      +
    • Necessary in the uncommon circumstance where two contentinfo landmark regions are present on the same page. It is otherwise optional.
      • +
    • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
      • +
    +
    definition
      -
    • Recommended to distinguish articles from one another; helps users when navigating among articles.
      • +
    • Recommended to distinguish articles from one another; helps users when navigating among articles.
    • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
    		 Always NoguidanceFor the HTML img element, use the alt attribute. For other elements with the img role, use aria-labelledby or aria-label.
    link
    mainnamerequiredSometimes No guidance
    navigationnamerequiredSometimes No guidance
    tabnamerequiredAlways Yes guidance
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    roleWhen to NameContent Can NameGuidance
    alertSometimesNoTo-do: can we think of a circumstance where naming an alert would serve a useful purpose? Are there any assistive technologies that would render the boundaries of an alert container or have a way to render the name?
    alertdialogAlwaysNoNamed using aria-labelledby if a visible title is present, otherwise with aria-label.
    applicationAlwaysNoNamed using aria-labelledby if a visible title is present, otherwise with aria-label.
    articleUsuallyNo -
      -
    • Recommended to distinguish articles from one another; helps users when navigating among articles.
      • -
    • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
      • -
    -
    bannerSometimesNo -
      -
    • Necessary in the uncommon circumstance where two banner landmark regions are present on the same page. It is otherwise optional.
      • -
    • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
      • -
    -
    buttonAlwaysYes -
      -
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • -
    • Ideally named by visible, descendant content.
      • -
    -
    cellAlwaysYes -
      -
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • -
    • Ideally named by visible, descendant content.
      • -
    • Note that associated row or column headers do not name a cell; a cell's name is its content. Headers are complementary information.
      • -
    -
    checkboxAlwaysYes -
      -
    • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
      • -
    • If based on HTML type="checkbox", ideally named with a label element.
      • -
    • Otherwise, often named referencing visible content via aria-labelledby.
      • -
    -
    columnheaderAlwaysYes -
      -
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • -
    • Ideally named by visible, descendant content.
      • -
    -
    comboboxAlwaysNoNamed using aria-labelledby if a visible title is present, otherwise with aria-label.
    complementaryUsuallyNo -
      -
    • Naming is necessary when two complementary landmark regions are present on the same page.
      • -
    • Naming is recommended even when one complementary region is present to help users understand the purpose of the region's content when navigating among landmark regions.
      • -
    • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
      • -
    -
    contentinfoSometimesNo -
      -
    • Necessary in the uncommon circumstance where two contentinfo landmark regions are present on the same page. It is otherwise optional.
      • -
    • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
      • -
    -
    definitionnamerequiredNoguidance
    dialogAlwaysNoguidance
    directorynamerequiredNoguidance
    documentnamerequiredNoguidance
    feednamerequiredNoguidance
    figurenamerequiredNoguidance
    formnamerequiredNoguidance
    gridAlwaysNoguidance
    gridcellAlwaysYesguidance
    groupnamerequiredNoguidance
    headingAlwaysYesguidance
    imgAlwaysNoFor the HTML img element, use the alt attribute. For other elements with the img role, use aria-labelledby or aria-label.
    linkAlwaysYesguidance
    listnamerequiredNoguidance
    listboxAlwaysNoguidance
    listitemnamerequiredNoguidance
    logAlwaysNoguidance
    mainSometimesNoguidance
    marqueeAlwaysNoguidance
    mathnamerequiredNoguidance
    menunamerequiredNoguidance
    menubarnamerequiredNoguidance
    menuitemAlwaysYesguidance
    menuitemcheckboxAlwaysYesguidance
    menuitemradioAlwaysYesguidance
    navigationSometimesNoguidance
    none, presentationNeverNo
    notenamerequiredNoguidance
    optionAlwaysYesguidance
    progressbarAlwaysNoguidance
    radioAlwaysYesguidance
    radiogroupAlwaysNoguidance
    regionAlwaysNoguidance
    rownamerequiredYesguidance
    rowgroupnamerequiredYesguidance
    rowheaderAlwaysYesguidance
    scrollbarAlwaysNoguidance
    searchnamerequiredNoguidance
    searchboxAlwaysNoguidance
    separatornamerequiredNoguidance
    sliderAlwaysNoguidance
    spinbuttonAlwaysNoguidance
    statusnamerequiredNoguidance
    switchAlwaysYesguidance
    tabAlwaysYesguidance
    tableAlwaysNoguidance
    tablistnamerequiredNoguidance
    tabpanelAlwaysNoguidance
    termnamerequiredNoguidance
    textboxAlwaysNoguidance
    timerAlwaysNoguidance
    toolbarnamerequiredNoguidance
    tooltipAlwaysYesguidance
    treeAlwaysYesguidance
    treegridAlwaysNoguidance
    treeitemAlwaysYesguidance
    roleWhen to NameGuidance
    alertSometimesTo-do: can we think of a circumstance where naming an alert would serve a useful purpose? Are there any assistive technologies that would render the boundaries of an alert container or have a way to render the name?
    alertdialogAlwaysNamed using aria-labelledby if a visible title is present, otherwise with aria-label.
    applicationAlwaysNamed using aria-labelledby if a visible title is present, otherwise with aria-label.
    articleUsually +
      +
    • Recommended to distinguish articles from one another; helps users when navigating among articles.
      • +
    • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
      • +
    +
    bannerSometimes +
      +
    • Necessary in the uncommon circumstance where two banner landmark regions are present on the same page. It is otherwise optional.
      • +
    • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
      • +
    +
    buttonAlways +
      +
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • +
    • Ideally named by visible, descendant content.
      • +
    +
    cellAlways +
      +
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • +
    • Ideally named by visible, descendant content.
      • +
    • Note that associated row or column headers do not name a cell; a cell's name is its content. Headers are complementary information.
      • +
    +
    checkboxAlways +
      +
    • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
      • +
    • If based on HTML type="checkbox", ideally named with a label element.
      • +
    • Otherwise, often named referencing visible content via aria-labelledby.
      • +
    +
    columnheaderAlways +
      +
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • +
    • Ideally named by visible, descendant content.
      • +
    +
    comboboxAlwaysNamed using aria-labelledby if a visible title is present, otherwise with aria-label.
    complementaryUsually +
      +
    • Naming is necessary when two complementary landmark regions are present on the same page.
      • +
    • Naming is recommended even when one complementary region is present to help users understand the purpose of the region's content when navigating among landmark regions.
      • +
    • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
      • +
    +
    contentinfoSometimes +
      +
    • Necessary in the uncommon circumstance where two contentinfo landmark regions are present on the same page. It is otherwise optional.
      • +
    • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
      • +
    +
    definitionnamerequiredguidance
    dialogAlwaysguidance
    directorynamerequiredguidance
    documentnamerequiredguidance
    feednamerequiredguidance
    figurenamerequiredguidance
    formnamerequiredguidance
    gridAlwaysguidance
    gridcellAlwaysguidance
    groupnamerequiredguidance
    headingAlwaysguidance
    imgAlwaysFor the HTML img element, use the alt attribute. For other elements with the img role, use aria-labelledby or aria-label.
    linkAlwaysguidance
    listnamerequiredguidance
    listboxAlwaysguidance
    listitemnamerequiredguidance
    logAlwaysguidance
    mainSometimesguidance
    marqueeAlwaysguidance
    mathnamerequiredguidance
    menunamerequiredguidance
    menubarnamerequiredguidance
    menuitemAlwaysguidance
    menuitemcheckboxAlwaysguidance
    menuitemradioAlwaysguidance
    navigationSometimesguidance
    none, presentationNever
    notenamerequiredguidance
    optionAlwaysguidance
    progressbarAlwaysguidance
    radioAlwaysguidance
    radiogroupAlwaysguidance
    regionAlwaysguidance
    rownamerequiredguidance
    rowgroupnamerequiredguidance
    rowheaderAlwaysguidance
    scrollbarAlwaysguidance
    searchnamerequiredguidance
    searchboxAlwaysguidance
    separatornamerequiredguidance
    sliderAlwaysguidance
    spinbuttonAlwaysguidance
    statusnamerequiredguidance
    switchAlwaysguidance
    tabAlwaysguidance
    tableAlwaysguidance
    tablistnamerequiredguidance
    tabpanelAlwaysguidance
    termnamerequiredguidance
    textboxAlwaysguidance
    timerAlwaysguidance
    toolbarnamerequiredguidance
    tooltipAlwaysguidance
    treeAlwaysguidance
    treegridAlwaysguidance
    treeitemAlwaysguidance
    From 66a46fcad70858226e779ad2dd4298255745b042 Mon Sep 17 00:00:00 2001 From: Matt King Date: Sun, 23 Jun 2019 23:31:57 -0700 Subject: [PATCH 072/131] More editorial revisions to naming guidance table --- aria-practices.html | 285 +++++++++++++++++++++++++++----------------- 1 file changed, 175 insertions(+), 110 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 66cc39065f..d2118e89ae 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4142,57 +4142,65 @@

    Accessible Name Guidance by Role
    -
    When to Name:
    +
    Necessaty of Naming
    - This column contains Always, Usually, Sometimes, or Never. - If the value is Always, the ARIA specification requires authors to provide a name, and a missing name will trigger accessibility validators to flag a violation. - If the value is Usually, providing a name is strongly recommended. - If the value is Sometimes, naming is optional and may even be discouraged; the guidance column may provide additional explanation. - And, if the value is Never, naming is strongly discouraged even if it is technically permitted. This generally means that assistive technologies are unlikely to present a name even if provided. + Indicates how necessary it is for authors to add a naming attribute or element to supplement or override the content of an element with the specified role. + This column may include one of the following values: +
      +
    • + Required ONLY IF Content Insufficient: An element with this role is named by its descendant content. + If aria-label or aria-labelledby is applied, content contained in the element and its descendants is hidden from assistive technology users unless it is also referenced by aria-labelledby. + Avoid hiding descendant content except in the rare circumstances where doing so benefits assistive technology users. +
      • +
    • Required: The ARIA specification requires authors to provide a name; a missing name triggers accessibility validators to flag a violation.
      • +
    • Recommended: Providing a name is strongly recommended.
      • +
    • Discretionary: Naming is either optional or, in the circumstances described in the guidance column, is discouraged.
      • +
    • DO NOT NAME:< Naming is strongly discouraged even if it is technically permitted; often assistive technologies do not render a name even if provided.
      • +
    -
    Content Can Name
    +
    Guidance:
    - This column contains Yes or No. - If the value is Yes, browsers will calculate a name for elements with that role from the text of all descendant content unless aria-label or aria-labelledby is used to override the content. - It is strongly recommended to avoid using aria-label or aria-labelledby on elements having one of the roles where this column contains Yes except in rare circumstances where hiding descendant content of the element from assistive technology users is beneficial. + Provides information to help determine if providing a name is beneficial, and if so, describes any recommended techniques.
    -
    Guidance:
    -
    Provides information to help determine if providing a name is beneficial, and if so, identifies any recommended techniques.
    - + - - + + - - + + - - + + - + - + - + - + - + - + - - + + - + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + - + - + - - + + @@ -4410,33 +4462,46 @@

    Accessible Name Guidance by Role

    - + + + + + + - + - + - + - + - - + + @@ -4445,12 +4510,12 @@

    Accessible Name Guidance by Role

    - - + + - + @@ -4460,7 +4525,7 @@

    Accessible Name Guidance by Role

    - + @@ -4470,12 +4535,12 @@

    Accessible Name Guidance by Role

    - + - + @@ -4485,17 +4550,17 @@

    Accessible Name Guidance by Role

    - - + + - - + + - + @@ -4505,7 +4570,7 @@

    Accessible Name Guidance by Role

    - + @@ -4515,12 +4580,12 @@

    Accessible Name Guidance by Role

    - + - + @@ -4530,23 +4595,23 @@

    Accessible Name Guidance by Role

    - - + + - + - + - - + +
    roleWhen to NameNecessaty of Naming Guidance
    alertSometimesTo-do: can we think of a circumstance where naming an alert would serve a useful purpose? Are there any assistive technologies that would render the boundaries of an alert container or have a way to render the name?Discretionary + Some screen readers announce the name of an alert before announcing the content of the alert. + Thus, aria-label provides a method for prefacing the visible content of an alert with text that is not displayed as part of the alert. + Using aria-label is functionally equivalent to providing off-screen text in the contents of the alert, except off-screen text would be announced by screen readers that do not support aria-label on alert elements. +
    alertdialogAlwaysNamed using aria-labelledby if a visible title is present, otherwise with aria-label.RequiredUse aria-labelledby if a visible title is present, otherwise use aria-label.
    applicationAlwaysNamed using aria-labelledby if a visible title is present, otherwise with aria-label.RequiredUse aria-labelledby if a visible title is present, otherwise use aria-label.
    articleUsuallyRecommended
    • Recommended to distinguish articles from one another; helps users when navigating among articles.
      • -
    • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
      • +
    • Use aria-labelledby if a visible title is present, otherwise use aria-label.
    bannerSometimesDiscretionary
    • Necessary in the uncommon circumstance where two banner landmark regions are present on the same page. It is otherwise optional.
      • @@ -4202,7 +4210,7 @@

      Accessible Name Guidance by Role

    buttonAlwaysRequired ONLY IF Content Insufficient
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • @@ -4212,7 +4220,7 @@

      Accessible Name Guidance by Role

    cellAlwaysRequired ONLY IF Content Insufficient
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • @@ -4223,44 +4231,51 @@

      Accessible Name Guidance by Role

    checkboxAlwaysRequired ONLY IF Content Insufficient
    • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
      • -
    • If based on HTML type="checkbox", ideally named with a label element.
      • -
    • Otherwise, often named referencing visible content via aria-labelledby.
      • +
    • If based on HTML type="checkbox", use a label element.
      • +
    • Otherwise, reference visible content via aria-labelledby.
    columnheaderAlwaysRequired ONLY IF Content Insufficient
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
    • Ideally named by visible, descendant content.
      • +
    • If the columnheader role is implied from an HTML th, the HTML abbr attribute can be used to specify an abbreviated version of the name that is only announced when screen readers are reading an associated cell within the table, grid, or treegrid.
    comboboxAlwaysNamed using aria-labelledby if a visible title is present, otherwise with aria-label.Required +
      +
    • If the combobox role is applied to an HTML input, may be named with an HTML label element.
      • +
    • Otherwise use aria-labelledby if a visible title is present.
      • +
    • Use aria-label if a visible label is not present.
      • +
    +
    complementaryUsuallyRecommended
    • Naming is necessary when two complementary landmark regions are present on the same page.
    • Naming is recommended even when one complementary region is present to help users understand the purpose of the region's content when navigating among landmark regions.
      • -
    • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
      • +
    • Use aria-labelledby if a visible title is present, otherwise use aria-label.
    contentinfoSometimesDiscretionary
    • Necessary in the uncommon circumstance where two contentinfo landmark regions are present on the same page. It is otherwise optional.
      • @@ -4270,137 +4285,174 @@

      Accessible Name Guidance by Role

    definitionnamerequiredguidanceTo-do: look up requirementTo-do: write guidance
    dialogAlwaysguidanceRequiredTo-do: similar to alertdialog
    directorynamerequiredguidanceDiscretionaryTo-do: probably similar to complementary
    documentnamerequiredguidanceDiscretionaryTo-do: write guidance; techniques similar to complementary.
    feednamerequiredguidanceRecommendedTo-do: similar to navigation
    figurenamerequiredguidanceTo-do: lookup requirementTo-do: write guidance
    formnamerequiredguidanceRecommendedTo-do: write guidance, probably similar to navigation
    gridAlwaysguidanceRequiredTo-do: write guidance similar to combobox except instead of label, uses caption if made from an HTML table. Include note that caption becomes a description if aria-label or aria-labelledby are used.
    gridcellAlwaysguidanceRequired ONLY IF Content InsufficientTo-do: write guidance similar to cell
    groupnamerequiredguidanceTo-do: lookup requirementTo-do: write guidance
    headingAlwaysguidanceRequired ONLY IF Content Insufficient +
      +
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • +
    • Ideally named by visible, descendant content.
      • +
    +
    imgAlwaysRequired For the HTML img element, use the alt attribute. For other elements with the img role, use aria-labelledby or aria-label.
    linkAlwaysguidanceRequired ONLY IF Content Insufficient +
      +
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • +
    • Ideally named by visible, descendant content.
      • +
    +
    listnamerequiredguidanceDiscretionary +
      +
    • Potentially beneficial for users of screen readers that support both list names and navigation among lists on a page.
      • +
    • Potentially a source of distracting or undesirable screen reader verbosity, especially if nested within a named container, such as a navigation region.
      • +
    • Can be named using aria-labelledby if a visible title is present, otherwise with aria-label.
      • +
    +
    listboxAlwaysguidanceRequiredTo-do: write guidance similar to combobox except that HTML select replaces input
    listitemnamerequiredguidanceDo Not NameNot supported by assistive technologies; it is necessary to include all relevant content within the list item.
    logAlwaysguidanceRequiredUse aria-labelledby if a visible title is present, otherwise use aria-label.
    mainSometimesguidanceDiscretionary +
      +
    • Potentially helpful for orienting assistive technology users, especially in single-page applications where main content changes happen without generating a page load event.
      • +
    • Can be named using aria-labelledby if a visible title is present, otherwise with aria-label.
      • +
    +
    marqueeAlwaysguidanceRequiredUse aria-labelledby if a visible title is present, otherwise use aria-label.
    mathnamerequiredguidanceRecommendedTo-do: write guidance; probably similar to complementary
    menunamerequiredguidanceDiscretionary +
      +
    • Recommended to distinguish articles from one another; helps users when navigating among articles.
      • +
    • Use aria-labelledby if a visible title is present, otherwise use aria-label.
      • +
    +
    menubarnamerequiredguidanceRecommended +
      +
    • + Helps screen reader users understand the context and purpose of menuitem elements in a menubar. + Naming a menubar is comparable to naming a menu button. + The name of a button that opens a menu conveys the purpose of the menu it opens. + Since a menubar element is displayed persistently, a name on the menubar can serve that same purpose. +
      • +
    • Use aria-labelledby if a visible title is present, otherwise use aria-label.
      • +
    +
    menuitemAlwaysguidanceRequired ONLY IF Content Insufficient +
    menuitemcheckboxAlwaysRequired ONLY IF Content Insufficient guidance
    menuitemradioAlwaysRequired ONLY IF Content Insufficient guidance
    navigationSometimesRecommended guidance
    none, presentationNevernoneDo Not Name
    optionAlwaysRequired ONLY IF Content Insufficient guidance
    presentationDo Not NameTo-do: same as none
    progressbarAlwaysRequired guidance
    radioAlwaysRequired ONLY IF Content Insufficient guidance
    radiogroupAlwaysRequired guidance
    regionAlwaysRequired guidance
    rownamerequiredguidance + Required ONLY IF Content Insufficient + AND descendant of a treegrid + AND the row is focusable. + + When row elements are focusable in a treegrid, screen readers announce the entire contents of a row when navigating by row. + This is typically the most appropriate behavior. + However, in some circumstances, it could be beneficial to change the order in which cells are announced or exclude announcement of certain cells by using aria-labelledby to specify which cells to announce. +
    rowgroup
    rowheaderAlwaysguidanceRequired ONLY IF Content InsufficientTo-do: similar to columnheader
    scrollbarAlwaysRequired guidance
    searchboxAlwaysRequired guidance
    sliderAlwaysRequired guidance
    spinbuttonAlwaysRequired guidance
    switchAlwaysguidanceRequired ONLY IF Content InsufficientTo-do: similar to checkbox
    tabAlwaysguidanceRequired ONLY IF Content InsufficientTo-do: similar to button
    tableAlwaysRequired guidance
    tabpanelAlwaysRequired guidance
    textboxAlwaysRequired guidance
    timerAlwaysRequired guidance
    tooltipAlwaysguidanceRequired ONLY IF Content InsufficientTo-do: similar to alert
    treeAlwaysRequired guidance
    treegridAlwaysRequired guidance
    treeitemAlwaysguidanceRequired ONLY IF Content InsufficientTo-do: similar to menuitem

    From 1097ac6b502805c191a336369e53696f8895017b Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 15:19:18 +0200 Subject: [PATCH 073/131] Combobox role can be used on HTML select and input --- aria-practices.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index d2118e89ae..90c49efc0e 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4247,7 +4247,7 @@

    Accessible Name Guidance by Role
  • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
  • Ideally named by visible, descendant content.
    • -
  • If the columnheader role is implied from an HTML th, the HTML abbr attribute can be used to specify an abbreviated version of the name that is only announced when screen readers are reading an associated cell within the table, grid, or treegrid.
    • +
  • If the columnheader role is implied from an HTML th, the HTML abbr attribute can be used to specify an abbreviated version of the name that is only announced when screen readers are reading an associated cell within the table, grid, or treegrid.

@@ -4256,7 +4256,7 @@

Accessible Name Guidance by RoleRequired
    -
  • If the combobox role is applied to an HTML input, may be named with an HTML label element.
    • +
  • If the combobox role is applied to an HTML select or input element, can be named with an HTML label element.
  • Otherwise use aria-labelledby if a visible title is present.
  • Use aria-label if a visible label is not present.
@@ -4499,7 +4499,7 @@

Accessible Name Guidance by Role When row elements are focusable in a treegrid, screen readers announce the entire contents of a row when navigating by row. - This is typically the most appropriate behavior. + This is typically the most appropriate behavior. However, in some circumstances, it could be beneficial to change the order in which cells are announced or exclude announcement of certain cells by using aria-labelledby to specify which cells to announce. From 47f75cae7c85d05ed71cd66e98f57301fd74bfbd Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 15:23:21 +0200 Subject: [PATCH 074/131] Avoid all-caps --- aria-practices.html | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 90c49efc0e..db5f981e6b 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4148,14 +4148,14 @@

Accessible Name Guidance by Role
  • - Required ONLY IF Content Insufficient: An element with this role is named by its descendant content. + Required Only If Content Insufficient: An element with this role is named by its descendant content. If aria-label or aria-labelledby is applied, content contained in the element and its descendants is hidden from assistive technology users unless it is also referenced by aria-labelledby. Avoid hiding descendant content except in the rare circumstances where doing so benefits assistive technology users.
  • Required: The ARIA specification requires authors to provide a name; a missing name triggers accessibility validators to flag a violation.
  • Recommended: Providing a name is strongly recommended.
  • Discretionary: Naming is either optional or, in the circumstances described in the guidance column, is discouraged.
    • -
  • DO NOT NAME:< Naming is strongly discouraged even if it is technically permitted; often assistive technologies do not render a name even if provided.
    • +
  • Do Not Name: Naming is strongly discouraged even if it is technically permitted; often assistive technologies do not render a name even if provided.
    • Guidance:
    @@ -4210,7 +4210,7 @@

    Accessible Name Guidance by Role button - Required ONLY IF Content Insufficient + Required Only If Content Insufficient
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • @@ -4220,7 +4220,7 @@

      Accessible Name Guidance by Role cell - Required ONLY IF Content Insufficient + Required Only If Content Insufficient
      • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
        • @@ -4231,7 +4231,7 @@

        Accessible Name Guidance by Role checkbox - Required ONLY IF Content Insufficient + Required Only If Content Insufficient
        • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
          • @@ -4242,7 +4242,7 @@

          Accessible Name Guidance by Role columnheader - Required ONLY IF Content Insufficient + Required Only If Content Insufficient
          • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
            • @@ -4325,7 +4325,7 @@

            Accessible Name Guidance by Role gridcell - Required ONLY IF Content Insufficient + Required Only If Content Insufficient To-do: write guidance similar to cell @@ -4335,7 +4335,7 @@

            Accessible Name Guidance by Role heading - Required ONLY IF Content Insufficient + Required Only If Content Insufficient
            • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
              • @@ -4350,7 +4350,7 @@

              Accessible Name Guidance by Role link - Required ONLY IF Content Insufficient + Required Only If Content Insufficient
              • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
                • @@ -4431,18 +4431,18 @@

                Accessible Name Guidance by Role menuitem - Required ONLY IF Content Insufficient + Required Only If Content Insufficient menuitemcheckbox - Required ONLY IF Content Insufficient + Required Only If Content Insufficient guidance menuitemradio - Required ONLY IF Content Insufficient + Required Only If Content Insufficient guidance @@ -4462,7 +4462,7 @@

                Accessible Name Guidance by Role option - Required ONLY IF Content Insufficient + Required Only If Content Insufficient guidance @@ -4477,7 +4477,7 @@

                Accessible Name Guidance by Role radio - Required ONLY IF Content Insufficient + Required Only If Content Insufficient guidance @@ -4493,7 +4493,7 @@

                Accessible Name Guidance by Role row - Required ONLY IF Content Insufficient + Required Only If Content Insufficient AND descendant of a treegrid AND the row is focusable. @@ -4510,7 +4510,7 @@

                Accessible Name Guidance by Role rowheader - Required ONLY IF Content Insufficient + Required Only If Content Insufficient To-do: similar to columnheader @@ -4550,12 +4550,12 @@

                Accessible Name Guidance by Role switch - Required ONLY IF Content Insufficient + Required Only If Content Insufficient To-do: similar to checkbox tab - Required ONLY IF Content Insufficient + Required Only If Content Insufficient To-do: similar to button @@ -4595,7 +4595,7 @@

                Accessible Name Guidance by Role tooltip - Required ONLY IF Content Insufficient + Required Only If Content Insufficient To-do: similar to alert @@ -4610,7 +4610,7 @@

                Accessible Name Guidance by Role treeitem - Required ONLY IF Content Insufficient + Required Only If Content Insufficient To-do: similar to menuitem From 063a6314ed27ced4a9b5aad4e135faf812002bdc Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 15:41:30 +0200 Subject: [PATCH 075/131] Recommendations for definition and term roles --- aria-practices.html | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index db5f981e6b..6b19e3af1f 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4285,8 +4285,8 @@

                Accessible Name Guidance by Role definition - To-do: look up requirement - To-do: write guidance + Recommended + Reference the term being defined with role="term", using aria-labelledby. dialog @@ -4575,8 +4575,8 @@

                Accessible Name Guidance by Role term - namerequired - guidance + Do Not Name + Since a term is usually the name for the role="definition" element, it could be confusing if the term itself also has a name. textbox From 261a26140571bee363ec6162390d4f20edb5d52e Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 16:20:53 +0200 Subject: [PATCH 076/131] Recommendation for document role --- aria-practices.html | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 6b19e3af1f..e16f656c37 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4291,17 +4291,22 @@

                Accessible Name Guidance by Role dialog Required - To-do: similar to alertdialog + Use aria-labelledby if a visible title is present, otherwise use aria-label. directory Discretionary - To-do: probably similar to complementary + +
                  +
                • Naming can help users understand the purpose of the directory.
                  • +
                • Use aria-labelledby if a visible title is present, otherwise use aria-label.
                  • +
                + document - Discretionary - To-do: write guidance; techniques similar to complementary. + Do Not Name + The document role is used to hint to the assistive technology to switch back to "reading mode" within an application or widget. That element should have a name. feed From 3e406d270be2994f1d307b34f0e2fffb9a6518c4 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 16:41:49 +0200 Subject: [PATCH 077/131] Recommendations for feed, form, navigation --- aria-practices.html | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index e16f656c37..0574a2c7da 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4311,7 +4311,11 @@

                Accessible Name Guidance by Role feed Recommended - To-do: similar to navigation +
                  +
                • Helps screen reader users understand the context and purpose of the feed.
                  • +
                • Use aria-labelledby if a visible title is present, otherwise use aria-label.
                  • +
                • See the Feed Design Pattern.
                  • +
                figure @@ -4321,7 +4325,11 @@

                Accessible Name Guidance by Role form Recommended - To-do: write guidance, probably similar to navigation +
                  +
                • Helps screen reader users understand the context and purpose of the form landmark.
                  • +
                • Use aria-labelledby if a visible title is present, otherwise use aria-label.
                  • +
                • See the Form Design Pattern.
                  • +
                grid @@ -4453,7 +4461,13 @@

                Accessible Name Guidance by Role navigation Recommended - guidance + +
                  +
                • Helps screen reader users understand the context and purpose of the navigation landmark.
                  • +
                • Use aria-labelledby if a visible title is present, otherwise use aria-label.
                  • +
                • See the Navigation Design Pattern.
                  • +
                + none From b87ad08e646ce9918d75d02bb173737d4af1b19d Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 16:48:25 +0200 Subject: [PATCH 078/131] Fix markup errors --- aria-practices.html | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/aria-practices.html b/aria-practices.html index 0574a2c7da..703169196f 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4311,11 +4311,13 @@

                Accessible Name Guidance by Role feed Recommended +
                • Helps screen reader users understand the context and purpose of the feed.
                • Use aria-labelledby if a visible title is present, otherwise use aria-label.
                • See the Feed Design Pattern.
                + figure @@ -4325,11 +4327,13 @@

                Accessible Name Guidance by Role form Recommended +
                • Helps screen reader users understand the context and purpose of the form landmark.
                • Use aria-labelledby if a visible title is present, otherwise use aria-label.
                • See the Form Design Pattern.
                + grid From 3d1f8d34e068a19c51c83a84a97961a22c81f30c Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 19:02:03 +0200 Subject: [PATCH 079/131] Fix markup typo --- aria-practices.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aria-practices.html b/aria-practices.html index 703169196f..de4eeb53a7 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4174,7 +4174,7 @@

                Accessible Name Guidance by RoleDiscretionary Some screen readers announce the name of an alert before announcing the content of the alert. - Thus, aria-label provides a method for prefacing the visible content of an alert with text that is not displayed as part of the alert. + Thus, aria-label provides a method for prefacing the visible content of an alert with text that is not displayed as part of the alert. Using aria-label is functionally equivalent to providing off-screen text in the contents of the alert, except off-screen text would be announced by screen readers that do not support aria-label on alert elements. From cd014005ea59c37a713efb0321135adf495b608a Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 19:15:18 +0200 Subject: [PATCH 080/131] Recommendation for figure --- aria-practices.html | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index de4eeb53a7..1ce8a02235 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4321,8 +4321,14 @@

                Accessible Name Guidance by Role figure - To-do: lookup requirement - To-do: write guidance + Recommended + +
                  +
                • For HTML, use the figure and figcaption elements. The figcaption will serve as the accessible name for the figure. See the Naming Tables and Figures with Captions section.
                  • +
                • When not using HTML, or when retrofitting legacy HTML, use the aria-labelledby on the figure, pointing to the figure's caption.
                  • +
                • If there is no visible caption, aria-label can be used.
                  • +
                + form From 73df64ec59e6ca5440bb116b808b4a7359481e10 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 19:23:06 +0200 Subject: [PATCH 081/131] Fix a ReSpec link error --- aria-practices.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aria-practices.html b/aria-practices.html index 1ce8a02235..0beee6246f 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4480,7 +4480,7 @@

                Accessible Name Guidance by Role - none + none Do Not Name From dab37063d3a44235bd3b090adc0f9493f35dd7df Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 19:26:56 +0200 Subject: [PATCH 082/131] Recommendation for none/presentation --- aria-practices.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 0beee6246f..7de3b70c5c 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4482,7 +4482,7 @@

                Accessible Name Guidance by Role none Do Not Name - + An element with role="none" is not part of the accessibility tree (except in error cases). Do not use aria-labelledby or aria-label. note @@ -4497,7 +4497,7 @@

                Accessible Name Guidance by Role presentation Do Not Name - To-do: same as none + An element with role="presentation" is not part of the accessibility tree (except in error cases). Do not use aria-labelledby or aria-label. progressbar From 6bf004fe9ab303b148fa5daaefea39a6217064b6 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 19:28:45 +0200 Subject: [PATCH 083/131] Recommendation for rowheader --- aria-practices.html | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/aria-practices.html b/aria-practices.html index 7de3b70c5c..8d19951d0a 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4540,7 +4540,13 @@

                Accessible Name Guidance by Role rowheader Required Only If Content Insufficient - To-do: similar to columnheader + +
                  +
                • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
                  • +
                • Ideally named by visible, descendant content.
                  • +
                • If the rowheader role is implied from an HTML th, the HTML abbr attribute can be used to specify an abbreviated version of the name that is only announced when screen readers are reading an associated cell within the table, grid, or treegrid.
                  • +
                + scrollbar From 014d0d836390945465b1e0065019840d046d526f Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 19:39:11 +0200 Subject: [PATCH 084/131] Recommendation for menuitemcheckbox, menuitemradio, radio, switch --- aria-practices.html | 32 ++++++++++++++++++++++++++++---- 1 file changed, 28 insertions(+), 4 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 8d19951d0a..bdabe626cf 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4461,12 +4461,24 @@

                Accessible Name Guidance by Role menuitemcheckbox Required Only If Content Insufficient - guidance + +
                  +
                • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
                  • +
                • Use the element's contents as the accessible name if possible. Otherwise, use aria-labelledby.
                  • +
                • See the Menu or Menu bar Design Pattern.
                  • +
                + menuitemradio Required Only If Content Insufficient - guidance + +
                  +
                • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
                  • +
                • Use the element's contents as the accessible name if possible. Otherwise, use aria-labelledby.
                  • +
                • See the Menu or Menu bar Design Pattern.
                  • +
                + navigation @@ -4507,7 +4519,13 @@

                Accessible Name Guidance by Role radio Required Only If Content Insufficient - guidance + +
                  +
                • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
                  • +
                • If based on HTML type="checkbox", use a label element.
                  • +
                • Otherwise, reference visible content via aria-labelledby.
                  • +
                + radiogroup @@ -4586,7 +4604,13 @@

                Accessible Name Guidance by Role switch Required Only If Content Insufficient - To-do: similar to checkbox + +
                  +
                • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
                  • +
                • If based on HTML type="checkbox", use a label element.
                  • +
                • Otherwise, reference visible content via aria-labelledby.
                  • +
                + tab From 1a25bf3f6ed56256148eca1526b51fb9efc67bf9 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 19:46:13 +0200 Subject: [PATCH 085/131] Recommendation for tab; use consistent wording for menuitemcheckbox, menuitemradio --- aria-practices.html | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index bdabe626cf..9ef89e7f61 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4464,7 +4464,7 @@

                Accessible Name Guidance by Role
                • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
                  • -
                • Use the element's contents as the accessible name if possible. Otherwise, use aria-labelledby.
                  • +
                • Ideally named by visible, descendant content.
                • See the Menu or Menu bar Design Pattern.
                @@ -4475,7 +4475,7 @@

                Accessible Name Guidance by Role
                • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
                  • -
                • Use the element's contents as the accessible name if possible. Otherwise, use aria-labelledby.
                  • +
                • Ideally named by visible, descendant content.
                • See the Menu or Menu bar Design Pattern.
                @@ -4615,7 +4615,12 @@

                Accessible Name Guidance by Role tab Required Only If Content Insufficient - To-do: similar to button + +
                  +
                • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
                  • +
                • Ideally named by visible, descendant content.
                  • +
                + table From 6b0984b5d1e993e85e45777330e693b099d1648f Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 19:49:28 +0200 Subject: [PATCH 086/131] Recommendation for tooltip (copied button, NOT alert) --- aria-practices.html | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/aria-practices.html b/aria-practices.html index 9ef89e7f61..9dcac5e278 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4660,7 +4660,12 @@

                Accessible Name Guidance by Role tooltip Required Only If Content Insufficient - To-do: similar to alert + +
                  +
                • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
                  • +
                • Ideally named by visible, descendant content.
                  • +
                + tree From 0a87de0ab3a95a74f1e32092254737a1ecffe473 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 20:00:46 +0200 Subject: [PATCH 087/131] Recommendation for menu (change from Discretionary to Recommended) and menuitem --- aria-practices.html | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 9dcac5e278..6483d4533f 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4429,11 +4429,12 @@

                Accessible Name Guidance by Role menu - Discretionary + Recommended
                  -
                • Recommended to distinguish articles from one another; helps users when navigating among articles.
                  • -
                • Use aria-labelledby if a visible title is present, otherwise use aria-label.
                  • +
                • Use aria-labelledby to refer to the menuitem or button that controls this element's display.
                  • +
                • Otherwise, use aria-label.
                  • +
                • See the Menu or Menu bar Design Pattern.
                @@ -4449,6 +4450,7 @@

                Accessible Name Guidance by Rolemenubar element is displayed persistently, a name on the menubar can serve that same purpose.
              • Use aria-labelledby if a visible title is present, otherwise use aria-label.
                • +
              • See the Menu or Menu bar Design Pattern.

              @@ -4456,6 +4458,11 @@

              Accessible Name Guidance by Rolemenuitem Required Only If Content Insufficient +
                +
              • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
                • +
              • Ideally named by visible, descendant content.
                • +
              • See the Menu or Menu bar Design Pattern.
                • +
              From 5e39a2fb41e42cf6157f791b691129d190596c5e Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 20:22:23 +0200 Subject: [PATCH 088/131] Recommendation for grid, tree, treegrid, treeitem --- aria-practices.html | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 6483d4533f..beea49ca20 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4344,7 +4344,12 @@

              Accessible Name Guidance by Role grid Required - To-do: write guidance similar to combobox except instead of label, uses caption if made from an HTML table. Include note that caption becomes a description if aria-label or aria-labelledby are used. + +
                +
              • If the grid is applied to an HTML table element, then the accessible name can be derived from the table's caption element.
                • +
              • Otherwise, use aria-labelledby if a visible title is present, otherwise use aria-label.
                • +
              + gridcell @@ -4677,17 +4682,34 @@

              Accessible Name Guidance by Role tree Required - guidance + + + treegrid Required - guidance + +
                +
              • If the treegrid is applied to an HTML table element, then the accessible name can be derived from the table's caption element.
                • +
              • Otherwise, use aria-labelledby if a visible title is present, otherwise use aria-label.
                • +
              • See the Treegrid Design Pattern.
                • +
              + treeitem Required Only If Content Insufficient - To-do: similar to menuitem + +
                +
              • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
                • +
              • Ideally named by visible, descendant content.
                • +
              • See the Tree View Design Pattern.
                • +
              + From 37e71364e808cbd90a1c8b70f612cf7827d3e858 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 20:29:50 +0200 Subject: [PATCH 089/131] Recommendation for gridcell --- aria-practices.html | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/aria-practices.html b/aria-practices.html index beea49ca20..0fb52a88b4 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4354,7 +4354,13 @@

              Accessible Name Guidance by Role gridcell Required Only If Content Insufficient - To-do: write guidance similar to cell + +
                +
              • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
                • +
              • Ideally named by visible, descendant content.
                • +
              • Note that associated row or column headers do not name a cell; a cell's name is its content. Headers are complementary information.
                • +
              + group From 66095e4ad0c192c4ddc376fbe3111b0ca68f962d Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 20:36:25 +0200 Subject: [PATCH 090/131] Recommendation for listbox --- aria-practices.html | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 0fb52a88b4..6aa8390cee 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4257,7 +4257,7 @@

              Accessible Name Guidance by Role
              • If the combobox role is applied to an HTML select or input element, can be named with an HTML label element.
                • -
              • Otherwise use aria-labelledby if a visible title is present.
                • +
              • Otherwise use aria-labelledby if a visible label is present.
              • Use aria-label if a visible label is not present.
              @@ -4406,7 +4406,14 @@

              Accessible Name Guidance by Role listbox Required - To-do: write guidance similar to combobox except that HTML select replaces input + +
                +
              • If the listbox role is applied to an HTML select element (with the multiple attribute or a size attribute having a value greater than 1), can be named with an HTML label element.
                • +
              • Otherwise use aria-labelledby if a visible label is present.
                • +
              • Use aria-label if a visible label is not present.
                • +
              • See the Listbox Design Pattern.
                • +
              + listitem From 50c98802262f5209293f9891987308030bca6a7f Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 20:52:38 +0200 Subject: [PATCH 091/131] Recommendation for group --- aria-practices.html | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 6aa8390cee..2776cde3a0 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4364,8 +4364,15 @@

              Accessible Name Guidance by Role group - To-do: lookup requirement - To-do: write guidance + Discretionary + +
                +
              • When using the HTML fieldset element, the accessible name can be derived from the legend element.
                • +
              • When using the HTML details element, do not provide an accessible name for this element. The user interacts with the summary element, and that can derive its accessible name from its contents.
                • +
              • When using the HTML optgroup element, use the label attribute.
                • +
              • Otherwise, use aria-labelledby if a visible title is present, otherwise use aria-label.
                • +
              + heading From 7443aa1a199da6de8bde2ee6ef86d26185c3d41a Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 20:58:15 +0200 Subject: [PATCH 092/131] Link to issue 26 for role=math --- aria-practices.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aria-practices.html b/aria-practices.html index 2776cde3a0..bc963c2c64 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4450,7 +4450,7 @@

              Accessible Name Guidance by Role math Recommended - To-do: write guidance; probably similar to complementary + To-do: write guidance; probably similar to complementary. See issue #26. menu From 4d990cc6d46156ed015cbab156138ba07b06f79d Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 21:55:26 +0200 Subject: [PATCH 093/131] Address feedback: necessity; remove spaces before punctuation --- aria-practices.html | 44 ++++++++++++++++++++------------------------ 1 file changed, 20 insertions(+), 24 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index bc963c2c64..fb4242aeb5 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -1386,7 +1386,7 @@

              WAI-ARIA Roles, States, and Properties

              Grids : Interactive Tabular Data and Layout Containers

              - A grid widget is a container that enables users to navigate the information or interactive elements it contains using directional navigation keys, such as arrow keys, Home , and End. + A grid widget is a container that enables users to navigate the information or interactive elements it contains using directional navigation keys, such as arrow keys, Home, and End. As a generic container widget that offers flexible keyboard navigation, it can serve a wide variety of needs. It can be used for purposes as simple as grouping a collection of checkboxes or navigation links or as complex as creating a full-featured spreadsheet application. While the words "row" and "column" are used in the names of WAI-ARIA attributes and by assistive technologies when describing and presenting the logical structure of elements with the grid role, using the grid role on an element does not necessarily imply that its visual presentation is tabular. @@ -1834,7 +1834,7 @@

              Keyboard Interaction

              • Recommended selection model -- holding modifier keys is not necessary:
                  -
                • Space: changes the selection state of the focused option .
                  • +
                • Space: changes the selection state of the focused option.
                • Shift + Down Arrow (Optional): Moves focus to and toggles the selected state of the next option.
                • Shift + Up Arrow (Optional): Moves focus to and toggles the selected state of the previous option.
                • Shift + Space (Optional): Selects contiguous items from the most recently selected item to the focused item.
                  • @@ -2252,13 +2252,11 @@

                  WAI-ARIA Roles, States, and Properties

                  • The radio buttons are contained in or owned by an element with role - radiogroup - . + radiogroup.
                  • Each radio button element has role - radio - . + radio.
                  • If a radio button is checked, the radio element has @@ -2270,17 +2268,15 @@

                    WAI-ARIA Roles, States, and Properties

                  • Each radio element is labeled by its content, has a visible label referenced by - aria-labelledby - , or has a label specified with - aria-label - . + aria-labelledby, + or has a label specified with + aria-label.
                  • The radiogroup element has a visible label referenced by aria-labelledby or has a label specified with - aria-label - . + aria-label.
                  • If elements providing additional information about either the radio group or each radio @@ -2590,7 +2586,7 @@

                    Keyboard Interaction

                    For the tab list:

                    • - Tab: When focus moves into the tab list, places focus on the active tab element . + Tab: When focus moves into the tab list, places focus on the active tab element. When the tab list contains the focus, moves focus to the next element in the page tab sequence outside the tablist, which is typically either the first focusable element inside the tab panel or the tab panel itself.
                    • When focus is on a tab element in a horizontal tab list: @@ -3267,7 +3263,7 @@

                      WAI-ARIA Roles, States, and Properties

                    • The element that serves as the focusable splitter has role separator.
                    • The separator element has the aria-valuenow property set to a decimal value representing the current position of the separator.
                    • The separator element has the aria-valuemin property set to a decimal value that represents the position where the primary pane has its minimum size. This is typically 0.
                      • -
                    • The separator element has the aria-valuemax property set to a decimal value that represents the position where the primary pane has its maximum size . This is typically 100.
                      • +
                    • The separator element has the aria-valuemax property set to a decimal value that represents the position where the primary pane has its maximum size. This is typically 100.
                    • If the primary pane has a visible label, it is referenced by aria-labelledby on the separator element. @@ -3786,7 +3782,7 @@
                      Rule 2: Prefer Visible Text
                      When names are generated from text that exists only in markup and is never displayed visually, there is a greater likelihood that accessible names will not be updated when the user interface design or content are changed.

                      - If an interactive element, such as an input field or button , does not have a visually persistent text label, consider adjusting the design to include one. + If an interactive element, such as an input field or button, does not have a visually persistent text label, consider adjusting the design to include one. In addition to serving as a more robust source for an accessible name, visible text labels enhance accessibility for many people with disabilities who do not use assistive technologies that present invisible accessible names. In most circumstances, visible text labels also make the user interface easier to understand for all users.

                      @@ -4142,9 +4138,9 @@

                      Accessible Name Guidance by Role
                      -
                      Necessaty of Naming
                      +
                      Necessity of Naming
                      - Indicates how necessary it is for authors to add a naming attribute or element to supplement or override the content of an element with the specified role. + Indicates how necessity it is for authors to add a naming attribute or element to supplement or override the content of an element with the specified role. This column may include one of the following values:
                      • @@ -4166,7 +4162,7 @@

                        Accessible Name Guidance by Role role - Necessaty of Naming + Necessity of Naming Guidance @@ -5552,7 +5548,7 @@
                        Choose Appropriate Shortcut Behavior
                        Choose Where to Add Shortcuts

                        Work to draft content for this section is tracked in issue 219.

                        -

                        The first goal when designing a keyboard interface is simple, efficient, and intuitive operation with only basic keyboard navigation support. If basic operation of a keyboard interface is inefficient , attempting to compensate for fundamental design issues, such as suboptimal layout or command structure, by implementing keyboard shortcuts will not likely reduce user frustration. The practical implication of this is that, in most well-designed user interfaces, the percentage of functionality that needs to be accessible via a keyboard shortcut in order to create optimal usability is not very high. In many simple user interfaces, keyboard shortcuts can be entirely superfluous. And, in user interfaces with too many keyboard shortcuts, the excess shortcuts create cognitive load that make the most useful ones more difficult to remember.

                        +

                        The first goal when designing a keyboard interface is simple, efficient, and intuitive operation with only basic keyboard navigation support. If basic operation of a keyboard interface is inefficient, attempting to compensate for fundamental design issues, such as suboptimal layout or command structure, by implementing keyboard shortcuts will not likely reduce user frustration. The practical implication of this is that, in most well-designed user interfaces, the percentage of functionality that needs to be accessible via a keyboard shortcut in order to create optimal usability is not very high. In many simple user interfaces, keyboard shortcuts can be entirely superfluous. And, in user interfaces with too many keyboard shortcuts, the excess shortcuts create cognitive load that make the most useful ones more difficult to remember.

                        Consider the following when deciding where to assign keyboard shortcuts:

                          @@ -6155,8 +6151,8 @@

                          Intentionally Hiding Semantics with the presentation Role

                          presentation role, which declares that an element is being used only for presentation and therefore does not have any accessibility semantics. The ARIA 1.1 specification also includes role - none - , which serves as a synonym for presentation. + none, + which serves as a synonym for presentation.

                          For example, consider a tabs widget built using an HTML ul element. @@ -6231,11 +6227,11 @@

                          Browsers ignore role="presentation", and it therefore has no effect, if either of the following are true about the element to which it is applied:

                        From c59cc43b0a143ada5aac6460ee2a8474e8790679 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 21:58:28 +0200 Subject: [PATCH 094/131] Address feedback: around title and placeholder --- aria-practices.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aria-practices.html b/aria-practices.html index fb4242aeb5..7a5aab03a2 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3800,7 +3800,7 @@
                        Rule 3: Prefer Native Techniques
                        Rule 4: Avoid Browser Fallback

                        When authors do not specify an accessible name using an element or attribute that is intended for naming, browsers attempt to help assistive technology users by resorting to fallback methods for generating a name. - For example, the HTML title and placeholder attributes are used as last resort sources of content for accessible names. + For example, the HTML title and placeholder attributes are used as last resort sources of content for accessible names. Because the purpose of these attributes is not naming, their content typically yields low quality accessible names that are not effective.

                        From 774b26c868ed5da6bc3111383db98a2e75c25298 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 22:03:15 +0200 Subject: [PATCH 095/131] Address feedback: aria-label is not rendered visually; mention hidden attribute in accname algo --- aria-practices.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 7a5aab03a2..05d541631c 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3863,7 +3863,7 @@
                        Naming with Child Content
                        Naming with a String Attribute Via aria-label

                        - The aria-label property enables authors to specify a string that will name an element. + The aria-label property enables authors to specify a string that will name an element without being rendered visually. For example, the name of the following button is "Close". 

                        <button type="button" aria-label="Close">X</button>
                        @@ -3919,7 +3919,7 @@
                        Naming with Referenced Content Via aria-labelledby

                      • It has the highest precedence when browsers calculate accessible names, i.e., it overrides names from child content and all other naming attributes, including aria-label.

                      • It can concatenate content from multiple elements into a single name string.

                      • -

                        It incorporates content from elements regardless of their visibility, i.e., it even includes content from elements with display:none or visibility:hidden in the calculated name string.

                        +

                        It incorporates content from elements regardless of their visibility, i.e., it even includes content from elements with the HTML hidden attribute, or CSS display: none or visibility: hidden in the calculated name string.

                        <span id="night-mode-label" hidden>Night mode</span>
   <input type="checkbox" role="switch" aria-labelledby="night-mode-label">
                        • From 8a832bd7a4e68177cca5f59294cc7655d2252d0a Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 22:08:55 +0200 Subject: [PATCH 096/131] =?UTF-8?q?Address=20feedback:=20alert=20=E2=86=92?= =?UTF-8?q?=20button?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- aria-practices.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aria-practices.html b/aria-practices.html index 05d541631c..7cf65972e8 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3942,7 +3942,7 @@
                        Naming with Referenced Content Via aria-labelledby

                        <button id="download-button" aria-labelledby="download-button download-details">Download</button>
 <span id="download-details">PDF, 2.4 MB</span>
                        -

                        In the above example, the accessible name of the alert will be "Download PDF, 2.4 MB", with a space between "Download" and "PDF", and not "DownloadPDF, 2.4 MB".

                        +

                        In the above example, the accessible name of the button will be "Download PDF, 2.4 MB", with a space between "Download" and "PDF", and not "DownloadPDF, 2.4 MB".

                        1. The aria-labelledby property cannot be chained, i.e., if an element with aria-labelledby references another element that also has aria-labelledby, the aria-labelledby attribute on the referenced element will be ignored.
                        2. If an element is referenced by aria-labelledby more than one time during a name calculation, the second and any subsequent references will be ignored.
                          3. From 7f17265f629f6e6b7a9c46bd5aa4f5f42aaab2f8 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 22:10:09 +0200 Subject: [PATCH 097/131] =?UTF-8?q?Address=20feedback:=20Browsers=20?= =?UTF-8?q?=E2=86=92=20browsers?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- aria-practices.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aria-practices.html b/aria-practices.html index 7cf65972e8..0d6261753e 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3959,7 +3959,7 @@
                          Naming with Referenced Content Via aria-labelledby
                          Naming Form Controls with the Label Element

                          The HTML label element enables authors to identify content that serves as a label and associate it with a form control. - When a label element is associated with a form control, Browsers calculate an accessible name for the form control from the label content. + When a label element is associated with a form control, browsers calculate an accessible name for the form control from the label content.

                          For example, text displayed adjacent to a checkbox may be visually associated with the checkbox, so it is understood as the checkbox label by users who can perceive that visual association. From 8fb9dbe39329612afe4d03b63c09ff8db78f6b28 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Mon, 24 Jun 2019 22:12:36 +0200 Subject: [PATCH 098/131] =?UTF-8?q?Address=20feedback:=20labeling=20?= =?UTF-8?q?=E2=86=92=20labelling,=20labeled=20=E2=86=92=20labelled?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- aria-practices.html | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 0d6261753e..375bac20d9 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -377,7 +377,7 @@

                          Keyboard Interaction

                          WAI-ARIA Roles, States, and Properties

                          • Breadcrumb trail is contained within a navigation landmark region.
                            • -
                          • The landmark region is labeled via aria-label or aria-labelledby.
                            • +
                          • The landmark region is labelled via aria-label or aria-labelledby.
                          • The link to the current page has aria-current set to page. If the element representing the current page is not a link, aria-current is optional. @@ -397,7 +397,7 @@

                            Button

                          • Toggle button: A two-state button that can be either off (not pressed) or on (pressed). To tell assistive technologies that a button is a toggle button, specify a value for the attribute aria-pressed. - For example, a button labeled mute in an audio player could indicate that sound is muted by setting the pressed state true. + For example, a button labelled mute in an audio player could indicate that sound is muted by setting the pressed state true. Important: it is critical the label on a toggle does not change when its state changes. In this example, when the pressed state is true, the label remains "Mute" so a screen reader would say something like "Mute toggle button pressed". Alternatively, if the design were to call for the button label to change from "Mute" to "Unmute," the aria-pressed attribute would not be needed. @@ -1045,7 +1045,7 @@

                            WAI-ARIA Roles, States, and Properties

                          • When a descendant of a listbox, grid, or tree popup is focused, DOM focus remains on the textbox and the textbox has aria-activedescendant set to a value that refers to the focused element within the popup.
                          • In a combobox with a listbox, grid, or tree popup, when a suggested value is visually indicated as the currently selected value, the option, gridcell, row, or treeitem containing that value has aria-selected set to true.
                          • - If the combobox has a visible label, the element with role combobox has aria-labelledby set to a value that refers to the labeling element. + If the combobox has a visible label, the element with role combobox has aria-labelledby set to a value that refers to the labelling element. Otherwise, the combobox element has a label provided by aria-label.
                          • The textbox element has aria-autocomplete set to a value that corresponds to its autocomplete behavior: @@ -1496,7 +1496,7 @@

                            Layout Grids for Grouping Widgets

                            - Unlike grids used to present data, A grid used for layout does not necessarily have header cells for labeling rows or columns and might contain only a single row or a single column. + Unlike grids used to present data, A grid used for layout does not necessarily have header cells for labelling rows or columns and might contain only a single row or a single column. Even if it has multiple rows and columns, it may present a single, logically homogenous set of elements. For example, a list of recipients for a message may be a grid where each cell contains a link that represents a recipient. The grid may initially have a single row but then wrap into multiple rows as recipients are added. @@ -1689,7 +1689,7 @@

                            WAI-ARIA Roles, States, and Properties

                        3. - If there is an element in the user interface that serves as a label for the grid, aria-labelledby is set on the grid element with a value that refers to the labeling element. + If there is an element in the user interface that serves as a label for the grid, aria-labelledby is set on the grid element with a value that refers to the labelling element. Otherwise, a label is specified for the grid element using aria-label.
                        4. If the grid has a caption or description, aria-describedby is set on the grid element with a value referring to the element containing the description.
                          5. @@ -2072,7 +2072,7 @@

                          WAI-ARIA Roles, States, and Properties

                        5. Items in a menu may be divided into groups by placing an element with a role of separator between groups. For example, this technique should be used when a menu contains a set of menuitemradio items.
                        6. All separators should have aria-orientation consistent with the separator's orientation.
                        7. - If a menubar has a visible label, the element with role menubar has aria-labelledby set to a value that refers to the labeling element. + If a menubar has a visible label, the element with role menubar has aria-labelledby set to a value that refers to the labelling element. Otherwise, the menubar element has a label provided by aria-label.
                        8. @@ -2266,7 +2266,7 @@

                          WAI-ARIA Roles, States, and Properties

                          set to false.
                        9. - Each radio element is labeled by its content, has a visible label + Each radio element is labelled by its content, has a visible label referenced by aria-labelledby, or has a label specified with @@ -2529,7 +2529,7 @@

                          WAI-ARIA Roles, States, and Properties

                    • - If there is an element in the user interface that serves as a label for the table, aria-labelledby is set on the table element with a value that refers to the labeling element. + If there is an element in the user interface that serves as a label for the table, aria-labelledby is set on the table element with a value that refers to the labelling element. Otherwise, a label is specified for the table element using aria-label.
                    • If the table has a caption or description, aria-describedby is set on the table element with a value referring to the element containing the description.
                      • @@ -2645,7 +2645,7 @@

                      WAI-ARIA Roles, States, and Properties

                    • Each element that serves as a tab has role tab and is contained within the element with role tablist.
                    • Each element that contains the content panel for a tab has role tabpanel.
                    • - If the tab list has a visible label, the element with role tablist has aria-labelledby set to a value that refers to the labeling element. + If the tab list has a visible label, the element with role tablist has aria-labelledby set to a value that refers to the labelling element. Otherwise, the tablist element has a label provided by aria-label.
                    • Each element with role tab has the property aria-controls referring to its associated tabpanel element.
                      • @@ -3178,7 +3178,7 @@

                      WAI-ARIA Roles, States, and Properties

                  • - If there is an element in the user interface that serves as a label for the treegrid, aria-labelledby is set on the grid element with a value that refers to the labeling element. + If there is an element in the user interface that serves as a label for the treegrid, aria-labelledby is set on the grid element with a value that refers to the labelling element. Otherwise, a label is specified for the grid element using aria-label.
                  • If the treegrid has a caption or description, aria-describedby is set on the grid element with a value referring to the element containing the description.
                    • @@ -3229,7 +3229,7 @@

                    Window Splitter

                    For example, consider a book reading application with a primary pane for the table of contents and a secondary pane that displays content from a section of the book. - The two panes are divided by a vertical splitter labeled "Table of Contents". + The two panes are divided by a vertical splitter labelled "Table of Contents". When the table of contents pane has its maximum size, the splitter has a value of 100, and when the table of contents is completely collapsed, the splitter has a value of 0.

                    @@ -3280,7 +3280,7 @@

                    WAI-ARIA Roles, States, and Properties

                    Landmark Regions

                    ARIA landmark roles provide a powerful way to identify the organization and structure of a web page. - By classifying and labeling sections of a page, they enable structural information that is conveyed visually through layout to be represented programmatically. + By classifying and labelling sections of a page, they enable structural information that is conveyed visually through layout to be represented programmatically. Screen readers exploit landmark roles to provide keyboard navigation to important sections of a page. Landmark regions can also be used as targets for "skip links" and by browser extensions to enhanced keyboard navigation.

                    @@ -3378,7 +3378,7 @@

                    General Principles of Landmark Design

                  • If a specific landmark role is used more than once on a page, provide each instance of that landmark with a unique label. There is one rare circumstance where providing the same label to multiple instances of a landmark can be beneficial: the content and purpose of each instance is identical. - For example, a large search results table has two sets of identical pagination controls -- one above and one below the table, so each set is in a navigation region labeled Search Results. + For example, a large search results table has two sets of identical pagination controls -- one above and one below the table, so each set is in a navigation region labelled Search Results. In this case, adding extra information to the label that distinguishes the two instances may be more distracting than helpful.
                    • @@ -3964,7 +3964,7 @@
                    Naming Form Controls with the Label Element

                    For example, text displayed adjacent to a checkbox may be visually associated with the checkbox, so it is understood as the checkbox label by users who can perceive that visual association. However, unless the text is programmatically associated with the checkbox, assistive technology users will experience a checkbox without a label. - Wrapping the checkbox and the labeling text in a label element as follows gives the checkbox an accessible name. + Wrapping the checkbox and the labelling text in a label element as follows gives the checkbox an accessible name. 

                    
   <label>
@@ -3984,7 +3984,7 @@ 
                    Naming Form Controls with the Label Element
                    
           
                    
             Using the label element is an effective technique for satisfying Rule 2: Prefer Visible Text.
             It also satisfies Rule 3: Prefer Native Techniques.
-            Native HTML labels offer an important usability and accessibility advantage over ARIA labeling techniques: browsers automatically make clicking the label equivalent to clicking the form control.
+            Native HTML labels offer an important usability and accessibility advantage over ARIA labelling techniques: browsers automatically make clicking the label equivalent to clicking the form control.
             This increases the hit area of the form control.
           
                    
         
@@ -4067,7 +4067,7 @@ 
                    Naming Tables and Figures with Captions
                    
 
         
                    
           
                    Fallback Names Derived from Titles and Placeholders
                    
-          
                    When an accessible name is not provided using one of the primary techniques (e.g., the aria-label or aria-labelledby attributes), or native markup techniques (e.g., the HTML label element, or the alt attribute of the HTML img element), an accessible name can be derived from some other attributes as a fallback mechanism. In general, prefer the explicit labeling techniques described above over fallback techniques described in this section.
                    
+          
                    When an accessible name is not provided using one of the primary techniques (e.g., the aria-label or aria-labelledby attributes), or native markup techniques (e.g., the HTML label element, or the alt attribute of the HTML img element), an accessible name can be derived from some other attributes as a fallback mechanism. In general, prefer the explicit labelling techniques described above over fallback techniques described in this section.
                    
 
           
                    Any HTML element can have a title attribute specified. The title attribute is used as the element's fallback accessible name. The title attribute is commonly presented visually as a tooltip when the user hovers over the element with a pointing device, which is not particularly discoverable, and is also not accessible to visual users without a pointing device.
                    
 
@@ -4079,7 +4079,7 @@ 
                    Fallback Names Derived from Titles and Placeholders
                    
     <label><input name="starter-class" value="blue"> Blue</label>
    </fieldset>
                    -

                    For the HTML input and textarea elements, the placeholder attribute is used as a fallback labeling mechanism if nothing else (including the title attribute) results in a label. It is better to use a label element, since it does not disappear visually when the user focuses the form control.

                    +

                    For the HTML input and textarea elements, the placeholder attribute is used as a fallback labelling mechanism if nothing else (including the title attribute) results in a label. It is better to use a label element, since it does not disappear visually when the user focuses the form control.

                    <!-- Using a <label> is recommended -->
 <label>Search <input type=search name=q></label>

From a16cf6b75eb7cf9e9fd5edf5c6408dd4545a86eb Mon Sep 17 00:00:00 2001
From: Simon Pieters 
Date: Mon, 24 Jun 2019 22:16:56 +0200
Subject: [PATCH 099/131] Address feedback: move a paragraph in fieldset
 section

---
 aria-practices.html | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/aria-practices.html b/aria-practices.html
index 375bac20d9..afb6f7eacb 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -3995,11 +3995,6 @@ 
                    Naming Fieldsets with the Legend Element
                    
             The HTML fieldset element can be used to group form controls, which can make forms easier to navigate.
             The legend element can be used to give the group a name.
           
                    
-          
                    
-            This grouping technique is particularly useful for presenting multiple choice questions.
-            It enables authors to associate a question with a group of answers.
-            If a question is not programmatically associated with its answer options, assistive technology users could access the answers without being aware of the question.
-          
                    
           
                    For example, a group of radio buttons can be grouped together in a fieldset, where the legend element labels the group for the radio buttons.
                    
           
                    
   <fieldset>
@@ -4009,6 +4004,11 @@ 
                    Naming Fieldsets with the Legend Element
                    
     <label><input name="starter-class" value="blue"> Blue</label>
   </fieldset>
           
                    
+          
                    
+            This grouping technique is particularly useful for presenting multiple choice questions.
+            It enables authors to associate a question with a group of answers.
+            If a question is not programmatically associated with its answer options, assistive technology users could access the answers without being aware of the question.
+          
                    
           
                    
             Other types of related form fields can also be grouped using fieldset and legend.
             This helps users navigate the form group-by-group.

From 972fe21d4e0edecf6adc8dc911f2a97879b54af7 Mon Sep 17 00:00:00 2001
From: Simon Pieters 
Date: Mon, 24 Jun 2019 22:42:10 +0200
Subject: [PATCH 100/131] Address feedback: remove duplicate area alt

---
 aria-practices.html | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/aria-practices.html b/aria-practices.html
index afb6f7eacb..7c799f7f56 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -4762,9 +4762,6 @@ 
                    Accessible name calculation
                    
 
               
                    table
                    
               
                    The first child caption element.
                    
-
-              
                    area
                    
-              
                    The alt attribute.
                    
             
           
           
                  • If the name is still empty, then for elements with a role that supports naming from child content, the content of the element is used.
                    • 

From 47887c00e66f917a1a4be98fc07fe31d0136bc03 Mon Sep 17 00:00:00 2001
From: Simon Pieters 
Date: Mon, 24 Jun 2019 22:42:47 +0200
Subject: [PATCH 101/131] Address feedback: fix typo falback

---
 aria-practices.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/aria-practices.html b/aria-practices.html
index 7c799f7f56..8ceb4d8fac 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -4803,7 +4803,7 @@ 
                    Accessible name calculation
                    
           
                    Examples of non-recursive accessible name calculation
                    
           
                    Consider an input element that has no associated label element and only a name attribute and so does not have an accessible name (do not do this):
                    
           
                    <input name="code">
                    
-          
                    If there is a placeholder attribute, then it serves as a naming falback mechanism (avoid doing this):
                    
+          
                    If there is a placeholder attribute, then it serves as a naming fallback mechanism (avoid doing this):
                    
 
           
                    <input name="code"
        placeholder="One-time code">
                    

From 8de8e443d886827da4c5f39ecdfcb17709ba6657 Mon Sep 17 00:00:00 2001
From: Simon Pieters 
Date: Mon, 24 Jun 2019 22:44:27 +0200
Subject: [PATCH 102/131] Address feedback: clarify aria-labelledby recursion
 is not chaining

---
 aria-practices.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/aria-practices.html b/aria-practices.html
index 8ceb4d8fac..a0049bc232 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -4794,7 +4794,7 @@ 
                    Accessible name calculation
                    
         
                    
         
                    
           When calculating a name from content, the user agent walks through all descendant nodes.
-          And, when following aria-labelledby references, it similarly walks the tree of each referenced element.
+          And, when following references in an aria-labelledby attribute, it similarly walks the tree of each referenced element.
           Thus, the naming algorithm is recursive.
           The following two sections provide non-recursive and recursive examples of how the algorithm works.
         
                    

From 1d38d3bb3a4a818c66714bd1a115693437965f22 Mon Sep 17 00:00:00 2001
From: Simon Pieters 
Date: Mon, 24 Jun 2019 22:47:37 +0200
Subject: [PATCH 103/131] Address feedback: fix typo an label; fix consistency
 in aria-label example

---
 aria-practices.html | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/aria-practices.html b/aria-practices.html
index a0049bc232..850c1a0b8f 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -4814,7 +4814,7 @@ 
                    Examples of non-recursive accessible name calculation
                    
        placeholder="123456"
        title="One-time code">
                    -

                    If there is also an label element (recommended), then that is used as the accessible name, and the title attribute is instead used as the accessible description:

                    +

                    If there is also a label element (recommended), then that is used as the accessible name, and the title attribute is instead used as the accessible description:

                    <label>One-time code
  <input name="code"
@@ -4822,7 +4822,7 @@ 
                    Examples of non-recursive accessible name calculation
                    
         title="Get your code from the app.">
 </label>
                    -

                    If there is also an aria-label attribute, then that overrides the label element:

                    +

                    If there is also an aria-label attribute (not recommended unless it adds clarity for assistive technology users), then that becomes the accessible name, overriding the label element:

                    <label>Code
  <input name="code"

From debb672134203f8360f760924c2c6a075230cebf Mon Sep 17 00:00:00 2001
From: Matt King 
Date: Mon, 24 Jun 2019 23:35:34 -0700
Subject: [PATCH 104/131] Revise description of aria-label to clarify that the
 string is not visually rendered as opposed to the element being named.

---
 aria-practices.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/aria-practices.html b/aria-practices.html
index 850c1a0b8f..83fc48b9cd 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -3863,7 +3863,7 @@ 
                    Naming with Child Content
                    
         
                    
           
                    Naming with a String Attribute Via aria-label
                    
           
                    
-            The aria-label property enables authors to specify a string that will name an element without being rendered visually.
+            The aria-label property enables authors to name an element with a string that is not visually rendered.
             For example, the name of the following button is "Close".
           
                    
           
                    <button type="button" aria-label="Close">X</button>
                    

From 82f3b2fb0378a50431abd360676501e64130db58 Mon Sep 17 00:00:00 2001
From: Matt King 
Date: Mon, 24 Jun 2019 23:44:01 -0700
Subject: [PATCH 105/131] Minor editorial revision to aria-labelledby feature
 list

---
 aria-practices.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/aria-practices.html b/aria-practices.html
index 83fc48b9cd..61c07dd792 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -3919,7 +3919,7 @@ 
                    Naming with Referenced Content Via aria-labelledby
                    
     
                  • It has the highest precedence when browsers calculate accessible names, i.e., it overrides names from child content and all other naming attributes, including aria-label.
                    • 
     
                  • It can concatenate content from multiple elements into a single name string.
                    • 
     
                  • 
-      
                    It incorporates content from elements regardless of their visibility, i.e., it even includes content from elements with the HTML hidden attribute, or CSS display: none or visibility: hidden in the calculated name string.
                    
+      
                    It incorporates content from elements regardless of their visibility, i.e., it even includes content from elements with the HTML hidden attribute, CSS display: none, or CSS visibility: hidden in the calculated name string.
                    
       
                    <span id="night-mode-label" hidden>Night mode</span>
   <input type="checkbox" role="switch" aria-labelledby="night-mode-label">
                    
     
                    • 

From 1ee6b0985e25566b4e54d827ae29e274cb745898 Mon Sep 17 00:00:00 2001
From: Matt King 
Date: Tue, 25 Jun 2019 00:05:26 -0700
Subject: [PATCH 106/131] Change labelled and labelling to labeled and labeling
 except in aria-labelledby

---
 aria-practices.html | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/aria-practices.html b/aria-practices.html
index 61c07dd792..efd0ca7c6e 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -3906,7 +3906,7 @@ 
                    Naming with Referenced Content Via aria-labelledby
                    
   <span role="switch" aria-checked="false" tabindex="0" aria-labelledby="night-mode-label"></span>

                    - Note that while using aria-labelledby is similar in this situation to using an HTML label element with the for attribute, one significant difference is that browsers do not automatically make clicking on the labelling element activate the labelled element; that is an author responsibility. + Note that while using aria-labelledby is similar in this situation to using an HTML label element with the for attribute, one significant difference is that browsers do not automatically make clicking on the labeling element activate the labeled element; that is an author responsibility. However, HTML label cannot be used to label a span element. Fortunately, an HTML input with type="checkbox" allows the ARIA switch role, so when feasible, using the following approach creates a more robust solution.

                    @@ -3964,7 +3964,7 @@
                    Naming Form Controls with the Label Element

                    For example, text displayed adjacent to a checkbox may be visually associated with the checkbox, so it is understood as the checkbox label by users who can perceive that visual association. However, unless the text is programmatically associated with the checkbox, assistive technology users will experience a checkbox without a label. - Wrapping the checkbox and the labelling text in a label element as follows gives the checkbox an accessible name. + Wrapping the checkbox and the labeling text in a label element as follows gives the checkbox an accessible name. 

                    
   <label>
@@ -3984,7 +3984,7 @@ 
                    Naming Form Controls with the Label Element
                    
           
                    
             Using the label element is an effective technique for satisfying Rule 2: Prefer Visible Text.
             It also satisfies Rule 3: Prefer Native Techniques.
-            Native HTML labels offer an important usability and accessibility advantage over ARIA labelling techniques: browsers automatically make clicking the label equivalent to clicking the form control.
+            Native HTML labels offer an important usability and accessibility advantage over ARIA labeling techniques: browsers automatically make clicking the label equivalent to clicking the form control.
             This increases the hit area of the form control.
           
                    
         
@@ -4067,7 +4067,7 @@ 
                    Naming Tables and Figures with Captions
                    
 
         
                    
           
                    Fallback Names Derived from Titles and Placeholders
                    
-          
                    When an accessible name is not provided using one of the primary techniques (e.g., the aria-label or aria-labelledby attributes), or native markup techniques (e.g., the HTML label element, or the alt attribute of the HTML img element), an accessible name can be derived from some other attributes as a fallback mechanism. In general, prefer the explicit labelling techniques described above over fallback techniques described in this section.
                    
+          
                    When an accessible name is not provided using one of the primary techniques (e.g., the aria-label or aria-labelledby attributes), or native markup techniques (e.g., the HTML label element, or the alt attribute of the HTML img element), an accessible name can be derived from some other attributes as a fallback mechanism. In general, prefer the explicit labeling techniques described above over fallback techniques described in this section.
                    
 
           
                    Any HTML element can have a title attribute specified. The title attribute is used as the element's fallback accessible name. The title attribute is commonly presented visually as a tooltip when the user hovers over the element with a pointing device, which is not particularly discoverable, and is also not accessible to visual users without a pointing device.
                    
 
@@ -4079,7 +4079,7 @@ 
                    Fallback Names Derived from Titles and Placeholders
                    
     <label><input name="starter-class" value="blue"> Blue</label>
    </fieldset>
                    -

                    For the HTML input and textarea elements, the placeholder attribute is used as a fallback labelling mechanism if nothing else (including the title attribute) results in a label. It is better to use a label element, since it does not disappear visually when the user focuses the form control.

                    +

                    For the HTML input and textarea elements, the placeholder attribute is used as a fallback labeling mechanism if nothing else (including the title attribute) results in a label. It is better to use a label element, since it does not disappear visually when the user focuses the form control.

                    <!-- Using a <label> is recommended -->
 <label>Search <input type=search name=q></label>
@@ -4790,7 +4790,7 @@ 
                    Accessible name calculation
                    
           
         
         
                    
-          The final step is a fallback mechanism. Generally when labelling an element, use one of the non-fallback mechanisms.
+          The final step is a fallback mechanism. Generally when labeling an element, use one of the non-fallback mechanisms.
         
                    
         
                    
           When calculating a name from content, the user agent walks through all descendant nodes.
@@ -4847,7 +4847,7 @@ 
                    Examples of non-recursive accessible name calculation
                    
 
           
                    
             
                    Examples of recursive accessible name calculation
                    
-            
                    The accessible name calculation algorithm will be invoked recursively when necessary. An `aria-labelledby` reference causes the algorithm to be invoked recursively, and when computing an accessible name from content the algorithm is invoked recursively for each child node.
                    
+            
                    The accessible name calculation algorithm will be invoked recursively when necessary. An aria-labelledby reference causes the algorithm to be invoked recursively, and when computing an accessible name from content the algorithm is invoked recursively for each child node.
                    
 
             
                    In this example, the label for the button is computed by recursing into each child node, resulting in Move to trash.
                    
 

From 0797c1e4e39e5f5d449b1568d3baa35ae7da0c85 Mon Sep 17 00:00:00 2001
From: Matt King 
Date: Tue, 25 Jun 2019 00:23:27 -0700
Subject: [PATCH 107/131] Change 'necessity' tto 'necessary' in table column
 description

---
 aria-practices.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/aria-practices.html b/aria-practices.html
index efd0ca7c6e..4361f8bf0b 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -4140,7 +4140,7 @@ 
                    Accessible Name Guidance by Role
           
                    Necessity of Naming
                    
           
                    
-            Indicates how necessity it is for authors to add a naming attribute or element to supplement or override the content of an element with the specified role.
+            Indicates how necessary it is for authors to add a naming attribute or element to supplement or override the content of an element with the specified role.
             This column may include one of the following values:
             
                      
               
                    • 

From 03f1ee209e4483a875ab7123befa4e9bf55d3e24 Mon Sep 17 00:00:00 2001
From: Matt King 
Date: Tue, 25 Jun 2019 01:25:19 -0700
Subject: [PATCH 108/131] Revise naming guidance for document role

---
 aria-practices.html | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/aria-practices.html b/aria-practices.html
index 4361f8bf0b..a937655926 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -4301,8 +4301,12 @@ 
                      Accessible Name Guidance by Role
             
               document
-              Do Not Name
-              The document role is used to hint to the assistive technology to switch back to "reading mode" within an application or widget. That element should have a name.
+              Discretionary
+              
+                Elements with the document role are contained within an element with the application element, which is required to have a name.
+                Typically, the name of the application element will provide sufficient context and identity for the document element.
+                Because the application element is used only to create unusual, custom widgets, careful assessment is necessary to determine whether or not adding an accessible name is beneficial.
+              
             
             
               feed

From be8ed01e725f0dc23e4d23dde0ec208887570e5a Mon Sep 17 00:00:00 2001
From: Simon Pieters 
Date: Tue, 25 Jun 2019 18:18:43 +0200
Subject: [PATCH 109/131] Address feedback: typo

---
 aria-practices.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/aria-practices.html b/aria-practices.html
index a937655926..b69b53bc8b 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -4303,7 +4303,7 @@ 
                      Accessible Name Guidance by Roledocument
               Discretionary
               
-                Elements with the document role are contained within an element with the application element, which is required to have a name.
+                Elements with the document role are contained within an element with the application role, which is required to have a name.
                 Typically, the name of the application element will provide sufficient context and identity for the document element.
                 Because the application element is used only to create unusual, custom widgets, careful assessment is necessary to determine whether or not adding an accessible name is beneficial.
               

From bed7986ccacb439314cddba8cec78ff7a5e9041f Mon Sep 17 00:00:00 2001
From: Simon Pieters 
Date: Tue, 25 Jun 2019 20:18:05 +0200
Subject: [PATCH 110/131] Recommendation for note

---
 aria-practices.html | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/aria-practices.html b/aria-practices.html
index b69b53bc8b..185ec000df 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -4530,8 +4530,13 @@ 
                      Accessible Name Guidance by Role
             
               note
-              namerequired
-              guidance
+              Discretionary
+              
+                
                        
+                  
                      • Naming is optional, but can help screen reader users understand the context and purpose of the note.
                        • 
+                  
                      • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
                        • 
+                
                      
+              
             
             
               option

From ae5938cb62e7eacf4a5f8826a4e8e69e99bd012a Mon Sep 17 00:00:00 2001
From: Simon Pieters 
Date: Tue, 25 Jun 2019 20:24:10 +0200
Subject: [PATCH 111/131] Recommendation for option

---
 aria-practices.html | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/aria-practices.html b/aria-practices.html
index 185ec000df..f3e47074cc 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -4541,7 +4541,13 @@ 
                      Accessible Name Guidance by Role
               option
               Required Only If Content Insufficient
-              guidance
+              
+                
                        
+                  
                      • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
                        • 
+                  
                      • Ideally named by visible, descendant content.
                        • 
+                  
                      • See the Combo Box Design Pattern.
                        • 
+                
                      
+              
             
             
               presentation

From f1b5a9376ed8b7f36ddf9904cfb264fcd0278f36 Mon Sep 17 00:00:00 2001
From: Simon Pieters 
Date: Tue, 25 Jun 2019 20:29:10 +0200
Subject: [PATCH 112/131] Recommendation for progressbar

---
 aria-practices.html | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/aria-practices.html b/aria-practices.html
index f3e47074cc..1e2946f1a1 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -4557,7 +4557,13 @@ 
                      Accessible Name Guidance by Role
               progressbar
               Required
-              guidance
+              
+                
                        
+                  
                      • If the progressbar role is applied to an HTML progress element, can be named with an HTML label element.
                        • 
+                  
                      • Otherwise use aria-labelledby if a visible label is present.
                        • 
+                  
                      • Use aria-label if a visible label is not present.
                        • 
+                
                      
+              
             
             
               radio

From 0e10d3788ee1a923f42aefccbe108b633e41cd08 Mon Sep 17 00:00:00 2001
From: Simon Pieters 
Date: Wed, 26 Jun 2019 14:51:46 +0200
Subject: [PATCH 113/131] Recommendation for radiogroup

---
 aria-practices.html | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/aria-practices.html b/aria-practices.html
index 1e2946f1a1..3fd6ce73cc 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -4579,7 +4579,15 @@ 
                      Accessible Name Guidance by Role
               radiogroup
               Required
-              guidance
+              
+                
                        
+                  
                      • Recommended to label a group of radio buttons.
                        • 
+                  
                      • Use aria-labelledby if a visible title is present, otherwise use aria-label.
                        • 
+                  
                      • See the Radio Group Design Pattern.
                        • 
+                
                      
+
+                To-do: What's the relationship between fieldset and radiogroup?
+              
             
             
               region

From 50fc11dba99e0a891de5d9aaa8cad3ca5f7a702f Mon Sep 17 00:00:00 2001
From: Simon Pieters 
Date: Wed, 26 Jun 2019 15:01:09 +0200
Subject: [PATCH 114/131] Recommendation for region, search

---
 aria-practices.html | 25 ++++++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/aria-practices.html b/aria-practices.html
index 3fd6ce73cc..d7c0ed6edc 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -4201,6 +4201,7 @@ 
                      Accessible Name Guidance by Role
                   
                    • Necessary in the uncommon circumstance where two banner landmark regions are present on the same page. It is otherwise optional.
                      • 
                   
                    • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
                      • 
+                  
                    • See the Banner Landmark Role.
                      • 
                 
                    
               
             
@@ -4266,6 +4267,7 @@ 
                    Accessible Name Guidance by RoleNaming is necessary when two complementary landmark regions are present on the same page.
                   
                  • Naming is recommended even when one complementary region is present to help users understand the purpose of the region's content when navigating among landmark regions.
                    • 
                   
                  • Use aria-labelledby if a visible title is present, otherwise use aria-label.
                    • 
+                  
                  • See the Complementary Landmark Role.
                    •
                  @@ -4337,7 +4339,7 @@

                  Accessible Name Guidance by Role
                • Helps screen reader users understand the context and purpose of the form landmark.
                • Use aria-labelledby if a visible title is present, otherwise use aria-label.
                  • -
                • See the Form Design Pattern.
                  • +
                • See the Form Landmark Role.

                @@ -4439,6 +4441,7 @@

                Accessible Name Guidance by Role
              • Potentially helpful for orienting assistive technology users, especially in single-page applications where main content changes happen without generating a page load event.
              • Can be named using aria-labelledby if a visible title is present, otherwise with aria-label.
                • +
              • See the Main Landmark Role.

              @@ -4519,7 +4522,7 @@

              Accessible Name Guidance by Role
            • Helps screen reader users understand the context and purpose of the navigation landmark.
            • Use aria-labelledby if a visible title is present, otherwise use aria-label.
              • -
            • See the Navigation Design Pattern.
              • +
            • See the Navigation Landmark Role.

            @@ -4592,7 +4595,13 @@

            Accessible Name Guidance by Role region Required - guidance + +
              +
            • Helps screen reader users understand the context and purpose of the landmark.
              • +
            • Use aria-labelledby if a visible title is present, otherwise use aria-label.
              • +
            • See the Region Landmark Role.
              • +
            + row @@ -4630,8 +4639,14 @@

            Accessible Name Guidance by Role search - namerequired - guidance + Recommended + +
              +
            • Helps screen reader users understand the context and purpose of the search landmark.
              • +
            • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
              • +
            • See the Search Landmark Role.
              • +
            + searchbox From ffc6261132774aa24a3c2cf159caf657f13fd3d3 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Wed, 26 Jun 2019 15:04:28 +0200 Subject: [PATCH 115/131] Recommendation for scrollbar --- aria-practices.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index d7c0ed6edc..a93cfb006e 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4634,8 +4634,8 @@

            Accessible Name Guidance by Role scrollbar - Required - guidance + Do Not Name + Use aria-controls to indicate which element the scrollbar controls. search From 788130aee5ef8d87675ec464a89c6e128215ff7a Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Wed, 26 Jun 2019 15:07:24 +0200 Subject: [PATCH 116/131] Recommendation for searchbox, textbox --- aria-practices.html | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index a93cfb006e..ec6d433fd5 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4651,7 +4651,13 @@

            Accessible Name Guidance by Role searchbox Required - guidance + +
              +
            • If the searchbox role is applied to an HTML input element, can be named with an HTML label element.
              • +
            • Otherwise use aria-labelledby if a visible label is present.
              • +
            • Use aria-label if a visible label is not present.
              • +
            + separator @@ -4717,7 +4723,13 @@

            Accessible Name Guidance by Role textbox Required - guidance + +
              +
            • If the textbox role is applied to an HTML input or textarea element, can be named with an HTML label element.
              • +
            • Otherwise use aria-labelledby if a visible label is present.
              • +
            • Use aria-label if a visible label is not present.
              • +
            + timer From ef3d1f93a951ddd9f0ef9f878e622382e70d0ba9 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Wed, 26 Jun 2019 15:35:18 +0200 Subject: [PATCH 117/131] Recommendation for table --- aria-practices.html | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/aria-practices.html b/aria-practices.html index ec6d433fd5..f8f69e4ed9 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4703,7 +4703,14 @@

            Accessible Name Guidance by Role table Required - guidance + +
              +
            • If using HTML table element, use the caption element.
              • +
            • Otherwise use aria-labelledby if a visible label is present.
              • +
            • Use aria-label if a visible label is not present.
              • +
            • See the Table Design Pattern.
              • +
            + tablist From a0f4104649014e47df181e3a936063a680003754 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Wed, 26 Jun 2019 15:39:15 +0200 Subject: [PATCH 118/131] Recommendation for tablist --- aria-practices.html | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index f8f69e4ed9..a994b328ed 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4714,8 +4714,14 @@

            Accessible Name Guidance by Role tablist - namerequired - guidance + Recommended + +
              +
            • Helps screen reader users understand the context and purpose of the tablist.
              • +
            • Use aria-labelledby if a visible title is present, otherwise use aria-label.
              • +
            • See the Carousel Design Pattenr and Tabs Design Pattern.
              • +
            + tabpanel From a735dc86a89c0a22d2852a64c89dd441c8e7a43e Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Wed, 26 Jun 2019 15:52:11 +0200 Subject: [PATCH 119/131] Recommendation for tabpanel --- aria-practices.html | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/aria-practices.html b/aria-practices.html index a994b328ed..d391034c6c 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4726,7 +4726,12 @@

            Accessible Name Guidance by Role tabpanel Required - guidance + + + term From ef6c0980a6c53516504737d3b69613587a8f04da Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Wed, 26 Jun 2019 17:30:49 +0200 Subject: [PATCH 120/131] Recommendation for rowgroup (WIP) --- aria-practices.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index d391034c6c..ce39ed2993 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4618,8 +4618,8 @@

            Accessible Name Guidance by Role rowgroup - namerequired - guidance + Do Not Name + To-do: guidance rowheader From 9ffece998f6fcb1949604263425fe90ae21f8566 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Wed, 26 Jun 2019 21:11:52 +0200 Subject: [PATCH 121/131] Change visible title to visible label --- aria-practices.html | 58 ++++++++++++++++++++++----------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index ce39ed2993..4913fafaae 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -337,12 +337,12 @@

            WAI-ARIA Roles, States, and Properties

            A value for aria-labelledby that refers to the element containing the title of the dialog if the - dialog has a visible title. + dialog has a visible label.
          • A value for aria-label - if the dialog does not have a visible title. + if the dialog does not have a visible label.

          @@ -1341,7 +1341,7 @@

          WAI-ARIA Roles, States, and Properties

          • The element that contains the set of feed articles has role feed.
          • - If the feed has a visible title, the feed element has aria-labelledby referring to the element containing the title. + If the feed has a visible label, the feed element has aria-labelledby referring to the element containing the title. Otherwise, the feed element has a label specified with aria-label.
          • @@ -4177,12 +4177,12 @@

            Accessible Name Guidance by Role alertdialog Required - Use aria-labelledby if a visible title is present, otherwise use aria-label. + Use aria-labelledby if a visible label is present, otherwise use aria-label. application Required - Use aria-labelledby if a visible title is present, otherwise use aria-label. + Use aria-labelledby if a visible label is present, otherwise use aria-label. article @@ -4190,7 +4190,7 @@

            Accessible Name Guidance by Role
            • Recommended to distinguish articles from one another; helps users when navigating among articles.
              • -
            • Use aria-labelledby if a visible title is present, otherwise use aria-label.
              • +
            • Use aria-labelledby if a visible label is present, otherwise use aria-label.
            @@ -4200,7 +4200,7 @@

            Accessible Name Guidance by Role
            • Necessary in the uncommon circumstance where two banner landmark regions are present on the same page. It is otherwise optional.
              • -
            • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
              • +
            • Named using aria-labelledby if a visible label is present, otherwise with aria-label.
            • See the Banner Landmark Role.
            @@ -4266,7 +4266,7 @@

            Accessible Name Guidance by Role
          • Naming is necessary when two complementary landmark regions are present on the same page.
          • Naming is recommended even when one complementary region is present to help users understand the purpose of the region's content when navigating among landmark regions.
            • -
          • Use aria-labelledby if a visible title is present, otherwise use aria-label.
            • +
          • Use aria-labelledby if a visible label is present, otherwise use aria-label.
          • See the Complementary Landmark Role.

          @@ -4277,7 +4277,7 @@

          Accessible Name Guidance by Role
          • Necessary in the uncommon circumstance where two contentinfo landmark regions are present on the same page. It is otherwise optional.
            • -
          • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
            • +
          • Named using aria-labelledby if a visible label is present, otherwise with aria-label.
          @@ -4289,7 +4289,7 @@

          Accessible Name Guidance by Role dialog Required - Use aria-labelledby if a visible title is present, otherwise use aria-label. + Use aria-labelledby if a visible label is present, otherwise use aria-label. directory @@ -4297,7 +4297,7 @@

          Accessible Name Guidance by Role
          • Naming can help users understand the purpose of the directory.
            • -
          • Use aria-labelledby if a visible title is present, otherwise use aria-label.
            • +
          • Use aria-labelledby if a visible label is present, otherwise use aria-label.
          @@ -4316,7 +4316,7 @@

          Accessible Name Guidance by Role
          • Helps screen reader users understand the context and purpose of the feed.
            • -
          • Use aria-labelledby if a visible title is present, otherwise use aria-label.
            • +
          • Use aria-labelledby if a visible label is present, otherwise use aria-label.
          • See the Feed Design Pattern.
          @@ -4338,7 +4338,7 @@

          Accessible Name Guidance by Role
          • Helps screen reader users understand the context and purpose of the form landmark.
            • -
          • Use aria-labelledby if a visible title is present, otherwise use aria-label.
            • +
          • Use aria-labelledby if a visible label is present, otherwise use aria-label.
          • See the Form Landmark Role.
          @@ -4349,7 +4349,7 @@

          Accessible Name Guidance by Role
          • If the grid is applied to an HTML table element, then the accessible name can be derived from the table's caption element.
            • -
          • Otherwise, use aria-labelledby if a visible title is present, otherwise use aria-label.
            • +
          • Otherwise, use aria-labelledby if a visible label is present, otherwise use aria-label.
          @@ -4372,7 +4372,7 @@

          Accessible Name Guidance by RoleWhen using the HTML fieldset element, the accessible name can be derived from the legend element.
        • When using the HTML details element, do not provide an accessible name for this element. The user interacts with the summary element, and that can derive its accessible name from its contents.
        • When using the HTML optgroup element, use the label attribute.
          • -
        • Otherwise, use aria-labelledby if a visible title is present, otherwise use aria-label.
          • +
        • Otherwise, use aria-labelledby if a visible label is present, otherwise use aria-label.

        @@ -4408,7 +4408,7 @@

        Accessible Name Guidance by Role
      • Potentially beneficial for users of screen readers that support both list names and navigation among lists on a page.
      • Potentially a source of distracting or undesirable screen reader verbosity, especially if nested within a named container, such as a navigation region.
        • -
      • Can be named using aria-labelledby if a visible title is present, otherwise with aria-label.
        • +
      • Can be named using aria-labelledby if a visible label is present, otherwise with aria-label.

      @@ -4432,7 +4432,7 @@

      Accessible Name Guidance by Role log Required - Use aria-labelledby if a visible title is present, otherwise use aria-label. + Use aria-labelledby if a visible label is present, otherwise use aria-label. main @@ -4440,7 +4440,7 @@

      Accessible Name Guidance by Role
      • Potentially helpful for orienting assistive technology users, especially in single-page applications where main content changes happen without generating a page load event.
        • -
      • Can be named using aria-labelledby if a visible title is present, otherwise with aria-label.
        • +
      • Can be named using aria-labelledby if a visible label is present, otherwise with aria-label.
      • See the Main Landmark Role.
      @@ -4448,7 +4448,7 @@

      Accessible Name Guidance by Role marquee Required - Use aria-labelledby if a visible title is present, otherwise use aria-label. + Use aria-labelledby if a visible label is present, otherwise use aria-label. math @@ -4477,7 +4477,7 @@

      Accessible Name Guidance by Rolebutton that opens a menu conveys the purpose of the menu it opens. Since a menubar element is displayed persistently, a name on the menubar can serve that same purpose. -
    • Use aria-labelledby if a visible title is present, otherwise use aria-label.
      • +
    • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • See the Menu or Menu bar Design Pattern.

    @@ -4521,7 +4521,7 @@

    Accessible Name Guidance by Role
    • Helps screen reader users understand the context and purpose of the navigation landmark.
      • -
    • Use aria-labelledby if a visible title is present, otherwise use aria-label.
      • +
    • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • See the Navigation Landmark Role.
    @@ -4537,7 +4537,7 @@

    Accessible Name Guidance by Role
    • Naming is optional, but can help screen reader users understand the context and purpose of the note.
      • -
    • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
      • +
    • Named using aria-labelledby if a visible label is present, otherwise with aria-label.
    @@ -4585,7 +4585,7 @@

    Accessible Name Guidance by Role
    • Recommended to label a group of radio buttons.
      • -
    • Use aria-labelledby if a visible title is present, otherwise use aria-label.
      • +
    • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • See the Radio Group Design Pattern.
    @@ -4598,7 +4598,7 @@

    Accessible Name Guidance by Role
    • Helps screen reader users understand the context and purpose of the landmark.
      • -
    • Use aria-labelledby if a visible title is present, otherwise use aria-label.
      • +
    • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • See the Region Landmark Role.
    @@ -4619,7 +4619,7 @@

    Accessible Name Guidance by Role rowgroup Do Not Name - To-do: guidance + Not supported by assistive technologies. rowheader @@ -4643,7 +4643,7 @@

    Accessible Name Guidance by Role
    • Helps screen reader users understand the context and purpose of the search landmark.
      • -
    • Named using aria-labelledby if a visible title is present, otherwise with aria-label.
      • +
    • Named using aria-labelledby if a visible label is present, otherwise with aria-label.
    • See the Search Landmark Role.
    @@ -4718,7 +4718,7 @@

    Accessible Name Guidance by Role
    • Helps screen reader users understand the context and purpose of the tablist.
      • -
    • Use aria-labelledby if a visible title is present, otherwise use aria-label.
      • +
    • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • See the Carousel Design Pattenr and Tabs Design Pattern.
    @@ -4774,7 +4774,7 @@

    Accessible Name Guidance by RoleRequired
      -
    • Use aria-labelledby if a visible title is present, otherwise use aria-label.
      • +
    • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • See the Tree View Design Pattern.
    @@ -4785,7 +4785,7 @@

    Accessible Name Guidance by Role
    • If the treegrid is applied to an HTML table element, then the accessible name can be derived from the table's caption element.
      • -
    • Otherwise, use aria-labelledby if a visible title is present, otherwise use aria-label.
      • +
    • Otherwise, use aria-labelledby if a visible label is present, otherwise use aria-label.
    • See the Treegrid Design Pattern.
    From ab3f3cc12555e9d12ad4ac2ce47ab58faa12c575 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Wed, 26 Jun 2019 21:29:18 +0200 Subject: [PATCH 122/131] Recommendation for scrollbar --- aria-practices.html | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 4913fafaae..c2406c9f25 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4522,7 +4522,7 @@

    Accessible Name Guidance by Role
  • Helps screen reader users understand the context and purpose of the navigation landmark.
  • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • -
  • See the Navigation Landmark Role.
    • +
  • See the Navigation Landmark section.
    • @@ -4584,12 +4584,10 @@

    Accessible Name Guidance by RoleRequired
      -
    • Recommended to label a group of radio buttons.
      • +
    • Recommended to help assistive technology users to understand the purpose of the of the group of radio buttons.
    • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • See the Radio Group Design Pattern.
    - - To-do: What's the relationship between fieldset and radiogroup? @@ -4634,8 +4632,13 @@

    Accessible Name Guidance by Role scrollbar - Do Not Name - Use aria-controls to indicate which element the scrollbar controls. + Discretionary + +
      +
    • Naming is optional, but can potentially help screen reader users understand the purpose of the scrollbar. The purpose is also conveyed using the aria-control attribute, which is required for scrollbar.
      • +
    • Named using aria-labelledby if a visible label is present, otherwise with aria-label.
      • +
    + search From 9704274c30cd390ec07e44f00fc8b3a7295946a7 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Wed, 26 Jun 2019 21:35:25 +0200 Subject: [PATCH 123/131] Recommendation for separator --- aria-practices.html | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index c2406c9f25..f6411f0ef4 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4664,8 +4664,14 @@

    Accessible Name Guidance by Role separator - namerequired - guidance + Discretionary + +
      +
    • Recommended if there are more than one focusable separator elements on the page.
      • +
    • Can help assistive technology users understand the purpose of the separator.
      • +
    • Named using aria-labelledby if a visible label is present, otherwise with aria-label.
      • +
    + slider From 2badb95912bee9e20a8b8114b27864b33aca4c8b Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Wed, 26 Jun 2019 21:42:03 +0200 Subject: [PATCH 124/131] Recommendation for status --- aria-practices.html | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index f6411f0ef4..766fe76c74 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4676,17 +4676,35 @@

    Accessible Name Guidance by Role slider Required - guidance + +
      +
    • If the slider role is applied to an HTML input element, can be named with an HTML label element.
      • +
    • Otherwise use aria-labelledby if a visible label is present.
      • +
    • Use aria-label if a visible label is not present.
      • +
    • See the Slider Widget and Slider (Multi-Thumb) Widget sections.
      • +
    + spinbutton Required - guidance + +
      +
    • If the textbox role is applied to an HTML input element, can be named with an HTML label element.
      • +
    • Otherwise use aria-labelledby if a visible label is present.
      • +
    • Use aria-label if a visible label is not present.
      • +
    • See the Spinbutton Widget section.
      • +
    + status - namerequired - guidance + Discretionary + + Some screen readers announce the name of a status element before announcing the content of the status element. + Thus, aria-label provides a method for prefacing the visible content of a status element with text that is not displayed as part of the status element. + Using aria-label is functionally equivalent to providing off-screen text in the contents of the status element, except off-screen text would be announced by screen readers that do not support aria-label on status elements. + switch From 875a29464f733e30772bcb506c9b596511d8e4b8 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Wed, 26 Jun 2019 21:52:07 +0200 Subject: [PATCH 125/131] Recommendation for toolbar --- aria-practices.html | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 766fe76c74..75e0a86337 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4779,12 +4779,19 @@

    Accessible Name Guidance by Role timer Required - guidance + Use aria-labelledby if a visible label is present, otherwise use aria-label. toolbar - namerequired - guidance + Recommended + +
      +
    • If there are more than one toolbar elements on the page, naming is required.
      • +
    • Helps assistive technology users to understand the purpose of the toolbar, even when there is only one toolbar on the page.
      • +
    • Use aria-labelledby if a visible label is present, otherwise use aria-label.
      • +
    • See the Toolbar Pattern.
      • +
    + tooltip From dee5cec8a03537f4d277fbbd366b7a5625a7b3af Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Wed, 26 Jun 2019 21:58:22 +0200 Subject: [PATCH 126/131] Notes on how name from content works for treeitem and menuitem --- aria-practices.html | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/aria-practices.html b/aria-practices.html index 75e0a86337..b4300fb2db 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4427,7 +4427,7 @@

    Accessible Name Guidance by Role listitem Do Not Name - Not supported by assistive technologies; it is necessary to include all relevant content within the list item. + Not supported by assistive technologies; it is necessary to include relevant content within the list item. log @@ -4489,6 +4489,7 @@

    Accessible Name Guidance by Role
  • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
  • Ideally named by visible, descendant content.
    • +
  • Note: content contained within a child menu is automatically excluded from the accessible name calculation.
  • See the Menu or Menu bar Design Pattern.
    • @@ -4831,6 +4832,7 @@

    Accessible Name Guidance by Role
  • Warning! Using aria-label or aria-labelledby will hide any descendant content from assistive technologies.
  • Ideally named by visible, descendant content.
    • +
  • Note: content contained within a child group is automatically excluded from the accessible name calculation.
  • See the Tree View Design Pattern.
    • From 45f39daf4c7530910497ae9593f1ddcba86b61ab Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Wed, 26 Jun 2019 22:18:00 +0200 Subject: [PATCH 127/131] Add text and examples for how name from content excludes stuff for treeitem and menuitem --- aria-practices.html | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/aria-practices.html b/aria-practices.html index b4300fb2db..e30743ef94 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4903,11 +4903,31 @@

    Accessible name calculation

    The final step is a fallback mechanism. Generally when labeling an element, use one of the non-fallback mechanisms.

    - When calculating a name from content, the user agent walks through all descendant nodes. + When calculating a name from content, the user agent walks through all descendant nodes (except as noted below). And, when following references in an aria-labelledby attribute, it similarly walks the tree of each referenced element. Thus, the naming algorithm is recursive. The following two sections provide non-recursive and recursive examples of how the algorithm works.

    +

    When calculating a name from content for the treeitem role, descendant content of child group elements are not included.

    + 
    <ul role="tree">
+  <li role="treeitem">Fruits
+    <ul role="group">
+      <li role="treeitem">Apples</li>
+      <li role="treeitem">Bananas</li>
+      <li role="treeitem">Oranges</li>
+    </ul>
+  </li>
+</ul>
    +

    When calculating a name from content for the treeitem role, descendant content of child menu elements are not included.

    + 
    <ul role="menu">
+  <li role="menuitem">Fruits
+    <ul role="menu">
+      <li role="menuitem">Apples</li>
+      <li role="menuitem">Bananas</li>
+      <li role="menuitem">Oranges</li>
+    </ul>
+  </li>
+</ul>
    Examples of non-recursive accessible name calculation
    From f55702a60a667261f9e32f0c1fed850766785ae0 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Wed, 26 Jun 2019 22:21:27 +0200 Subject: [PATCH 128/131] Move the example with a hidden element referenced from aria-labelledby --- aria-practices.html | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index e30743ef94..506579eb23 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3920,11 +3920,13 @@
    Naming with Referenced Content Via aria-labelledby

  • It can concatenate content from multiple elements into a single name string.

  • It incorporates content from elements regardless of their visibility, i.e., it even includes content from elements with the HTML hidden attribute, CSS display: none, or CSS visibility: hidden in the calculated name string.

    - 
    <span id="night-mode-label" hidden>Night mode</span>
-  <input type="checkbox" role="switch" aria-labelledby="night-mode-label">

  • It incorporates the value of input elements, i.e., if it references a textbox, the value of the textbox is included in the calculated name string.

    • +

    An example of referencing a hidden element with aria-labelledby could be a label for a night switch control:

    + 
    <span id="night-mode-label" hidden>Night mode</span>
+  <input type="checkbox" role="switch" aria-labelledby="night-mode-label">
    +

    In some cases, the most effective name for an element is its own content combined with the content of another element. Because aria-labelledby has highest precedence in name calculation, in those situations, it is possible to use aria-labelledby to reference both the element itself and the other element. From 1db2cede8d3dd09cfc9715ed5c16167296d02743 Mon Sep 17 00:00:00 2001 From: Matt King Date: Wed, 26 Jun 2019 19:36:07 -0700 Subject: [PATCH 129/131] Add math guidance and some editorial revisions --- aria-practices.html | 106 ++++++++++++++++++++++++++++++-------------- 1 file changed, 73 insertions(+), 33 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index 506579eb23..63fd6fa613 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -3832,7 +3832,7 @@

    Naming with Child Content
    This is in contrast to other elements, such as text fields or tables, where the accessible name is a label that is presented in addition to the value or content of the element. For instance, the accessible name of a table can be derived from a caption element, and assistive technologies render both the caption and all other content contained inside the table.

    -

    Elements having one of the following roles are, by default, named by a string calculated from all their descendant content:

    +

    Elements having one of the following roles are, by default, named by a string calculated from their descendant content:

    • button
    • cell
      • @@ -3841,7 +3841,7 @@
      Naming with Child Content
    • gridcell
    • heading
    • link
      • -
    • menuitem
      • +
    • menuitem (content contained in a child menu element is excluded.)
    • menuitemcheckbox
    • menuitemradio
    • option
      • @@ -3851,10 +3851,26 @@
      Naming with Child Content
    • switch
    • tab
    • tooltip
      • -
    • treeitem
      • +
    • treeitem (content included in a child group element is excluded.)
    +

    + When calculating a name from content for an element, user agents recursively walk through each of its descendant elements, calculate a name string for each descendant, and concatenate the resulting strings. + In two special cases, certain descendants are ignored: group descendants of treeitem elements and menu descendants of menuitem elements are omitted from the calculation. + For example, in the following tree, the name of the first tree item is Fruits; Apples, Bananas, and Oranges are omitted. +

    + 
    
+<ul role="tree">
+  <li role="treeitem">Fruits
+    <ul role="group">
+      <li role="treeitem">Apples</li>
+      <li role="treeitem">Bananas</li>
+      <li role="treeitem">Oranges</li>
+    </ul>
+  </li>
+</ul>
+

    - If an element with one of the above roles is named by using aria-label or aria-labelledby, content contained in the element and its descendants is hidden from assistive technology users unless the descendant content is referenced by aria-labelledby. + If an element with one of the above roles that supports naming from child content is named by using aria-label or aria-labelledby, content contained in the element and its descendants is hidden from assistive technology users unless the descendant content is referenced by aria-labelledby. It is strongly recommended to avoid using either of these attributes to override content of one of the above elements except in rare circumstances where hiding content from assistive technology users is beneficial. In addition, in situations where visible content is hidden from assistive technology users by use of one of these attributes, thorough testing with assistive technologies is particularly important.

    @@ -3994,10 +4010,9 @@
    Naming Form Controls with the Label Element
    Naming Fieldsets with the Legend Element

    - The HTML fieldset element can be used to group form controls, which can make forms easier to navigate. - The legend element can be used to give the group a name. + The HTML fieldset element can be used to group form controls, and the legend element can be used to give the group a name. + For example, a group of radio buttons can be grouped together in a fieldset, where the legend element labels the group for the radio buttons.

    -

    For example, a group of radio buttons can be grouped together in a fieldset, where the legend element labels the group for the radio buttons.

    
   <fieldset>
     <legend>Select your starter class</legend>
@@ -4009,11 +4024,10 @@ 
    Naming Fieldsets with the Legend Element
    
           
    
             This grouping technique is particularly useful for presenting multiple choice questions.
             It enables authors to associate a question with a group of answers.
-            If a question is not programmatically associated with its answer options, assistive technology users could access the answers without being aware of the question.
+            If a question is not programmatically associated with its answer options, assistive technology users may access the answers without being aware of the question.
           
    
           
    
-            Other types of related form fields can also be grouped using fieldset and legend.
-            This helps users navigate the form group-by-group.
+            Similar benefits can be gained from grouping and naming other types of related form fields using fieldset and legend.
           
    
           
    
   <fieldset>
@@ -4069,9 +4083,16 @@ 
    Naming Tables and Figures with Captions
    
 
         
    
           
    Fallback Names Derived from Titles and Placeholders
    
-          
    When an accessible name is not provided using one of the primary techniques (e.g., the aria-label or aria-labelledby attributes), or native markup techniques (e.g., the HTML label element, or the alt attribute of the HTML img element), an accessible name can be derived from some other attributes as a fallback mechanism. In general, prefer the explicit labeling techniques described above over fallback techniques described in this section.
    
+          
    
+            When an accessible name is not provided using one of the primary techniques (e.g., the aria-label or aria-labelledby attributes), or native markup techniques (e.g., the HTML label element, or the alt attribute of the HTML img element), browsers calculate an accessible name from other attributes as a fallback mechanism.
+            It is recommended authors prefer the explicit labeling techniques described above over fallback techniques described in this section.
+          
    
 
-          
    Any HTML element can have a title attribute specified. The title attribute is used as the element's fallback accessible name. The title attribute is commonly presented visually as a tooltip when the user hovers over the element with a pointing device, which is not particularly discoverable, and is also not accessible to visual users without a pointing device.
    
+          
    
+            Any HTML element can have a title attribute specified.
+            The title attribute may be used as the element's fallback accessible name.
+            The title attribute is commonly presented visually as a tooltip when the user hovers over the element with a pointing device, which is not particularly discoverable, and is also not accessible to visual users without a pointing device.
+          
    
 
           
    For example, a fieldset element without a legend element child, but with a title attribute, gets its accessible name from the title attribute.
    
 
@@ -4081,7 +4102,10 @@ 
    Fallback Names Derived from Titles and Placeholders
    
     <label><input name="starter-class" value="blue"> Blue</label>
    </fieldset>
    
 
-          
    For the HTML input and textarea elements, the placeholder attribute is used as a fallback labeling mechanism if nothing else (including the title attribute) results in a label. It is better to use a label element, since it does not disappear visually when the user focuses the form control.
    
+          
    
+            For the HTML input and textarea elements, the placeholder attribute is used as a fallback labeling mechanism if nothing else (including the title attribute) results in a label.
+            It is better to use a label element, since it does not disappear visually when the user focuses the form control.
+          
    
 
           
    <!-- Using a <label> is recommended -->
 <label>Search <input type=search name=q></label>
@@ -4203,7 +4227,7 @@ 
    Accessible Name Guidance by Role
                   
  • Necessary in the uncommon circumstance where two banner landmark regions are present on the same page. It is otherwise optional.
    • 
                   
  • Named using aria-labelledby if a visible label is present, otherwise with aria-label.
    • 
-                  
  • See the Banner Landmark Role.
    • 
+                  
  • See the Banner Landmark section.
    • 
                 
               
             
@@ -4269,7 +4293,7 @@ 
    Accessible Name Guidance by RoleNaming is necessary when two complementary landmark regions are present on the same page.
                   
  • Naming is recommended even when one complementary region is present to help users understand the purpose of the region's content when navigating among landmark regions.
    • 
                   
  • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • 
-                  
  • See the Complementary Landmark Role.
    • 
+                  
  • See the Complementary Landmark section.
    • 
                 
               
             
@@ -4341,7 +4365,7 @@ 
    Accessible Name Guidance by Role
                   
  • Helps screen reader users understand the context and purpose of the form landmark.
    • 
                   
  • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • 
-                  
  • See the Form Landmark Role.
    • 
+                  
  • See the Form Landmark section.
    • 
                 
               
             
@@ -4443,7 +4467,7 @@ 
    Accessible Name Guidance by Role
                   
  • Potentially helpful for orienting assistive technology users, especially in single-page applications where main content changes happen without generating a page load event.
    • 
                   
  • Can be named using aria-labelledby if a visible label is present, otherwise with aria-label.
    • 
-                  
  • See the Main Landmark Role.
    • 
+                  
  • See the Main Landmark section.
    • 
                 
               
             
@@ -4455,7 +4479,13 @@ 
    Accessible Name Guidance by Role
               math
               Recommended
-              To-do: write guidance; probably similar to complementary. See issue #26.
+              
+                
      
+                  
    • If the math element has only presentational children and the accessible name is intended to convey the mathematical expression, use aria-label to provide a string that represents the expression.
      • 
+                  
    • If the math element contains navigable content that conveys the mathematical expression and a visible label for the expression is present, use aria-labelledby.
      •  
+                  
    • Otherwise, use aaria-label to name the expression, e.g., aria-label="Pythagorean Theorem".
      • 
+                
    
+              
             
             
               menu
@@ -4587,7 +4617,7 @@ 
    Accessible Name Guidance by RoleRequired
               
                 
      
-                  
    • Recommended to help assistive technology users to understand the purpose of the of the group of radio buttons.
      • 
+                  
    • Recommended to help assistive technology users understand the purpose of the group of radio buttons.
      • 
                   
    • Use aria-labelledby if a visible label is present, otherwise use aria-label.
      • 
                   
    • See the Radio Group Design Pattern.
      • 
                 
    
@@ -4609,7 +4639,7 @@ 
    Accessible Name Guidance by Role
                 Required Only If Content Insufficient
                 AND descendant of a treegrid
-                AND the row is focusable.
+                AND the row is focusable
               
               
                 When row elements are focusable in a treegrid, screen readers announce the entire contents of a row when navigating by row.
@@ -4638,7 +4668,7 @@ 
    Accessible Name Guidance by RoleDiscretionary
               
                 
      
-                  
    • Naming is optional, but can potentially help screen reader users understand the purpose of the scrollbar. The purpose is also conveyed using the aria-control attribute, which is required for scrollbar.
      • 
+                  
    • Naming is optional, but can potentially help screen reader users understand the purpose of the scrollbar. The purpose is also conveyed using the aria-controls attribute, which is required for scrollbar.
      • 
                   
    • Named using aria-labelledby if a visible label is present, otherwise with aria-label.
      • 
                 
    
               
@@ -4670,7 +4700,7 @@ 
    Accessible Name Guidance by RoleDiscretionary
               
                 
      
-                  
    • Recommended if there are more than one focusable separator elements on the page.
      • 
+                  
    • Recommended if there is more than one focusable separator element on the page.
      • 
                   
    • Can help assistive technology users understand the purpose of the separator.
      • 
                   
    • Named using aria-labelledby if a visible label is present, otherwise with aria-label.
      • 
                 
    
@@ -4684,7 +4714,7 @@ 
    Accessible Name Guidance by RoleIf the slider role is applied to an HTML input element, can be named with an HTML label element.
                   
  • Otherwise use aria-labelledby if a visible label is present.
    • 
                   
  • Use aria-label if a visible label is not present.
    • 
-                  
  • See the Slider Widget and Slider (Multi-Thumb) Widget sections.
    • 
+                  
  • See the Slider Design Pattern and the Slider (Multi-Thumb) Design Pattern.
    • 
                 
               
             
@@ -4696,7 +4726,7 @@ 
    Accessible Name Guidance by RoleIf the textbox role is applied to an HTML input element, can be named with an HTML label element.
                   
  • Otherwise use aria-labelledby if a visible label is present.
    • 
                   
  • Use aria-label if a visible label is not present.
    • 
-                  
  • See the Spinbutton Widget section.
    • 
+                  
  • See the Spinbutton Design Pattern.
    • 
                 
               
             
@@ -4789,7 +4819,7 @@ 
    Accessible Name Guidance by RoleRecommended
               
                 
      
-                  
    • If there are more than one toolbar elements on the page, naming is required.
      • 
+                  
    • If there is more than one toolbar element on the page, naming is required.
      • 
                   
    • Helps assistive technology users to understand the purpose of the toolbar, even when there is only one toolbar on the page.
      • 
                   
    • Use aria-labelledby if a visible label is present, otherwise use aria-label.
      • 
                   
    • See the Toolbar Pattern.
      • 
@@ -4905,13 +4935,17 @@ 
      Accessible name calculation
      
           The final step is a fallback mechanism. Generally when labeling an element, use one of the non-fallback mechanisms.
         
      
         
      
-          When calculating a name from content, the user agent walks through all descendant nodes (except as noted below).
+          When calculating a name from content, the user agent walks through all descendant nodes except in the cases of treeitem and menuitem as described below.
           And, when following references in an aria-labelledby attribute, it similarly walks the tree of each referenced element.
           Thus, the naming algorithm is recursive.
-          The following two sections provide non-recursive and recursive examples of how the algorithm works.
+          The following two sections explain non-recursive and recursive examples of how the algorithm works.
+        
      
+        
      
+          When calculating a name from content for the treeitem role, descendant content of child group elements are not included.
+          For example, in the following tree, the name of the first tree item is Fruits; Apples, Bananas, and Oranges are automatically omitted.
         
      
-        
      When calculating a name from content for the treeitem role, descendant content of child group elements are not included.
      
-        
      <ul role="tree">
+        
      
+<ul role="tree">
   <li role="treeitem">Fruits
     <ul role="group">
       <li role="treeitem">Apples</li>
@@ -4919,9 +4953,14 @@ 
      Accessible name calculation
      
       <li role="treeitem">Oranges</li>
     </ul>
   </li>
-</ul>
      
-        
      When calculating a name from content for the treeitem role, descendant content of child menu elements are not included.
      
-        
      <ul role="menu">
+</ul>
+        
      
+        
      
+          Similarly, when calculating a name from content for the menuitem role, descendant content of child menu elements are not included.
+          So, the name of the first parent menuitem in the following menu is Fruits.
+        
      
+        
      
+<ul role="menu">
   <li role="menuitem">Fruits
     <ul role="menu">
       <li role="menuitem">Apples</li>
@@ -4929,7 +4968,8 @@ 
      Accessible name calculation
      
       <li role="menuitem">Oranges</li>
     </ul>
   </li>
-</ul>
      
+</ul>
+        
      
 
         
      
           
      Examples of non-recursive accessible name calculation
      

From 826e12b9aadd3252ddd42a8dc50bd2cea7b6992b Mon Sep 17 00:00:00 2001
From: Matt King 
Date: Wed, 26 Jun 2019 20:39:22 -0700
Subject: [PATCH 130/131] Add link to feedback issue 1050

---
 aria-practices.html | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/aria-practices.html b/aria-practices.html
index 63fd6fa613..b10e3c7018 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -3695,6 +3695,11 @@ 
      Examples
      
 
   
      
     
      Providing Accessible Names and Descriptions
      
+    
      
+      Note: This is a draft of a new section.
+      Please provide feedback in
+      issue 1050.
+    
      
     
      
       Providing elements with accessible names, and where appropriate, accessible descriptions is one of the most fundamental and important responsibilities authors have when developing accessible web experiences.
       While doing so is straightforward for most elements, technical mistakes that can have devastating impacts on users of assistive technologies are easy to make and unfortunately common.

From 299cab5e208d6edce4e3a47c735803fe69976844 Mon Sep 17 00:00:00 2001
From: Simon Pieters 
Date: Thu, 27 Jun 2019 16:32:33 +0200
Subject: [PATCH 131/131] Typos

---
 aria-practices.html | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/aria-practices.html b/aria-practices.html
index b10e3c7018..4ce1dbba82 100644
--- a/aria-practices.html
+++ b/aria-practices.html
@@ -4487,7 +4487,7 @@ 
      Accessible Name Guidance by Role
                 
        
                   
      • If the math element has only presentational children and the accessible name is intended to convey the mathematical expression, use aria-label to provide a string that represents the expression.
        • 
-                  
      • If the math element contains navigable content that conveys the mathematical expression and a visible label for the expression is present, use aria-labelledby.
        •  
+                  
      • If the math element contains navigable content that conveys the mathematical expression and a visible label for the expression is present, use aria-labelledby.
        • 
                   
      • Otherwise, use aaria-label to name the expression, e.g., aria-label="Pythagorean Theorem".
        • 
                 
      
               
@@ -4635,7 +4635,7 @@ 
      Accessible Name Guidance by Role
                   
    • Helps screen reader users understand the context and purpose of the landmark.
      • 
                   
    • Use aria-labelledby if a visible label is present, otherwise use aria-label.
      • 
-                  
    • See the Region Landmark Role.
      • 
+                  
    • See the Region Landmark section.
      • 
                 
    
             
             
@@ -4685,7 +4685,7 @@ 
    Accessible Name Guidance by Role
                   
  • Helps screen reader users understand the context and purpose of the search landmark.
    • 
                   
  • Named using aria-labelledby if a visible label is present, otherwise with aria-label.
    • 
-                  
  • See the Search Landmark Role.
    • 
+                  
  • See the Search Landmark section.
    • 
                 
               
             
@@ -4784,7 +4784,7 @@ 
    Accessible Name Guidance by Role
                   
  • Helps screen reader users understand the context and purpose of the tablist.
    • 
                   
  • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • 
-                  
  • See the Carousel Design Pattenr and Tabs Design Pattern.
    • 
+                  
  • See the Carousel Design Pattern and Tabs Design Pattern.
    • 
                 
               
             
@@ -4794,7 +4794,7 @@ 
    Accessible Name Guidance by Role