Re: Alternative draft of the labeling and describing section

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

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