RE: Alternative draft of the labeling and describing section

Hi,
In addition to Simon’s comments, the following doesn’t make sense to me.

> This section will describe the following labeling techniques and their priority in the accessible name computation:
> * Text Content
> * `aria-label` attribute
> * `aria-labelledby` attribute
> * `title` attribute`
> * `label` element
> * `label` role

Actually this order is incorrect, and should be:

* `aria-labelledby` attribute
* `aria-label` attribute
* `label` element (form fields only)
* `label` role (specified widget roles only)
* Text Content
* `title` attribute`

This is how AccName works anyway.

Bryan Garaventa
Principal Accessibility Architect
Level Access, Inc.
Bryan.Garaventa@LevelAccess.com
415.624.2709 (o)
www.LevelAccess.com<http://www.levelaccess.com/>

From: Simon Pieters <zcorpan@gmail.com>
Sent: Thursday, April 25, 2019 7:36 AM
To: Gunderson, Jon R <jongund@illinois.edu>
Cc: public-aria-practices@w3.org
Subject: Re: Alternative draft of the labeling and describing section

CAUTION: This email originated from outside of the organization. Do not click links or open attachments unless you recognize the sender and know the content is safe.

Thanks, Jon.

It seems I can't provide inline comments in the wiki itself, like is possible with a PR. I'll comment here instead.

> ## Accessible Name
>
> Screen readers speak or display in Braille the role and accessible name of HTML form controls and ARIA enabled widgets and it is the responsibility of the authors to define a unique accessible name that describes the purpose of each form control and widget within a web resource.

There are many things that can have accessible names (like, images, headings, tables, regions...).

> There are a number of different labeling techniques available to authors to define an accessible name.  The [Accessible Name and Description Computation Specification](https://www.w3.org/TR/accname/) provides a detailed description of how browsers compute the accessible name based on the author's labeling information.
>
> This section will describe the following labeling techniques and their priority in the the accessible name computation:
>
> * Text Content
> * `aria-label` attribute
> * `aria-labelledby` attribute
> * `title` attribute`
> * `label` element
> * `label` role
>
> In general the visible label should be used to provide the accessible name to assistive technologies.

My understanding is that "should" should be avoided in APG, since it's a normative keyword, but APG is non-normative, it could cause confusion.

I noticed that this also applies to text already in APG, so I filed a new issue: https://github.com/w3c/aria-practices/issues/1019


>   The synchronization of the visible label and the accessible name helps reduce confusion when screen reader users and sighted users abre working with each other on the same form or web application.

Is this a common scenario? If not, it might be more convincing to explain advantages to good labeling in the most common scenario (I assume would be a single user using a web page or app).

> There are cases where there are no visible labels or the visible labels are insufficient to describe the purpose of the form controls and widgets and in this case authors can use the `aria-label` attribute or off-screen text references .  Web resources that were designed with out accessibility features may be easier to remediate using the `aria-label` and `aria-labelledby` techniques since it minimizes modifying existing markup on the page or application.

"off-screen text references" is not explained. Is there an APG example to point to? Is off-screen text a recommended approach?

> ### Text Content
>
> For aria widget roles

Again, not only widget roles.

> that can have their accessible name defined from "content", like `checkbox`, `radio` and `link`, the descendant text content of the element is used to compute the accessible name.   The following `checkbox` role example demonstrates the use of the text content technique to provide a screen reader with the information to speak or display in Braille "I agree to terms of service".
>
> #### Example: Text Content
> ```
> <div role="checkbox">I agree to terms of service</div>
> ```

This should use tabindex="0" to be keyboard-accessible. Also, I think using a div for a checkbox is not best practice; maybe we can use a different example?

> The text content technique is very powerful and useful to an author, since it requires no additional markup other than what the author is already providing for the visible label.   The visible label is the same as the accessible name being provided to users of screen readers and other assistive technology.
>
> ### `aria-label` attribute
>
> The `aria-label` attribute is explicitly defines the accessible name for a form control or widget using a text string.   The `aria-label` technique overrides the "text content", `label` element and `label` role techniques.  The following example demonstrates using the `aria-label` for a social media link that uses a CSS content techniques for the visual label.
>
> #### Example: `aria-label` attribute
> ```
> <a aria-label="our world social media" href="#"><span class="icon-our-world"></span></div>
> ```

The markup has the wrong end tag. Also I don't think using empty links is a best practice. There is further no reference for "CSS content techniques", and the example doesn't include the CSS for it, so I think this is confusing to someone who doesn't already know what that technique is.

> The `aria-label` technique is useful when:
> 1. Visible text content is not available for a label.

Yes.

> 1. Visible labels are insufficient in describing the purpose of the form control.

Not only form control.

> 2. Repairing existing web resources with unlabeled form controls and widgets and updating or adding content is being minimized.

This wording is unclear to me.

> ### `aria-labelledby` attribute
>
> The `aria-labelledby` attribute references other content elements on the page to define an accessible name through the use of IDREFs.

IDREF and IDREFS is XML terminology; HTML does not use this terminology (anymore). I see that the ARIA spec itself talks about IDREF in some places. I have reported https://github.com/w3c/aria/issues/952 about this.

https://w3c.github.io/aria/#propcharacteristic_value says the ARIA terminology is "ID reference" and "ID reference list".

> The content of the reference elements are concatenated in the order of the IDREFs to create the accessible name.   The technique requires having ids on the content elements for the control or widget to reference.  The `aria-labelledby` technique includes the ability to reference other form controls and widgets and instead of the text content of the element being used in the name computation, the value of the form control is used.  For example, referencing a textbox with the value "3" would result in the number "3" being included in the concatenation of the text for the accessible name.

This seems specific to form controls.

> #### Example 1: `aria-labelledby` attribute
>
> The following `aria-labelledby` example demonstrates defining the accessible name "Maxium Price" to a slider widget by referencing the `max_price` IDREF on the `div` element.
>
> ```
> <div id="max_price">Maximum Price</div>
> ...
> <div role="slider"
>      aria-labelledby="max_price"
>      aria-valuemin="0"
>      aria-valuenow="100"
>      aria-valuemax="500">
> </div>
> ...
>
> ```

This is missing tabindex="0". Couldn't this be using <label> and <input type="range">? I think it would be good if examples represent best practice.

> #### Example 2: `aria-labelledby` attribute
>
> The following `aria-labelledby` example demonstrates a set of questions laid out in tabular layout referencing multiple content elements.  The `aria-labelledby` technique overrides all other accessible naming techniques.  The computed accessible name by concatenating the text content of the IDREFS, so the for the first checkbox is references `yes`, `t1` and `dma` IDs and computes the accessible name "yes 9:00am daily meeting availability" and the second checkbox is changes the first reference to `maybe` and computes the accessible name "maybe 9:00am daily meeting availability".
>
> ```
> <p id="dma">Daily meeting availability:</p>

Should this be a <caption> of the table?

> <table role="presentation">

Why is this using role="presentation"?

> <tr>
>   <td></td>
>   <td id="yes">Yes</td>
>   <td id="maybe">Maybe</td>
>   <td id="no">No</td>
> </tr>
> <tr>
>   <td id="t1">
>     9:00am
>   </td>
>   <td>
>     <input type="checkbox" aria-labelledby="yes t1 dma">
>   <td>
>   <td>
>     <input type="checkbox" aria-labelledby="maybe t1 dma">
>   <td>
>   <td>
>     <input type="checkbox" aria-labelledby="no t1 dma">
>   <td>
> </tr>
> <tr>
>   <td id="t2">
>     10:00am
>   </td>
>   <td>
>     <input type="checkbox" aria-labelledby="yes t2 dma">
>   <td>
>   <td>
>     <input type="checkbox" aria-labelledby="maybe t2 dma">
>   <td>
>   <td>
>     <input type="checkbox" aria-labelledby="no t2 dma">
>   <td>
> </tr>
> ...
> ```
>
> ### `title` attribute
>
> The `title` attribute is only used in the accessible name computation if no other labeling techniques are available to compute and accessible name.  I is similar to using `aria-label` attribute, but many browsers use the `title` attribute to generate a visible tooltip when a user hovers a pointing device over the element.  The following example demonstrates adding an accessible name to a social media link that uses a CSS content technique for he visible label using the `title` attribute.
>
> #### Example: `title` attribute
> ```
> <a title="our world social media" href="#"><span class="icon-our-world"></span></div>
> ```
>
> ### `Label` Element (ARIA 1.2)

(I'll skip ARIA 1.2 stuff for now.)

> The use of the `label` element define an accessible name for widgets in addition to standard HTML form controls is being proposed in the ARIA 1.2.  The `label` element can be used in two ways to provide an accessible name:
>
> 1. By reference using the `label` elements `for` attribute.
> 1. By encapsulation when the `label` element is an ancestor of aria widget roles that support the encapsulation techniques, for example `checkbox`, 'radio` and `link` roles.
>
> #### Example: `label` element
> The following example demonstrating using the `label` element encapsulation technique to define the accessible name "I want to receive text message announcements on flight and schedule changes"
>
> ```
> <label>
>   <div role="checkbox" aria-checked="false">
>   I want to receive text message announcements on flight and schedule changes
> </label>
> ```
>
>
> ### `label` role (ARIA 1.2)
>
> The use of the `label` role to define an accessible name for a ARIA widget is proposed in the ARIA 1.2.  The `label` role can be used in two ways to provide an accessible name:
>
> 1. By reference using the element with role `label` using an `aria-labelledby` technique.
> 1. By encapsulation when the element with role `label` is an ancestor of an aria widget role that support the encapsulation technique, for example `checkbox`, 'radio` and `link` roles.
>
> #### Example: `label` role
>
> The following example demonstrating using the `label` role technique to define the accessible name "I want to receive text message announcements on flight and schedule changes"
>
> ```
> <div role="label">
>   <div role="checkbox" aria-checked="false">
>   I want to receive text message announcements on flight and schedule changes
> </div>
> ```
>
> ## Grouping Labels
>
> Grouping labels provide a accessible name for a group of controls and is based on the concepts of `fieldset/legend` group labeling elements in HTML5.

HTML. https://github.com/w3c/aria-practices/issues/1020


> Screen readers typically speak group labels once when keyboard focus moves from an element outside the group to one of the form controls or widgets inside the group of controls.

Do we want to frame things around what screen readers typically do? I think it's a bit backwards, and doesn't age very well (maybe screen readers find better ways to do things?). I think it is better to provide the best practice that enables ATs to make things accessible, and base it on what the ARIA spec supports.

Some of my comments also apply to the rest, below, but I don't want to repeat the same thing many times, so this is the last comment for now.

cheers,

> This is an important technique to help users of assistive identify form controls and widgets with the same accessible name with in a web page.   A common example is  shipping and billing address.  The shipping and billing address form fields contain the same controls (e.g. name, address, city, state, country, zip code).  The use of grouping labels helps users of screen reader understand when they are in the billing address versus the shipping address field.
>
> ### `group` and `radiogroup` roles
>
> The `group` and `radiogroup` roles are used on container elements for the collection of related form controls.  The accessible name for the group uses the same accessible name techniques found in the previous section on "Accessible Name".
>
> The following example is a group of radio button widgets within a `radiogroup` grouping role with the related radio buttons descendants of the grouping element.   A screen reader would speak the question "What is 2 times 3" when focus first moved to one of the radio buttons in the group.
>
> Example:
> ```
> <div role="radiogroup" aria-labelledby="quest">
>
>   <div id="quest">How much is 2 times 3</div>
>
>   <div role="radio">2</div>
>   <div role="radio">3</div>
>   <div role="radio">6</div>
>   <div role="radio">9</div>
> </div>
> ```
>
> ### `legend` role (ARIA 1.2)
>
> The `legend` role has been proposed as a new role in ARIA 1.2 and provides a means to define an accessible name for the `group` and `radiogroup` roles through one of two methods:
>
> 1. The element with role `legend` is a descendant element of the element with the grouping role.
> 1. The element with role `legend` is referenced by the element with the grouping role using `aria-labelledby` technique.
>
> #### Example: `radiogroup` role
>
> The following example is a group of radio button widgets within a `radiogroup` grouping role with the related radio buttons descendants of the grouping element.  In this example the element with role `legend` is defining the accessible name for the element with the `radiogroup` role.   A screen reader would speak the question "What is 2 times 3" when focus first moved to one of the radio buttons in the group.
>
> ```
> <div role="radiogroup">
>
>   <div role="legend">How much is 2 times 3</div>
>
>   <div role="radio">2</div>
>   <div role="radio">3</div>
>   <div role="radio">6</div>
>   <div role="radio">9</div>
> </div>
> ```
>
> The use of the `legend` role in this example does not require the use of IDs and IREFs.
>
> ### `fieldset/legend` elements (ARIA 1.2)
>
> The `fieldset` element has the default role of `group` and the `legend` has the default role of `legend' so they can be used instead of the role attributes for defining a grouping label for a set of form controls.
>
> #### Example: `fieldset/legend` elements
>
> The following example is a group of radio button widgets using a `fieldset` element and a descendant `legend' element.   A screen reader would speak the question "What is 2 times 3" when focus first moved to one of the radio buttons in the group.
>
> ```
> <fieldset>
>
>   <legend>How much is 2 times 3</legend>
>
>   <div role="radio">2</div>
>   <div role="radio">3</div>
>   <div role="radio">6</div>
>   <div role="radio">9</div>
> </fieldset>
> ```
>
> The use of the use of the `fieldset` and `legend` elements uses HTML elements with the native semantics for defining a group label for related form controls and widgets.
>
> ## Accessible Description
>
> Accessible descriptions is a text string commonly used to provide additional information about a form control or widget, for example instructions or error feedback information.   Screen readers by default are configured to speak accessible descriptions after other information about the role, accessible name, properties and states are spoken.   There are three ways to define an accessible description for a form control or widget:
>
> 1. `aria-describedby` attribute references other elements trough the use of a list of IDREFs and the text content of the elements are concatenated to define the accessible description, similar to the way `aria-labelledby` is computed.
> 1. `aria-errormessage` attribute is essentially the same as `aria-descibedby` attribute, but it provides a means for screen readers to identify the description as an error message.  Screen reader are often configured by their users not speak accessible descriptions, especially on familiar web pages and applications to reduce the amount of verbal "noise" they need to listen too.  But error messages are different, they should not be ignored, so by identify error information screen readers can speak this information even when other description information is not spoken.
> 1. `title` attribute is used for the accessible description when it is not being used to compute the accessible name.
>
> ### Example: `aria-describedby` attribute
>
> A typical screen reader when configured a
>
> In the `aria-describedby` attribute example the description describes the date format that is displayed using the `placeholder` attribute for people who can see the form control.  The description is hidden off screen using the "sr-only" class name, who's properties are defined by the author in a CSS style sheet.
>
> ```
> <label>
>   Date
>   <input type="text"
>          placeholder="mmm/dd/yyyy"
>          aria-describedby="date_format">
>   <span class="sr-only"
>         id="date_format">
>     the format for the date is 1 or 2 digit month, back slash, 1 or 2 digit day, back slash and 4 digit year
>   </span>
> </label>
> ```
>
> ### Example: `aria-errormessage` attribute
>
> In the `aria-errormessage` example the error message is rendered visually and the `aria-errormessage` attribute references the visible message.  The `span` element also defines the `status` role, so the error message will be spoken when it first appears on the screen.  The error message will be spoken when the textbox receives keyboard focus.
>
> ```
> <label>
>   Date
>   <input type="text"
>          placeholder="mmm/dd/yyyy"
>          value="2019 September 29th"
>          aria-describedby="date_format"
>          aria-errormessage="date-error">
>   <span id="date_format"
>         class="sr-only" >
>     the format for the date is 1 or 2 digit month, back slash, 1 or 2 digit day, back slash and 4 digit year
>   </span>
>   <span id="date_error"
>         role="status">
>     The date you entered in not a valid date format, the format for the date is 1 or 2 digit month, back slash, 1 or 2 digit day, back slash and 4 digit year
>   </span>
> </label>
> ```
>
> ### Example: `title` attribute
>
> The `title` attribute will define an accessible description when it is not being used as part of the accessible name computation.   The `title` is used by most browser to create a visible tooltip and so authors should be aware that the tooltip information will be communicated to assistive technology users as an accessible description.  In the following example the accessible name is defined by the `aria-label` attribute and the `title` attribute will define the accessible description "Come and explore the all new Our World social media service".
>
> Example:
> ```
> <a aria-label="our world social media"
>    href="#"
>    title="Come and explore the all new Our World social media service">
>   <span class="icon-our-world"></span>
> </div>
> ```
>
>

Den sön 7 apr. 2019 kl 23:01 skrev Gunderson, Jon R <jongund@illinois.edu<mailto:jongund@illinois.edu>>:
I have drafted a labeling and describing section in the github wiki for the aria practices, that I believe is much more straight forward in defining and describing  the concepts of accessible name, grouping label and accessible description.   I had concerns over using the terms “implicit” and “explicit”, I think it is much more straight forward to developers to  help them understand the concepts of accessible name, grouping labels and accessible descriptions and the techniques to define these properties.

https://github.com/w3c/aria-practices/wiki/Draft-Labeling-and-Describing-Section-(Jon-Gunderson)

I hope this provides a step forward in the development of the labeling and describing section of the ARIA practices and interested in feedback.

I am attending a conference workshop on Tuesday, so I will probably not be on the call Tuesday, but I might be able to come to the last half hour.

Jon Gunderson, Ph.D., CPWA
Coordinator of Accessible IT Group
University of Illinois at Urbana/Champaign
1207 S. Oak Street
Champaign, IL 61820

www: https://go.illinois.edu/jongund



--
Simon Pieters
https://bocoup.com/