From de49b6102d87213d84ae17be65c5b54cd76af3cc Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Thu, 28 Feb 2019 14:42:26 +0100 Subject: [PATCH 01/55] 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 02/55] 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 03/55] 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 04/55] 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 07/55] 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 08/55] 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 09/55] 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 10/55] 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 11/55] 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 14/55] 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 15/55] 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 16/55] 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 17/55] 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 18/55] 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 19/55] 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 20/55] 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 21/55] 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 22/55] 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 23/55] 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 24/55] 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 25/55] 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 26/55] 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 27/55] 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 28/55] 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 4b3c7b3927add742b9ca43f008801b9eb2e3a175 Mon Sep 17 00:00:00 2001 From: JaEun Jemma Ku Date: Thu, 16 May 2019 22:10:55 -0500 Subject: [PATCH 29/55] set up meter example --- examples/meter/meter.html | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 examples/meter/meter.html diff --git a/examples/meter/meter.html b/examples/meter/meter.html new file mode 100644 index 0000000000..e69de29bb2 From fc34fc3a452ad6439dafc3777ec21a6c2db35f84 Mon Sep 17 00:00:00 2001 From: JaEun Jemma Ku Date: Thu, 16 May 2019 22:17:49 -0500 Subject: [PATCH 30/55] copy of google meter example --- examples/meter/meter.html | 68 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/examples/meter/meter.html b/examples/meter/meter.html index e69de29bb2..b731a04f68 100644 --- a/examples/meter/meter.html +++ b/examples/meter/meter.html @@ -0,0 +1,68 @@ + + + + Meter Blueprint + + + + +

    This meter changes its value randomly every 5 seconds.

    +
    + +
    + + From 4016485df5fdf0b0a9833f41074ce0c82b1c8d05 Mon Sep 17 00:00:00 2001 From: JaEun Jemma Ku Date: Thu, 16 May 2019 22:24:26 -0500 Subject: [PATCH 31/55] recover the memory of APG example set up --- examples/meter/css/meter.css | 13 +++++++++++++ examples/meter/meter.html | 16 ++-------------- 2 files changed, 15 insertions(+), 14 deletions(-) create mode 100644 examples/meter/css/meter.css diff --git a/examples/meter/css/meter.css b/examples/meter/css/meter.css new file mode 100644 index 0000000000..18a5519086 --- /dev/null +++ b/examples/meter/css/meter.css @@ -0,0 +1,13 @@ + +[role=meter] { + position: relative; + border: 4px solid black; + height: 20px; + width: 200px; +} + +#fill { + position: absolute; + height: 100%; + background-color: black; +} diff --git a/examples/meter/meter.html b/examples/meter/meter.html index b731a04f68..a34642b33b 100644 --- a/examples/meter/meter.html +++ b/examples/meter/meter.html @@ -2,20 +2,8 @@ Meter Blueprint - + + + + + + + + + + + + +
    +

    Meter Example

    + The following meter examples demonstrate the meter design pattern. + +
    +

    Example

    + + + +
    +

    This meter changes its value randomly every 5 seconds.

    +
    + +
    +
    + +
    +
    +

    Keyboard Support

    + + + + + + + + + + + + + + + + + + +
    KeyFunction
    HomeSets meter to its minimum value? +
    EndSets meter to its maximum value?
    +
    + +
    +

    Role, Property, State, and Tabindex Attributes

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    RoleAttributeElementUsage
    meter + div + +
      +
    • Identifies the element as a meter widget.
      • +
    +
    + tabindex="0" + + div + +
      +
    • Includes the element in the tab sequence.
      • +
    +
    aria-valuemin="NUMBER"div +
      +
    • Specifies a numeric value that is the minimum value the meter can have.
      • +
    +
    aria-valuemax="NUMBER"div +
      +
    • Specifies a numeric value that is the maximum value the meter can have.
      • +
    +
    aria-valuenow="NUMBER"div +
      +
    • A numeric value that is the current value of the meter
      • +
    +
    aria-labeldiv +
      +
    • Identifies the accessible name for meter widget.
      • +
    +
    presentation + div + +
      +
    • Identifies that the visual indicator of meter value is being used only for visual presentation.
      • + +
    +
    +
    + +
    +

    Javascript and CSS Source Code

    + + +
    + +
    +

    HTML Source Code

    + + + +
    + + + - - -

    This meter changes its value randomly every 5 seconds.

    -
    - -
    - +
    +
    + + + diff --git a/examples/meter/meter.js b/examples/meter/meter.js new file mode 100644 index 0000000000..7c060c9efc --- /dev/null +++ b/examples/meter/meter.js @@ -0,0 +1,32 @@ +/** @type {!Element} Meter element. */ +let meterEl; +/** @type {!Element} Element visually filling the meter. */ +let visualFillEl; +/** @type {number} Minimum value. */ +let minUsage; +/** @type {number} Maximum value. */ +let maxUsage; +/** @type {number} Current value. */ +let usage; + +/** Set the value randomly between the minimum and maximum. */ +function randomizeUsage() { + const range = maxUsage - minUsage; + usage = Math.floor((Math.random() * range) + minUsage); + meterEl.setAttribute('aria-valuenow', usage); + render(); +} +function render() { + const asPercentage = (100 * usage) / (maxUsage - minUsage); + visualFillEl.style.width = asPercentage + '%'; +} +function init() { + meterEl = document.querySelector('[role=meter]'); + visualFillEl = document.getElementById('fill'); + minUsage = Number(meterEl.getAttribute('aria-valuemin')); + maxUsage = Number(meterEl.getAttribute('aria-valuemax')); + usage = Number(meterEl.getAttribute('aria-valuenow')); + render(); + setInterval(randomizeUsage, 5000); +} +window.addEventListener('load', init, false); From 1f7d940ca9872ff2f240c65ce4520338fbdbd3c6 Mon Sep 17 00:00:00 2001 From: Ku Date: Tue, 1 Oct 2019 09:40:43 -0500 Subject: [PATCH 34/55] Removed presentation role and updated keyboard section --- examples/meter/meter.html | 35 ++--------------------------------- 1 file changed, 2 insertions(+), 33 deletions(-) diff --git a/examples/meter/meter.html b/examples/meter/meter.html index 7eb096a45b..5d51a2cada 100644 --- a/examples/meter/meter.html +++ b/examples/meter/meter.html @@ -38,7 +38,7 @@

    Example

    This meter changes its value randomly every 5 seconds.

    - +
    @@ -46,25 +46,7 @@

    Example

    Keyboard Support

    - - - - - - - - - - - - - - - - - -
    KeyFunction
    HomeSets meter to its minimum value? -
    EndSets meter to its maximum value?
    +

    It would not have any keyboard support since this is system generated information.

    @@ -145,19 +127,6 @@

    Role, Property, State, and Tabindex Attributes

- - presentation - - - div - - -
    -
  • Identifies that the visual indicator of meter value is being used only for visual presentation.
    • - -
- - From 40e69e02c34fdaa9326ec85754483d66114f07d7 Mon Sep 17 00:00:00 2001 From: Ku Date: Tue, 1 Oct 2019 13:42:54 -0500 Subject: [PATCH 35/55] change aria-label from disk usage to cpu usage --- examples/meter/meter.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/meter/meter.html b/examples/meter/meter.html index 5d51a2cada..6ec03f2cf2 100644 --- a/examples/meter/meter.html +++ b/examples/meter/meter.html @@ -37,7 +37,7 @@

Example

This meter changes its value randomly every 5 seconds.

+ aria-label="CPU Usage">
From cf069f9f3c794b793f242cd83bb7f43cb95a5479 Mon Sep 17 00:00:00 2001 From: Ku Date: Tue, 1 Oct 2019 13:59:03 -0500 Subject: [PATCH 36/55] removed tab index and updated keyboard interaction info --- examples/meter/meter.html | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/examples/meter/meter.html b/examples/meter/meter.html index 6ec03f2cf2..5f3477d51e 100644 --- a/examples/meter/meter.html +++ b/examples/meter/meter.html @@ -46,7 +46,7 @@

Example

Keyboard Support

-

It would not have any keyboard support since this is system generated information.

+

No keyboard interaction needed.

@@ -73,20 +73,6 @@

Role, Property, State, and Tabindex Attributes

- - - - tabindex="0" - - - div - - -
    -
  • Includes the element in the tab sequence.
    • -
- - aria-valuemin="NUMBER" From 6df571d86b378c660c195d4830929c5fefb501aa Mon Sep 17 00:00:00 2001 From: Ku Date: Tue, 1 Oct 2019 14:11:40 -0500 Subject: [PATCH 37/55] changed the word, example from plural to single --- examples/meter/meter.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/meter/meter.html b/examples/meter/meter.html index 5f3477d51e..423f608fef 100644 --- a/examples/meter/meter.html +++ b/examples/meter/meter.html @@ -27,7 +27,7 @@

Meter Example

- The following meter examples demonstrate the meter design pattern. + The following meter example demonstrates the meter design pattern.

Example

From 35d8e46dc25ae72f40410b88670e2cf67e71c1d7 Mon Sep 17 00:00:00 2001 From: Ku Date: Tue, 1 Oct 2019 15:36:27 -0500 Subject: [PATCH 38/55] changed aria-label as aria-labelledby --- examples/meter/meter.html | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/examples/meter/meter.html b/examples/meter/meter.html index 423f608fef..35fa01c60e 100644 --- a/examples/meter/meter.html +++ b/examples/meter/meter.html @@ -27,7 +27,7 @@

Meter Example

- The following meter example demonstrates the meter design pattern. + The following meter example demonstrates the meter design pattern.

Example

@@ -36,8 +36,9 @@

Example

This meter changes its value randomly every 5 seconds.

-
+

Central Processing Unit(CPU) Usage

+
@@ -103,9 +104,9 @@

Role, Property, State, and Tabindex Attributes

- + - aria-label + aria-labelledby div
    From f9a89cb6c35f1b8b6e257025471d03395c100b0c Mon Sep 17 00:00:00 2001 From: Ku Date: Tue, 1 Oct 2019 15:56:57 -0500 Subject: [PATCH 39/55] changed CPU valuemax to 100 --- examples/meter/meter.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/meter/meter.html b/examples/meter/meter.html index 35fa01c60e..25fd92e037 100644 --- a/examples/meter/meter.html +++ b/examples/meter/meter.html @@ -37,7 +37,7 @@

    Example

    This meter changes its value randomly every 5 seconds.

    Central Processing Unit(CPU) Usage

    -
    From 0292f55d18e3f520697a6cf23674b76d5df615a0 Mon Sep 17 00:00:00 2001 From: Ku Date: Tue, 8 Oct 2019 14:10:41 -0500 Subject: [PATCH 40/55] fix conflict --- aria-practices.html | 1640 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 1334 insertions(+), 306 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index d85e0e7b5f..dd6e60d824 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.
@@ -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. @@ -480,11 +480,6 @@

    WAI-ARIA Roles, States, and Properties

  • Up Arrow (Optional): If the popup is available, places focus on the last focusable element in the popup.
    • -
  • Escape: Dismisses the popup if it is visible. Optionally, clears the textbox.
    • +
  • Escape: Dismisses the popup if it is visible. Optionally, if the popup is hidden before Escape is pressed, clears the textbox.
  • Enter: If an autocomplete suggestion is automatically selected, accepts the suggestion either by placing the input cursor at the end of the accepted value in the textbox or by performing a default action on the value. For example, in a messaging application, the default action may be to add the accepted value to a list of message recipients and then clear the textbox so the user can add another recipient. @@ -1045,7 +1040,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: @@ -1095,8 +1090,11 @@

    Dialog (Modal)

    -

    Example

    -

    Modal Dialog Example

    +

    Examples

    +
    @@ -1216,6 +1214,7 @@

    Examples

    @@ -1341,7 +1340,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.
    • @@ -1386,7 +1385,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. @@ -1496,7 +1495,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 +1688,7 @@

      WAI-ARIA Roles, States, and Properties

  • - 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.
  • 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.
    • @@ -1834,7 +1833,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.
        • @@ -2072,7 +2071,7 @@

        WAI-ARIA Roles, States, and Properties

      • 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.
      • All separators should have aria-orientation consistent with the separator's orientation.
      • - 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.
      • @@ -2151,43 +2150,6 @@

        WAI-ARIA Roles, States, and Properties

    -
    -

    Meter or Guage

    -

    - A meter is a non-interactive scalar measurement within a known range, or a fractional value; - for example disk usage, the relevance of a query result, or the fraction of a voting population - to have selected a particular candidate. This can also be known as a gauge. -

    -
    -

    Examples

    -

    Meter Example

    -
    -
    -

    Keyboard Interaction

    -

    Not applicable

    -
    -
    -

    WAI-ARIA Roles, States, and Properties

    -
      -
    • The element serving as the meter has role meter.
      • -
    • The meter element has the aria-valuenow property set to a decimal value representing the current value of the meter.
      • -
    • The meter element has the aria-valuemin property set to a decimal value representing the minimum allowed value of the meter.
      • -
    • The meter element has the aria-valuemax property set to a decimal value representing the maximum allowed value of the meter.
      • -
    • - If the value of aria-valuenow is not user-friendly, e.g., the day of the week is represented by a number, the - aria-valuetext - property is set to a string that makes the slider value understandable, e.g., "Monday". -
      • -
    • - If the meter has a visible label, it is referenced by - aria-labelledby on the meter element. - Otherwise, the meter element has a label provided by - aria-label. -
      • -
    -
    -
    -

    Radio Group

    @@ -2289,13 +2251,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 @@ -2305,19 +2265,17 @@

      WAI-ARIA Roles, States, and Properties

      set to false.
    • - 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 - 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 @@ -2395,8 +2353,8 @@

      Slider (Multi-Thumb)

      with two or more thumbs that each set a value in a group of related values. For example, in a product search, a two-thumb slider could be used to enable users to set the minimum and maximum price limits for the search. In many two-thumb sliders, the thumbs are not allowed to pass one another, such as when the slider sets the minimum and maximum values for a range. - For example, in a price range selector, the maxmimum value of the thumb that sets the lower end of the range is limited by the current value of the thumb that sets the upper end of the range. - Conversly the minimum value of the upper end thumb is limited by the current value of the lower end thumb. + For example, in a price range selector, the maximum value of the thumb that sets the lower end of the range is limited by the current value of the thumb that sets the upper end of the range. + Conversely, the minimum value of the upper end thumb is limited by the current value of the lower end thumb. However, in some multi-thumb sliders, each thumb sets a value that does not depend on the other thumb values.

      @@ -2461,10 +2419,7 @@

      Spinbutton

      Example

      -

      - Work to develop a spinbutton example is tracked by - issue 125. -

      +

      Date Picker Spin Button Example: Illustrates a date picker made from thre spin buttons for day, month, and year.

      @@ -2570,7 +2525,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.
    • @@ -2627,7 +2582,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: @@ -2686,7 +2641,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.
      • @@ -2718,7 +2673,7 @@

      Toolbar

    • In toolbars with multiple rows of controls, Left Arrow and Right Arrow can provide navigation that wraps from row to row, leaving the option of reserving vertical arrow keys for operating controls.
    -
  • Avoid including controls whose operation requires the pair of arrow keys used for toolbar navigation. If unavoidable, include only one such control and make it the last element in the toolbar. For example, in a horzontal toolbar, a textbox could be included as the last element.
    • +
  • Avoid including controls whose operation requires the pair of arrow keys used for toolbar navigation. If unavoidable, include only one such control and make it the last element in the toolbar. For example, in a horizontal toolbar, a textbox could be included as the last element.
  • Use toolbar as a grouping element only if the group contains 3 or more controls.
    • @@ -3013,11 +2968,6 @@

    WAI-ARIA Roles, States, and Properties

    Treegrid

    -

    - This pattern is new in APG 1.1 Release 2. - Please provide feedback in - issue 793. -

    A treegrid widget presents a hierarchical data grid consisting of tabular information that is editable or interactive. Any row in the hierarchy may have child rows, and rows with children may be expanded or collapsed to show or hide the children. @@ -3219,7 +3169,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.
    • @@ -3270,7 +3220,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.

    @@ -3304,7 +3254,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. @@ -3321,27 +3271,27 @@

    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.

    - This section explains how HTML5 sectioning elements and ARIA landmark roles + This section explains how HTML sectioning elements and ARIA landmark roles are used to make it easy for assistive technology users to understand the meaning of the layout of a page.

    -

    HTML5 Sectioning Elements

    +

    HTML Sectioning Elements

    - Several HTML5 sectioning elements automatically create ARIA landmark regions. + Several HTML sectioning elements automatically create ARIA landmark regions. So, in order to provide assistive technology users with a logical view of a page, - it is important to understand the effects of using HTML5 sectioning elements. - More information on HTML5 element role mapping. + it is important to understand the effects of using HTML sectioning elements. + [[HTML-ARIA]] contains more information on HTML element role mapping.

    - + - + @@ -3419,7 +3369,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.
    • @@ -3460,12 +3410,12 @@

    Banner

    -
    HTML5 Techniques
    +
    HTML Techniques
      -
    • The HTML5 header element defines a banner landmark when its context is the body element.
      • +
    • The HTML header element defines a banner landmark when its context is the body element.
    • - The HTML5 header element is not considered a banner landmark when it is descendant of any of following elements (see HTML Accessibility Mappings [[HTML-AAM]]): + The HTML header element is not considered a banner landmark when it is descendant of any of following elements (see HTML Accessibility Mappings [[HTML-AAM]]):
      • article
      • aside
        • @@ -3478,7 +3428,7 @@
        HTML5 Techniques
        ARIA Techniques
        -

        If the HTML5 header element technique is not being used, a role="banner" attribute should be used to define a banner landmark.

        +

        If the HTML header element technique is not being used, a role="banner" attribute should be used to define a banner landmark.

    @@ -3504,13 +3454,13 @@

    Complementary

    -
    HTML5 Technique
    +
    HTML Technique
    -

    Use the HTML5 aside element to define a complementary landmark.

    +

    Use the HTML aside element to define a complementary landmark.

    ARIA Technique
    -

    If the HTML5 aside element technique is not being used, use a role="complementary" attribute to define a complementary landmark.

    +

    If the HTML aside element technique is not being used, use a role="complementary" attribute to define a complementary landmark.

    @@ -3539,13 +3489,13 @@

    Contentinfo

    -
    HTML5 Techniques
    +
    HTML Techniques
      -
    • The HTML5 footer element defines a contentinfo landmark when its context is the body element.
      • +
    • The HTML footer element defines a contentinfo landmark when its context is the body element.
    • - The HTML5 footer element is not considered a contentinfo landmark when it is descendant of any of following elements (see HTML Accessibility Mappings [[HTML-AAM]]): + The HTML footer element is not considered a contentinfo landmark when it is descendant of any of following elements (see HTML Accessibility Mappings [[HTML-AAM]]):
      • article
      • aside
        • @@ -3558,7 +3508,7 @@
        HTML5 Techniques
        ARIA Technique
        -

        If the HTML5 footer element technique is not being used, a role="contentinfo" attribute should be used to define a contentinfo landmark.

        +

        If the HTML footer element technique is not being used, a role="contentinfo" attribute should be used to define a contentinfo landmark.

    @@ -3597,9 +3547,9 @@

    Form

    -
    HTML5 Techniques
    +
    HTML Techniques
    -

    The HTML5 form element defines a form landmark when it has an accessible name (e.g. aria-labelledby, aria-label or title).

    +

    The HTML form element defines a form landmark when it has an accessible name (e.g. aria-labelledby, aria-label or title).

    ARIA Technique
    @@ -3630,13 +3580,13 @@

    Main

    -
    HTML5 Technique
    +
    HTML Technique
    -

    Use the HTML5 main element to define a main landmark.

    +

    Use the HTML main element to define a main landmark.

    ARIA Technique
    -

    If the HTML5 main element technique is not being used, use a role="main" attribute to define a main landmark.

    +

    If the HTML main element technique is not being used, use a role="main" attribute to define a main landmark.

    @@ -3658,13 +3608,13 @@

    Navigation

    -
    HTML5 Technique
    +
    HTML Technique
    -

    Use the HTML5 nav element to define a navigation landmark.

    +

    Use the HTML nav element to define a navigation landmark.

    ARIA Technique
    -

    If the HTML5 nav element technique is not being used, use a role="navigation" attribute to define a navigation landmark.

    +

    If the HTML nav element technique is not being used, use a role="navigation" attribute to define a navigation landmark.

    @@ -3689,13 +3639,13 @@

    Region

    -
    HTML5 Technique
    +
    HTML Technique
    -

    The HTML5 section element defines a region landmark when it has an accessible name (e.g. aria-labelledby, aria-label or title).

    +

    The HTML section element defines a region landmark when it has an accessible name (e.g. aria-labelledby, aria-label or title).

    ARIA Technique
    -

    If the HTML5 section element technique is not being used, use a role="region" attribute to define a region landmark.

    +

    If the HTML section element technique is not being used, use a role="region" attribute to define a region landmark.

    @@ -3717,8 +3667,8 @@

    Search

    -
    HTML5 Technique
    -

    There is no HTML5 element that defines a search landmark.

    +
    HTML Technique
    +

    There is no HTML element that defines a search landmark.

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

      -
    • 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 form controls with the label element.
        • +
      • Naming fieldsets with the legend element.
        • +
      • Naming tables and figures with captions.
        • +
      • Fallback names derived from titles and placeholders.
        • +
      +
      • +
    • Describing: +
        +
      • Describing by referencing content with aria-describedby.
        • +
      • Describing tables and figures with captions.
        • +
      • Descriptions derived from titles.
        • +
      +
    @@ -3775,8 +3734,15 @@

    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. +

    +

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

    @@ -3784,8 +3750,8 @@

    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 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. +The sections on accessible name calculation and accessible description calculation explain the algorithms and how they implement precedence. +However, most authors do not need such 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.

    @@ -3797,8 +3763,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.

    @@ -3810,33 +3776,39 @@

    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 for form elements and caption element for tables. While less flexible, their simplicity and reliance on visible text help ensure robust accessible experiences. + Several of the naming techniques highlight specific accessibility advantages of using HTML features instead of ARIA attributes.

    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. + 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.

    -
    Rule 5: Compose Brief, Useful Names
    +
    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 section on Composing Effective and User-friendly Accessible Names provides guidance for balancing brevity and clarity.

    @@ -3854,11 +3826,11 @@
    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:

    +

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

    • button
    • cell
      • @@ -3867,7 +3839,7 @@
      Naming with Child Content
    • gridcell
    • heading
    • link
      • -
    • menuitem
      • +
    • menuitem (content contained in a child menu element is excluded.)
    • menuitemcheckbox
    • menuitemradio
    • option
      • @@ -3877,10 +3849,24 @@
      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, 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 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.

    @@ -3889,33 +3875,31 @@
    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 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>

    - 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.
    @@ -3927,50 +3911,50 @@
    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.

    - 
    
-  <span id="night-mode-label">Night mode</span>
-  <span role="switch" aria-checked="false" tabindex="0" aria-labelledby="night-mode-label"></span>
-
    + 
    <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 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.

    - 
    
-  <label for="night-mode">Night mode</label>
-  <input type="checkbox" role="switch" id="night-mode">
-
    + 
    <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, 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 the HTML hidden attribute, CSS display: none, or CSS 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.

    +

    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. - 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>
-  <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>
-
    + 
    <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. + 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.

    + 
    <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 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-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. 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.
      5. +
    5. 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.
      6. +
    6. 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.
    7. - 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.
    8. 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.
      9. @@ -3978,106 +3962,1079 @@
      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

    +
    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. +

    +

    + 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 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. +

    + 
    <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. +

    -
    -
    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.

    +
    +
    Naming Fieldsets with the Legend Element
    +

    + 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. +

    + 
    <fieldset>
+  <legend>Select your starter class</legend>
+  <label><input type="radio" name="starter-class" value="green"> Green</label>
+  <label><input type="radio" name="starter-class" value="red"> Red</label>
+  <label><input type="radio" 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 may access the answers without being aware of the question. +

    +

    + Similar benefits can be gained from grouping and naming other types of related form fields using fieldset and legend. +

    + 
    <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
    +

    + The accessible name for 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 they are about, how to read them, and sometimes giving them numbers used to refer to them in surrounding prose. + Captions can help all users better understand content, but are especially helpful to 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. + If the table element does not have aria-label or aria-labelledby, then the caption will be used as the accessible name. + For example, the accessible name of the following table is Special opening hours. +

    + 
    <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.

    + 
    <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>
    +

    Note: Above table content is from 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.

    +

    + If a table is named using aria-label or aria-labelledby, then a caption element, if present, will become an accessible description. + For an example, see Describing Tables and Figures with Captions. +

    +

    + Similarly, an 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>
    +

    + Like with table elements, if a figure is not named using aria-label or aria-labelledby, the content of the figcaption element will be used as the accessible name. + However unlike table elements, if the figcaption element is not used for the name, it does not become an accessible description unless it is referenced by aria-describedby. + Nevertheless, assistive technologies will render the content of a figcaption regardless of whether it is used as a name, description, or neither. +

    +

    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.

    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), browsers calculate an accessible name from other attributes as a fallback mechanism. + Because the attributes used in fallback name calculation are not intended for naming, they typically yield low quality accessible names that are not effective. +So, As advised by Rule 4: Avoid Browser Fallback, 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 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.

    + + 
    <fieldset title="Select your starter class">
+  <label><input type="radio" name="starter-class" value="green"> Green</label>
+  <label><input type="radio" name="starter-class" value="red"> Red</label>
+  <label><input type="radio" 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">

    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 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. + 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, 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. +
      • +
    • + 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 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. + Do not end names with a period; they are not sentences. +
      • +
    -

    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.
      • -
    +

    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 table below lists all ARIA roles and provides the following information for each : +

    +
    +
    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. + 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.
      • +
    +
    +
    Guidance:
    +
    + Provides information to help determine if providing a name is beneficial, and if so, describes any recommended techniques. +
    +
    +
    Default landmark roles for HTML5 sectioning elementsDefault landmark roles for HTML sectioning elements
    HTML5 ElementHTML Element Default Landmark Role
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    roleNecessity of NamingGuidance
    alertDiscretionary + 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. +
    alertdialogRequiredUse aria-labelledby if a visible label is present, otherwise use aria-label.
    applicationRequiredUse aria-labelledby if a visible label is present, otherwise use aria-label.
    articleRecommended +
      +
    • Recommended to distinguish articles from one another; helps users when navigating among articles.
      • +
    • Use aria-labelledby if a visible label is present, otherwise use aria-label.
      • +
    +
    bannerDiscretionary +
      +
    • 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 section.
      • +
    +
    buttonRequired Only If Content Insufficient +
      +
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • +
    • Ideally named by visible, descendant content.
      • +
    +
    cellRequired Only If Content Insufficient +
      +
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • +
    • Ideally named by visible, descendant content.
      • +
    • Note that a name is not required; assistive technologies expect an empty cell in a table to be represented by an empty name.
      • +
    • Note that associated row or column headers do not name a cell; the name of a cell in a table is its content. Headers are complementary information.
      • +
    +
    checkboxRequired 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", use a label element.
      • +
    • Otherwise, reference visible content via aria-labelledby.
      • +
    +
    columnheaderRequired 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.
      • +
    +
    comboboxRequired +
      +
    • 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 label is present.
      • +
    • Use aria-label if a visible label is not present.
      • +
    +
    complementaryRecommended +
      +
    • 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 label is present, otherwise use aria-label.
      • +
    • See the Complementary Landmark section.
      • +
    +
    contentinfoDiscretionary +
      +
    • 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 label is present, otherwise with aria-label.
      • +
    +
    definitionRecommendedReference the term being defined with role="term", using aria-labelledby.
    dialogRequiredUse aria-labelledby if a visible label is present, otherwise use aria-label.
    directoryDiscretionary +
      +
    • Naming can help users understand the purpose of the directory.
      • +
    • Use aria-labelledby if a visible label is present, otherwise use aria-label.
      • +
    +
    documentDiscretionary + 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. +
    feedRecommended +
      +
    • Helps screen reader users understand the context and purpose of the feed.
      • +
    • Use aria-labelledby if a visible label is present, otherwise use aria-label.
      • +
    • See the Feed Design Pattern.
      • +
    +
    figureRecommended +
      +
    • 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.
      • +
    +
    formRecommended +
      +
    • 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 section.
      • +
    +
    gridRequired +
      +
    • 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 label is present, otherwise use aria-label.
      • +
    +
    gridcellRequired Only If Content Insufficient +
      +
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • +
    • Ideally named by visible, descendant content.
      • +
    • Note that a name is not required; assistive technologies expect an empty cell in a grid to be represented by an empty name.
      • +
    • Note that associated row or column headers do not name a gridcell; the name of a cell in a grid is its content. Headers are complementary information.
      • +
    +
    groupDiscretionary +
      +
    • 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 label is present, otherwise use aria-label.
      • +
    +
    headingRequired Only If Content Insufficient +
      +
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • +
    • Ideally named by visible, descendant content.
      • +
    +
    imgRequiredFor the HTML img element, use the alt attribute. For other elements with the img role, use aria-labelledby or aria-label.
    linkRequired Only If Content Insufficient +
      +
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • +
    • Ideally named by visible, descendant content.
      • +
    +
    listDiscretionary +
      +
    • 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 label is present, otherwise with aria-label.
      • +
    +
    listboxRequired +
      +
    • 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.
      • +
    +
    listitemDo Not NameNot supported by assistive technologies; it is necessary to include relevant content within the list item.
    logRequiredUse aria-labelledby if a visible label is present, otherwise use aria-label.
    mainDiscretionary +
      +
    • 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 section.
      • +
    +
    marqueeRequiredUse aria-labelledby if a visible label is present, otherwise use aria-label.
    mathRecommended +
      +
    • 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".
      • +
    +
    menuRecommended +
      +
    • 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.
      • +
    +
    menubarRecommended +
      +
    • + 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 label is present, otherwise use aria-label.
      • +
    • See the Menu or Menu bar Design Pattern.
      • +
    +
    menuitemRequired 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.
      • +
    • Note: content contained within a child menu is automatically excluded from the accessible name calculation.
      • +
    • See the Menu or Menu bar Design Pattern.
      • +
    +
    menuitemcheckboxRequired 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.
      • +
    +
    menuitemradioRequired 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.
      • +
    +
    navigationRecommended +
      +
    • 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 section.
      • +
    +
    noneDo Not NameAn element with role="none" is not part of the accessibility tree (except in error cases). Do not use aria-labelledby or aria-label.
    noteDiscretionary +
      +
    • Naming is optional, but can help screen reader users understand the context and purpose of the note.
      • +
    • Named using aria-labelledby if a visible label is present, otherwise with aria-label.
      • +
    +
    optionRequired 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 Combo Box Design Pattern.
      • +
    +
    presentationDo Not NameAn element with role="presentation" is not part of the accessibility tree (except in error cases). Do not use aria-labelledby or aria-label.
    progressbarRequired +
      +
    • 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.
      • +
    +
    radioRequired 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", use a label element.
      • +
    • Otherwise, reference visible content via aria-labelledby.
      • +
    +
    radiogroupRequired +
      +
    • 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.
      • +
    +
    regionRequired +
      +
    • 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 section.
      • +
    +
    row + 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. +
    rowgroupDo Not NameNot supported by assistive technologies.
    rowheaderRequired 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 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.
      • +
    +
    scrollbarDiscretionary +
      +
    • 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.
      • +
    +
    searchRecommended +
      +
    • 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 section.
      • +
    +
    searchboxRequired +
      +
    • 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.
      • +
    +
    separatorDiscretionary +
      +
    • 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.
      • +
    +
    sliderRequired +
      +
    • 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 Design Pattern and the Slider (Multi-Thumb) Design Pattern.
      • +
    +
    spinbuttonRequired +
      +
    • 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 Design Pattern.
      • +
    +
    statusDiscretionary + 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. +
    switchRequired 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", use a label element.
      • +
    • Otherwise, reference visible content via aria-labelledby.
      • +
    +
    tabRequired Only If Content Insufficient +
      +
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • +
    • Ideally named by visible, descendant content.
      • +
    +
    tableRequired +
      +
    • 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.
      • +
    +
    tablistRecommended +
      +
    • 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 Pattern and Tabs Design Pattern.
      • +
    +
    tabpanelRequired + +
    termDo Not NameSince a term is usually the name for the role="definition" element, it could be confusing if the term itself also has a name.
    textboxRequired +
      +
    • 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.
      • +
    +
    timerRequiredUse aria-labelledby if a visible label is present, otherwise use aria-label.
    toolbarRecommended +
      +
    • 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.
      • +
    +
    tooltipRequired Only If Content Insufficient +
      +
    • Warning! Using aria-label or aria-labelledby will hide descendant content from assistive technologies.
      • +
    • Ideally named by visible, descendant content.
      • +
    +
    treeRequired + +
    treegridRequired +
      +
    • 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 label is present, otherwise use aria-label.
      • +
    • See the Treegrid Design Pattern.
      • +
    +
    treeitemRequired 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.
      • +
    • Note: content contained within a child group is automatically excluded from the accessible name calculation.
      • +
    • See the Tree View Design Pattern.
      • +
    +

    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.

      -
    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. 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
      +
      area
      +
      The alt attribute.
      + +
      fieldset
      +
      The first child legend element.
      + +
      Other form elements
      +
      The associated label element(s).
      + +
      figure
      +
      The first child figcaption element.
      + +
      table
      +
      The first child caption element.
      +
      +
      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".
      + +
      summary
      +
      The word "Details".
      + +
      Other elements
      +
      The title attribute.
      +
      +

    - 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. - And, when following aria-labelledby references, it similarly walks the tree of each referenced element. + 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. +

    + 
    <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>
    +

    + 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>
+      <li role="menuitem">Bananas</li>
+      <li role="menuitem">Oranges</li>
+    </ul>
+  </li>
+</ul>
    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>
    +

    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 fallback 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 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"
+        placeholder="123456"
+        title="Get your code from the app.">
+</label>
    + +

    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"
+        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>
    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>
    -

    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>
    + <button aria-labelledby="meeting-1" aria-label="Remove meeting:">X</button> + Daily status report +</div>
    • @@ -4086,60 +5043,124 @@
    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>
    - -

    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>
    +... +<p id="trash-desc">Items in the trash will be permanently removed after 30 days.</p>     + +

    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. + 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. +

    + + 
    <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`.

    +
    +
    Describing Tables and Figures with Captions
    +

    + In HTML, if the table is named using aria-label or aria-labelledby, a child caption element becomes an accessible description. + For example, a preceding heading might serve as an appropriate accessible name, and the caption element might contain a longer description. + In such a situation, aria-labelledby could be used on the table to set the accessible name to the heading content and the caption would become the accessible description. +

    + 
    <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<th>Saturday<th>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>
    +
    + +
    +
    Descriptions Derived from Titles
    +

    If 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 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>

    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. +

    +

    + 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. +

    +

    + 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. +
    @@ -4324,7 +5345,7 @@

    Keyboard Navigation Between Components (The Tab Sequence)

    As explained in section , all interactive UI components need to be reachable via the keyboard. This is best achieved by either including them in the tab sequence or by making them accessible from a component that is in the tab sequence, e.g., as part of a composite component. This section addresses building and managing the tab sequence, and subsequent sections cover making focusable elements that are contained within components keyboard accessible.

    - The HTML tabindex and SVG tabindex attributes can be used to add and remove elements from the tab sequence. + The [[HTML]] tabindex and [[SVG2]] tabindex attributes can be used to add and remove elements from the tab sequence. The value of tabindex can also influence the order of the tab sequence, although authors are strongly advised not to use tabindex for that purpose.

    @@ -4663,7 +5684,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:

      @@ -4962,7 +5983,7 @@

      Using aria-colcount and aria-colindex

      For example, specifying an invalid value for aria-colindex or setting it on some but not all cells in a row, could cause screen reader table reading functions to skip cells or simply stop functioning.

      -

      Using aria-colindex When Column Indicies Are Contiguous

      +

      Using aria-colindex When Column Indices Are Contiguous

      When all the cells in a row have column index numbers that are consecutive integers, aria-colindex can be set on the row element with a value equal to the index number of the first column in the set. @@ -5003,7 +6024,7 @@

      Using aria-colindex When Column Indicies Are Contiguous

      -

      Using aria-colindex When Column Indicies Are Not Contiguous

      +

      Using aria-colindex When Column Indices Are Not Contiguous

      When the cells in a row have column index numbers that are not consecutive integers, aria-colindex needs to be set on each cell in the row. The following example shows a grid for an online grade book where the first two columns contain a student name and subsequent columns contain scores. @@ -5266,8 +6287,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. @@ -5326,7 +6347,7 @@

    1. If presentation is applied to a ul or ol element, each child li element inherits the presentation role because ARIA requires the listitem elements to have the parent list element. So, the li elements are not exposed to assistive technologies, but elements contained inside of those li elements, including nested lists, are visible to assistive technologies.
    2. Similarly, if presentation is applied to a table element, - the descendant caption, thead, tbody, tfooter, + the descendant caption, thead, tbody, tfoot, tr, th, and td elements inherit role presentation and are thus not exposed to assistive technologies. But, elements inside of the th and td elements, including nested tables, are exposed to assistive technologies. @@ -5342,11 +6363,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:

      3. @@ -5447,6 +6468,7 @@

      Major Contributors to Version 1.1

      • Jon Gunderson and Nicholas Hoyt of the Division of Disability Resources and Education Services at the University of Illinois Urbana/Champaign and the students Max Foltz, Sulaiman Sanaullah, Mark McCarthy, and Jinyuan Zhou for their contributions to the development of many of the design pattern examples.
      • Valerie Young of Bocoup and her sponsor, Facebook, for development of the example test framework and regressions tests for more than 50 examples.
        • +
      • Simon Pieters of Bocoup and his sponsor, Facebook, for authoring of significant guidance sections, including comprehensive treatement of the topic of accessible names and descriptions.
    @@ -5454,17 +6476,24 @@

    Participants active in the ARIA Authoring Practices Task Force

    • Ann Abbott (Invited Expert)
    • Shirisha Balusani (Microsoft Corporation)
      • +
    • Dorothy Bass (Wells Fargo Bank N.A.)
    • Curt Bellew (Oracle)
      • -
    • Michiel Bijl (Invited Expert)
      • +
    • Zoë Bijl (Invited Expert)
    • Michael Cooper (W3C)
    • Bryan Garaventa (Level Access)
    • Jon Gunderson (University of Illinois at Urbana-Champaign)
      • +
    • Jesse Hausler(Salesforce)
      • +
    • Sarah Higley (Microsoft Corporation)
    • Hans Hillen (The Paciello Group, LLC)
    • Matt King (Facebook)
    • Jaeun Ku (University of Illinois at Urbana-Champaign)
    • Aaron Leventhal (Google)
      • +
    • Carolyn MacLeod (IBM Corporation)
    • Mark McCarthy (University of Illinois at Urbana-Champaign)
    • James Nurthen (Adobe)
      • +
    • Scott O'Hara (The Paciello Group, LLC)
      • +
    • Simon Pieters (Bocoup)
      • +
    • Scott Vinkle (Shopify)
    • Evan Yamanishi (W. W. Norton)
    • Valerie Young (Bocoup)
    @@ -5489,14 +6518,13 @@

    Other commenters and contributors to Version 1.1

  • Tatiana Iskandar
  • Patrick Lauke
  • Marek Lewandowski
    • -
  • Carolyn MacLeod
  • Dan Matthew
  • Shane McCarron
  • Victor Meyer
  • Jonathan Neal
  • Philipp Rudloff
  • Joseph Scheuhammer
    • -
  • Nick Schonni
    • +
  • Nick Schonning
  • thomascorthals
  • Christopher Tryens
    • From 9c462714fd8a9cfac7375111916b468a24a2ac2a Mon Sep 17 00:00:00 2001 From: Matt King Date: Fri, 11 Oct 2019 07:56:10 -0700 Subject: [PATCH 41/55] Remove outdated draft labeling and describing 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 93cbf9870596710bc782f9937f7b2d0dc2e1c75a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zoe=CC=88=20Bijl?= Date: Thu, 17 Oct 2019 15:45:03 +0200 Subject: [PATCH 42/55] Editorial: add a space (issue #955) --- examples/meter/meter.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/meter/meter.html b/examples/meter/meter.html index 25fd92e037..fcc8f6b1cb 100644 --- a/examples/meter/meter.html +++ b/examples/meter/meter.html @@ -36,7 +36,7 @@

    Example

    This meter changes its value randomly every 5 seconds.

    -

    Central Processing Unit(CPU) Usage

    +

    Central Processing Unit (CPU) Usage

    From 9bcfe10eee3aa80015387f6a69fa0edf0d2134ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zoe=CC=88=20Bijl?= Date: Thu, 17 Oct 2019 15:48:55 +0200 Subject: [PATCH 43/55] Editorial: add 'the' (issue #979) --- examples/meter/meter.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/meter/meter.html b/examples/meter/meter.html index fcc8f6b1cb..5cc56618ec 100644 --- a/examples/meter/meter.html +++ b/examples/meter/meter.html @@ -110,7 +110,7 @@

    Role, Property, State, and Tabindex Attributes

    div
      -
    • Identifies the accessible name for meter widget.
      • +
    • Identifies the accessible name for the meter widget.
    From b2df353ac2802dc9d2a0c94808f17118bfe10c64 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zoe=CC=88=20Bijl?= Date: Thu, 17 Oct 2019 16:24:55 +0200 Subject: [PATCH 44/55] Meter Example: update visual style (issue 979) --- examples/meter/css/meter.css | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/examples/meter/css/meter.css b/examples/meter/css/meter.css index 4ff3ca6f3b..7daa5f1c86 100644 --- a/examples/meter/css/meter.css +++ b/examples/meter/css/meter.css @@ -1,13 +1,15 @@ [role=meter] { - position: relative; - border: 5px solid black; + padding: 2px; + border: 2px solid black; + border-radius: 5px; height: 40px; width: 200px; } #fill { - position: absolute; + box-sizing: border-box; height: 100%; - background-color: black; + border-radius: 3px; + border: 20px solid black; } From 9ed4911b17aab42a21798838c51f2f826dcff90b Mon Sep 17 00:00:00 2001 From: Sarah Higley Date: Wed, 16 Oct 2019 17:31:14 -0700 Subject: [PATCH 45/55] update meter js, add pause button and color fill --- examples/meter/css/meter.css | 5 +- examples/meter/meter.html | 10 +-- examples/meter/meter.js | 162 ++++++++++++++++++++++++++++------- 3 files changed, 138 insertions(+), 39 deletions(-) diff --git a/examples/meter/css/meter.css b/examples/meter/css/meter.css index 7daa5f1c86..4c5cf54373 100644 --- a/examples/meter/css/meter.css +++ b/examples/meter/css/meter.css @@ -7,9 +7,10 @@ width: 200px; } -#fill { +.fill { box-sizing: border-box; height: 100%; border-radius: 3px; - border: 20px solid black; + background-color: black; + outline: 3px solid black; } diff --git a/examples/meter/meter.html b/examples/meter/meter.html index 5cc56618ec..11bff53a27 100644 --- a/examples/meter/meter.html +++ b/examples/meter/meter.html @@ -35,12 +35,12 @@

    Example

    -

    This meter changes its value randomly every 5 seconds.

    +

    This meter changes its value randomly every 5 seconds, with an option to pause changes.

    Central Processing Unit (CPU) Usage

    -
    -
    -
    +

    + +

    +
    diff --git a/examples/meter/meter.js b/examples/meter/meter.js index 7c060c9efc..1b6c5fb613 100644 --- a/examples/meter/meter.js +++ b/examples/meter/meter.js @@ -1,32 +1,130 @@ -/** @type {!Element} Meter element. */ -let meterEl; -/** @type {!Element} Element visually filling the meter. */ -let visualFillEl; -/** @type {number} Minimum value. */ -let minUsage; -/** @type {number} Maximum value. */ -let maxUsage; -/** @type {number} Current value. */ -let usage; - -/** Set the value randomly between the minimum and maximum. */ -function randomizeUsage() { - const range = maxUsage - minUsage; - usage = Math.floor((Math.random() * range) + minUsage); - meterEl.setAttribute('aria-valuenow', usage); - render(); -} -function render() { - const asPercentage = (100 * usage) / (maxUsage - minUsage); - visualFillEl.style.width = asPercentage + '%'; -} -function init() { - meterEl = document.querySelector('[role=meter]'); - visualFillEl = document.getElementById('fill'); - minUsage = Number(meterEl.getAttribute('aria-valuemin')); - maxUsage = Number(meterEl.getAttribute('aria-valuemax')); - usage = Number(meterEl.getAttribute('aria-valuenow')); - render(); - setInterval(randomizeUsage, 5000); -} -window.addEventListener('load', init, false); +var Meter = function (element) { + this.rootEl = element; + + // create fill + this.fillEl = this._createFill(); + this.rootEl.appendChild(this.fillEl); + + // set up min, max, and current value + var min = element.getAttribute('aria-valuemin'); + var max = element.getAttribute('aria-valuemax'); + var value = element.getAttribute('aria-valuenow'); + this._update(parseFloat(min), parseFloat(max), parseFloat(value)); +}; + +/* Private methods */ + +// returns an HTMLElement to be used as the fill +Meter.prototype._createFill = function () { + var element = document.createElement('div'); + element.classList.add('fill'); + return element; +}; + +// returns a number representing a percentage between 0 - 100 +Meter.prototype._calculatePercentFill = function (min, max, value) { + if (typeof min !== 'number' || typeof max !== 'number' || typeof value !== 'number') { + return 0; + } + + return 100 * value / (max - min); +}; + +// returns an hsl color string between red and green +Meter.prototype._getColorValue = function (percent) { + // red is 0deg, green is 120deg in hsl + // if percent is 100, hue should be red, and if percent is 0, hue should be green + var hue = (percent / 100) * (0 - 120) + 120; + + // also scale lightness slightly, so green is darker (just looks better) + var lightness = (percent / 100) * (50 - 30) + 20; + + return 'hsl(' + hue + ', 100%, ' + lightness + '%)'; +}; + +// no return value; updates the meter element +Meter.prototype._update = function (min, max, value) { + // update fill width + if (min !== this.min || max !== this.max || value !== this.value) { + var percentFill = this._calculatePercentFill(min, max, value); + this.fillEl.style.width = percentFill + '%'; + this.fillEl.style.backgroundColor = this._getColorValue(percentFill); + } + + // update aria attributes + if (min !== this.min) { + this.min = min; + this.rootEl.setAttribute('aria-valuemin', min + ''); + } + + if (max !== this.max) { + this.max = max; + this.rootEl.setAttribute('aria-valuemax', max + ''); + } + + if (value !== this.value) { + this.value = value; + this.rootEl.setAttribute('aria-valuenow', value + ''); + } +}; + +/* Public methods */ + +// no return value; modifies the meter element based on a new value +Meter.prototype.setValue = function (value) { + if (typeof value !== 'number') { + value = parseFloat(value); + } + + if (!isNaN(value)) { + this._update(this.min, this.max, value); + } +}; + +/* Code for example page */ + +window.addEventListener('load', function () { + // helper function to randomize example meter value + function getRandomValue (min, max) { + var range = max - min; + return Math.floor((Math.random() * range) + min); + } + + // init meters + var meterEls = document.querySelectorAll('[role=meter]'); + var meters = []; + Array.prototype.slice.call(meterEls).forEach(function (meterEl) { + meters.push(new Meter(meterEl)); + }); + + // randomly update meter values + + // returns an id for setInterval + function playMeters () { + return window.setInterval(function () { + meters.forEach(function (meter) { + meter.setValue(Math.random() * 100); + }); + }, 5000); + } + + // start meters + var updateInterval = playMeters(); + + // play/pause meter updates + var playButton = document.querySelector('.play-meters'); + playButton.addEventListener('click', function () { + var isPaused = playButton.classList.contains('paused'); + + if (isPaused) { + updateInterval = playMeters(); + playButton.classList.remove('paused'); + playButton.innerHTML = 'Pause Updates'; + } + else { + clearInterval(updateInterval); + playButton.classList.add('paused'); + playButton.innerHTML = 'Start Updates'; + } + }); +}); From 50d74bf58ccdfbcfe55e173a96cd1f687a8f4a5e Mon Sep 17 00:00:00 2001 From: Sarah Higley Date: Thu, 17 Oct 2019 10:34:33 -0700 Subject: [PATCH 46/55] add meter tests --- examples/meter/css/meter.css | 2 +- examples/meter/{ => js}/meter.js | 7 +-- examples/meter/meter.html | 84 ++++++++++++++++---------------- test/tests/meter_meter.js | 70 ++++++++++++++++++++++++++ 4 files changed, 115 insertions(+), 48 deletions(-) rename examples/meter/{ => js}/meter.js (94%) create mode 100644 test/tests/meter_meter.js diff --git a/examples/meter/css/meter.css b/examples/meter/css/meter.css index 4c5cf54373..67b9606fff 100644 --- a/examples/meter/css/meter.css +++ b/examples/meter/css/meter.css @@ -12,5 +12,5 @@ height: 100%; border-radius: 3px; background-color: black; - outline: 3px solid black; + border: 2px solid black; } diff --git a/examples/meter/meter.js b/examples/meter/js/meter.js similarity index 94% rename from examples/meter/meter.js rename to examples/meter/js/meter.js index 1b6c5fb613..76b7c2c686 100644 --- a/examples/meter/meter.js +++ b/examples/meter/js/meter.js @@ -27,7 +27,7 @@ Meter.prototype._calculatePercentFill = function (min, max, value) { return 0; } - return 100 * value / (max - min); + return 100 * (value - min) / (max - min); }; // returns an hsl color string between red and green @@ -36,10 +36,7 @@ Meter.prototype._getColorValue = function (percent) { // if percent is 100, hue should be red, and if percent is 0, hue should be green var hue = (percent / 100) * (0 - 120) + 120; - // also scale lightness slightly, so green is darker (just looks better) - var lightness = (percent / 100) * (50 - 30) + 20; - - return 'hsl(' + hue + ', 100%, ' + lightness + '%)'; + return 'hsl(' + hue + ', 100%, 40%)'; }; // no return value; updates the meter element diff --git a/examples/meter/meter.html b/examples/meter/meter.html index 11bff53a27..ac82f1a6df 100644 --- a/examples/meter/meter.html +++ b/examples/meter/meter.html @@ -13,7 +13,7 @@ - + @@ -40,7 +40,7 @@

    Central Processing Unit (CPU) Usage

    -
    +
    @@ -74,46 +74,46 @@

    Role, Property, State, and Tabindex Attributes

    - - - aria-valuemin="NUMBER" - div - -
      -
    • Specifies a numeric value that is the minimum value the meter can have.
      • -
    - - - - - aria-valuemax="NUMBER" - div - -
      -
    • Specifies a numeric value that is the maximum value the meter can have.
      • -
    - - - - - aria-valuenow="NUMBER" - div - -
      -
    • A numeric value that is the current value of the meter
      • -
    - - - - - aria-labelledby - div - -
      -
    • Identifies the accessible name for the meter widget.
      • -
    - - + + + aria-valuemin="NUMBER" + div + +
      +
    • Specifies a numeric value that is the minimum value the meter can have.
      • +
    + + + + + aria-valuemax="NUMBER" + div + +
      +
    • Specifies a numeric value that is the maximum value the meter can have.
      • +
    + + + + + aria-valuenow="NUMBER" + div + +
      +
    • A numeric value that is the current value of the meter
      • +
    + + + + + aria-labelledby + div + +
      +
    • Identifies the accessible name for the meter widget.
      • +
    + +
    diff --git a/test/tests/meter_meter.js b/test/tests/meter_meter.js new file mode 100644 index 0000000000..2f29af0a12 --- /dev/null +++ b/test/tests/meter_meter.js @@ -0,0 +1,70 @@ +'use strict'; + +const { ariaTest } = require('..'); +const { By } = require('selenium-webdriver'); +const assertAriaLabelledby = require('../util/assertAriaLabelledby'); + +const exampleFile = 'meter/meter.html'; + +const ex = { + meterSelector: '#example [role="meter"]', + fillSelector: '#example [role="meter"] > div' +}; + +// Attributes + +ariaTest('"aria-labelledby" attribute', exampleFile, 'meter-aria-labelledby', async (t) => { + await assertAriaLabelledby(t, ex.meterSelector); +}); + +ariaTest('"aria-valuemin" attribute', exampleFile, 'meter-aria-valuemin', async (t) => { + const meter = await t.context.session.findElement(By.css(ex.meterSelector)); + const valuemin = await meter.getAttribute('aria-valuemin'); + + t.is(typeof valuemin, 'string', 'aria-valuemin is present on the meter'); + t.false(isNaN(parseFloat(valuemin)), 'aria-valuemin is a number'); +}); + +ariaTest('"aria-valuemax" attribute', exampleFile, 'meter-aria-valuemax', async (t) => { + const meter = await t.context.session.findElement(By.css(ex.meterSelector)); + const [valuemax, valuemin] = await Promise.all([ + meter.getAttribute('aria-valuemax'), + meter.getAttribute('aria-valuemin') + ]); + + t.is(typeof valuemax, 'string', 'aria-valuemax is present on the meter'); + t.false(isNaN(parseFloat(valuemax)), 'aria-valuemax is a number'); + t.true(parseFloat(valuemax) >= parseFloat(valuemin), 'max value is greater than min value'); +}); + +ariaTest('"aria-valuenow" attribute', exampleFile, 'meter-aria-valuenow', async (t) => { + const meter = await t.context.session.findElement(By.css(ex.meterSelector)); + const [valuenow, valuemax, valuemin] = await Promise.all([ + meter.getAttribute('aria-valuenow'), + meter.getAttribute('aria-valuemax'), + meter.getAttribute('aria-valuemin') + ]); + + t.is(typeof valuenow, 'string', 'aria-valuenow is present on the meter'); + t.false(isNaN(parseFloat(valuenow)), 'aria-valuenow is a number'); + t.true(parseFloat(valuenow) >= parseFloat(valuemin), 'current value is greater than min value'); + t.true(parseFloat(valuenow) <= parseFloat(valuemax), 'current value is less than max value'); +}); + +ariaTest('fill matches current value', exampleFile, 'meter-aria-valuenow', async (t) => { + const meter = await t.context.session.findElement(By.css(ex.meterSelector)); + const fill = await t.context.session.findElement(By.css(ex.fillSelector)); + const [valuenow, valuemax, valuemin] = await Promise.all([ + meter.getAttribute('aria-valuenow'), + meter.getAttribute('aria-valuemax'), + meter.getAttribute('aria-valuemin') + ]); + + const currentPercent = (valuenow - valuemin) / (valuemax - valuemin); + const [fillSize, meterSize] = await Promise.all([fill.getRect(), meter.getRect()]); + + // fudging a little here, since meter has 8px total border + padding + // would be better in a unit test eventually + const expectedFillWidth = (meterSize.width - 8) * currentPercent; + t.true(Math.abs(expectedFillWidth - fillSize.width) < 10, 'Fill width is the correct percent of meter, +/- 10px'); +}); From bedc9e4cc137b95df9fa81837f83b938b27fb652 Mon Sep 17 00:00:00 2001 From: Sarah Higley Date: Thu, 17 Oct 2019 10:45:11 -0700 Subject: [PATCH 47/55] ignore meter role error in vnu-jar --- .vnurc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.vnurc b/.vnurc index db2d5aa3f5..904e2b308b 100644 --- a/.vnurc +++ b/.vnurc @@ -8,5 +8,7 @@ An “img” element must have an “alt” attribute, except under certain cond # Ignoring aria-posinset and aria-setsize on role row Attribute “aria-posinset” not allowed on element “tr” at this point. Attribute “aria-setsize” not allowed on element “tr” at this point. +# Ignoring role meter +Bad value “meter” for attribute “role” on element “div”. # Deleted Section Archive The “longdesc” attribute on the “img” element is obsolete. Use a regular “a” element to link to the description. From faac2e1d60ed9672f237e0abd39e708b4d38e81f Mon Sep 17 00:00:00 2001 From: Sarah Higley Date: Tue, 22 Oct 2019 23:55:42 -0700 Subject: [PATCH 48/55] use svg for meter fill and add role test --- examples/meter/css/meter.css | 1 + examples/meter/js/meter.js | 14 ++------------ examples/meter/meter.html | 6 +++++- test/tests/meter_meter.js | 3 +++ 4 files changed, 11 insertions(+), 13 deletions(-) diff --git a/examples/meter/css/meter.css b/examples/meter/css/meter.css index 67b9606fff..1281035c56 100644 --- a/examples/meter/css/meter.css +++ b/examples/meter/css/meter.css @@ -13,4 +13,5 @@ border-radius: 3px; background-color: black; border: 2px solid black; + width: 100%; } diff --git a/examples/meter/js/meter.js b/examples/meter/js/meter.js index 76b7c2c686..440647584a 100644 --- a/examples/meter/js/meter.js +++ b/examples/meter/js/meter.js @@ -1,9 +1,6 @@ var Meter = function (element) { this.rootEl = element; - - // create fill - this.fillEl = this._createFill(); - this.rootEl.appendChild(this.fillEl); + this.fillEl = element.querySelector('.fill'); // set up min, max, and current value var min = element.getAttribute('aria-valuemin'); @@ -14,13 +11,6 @@ var Meter = function (element) { /* Private methods */ -// returns an HTMLElement to be used as the fill -Meter.prototype._createFill = function () { - var element = document.createElement('div'); - element.classList.add('fill'); - return element; -}; - // returns a number representing a percentage between 0 - 100 Meter.prototype._calculatePercentFill = function (min, max, value) { if (typeof min !== 'number' || typeof max !== 'number' || typeof value !== 'number') { @@ -45,7 +35,7 @@ Meter.prototype._update = function (min, max, value) { if (min !== this.min || max !== this.max || value !== this.value) { var percentFill = this._calculatePercentFill(min, max, value); this.fillEl.style.width = percentFill + '%'; - this.fillEl.style.backgroundColor = this._getColorValue(percentFill); + this.fillEl.style.color = this._getColorValue(percentFill); } // update aria attributes diff --git a/examples/meter/meter.html b/examples/meter/meter.html index ac82f1a6df..7cfc227a17 100644 --- a/examples/meter/meter.html +++ b/examples/meter/meter.html @@ -40,7 +40,11 @@

    Central Processing Unit (CPU) Usage

    -
    +
    + +
    diff --git a/test/tests/meter_meter.js b/test/tests/meter_meter.js index 2f29af0a12..d5bfbbf4eb 100644 --- a/test/tests/meter_meter.js +++ b/test/tests/meter_meter.js @@ -12,6 +12,9 @@ const ex = { }; // Attributes +ariaTest('role="meter" element exists', exampleFile, 'meter-role', async (t) => { + await assertAriaRoles(t, 'example', 'meter', '1', 'div'); +}); ariaTest('"aria-labelledby" attribute', exampleFile, 'meter-aria-labelledby', async (t) => { await assertAriaLabelledby(t, ex.meterSelector); From 96ee9d76a7147d370571c8d1dfdb11c2e703c734 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zoe=CC=88=20Bijl?= Date: Wed, 23 Oct 2019 12:44:11 +0200 Subject: [PATCH 49/55] Reorder CSS properties --- examples/meter/css/meter.css | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/examples/meter/css/meter.css b/examples/meter/css/meter.css index 1281035c56..75934ca1e8 100644 --- a/examples/meter/css/meter.css +++ b/examples/meter/css/meter.css @@ -1,17 +1,17 @@ [role=meter] { padding: 2px; + width: 200px; + height: 40px; border: 2px solid black; border-radius: 5px; - height: 40px; - width: 200px; } .fill { - box-sizing: border-box; + width: 100%; height: 100%; + box-sizing: border-box; + border: 2px solid black; border-radius: 3px; background-color: black; - border: 2px solid black; - width: 100%; } From 48fe4551c38f40a6bea41afafdc4aa53c4c6cb3d Mon Sep 17 00:00:00 2001 From: Sarah Higley Date: Wed, 23 Oct 2019 06:11:50 -0700 Subject: [PATCH 50/55] fix meter tests --- test/tests/meter_meter.js | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/test/tests/meter_meter.js b/test/tests/meter_meter.js index d5bfbbf4eb..bde3005ee7 100644 --- a/test/tests/meter_meter.js +++ b/test/tests/meter_meter.js @@ -3,12 +3,13 @@ const { ariaTest } = require('..'); const { By } = require('selenium-webdriver'); const assertAriaLabelledby = require('../util/assertAriaLabelledby'); +const assertAriaRoles = require('../util/assertAriaRoles'); const exampleFile = 'meter/meter.html'; const ex = { meterSelector: '#example [role="meter"]', - fillSelector: '#example [role="meter"] > div' + fillSelector: '#example [role="meter"] > svg' }; // Attributes From 49a76a6759295a7a316d82a9afcbf2e67f468ece Mon Sep 17 00:00:00 2001 From: Matt King Date: Wed, 23 Oct 2019 17:21:33 -0700 Subject: [PATCH 51/55] Fix design pattern href in banner nav --- examples/meter/meter.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/meter/meter.html b/examples/meter/meter.html index 7cfc227a17..cc61cb7dd6 100644 --- a/examples/meter/meter.html +++ b/examples/meter/meter.html @@ -22,7 +22,7 @@
  • Browser and Assistive Technology Support
  • Report Issue
  • Related Issues
    • -
  • Design Pattern
    • +
  • Design Pattern
    • From 895d26553f79d072383f351ba03a30db7436da19 Mon Sep 17 00:00:00 2001 From: Matt King Date: Wed, 23 Oct 2019 17:38:13 -0700 Subject: [PATCH 52/55] Correct link to related issues --- examples/meter/meter.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/meter/meter.html b/examples/meter/meter.html index cc61cb7dd6..76d2cd7509 100644 --- a/examples/meter/meter.html +++ b/examples/meter/meter.html @@ -21,7 +21,7 @@ From c3ded30d3d3846824eac707f42c5f82dabffd43e Mon Sep 17 00:00:00 2001 From: Matt King Date: Wed, 23 Oct 2019 17:42:14 -0700 Subject: [PATCH 53/55] Add missing p tags and minor revision wording of intro --- examples/meter/meter.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/meter/meter.html b/examples/meter/meter.html index 76d2cd7509..fc7e3e850b 100644 --- a/examples/meter/meter.html +++ b/examples/meter/meter.html @@ -27,7 +27,7 @@

    Meter Example

    - The following meter example demonstrates the meter design pattern. +

    The following example of a CPU meter demonstrates the meter design pattern.

    Example

    From 4a2914980d17012615ff16bc696e2927334ab4eb Mon Sep 17 00:00:00 2001 From: Matt King Date: Wed, 23 Oct 2019 17:47:40 -0700 Subject: [PATCH 54/55] Revise wording of instructions --- examples/meter/meter.html | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/examples/meter/meter.html b/examples/meter/meter.html index fc7e3e850b..bf30152f72 100644 --- a/examples/meter/meter.html +++ b/examples/meter/meter.html @@ -31,11 +31,10 @@

    Meter Example

    Example

    -
    -

    This meter changes its value randomly every 5 seconds, with an option to pause changes.

    +

    The value of this meter changes every 5 seconds. Use the pause button to stop changes.

    Central Processing Unit (CPU) Usage

    @@ -49,9 +48,8 @@

    Central Processing Unit (CPU) Usage

    -

    Keyboard Support

    - -

    No keyboard interaction needed.

    +

    Keyboard Support

    +

    Not applicable.

    From efb3e527828f4d828b2b13eb75e876e1ef7dd01d Mon Sep 17 00:00:00 2001 From: Matt King Date: Wed, 23 Oct 2019 17:57:40 -0700 Subject: [PATCH 55/55] Editorial revisions to state and props table --- examples/meter/meter.html | 26 +++++--------------------- 1 file changed, 5 insertions(+), 21 deletions(-) diff --git a/examples/meter/meter.html b/examples/meter/meter.html index bf30152f72..6ad91436a6 100644 --- a/examples/meter/meter.html +++ b/examples/meter/meter.html @@ -72,7 +72,7 @@

    Role, Property, State, and Tabindex Attributes

      -
    • Identifies the element as a meter widget.
      • +
    • Identifies the element as a meter.
    @@ -80,41 +80,25 @@

    Role, Property, State, and Tabindex Attributes

    aria-valuemin="NUMBER" div - -
      -
    • Specifies a numeric value that is the minimum value the meter can have.
      • -
    - + Specifies the minimum value the meter can have. aria-valuemax="NUMBER" div - -
      -
    • Specifies a numeric value that is the maximum value the meter can have.
      • -
    - + Specifies the maximum value the meter can have. aria-valuenow="NUMBER" div - -
      -
    • A numeric value that is the current value of the meter
      • -
    - + Specifies the current value of the meter. aria-labelledby div - -
      -
    • Identifies the accessible name for the meter widget.
      • -
    - + Identifies the element that provides the accessible name of the meter.