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

Update label-in-name.html #2725

Merged
merged 17 commits into from Apr 11, 2024
Merged

Update label-in-name.html #2725

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
dbcd18a
Update label-in-name.html
mbgower Oct 11, 2022
0e3e259
Update label-in-name.html
mbgower Oct 12, 2022
d5329a3
Update label-in-name.html
mbgower Oct 12, 2022
1b7c0d5
Update G211.html
mbgower Oct 17, 2022
bcaa80d
Merge branch 'LabelInNameUnderstandingUpdates' of https://github.com/…
mbgower Oct 17, 2022
f90c61f
Update label-in-name.html
mbgower Oct 17, 2022
e877972
Update understanding/21/label-in-name.html
mbgower Jan 31, 2023
65ced68
Update G211.html
mbgower Jan 31, 2023
fa3006a
Update G211.html
mbgower Jan 31, 2023
6c31940
Update G211.html
mbgower Feb 1, 2023
eaf0c9b
Adding optionally
alastc Feb 3, 2023
eacd3e5
Update G211.html
mbgower Feb 15, 2023
c638219
tweaks to parenthetical term
mbgower Feb 15, 2023
d2c9f23
Update label-in-name.html
mbgower Feb 15, 2023
e40a7ff
No changes to content, only mark-up for code samples
fstrr May 19, 2023
0e8b2dc
Replaced image, added CSS to examples
fstrr May 19, 2023
bc66bd5
Merge branch 'main' into LabelInNameUnderstandingUpdates
mbgower Apr 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
144 changes: 81 additions & 63 deletions techniques/general/G211.html
View file
Open in desktop

Large diffs are not rendered by default.

Binary file modified techniques/general/img/stacked-label.png
View file
Open in desktop
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
81 changes: 47 additions & 34 deletions understanding/21/label-in-name.html
View file
Open in desktop
Expand Up @@ -41,48 +41,61 @@ <h3>Identifying label text for components</h3>
<section>
<h3>Text labels "express something in human language"</h3>
<section>
<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 definition of <a>text</a> in WCAG. For example, <a href="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 the figure below.</p>
<figure id="figure-RTE-github">
<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>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 (<code>&gt;</code>) 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>
</section>
<section>
<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:".</p>

<pre xml:space="preserve"><code class="language-html">
&lt;label for="firstname"&gt;First Name:&lt;/label&gt;
&lt;input id="firstname" type="text" name="firstname"&gt;
</code></pre>

<p>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.</p>
<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 definition of <a>text</a> in WCAG. 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 the figure below.</p>
<figure id="figure-RTE-github">
<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>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>
</section>
<h4>Punctuation and capitalization</h4>

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

<pre xml:space="preserve"><code class="language-html">
&lt;input type="submit" value="Next..."&gt;
</code></pre>
<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.<br />
<input type="submit" value="Next..." />. When in doubt, where a meaningful visible label exists, match the string exactly for the accessible name.</p>

</section>
<section>
<h4>Mathematical expressions and formulae</h4>
<p>Mathematical expressions are an exception to the previous subsection about symbolic characters. Math symbols can be used as labels; for example <code>11&#215;3=33</code> and <code>A&gt;B</code> convey meaning. The label should not be overwritten in the accessible name, and substitutions of words where a formula is used should be avoided since there are multiple ways to express the same equation. For example, making the name "eleven multiplied by three is equivalent to thirty-three" might mean a user who said "eleven times three equals thirty-three" may not match. It is best to leave the formulas as used in the label and count on the user's familiarity with their speech software to achieve a 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. Note that a consideration for authors is to use the proper symbol in the formula. For instance <code>11x3</code> (with a lower or upper case letter X), <code>11*3</code> (with the asterisk symbol), and <code>11&#215;3</code> (with the <code>&amp;times;</code> symbol) are all easy for sighted users to interpret as meaning the same formula, but may not all be matched to "11 times 3" by the speech recognition software. The proper operator symbol (in this case the times symbol) should be used.</p>

<h4>Mathematical expressions and formulae</h4>
<section>
<p>Mathematical expressions are an exception to the previous subsection about symbolic characters. Math symbols can be used as labels; for example "11&#215;3=33" and "A>B" convey meaning.<br />

<pre xml:space="preserve"><code class="language-html">
&lt;input type="radio" name="equation" id="answer1" value="A&gt;B"&gt;&lt;label for="answer1"&gt;A&gt;B&lt;/label&gt;
&lt;input type="radio" name="equation" id="answer2" value="A=B"&gt;&lt;label for="answer2"&gt;A=B&lt;/label&gt;
&lt;input type="radio" name="equation" id="answer3" value="A&lt;B"&gt;&lt;label for="answer3"&gt;A&lt;B&lt;/label&gt;
</code></pre>

<input type="radio" name="equation" id="answer1" value="A&gt;B" /><label for="answer1">A&gt;B</label>
<input type="radio" name="equation" id="answer2" value="11&times3=33" /><label for="answer2">11&times3=33</label>
</p>
<p>The label should not be overwritten in the accessible name, and substitutions of words where a formula is used should be avoided since there are multiple ways to express the same equation. For example, making the name "eleven multiplied by three is equivalent to thirty-three" might mean a user who said "eleven times three equals thirty-three" may not match. It is best to leave the formulas as used in the label and count on the user's familiarity with their speech software to achieve a 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. Note that a consideration for authors is to use the proper symbol in the formula. For instance 11x3 (with a lower or upper case letter X), 11*3 (with the asterisk symbol), and 11&#215;3 (with the <code>&amp;</code>times<code>;</code> symbol) are all easy for sighted users to interpret as meaning the same formula, but may not all be matched to "11 times 3" by the speech recognition software. The proper operator symbol (in this case the times symbol) should be used.</p>
</section>
</section>
<section>
<h3>Accessible Name and Description Computation specification</h3>
<p>It is important to understand how the accessible name is derived. The <a href="https://www.w3.org/TR/accname-1.1/">Accessible Name and Description Computation 1.1</a> and the <a href="https://www.w3.org/TR/html-aam-1.0/#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. For the most part, existing established programmatic relationships between labels and controls are reinforced by the specification.</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:</p>

<h3>Accessible Name and Description Computation specification</h3>
<p>It is important to understand how the accessible name is derived. 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. For the most part, existing established programmatic relationships between labels and controls are reinforced by the specification.</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:</p>
<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>
<p>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>It is important to note that the specification allows authors to override the name calculated through native semantics. Both <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>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>
mbgower marked this conversation as resolved.
Show resolved Hide resolved
</section>
<h4>Text in parentheses</h4>
<section>
<p>Note: The term "parenthetical" in this section is describing text that literally appears within a set of round brackets (). It is not used in the more abstract sense of "information related to".</p>
<p>It is important to mention parenthetical text in labels in the context of accessible name versus description. In common usage, text in parentheses is considered secondary but relevant to meaning. Users of speech recognition would not typically announce text in parentheses as part of the input name. For that reason, parenthetical text may be optionally considered a description and left out of the accessible name.</p>
<p>However, where parenthetical information provides important context, such as indication of a required field or limitations on what is allowed for input, this information must be provided programmatically in some other way to the user if that information is not included as part of the accessible name. For example, "Name (required)" and "Date (YYYY-MM-DD)" could accept "Name" and "Date" as the accessible names. However, in order to pass 1.3.1 Info & Relationships, authors would need to programmatically surface both the required state and the limit on the allowed data formatting (in this example, eight integers fitting the YYYY-MM-DD pattern). The "required" state could be surfaced through the HTML <code>required</code> attribute or by using <code>aria-required="true"</code>. The allowed data formatting could be surfaced by being referenced using the <code>aria-describedby</code>) attribute.</p>
Copy link

Choose a reason for hiding this comment

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

Is it possible to list outliers to this? In the US, area codes for telephone numbers are sometimes shown within parentheses. Ex: (202)555-5555. The area code should be part of the name.

Copy link

Choose a reason for hiding this comment

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

@kengdoj I think this use case falls under the "However, where parenthetical information provides important context, such as indication of a required field or limitations on what is allowed for input." I know how much easier it is top point developers to a line in a spec or documentation, but the possible number of cases that could be an outlier is potentially huge.
Also, I question any label that includes the formatting. That really should be aria-describedby information.

Copy link
Contributor

Choose a reason for hiding this comment

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

I don't think this text increases understanding. Parenthetical information (relevant, but not necessary to understand), is probably better in the description than the label. Whether it is presented in parentheses (round brackets) or not seems more like a typographical accident.

I'm prone to putting a lot in parentheses. Some use commas and subsidiary clauses instead, others write more sentences.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I'd agree with @nattarnoff that the example of the area code in parentheses doesn't seem to enter into the discussion on parentheses in a label. @kengdoj can you supply an example of an area code in a phone input label that would be problematic with the guidance listed in this subsection?

Copy link
Contributor Author

@mbgower mbgower Apr 11, 2024 •
edited

Choose a reason for hiding this comment

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

Parenthetical information (relevant, but not necessary to understand), is probably better in the description than the label.

@chaals I entirely agree, but there's an unfortunate gap between what people should do and what they DO. As well as a gap between the intent of this SC and how it is being interpreted. Also, you'll note that the final advice in the section is that anything used parenthetically which affects input limitations needs to be surfaced programmatically -- with aria-describedby as a suggestion for how to incorporate.

Whether it is presented in parentheses...seems more like a typographical accident. Some use commas and subsidiary clauses instead, others write more sentences.

Remember that we're discussing parentheses strictly in the context of input labels. These changes were introduced to address issues opened by users, and have support. In fact, this has already been voted on and approved by the WG.

</section>


<section id="benefits">
<h2>Benefits</h2>

<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>
Expand Down
17 changes: 15 additions & 2 deletions working-examples/label-in-name-general/example1.html
View file
Open in desktop
@@ -1,12 +1,25 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="EN">
<!DOCTYPE html>
<html lang="en">
<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<title>Example of Simple Radio Button Group</title>
<style>
html{
background: white;
color:black;
}
body{
font: 1rem/1.5 system-ui, "Segoe UI", Roboto, Helvetica, sans-serif;
}
</style>
</head>
<body>
<fieldset>

<legend>Call me when balance exceeds $10,000?</legend><br/>

<input type="radio" id="yes" name="callme" value="yes">
<label for="yes">Yes</label>
<input type="radio" id="no" name="callme" value="no">
Expand Down
56 changes: 37 additions & 19 deletions working-examples/label-in-name-general/example2.html
View file
Open in desktop
@@ -1,22 +1,43 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="EN">
<!DOCTYPE html>
<html lang="en">
<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>Example of Stacked Labels</title>
<style type="text/css">
form
{font-family:Arial,sans-serif;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;font-weight:400;}
.example-page
{padding:60px 30px 30px}
.form-group
{margin-bottom:20px}
.label
{font-size:1.2rem;line-height:1.3;color:#0b0c0c;display:block;margin-bottom:5px}
.hint
{font-size:1rem;line-height:1.25;display:block;margin-bottom:5px;color:#6f777b}
.input
{font-size: 1rem;line-height: 1.25;box-sizing: border-box;width: 70%;height: 40px;padding:5px;border: 2px solid #0b0c0c; border-radius: 0;}

<title>Example of Stacked Labels</title>
<style>
html{
background: white;
color:black;
}
body{
font: 1rem/1.5 system-ui, "Segoe UI", Roboto, Helvetica, sans-serif;
}
input{
border: 2px solid #0b0c0c;
border-radius: 0;
font:inherit;
letter-spacing: inherit;
padding:0.4em;
width: 70%;
word-spacing: inherit;
}
.form-group {
margin-bottom:1.125rem
}
.label {
color:#0b0c0c;
display:block;
font-size:1.2rem;
line-height:1.3;
margin-bottom:5px}
.hint{
color:#6f777b;
display:block;
font-size:1rem;
line-height:1.25;
margin-bottom:0.26em;
}
</style>

</head>
Expand All @@ -40,9 +61,6 @@
</span>
<input class="input" id="example-2" name="example-2" type="text" aria-describedby="example-2-hint">
</div>



</form>
</body>
</html>
21 changes: 19 additions & 2 deletions working-examples/label-in-name-general/example3.html
View file
Open in desktop
@@ -1,8 +1,25 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="EN">
<!DOCTYPE html>
<html lang="en">
<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<title>Example of Work Phone input set</title>
<style>
html{
background: white;
color:black;
}
body{
font: 1rem/1.5 system-ui, "Segoe UI", Roboto, Helvetica, sans-serif;
}
input{
border: 1px solid #0b0c0c;
font:inherit;
letter-spacing: inherit;
word-spacing: inherit;
}
</style>
</head>
<body>
<div role="group" aria-labelledby="groupLabel">
Expand Down
15 changes: 13 additions & 2 deletions working-examples/label-in-name-general/example4.html
View file
Open in desktop
@@ -1,8 +1,19 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="EN">
<!DOCTYPE html>
<html lang="en">
<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>

<title>Example of Range of Inputs</title>
<style>
html{
background: white;
color:black;
}
body{
font: 1rem/1.5 system-ui, "Segoe UI", Roboto, Helvetica, sans-serif;
}
</style>
</head>
<body>
<fieldset>
Expand Down