Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Label in name understanding doc update, large #614

Merged
merged 17 commits into from
Mar 8, 2019
Merged

Label in name understanding doc update, large #614

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
4138be3
Substantially modified Understanding doc and added image
mbgower Feb 11, 2019
270873d
Update label-in-name.html
mbgower Feb 11, 2019
6b713a3
Update label-in-name.html
mbgower Feb 26, 2019
b33f45d
Update label-in-name.html
mbgower Feb 26, 2019
c62d0b7
Update label-in-name.html
mbgower Mar 5, 2019
802a794
Update label-in-name.html
mbgower Mar 5, 2019
dcb1083
bunch of Oxford, Harvard, or serial commas and one space
Mar 5, 2019
a511128
Update label-in-name.html
mbgower Mar 6, 2019
eadf21b
Revert "Update label-in-name.html"
mbgower Mar 6, 2019
a4b2eec
Merge branch 'LabelinNameUnderstanding' of https://github.com/w3c/wca…
mbgower Mar 6, 2019
0f00921
Update label-in-name.html
mbgower Mar 6, 2019
7b3e4d8
Update label-in-name.html
mbgower Mar 6, 2019
b266fb4
Update label-in-name.html
mbgower Mar 6, 2019
4b637fb
Update label-in-name.html
mbgower Mar 6, 2019
8efdb35
added two commas
Mar 6, 2019
b2c56ed
minor edits
Mar 6, 2019
23094d1
Update label-in-name.html
mbgower Mar 8, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added understanding/21/img/rich-text-editor-detail.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
74 changes: 56 additions & 18 deletions understanding/21/label-in-name.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,23 +9,61 @@
<h1>Understanding Label in Name</h1>
<section id="intent">
<h2>Intent</h2>
<p>The intent of this Success Criterion (SC) is to help ensure that people with disabilities who rely on visual labels can also use
those labels programmatically. Controls are often labeled with visible text. Controls also have a programmatic label, known
as its <a href="https://www.w3.org/TR/accname-aam-1.1/">Accessible Name</a>. Users have a much better experience if the visible text labels of controls match their accessible names.</p>
<p>Speech input users can navigate by speaking the visible text labels of menus, links and buttons that appear on the
screen. It's confusing to speech input users when they say a visible text label they see, but the speech input does not work
because the accessible name that is enabled as a speech input command does not match the visible label.</p>
<p>In addition, when the accessible names of controls are visually hidden, speech users may accidentally activate these controls when they happen to speak words that map to these hidden accessible names.</p>
<p>Text-to-speech users will also have a better experience if the text they hear matches the text they see on the screen.</p>
<p>Sometimes authors want to add additional text to provide more context to a link or other control to make it more descriptive for users of assistive technologies. In this case, it is a recommended practice to add that text <strong>after</strong> the visible label so the accessible name starts with the visible label. In the case of the search button, the accessible name could be "search this site", in the case of the home link, the text could be "home - go to start page". In both cases, the hidden portion of the label may be supplied by different means, for example, as text accessibly hidden via CSS or by using the aria-label or the aria-labelledby attribute.</p>
<p>This issue is even more important for speech input and text-to-speech users who also have cognitive challenges. It’s an extra
cognitive load for a speech input user to remember and say a speech command that is different from the visible label they see on a
control. It’s also an extra cognitive load for a text-to-speech user to absorb and understand speech output that does not
match the visible label.</p>
<p>The intent of this Success Criterion (SC) is to make text that is <em>visually</em> associated with a component also associated with the component <em>programmatically</em>. This helps ensure that people with disabilities can rely on visible labels as a means to interact with the components.</p>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be picky, the first sentence makes it sound to me like it has to be the same piece of text in the markup that is associated. However, it can be duplicated as well (i.e. the visual text itself, and then an alternative that duplicates that particular text, e.g. First name <input ... aria-label="First name">(

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you have a wording suggestion that solves that, I'll be happy, but I find trying to be clear about text vs text string, etc., has resulted in it being more confusing (or at least a lot harder to parse). Yes, one could just recreate the visible string in an aria-label; however at some point automated rules are going to start failing the multiple variations which would probably be okay with speech recognition -- e.g., "First Name:" and "firstname" -- and it is just so much easier for everyone if aria-label is left out where possible.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would tend not to handwave away the ways in which it's perfectly valid to pass this SC (e.g. using aria-label). So starting with something like

The intent of this Success Criterion (SC) is to make sure that text that is <em>visually</em> associated with a component also forms part of the component's accessible name.

and then adding more explanations, references, examples could be better?

Examples could be along the lines of (grabbing something I threw together not so long ago for an unofficial explainer):

<a href="..." aria-label="Please read more about WCAG 2.1">Read more</a> would pass, as the “Read more” string (disregarding capitalization) is present in the aria-label

<a href="..." aria-label="Read about WCAG 2.1">Read more</a> would fail, as the string is not present

<a href="..." aria-label="Read some more about WCAG 2.1">Read more</a> would fail, as the aria-label does not contain the actual string “read more” (the word “some” is between “Read” and “more”)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about:
The intent of this Success Criterion (SC) is to make the accessible name include (or match) the text used for the visual label for a component. This helps ensure that people with disabilities can rely on visible labels as a means to interact with the components.

<p>Most controls are accompanied by a visible text <strong>label</strong>. Those same controls have a programmatic <strong>name</strong>, also known as the <a href="https://www.w3.org/TR/accname-aam-1.1/">Accessible Name</a>. Users typically have a much better experience if the words in the visible label of a control match (or are contained within) the accessible name. When these match, speech-input users (i.e., users of speech recognition applications) can navigate by speaking the visible text labels of components, such as menus, links and buttons, that appear on the screen. Sighted users who use text-to-speech (e.g., screen readers) will also have a better experience if the text they hear matches the text they see on the screen.</p>
<p>Note that where a visible text label does not exist for a component, this Success Criterion does not apply to that component.</p>
<p>Where text labels exist and are properly linked to the user interface components through established authoring practices, the label and name will normally match. When they don't match, speech-input users who attempt to use the visible text label as a means of navigation or selection (e.g., "move to Password") will be unsuccessful. The speech-based navigation fails because the visible label spoken by the users does not match (or is not part of) the accessible name that is enabled as a speech-input command. In addition, when the accessible name is different from the visible label, it may function as a hidden command that can be accidentally activated by speech-input users.</p>
<p>Mismatches between visible labels and programmatic names for controls are even more of an issue for speech-input and text-to-speech users who also have cognitive challenges. Mismatches create an extra cognitive load for speech-input users, who must remember to say a speech command that is different from the visible label they see on a control. It also creates extra cognitive load for a text-to-speech user to absorb and understand speech output that does not match the visible label.</p>
<h3>Confining the label to adjacent text</h3>
mbgower marked this conversation as resolved.
Show resolved Hide resolved
<p>In order for the label text and accessible name to be matched, it is first necessary to determine which text on the screen should be considered a label for any given control. There are often multiple text strings in a user interface that may be relevant to a control. However, there are reasons why it is best to conservatively interpret the label as being only the text in close proximity.</p>
<p>Conventionally the label for user interface components is the adjacent text string. The typical positioning for left to right languages is:
<ul><li>immediately to the left of comboboxes, dropdown lists, text inputs and other widgets (or in the absence of left-side labels, immediately above and aligned with the left edge of each input)</li>
<li>immediately to the right of checkboxes and radio buttons</li>
<li>inside buttons and tabs or immediately below icons serving as buttons</li>
</ul>
The rationale for some of these conventions is explained in <a href="https://www.w3.org/WAI/GL/2016/WD-WCAG20-TECHS-20160105/G162">G162: Positioning labels to maximize predictability of relationships</a>.
</p>
<p>It is important to bias towards treating only the adjacent text as a label because liberal interpretations of what constitutes a text label can jeopardize the value of this Success Criteria by lessening predictability. Isolating the label to the single string in close proximity to the component makes it easier for developers, testers and end users to identify the label targeted for evaluation in this SC. Predictable interpretation of labeling allows users of speech recognition technologies to interact with the element via its conventionally positioned label, and allows users of screen reading technologies to enjoy consistency between the nearby visible label and the announced name of the component.</p>
awkawk marked this conversation as resolved.
Show resolved Hide resolved
<p>Note that placeholder text within an input field is not considered an appropriate means of providing a label. The <a href="https://www.w3.org/TR/html52/sec-forms.html#the-placeholder-attribute">HTML5 specification</a> states <q>The placeholder attribute should not be used as an alternative to a &lt;label&gt;.</q> However, it is worth noting that "label" in that HTML5 statement is in code brackets and links to the <code>label</code> element. For the purposes of this Label in Name Success Criterion, "label" is not used in such a programmatic sense but is simply referring to a text string in close visual proximity to a component. As such, in the absence of any other nearby text string (as described in the preceding list), if an input contains placeholder text, such text may be a candidate for Label in Name. This is supported both through the accessible name calculation (discussed later) and from the practical sense that where a visible label is not otherwise provided, it is likely that a speech-input user may attempt to use the placeholder text value as a means of interacting with the input.</p>
<h3>Text labels "express something in human language"</h3>
<h4>Symbolic text characters</h4>
<p>For the purposes of this SC, text should not be considered a visible label if it is used in a symbolic manner, rather than directly <q>expressing something in human language</q> as per the <a href="https://www.w3.org/TR/WCAG21/#dfn-text">definition of text in WCAG</a>. For example, <a href="https://www.w3.org/TR/WCAG21/#images-of-text">1.4.5 Images of Text</a> describes considerations for "symbolic text characters." In the images of text example "B", "I" and "ABC" appear on icons in a text editor, where they are meant to symbolize the functions for Bold, Italics and Spelling, respectively. In such a case, the accessible name should be the function the button serves (e.g., "Spell check" or "Check spelling"), not the visible symbolic characters. A similar text editor is shown in Figure 1.</p>
<figure>
<img alt="Icons for transforming text, including heading, bold, italic, quote, code and link, along with icons for ordered and unordered lists and other controls" src="img/rich-text-editor-detail.png">
<figcaption>Figure 1. A detail of the rich text editor in Github, showing a variety of unlabeled icons, including icons resembling text characters.</figcaption>
</figure>
<p>Likewise, where an author has used a greater-than symbol (">") to mimic the appearance of the right-facing arrow, the text does not convey something in human language. It is a symbol, in this scenario likely meant to mimic the icons used for a "Play" button or a "Next" arrow.</p>
<h4>Punctuation and capitalization</h4>
<p>The use of punctuation and capitalization in labels <em>may</em> also be considered optional for the same reason. For example, the colon conventionally added at the end of input labels does not express something in human language, and capitals on the first letter of each word in a label do not normally alter the words' meaning. This is particularly relevant in the context of this SC, since it is primarily aimed at users of speech recognition; capitals and most punctuation are frequently ignored when a user speaks a label as a means of interacting with a control.</p>
<p>While it is certainly not an error to include the colon and capitalization in the accessible name, a computed name of "First name" should not be considered a failure of "First Name:".<br />
<label for="firstname">First Name: </label><input id="firstname" type="text" name="firstname"><br />
Likewise, "Next…" visibly shown on a button could have "Next" as the accessible name. When in doubt, where a meaningful visible label exists, match the string exactly for the accessible name.<br />
<input type="submit" value="Next..."></p>

<h4>Mathematical expressions and formulae</h4>
<p>Mathematical expressions can be used as labels, for example "11x3=33" and "A>B" convey meaning. The label should not be overwritten in the accessible name, and substitutions of words where a formula is used should be avoided, such as making the name "eleven times three equals thirty-three" or "A is greater than B". Doing so would mean that a user who said "eleven multiplied by 3 is equivalent to thirty-three" would be unlikely to match. Further, converting a mathematical formula label into an accessible name that is a spelled-out equivalent may create issues for translation. The name should match the label's formula text.<br />
mbgower marked this conversation as resolved.
Show resolved Hide resolved

<input type="radio" name="equation" id="answer1" value="A>B"><label for="answer1">A&gt;B</label>
<input type="radio" name="equation" id="answer2" value="A=B"><label for="answer2">A=B</label>
<input type="radio" name="equation" id="answer3" value="A<B"><label for="answer3">A&lt;B</label></p>

<h3>Accessible Name and Description Computation specification</h3>
<p>It is important to understand how the visible label may be different than the accessible name. The <a href="https://www.w3.org/TR/accname-1.1/">Accessible Name and Description Computation 1.1</a> and the <a href="https://w3c.github.io/html-aam/#accessible-name-and-description-computation">HTML Accessibility API Mappings 1.0</a> describe how the accessible name is computed, including which attributes are considered in its calculation, and in what order of preference. If a component has multiple possible attribute values that could be used for its accessible name, only the most preferred of those values will be computed. None of the other, less preferred values will be part of the name.</p>
<p>Some visually unobvious attribute values – specifically <code>aria-label</code> and <code>aria-labelledby</code> – take precedence in the name calculation (overriding the visible text as the accessible name) even when the visible text label is programmatically associated with the control. For this reason, when a visible label already exists, <code>aria-label</code> should be avoided or used carefully, and <code>aria-labelledby</code> should be used as a supplement with care.</p>
<p>Other text displayed on the screen that is correctly coded to meet 1.3.1: Info and Relationships is <strong>not</strong> normally factored into the calculation for the accessible name of a UI component without author intervention (via ARIA labeling techniques). The most common of these are:
<ul>
<li>headings and instructions</li>
<li>group labels for sets of components (i.e., used with <code>legend</code>/<code>fieldset</code> or with role of <code>group</code> or <code>radiogroup</code>)</li>
</ul>
Such textual information may constitute part of the component's <em>description</em>. So from both a programmatic viewpoint, and from the conservative tactic of only considering a label to be "adjacent text," neither headings, instructions nor group 'labels' should normally be considered <strong>labels</strong> for the purpose of this Success Criterion.
</p>
<p>Finally, <code>aria-describedby</code> is not included in the Accessible Name computation (instead it is part of the Accessible Description computation). By convention, text associated with a control through <code>aria-describedby</code> is announced immediately after the accessible name by screen readers. Therefore, the context of headings, instructions and group labels can be provided through the accessible description to assist users of screen readers without affecting the experience of those who navigate using speech recognition software.</p>


<section id="benefits">
<h3>Benefits</h3>
<h2>Benefits</h2>
<ul>
<li>Speech input users can directly activate controls on a page with fewer surprising changes of focus.</li>
<li>Speech-input users can directly activate controls on a page with fewer surprising changes of focus.</li>
<li>Text-to-speech users will have a better experience because the labels that they hear match the visible text labels that
they see on the screen.</li>
</ul>
Expand All @@ -35,7 +73,7 @@ <h3>Benefits</h3>
<h2>Examples</h2>
<ul>
<li><strong>Accessible name matches visible label:</strong> The accessible name and visible label of a control match.</li>
<li><strong>Accessible name starts with visible label:</strong> The acessible name of a "Buy Now" button begins with the same text as the visible label.</li>
<li><strong>Accessible name starts with visible label:</strong> The acessible name "Search for a value" begins with the text of the visible label, "Search".</li>
</ul>
</section>
<section id="resources">
Expand All @@ -62,9 +100,9 @@ <h2>Advisory</h2>
<section id="failure">
<h2>Failure</h2>
<ul>
<li><a href="../../techniques/failures/F96">F96</a></li>
<li><a href="../../techniques/failures/F96">Failure due to "accessible name" not containing the visibile label text</a></li>
<li>@@ Accessible name contains the visible label text, but the words of the visible label are not in the same order as they are in the visible label text</li>
<li>@@ Accessible name contains the visible label text, but one or more other words is interspersed in the label</li>
<li>@@ Accessible name contains the visible label text, but one or more other words are interspersed in the label</li>
</ul>
</section>
</section>
Expand Down