feat: aria-braillelabel (#923)

pkra · web-flow · commit 99763b0cd439 · 2020-03-11T09:50:13.000-07:00
diff --git a/index.html b/index.html
@@ -11818,6 +11818,56 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
 				</tbody>
 			</table>
 		</div>
+		<div class="property" id="aria-braillelabel">
+			<pdef>aria-braillelabel</pdef>
+			<div class="property-description">
+				<p>Defines a string value that labels the current element, which is intended to be converted into Braille. See related <pref>aria-label</pref>.</p>
+				<p>The purpose of <pref>aria-braillelabel</pref> is similar to that of <pref>aria-label</pref>. It provides the user with a recognizable name of the object in Braille.</p>
+				<p>The <pref>aria-braillelabel</pref> property gives authors the ability to override how assistive technologies localize and express the accessible name of an element in Braille. Thus inappropriately using <pref>aria-braillelabel</pref> may inhibit users' ability to understand an element on braille interfaces. Authors SHOULD limit use of <pref>aria-braillelabel</pref> to instances where the name of an element when converted to Braille is not the desired user experience.</p>
+				<p> When using <code>aria-braillelabel</code>, authors SHOULD also ensure that:</p>
+				<ol>
+					<li>The element to which <code>aria-braillelabel</code> is applied has a valid accessible name.</li>
+					<li>The value of <code>aria-braillelabel</code> is not empty or does not contain only whitespace characters.</li>
+					<li>The value of <code>aria-braillelabel</code> does not contain any characters in Unicode Braille Patterns (U+2800..U+28FF) or consists of only characters in Unicode Braille Patterns (U+2800..U+28FF) while not containing only Braille Pattern dots-0 (U+2800).</li>
+					<li>The value of <code>aria-braillelabel</code> is not identical to the element's accessible name.</li>
+				</ol>
+				<p class="note">Note that <a>Assistive Technologies</a> with braille support can convert the accessible name to Braille. In addition, assistive technologies will be able to customize such braille output according to user preferences. Using only the accessible name, e.g., from content or via <code>aria-label</code> is <strong>almost always</strong> the better user experience and authors are <strong>strongly discouraged</strong> from using <code>aria-braillelabel</code> to replicate <code>aria-label</code>. Instead, <code>aria-braillelabel</code> is meant to be used only if the accessible name cannot provide an adequate braille representation, i.e., when a specialized braille description is very different from a text description converted to Braille. It is very important to note that when using <code>aria-braillelabel</code> authors are solely responsible to align the attribute value with the document language and clearly communicate the use of this attribute to the user. This is even more important when the value consists of Unicode Braille Patterns because <a>Assistive Technologies</a> will pass such content directly to the user without applying user specific braille translations; in general, authors are <strong>strongly discouraged</strong> from using Unicode Braille Patterns in <code>aria-braillelabel</code>.
+				</p>
+				<p><a>Assistive technologies</a> SHOULD use the value of <code>aria-braillelabel</code> when presenting the accessible name of an element in Braille, but SHOULD NOT change other functionality. For example, an assistive technology that provides aural rendering SHOULD use the accessible name.</p>
+				<p><a>Assistive technologies</a> SHOULD expose the <code>aria-braillelabel</code> property as follows:</p>
+				<ol>
+					<li>If the value of <code>aria-braillelabel</code> does not contain characters in Unicode Braille Patterns (U+2800..U+28FF), translate the value according to the user's preferred translation table.</li>
+					<li>Otherwise, pass the value to the user without translation.</li>
+				</ol>
+				<p>The following example shows the use of <code>aria-braillelabel</code> to customize a button's name in braille output.</p>
+				<pre class="example highlight">&lt;button aria-braillelabel="****"&gt;
+  &lt;img alt="4 stars" src="images/stars.jpg"&gt;
+&lt;/button&gt;</pre>
+				<p>In the previous example, a braille display may display "btn ****" in Braille rather than the verbose "btn gra 4 stars".</p>			</div>
+			<table class="property-features">
+				<caption>Characteristics:</caption>
+				<thead>
+					<tr>
+						<th scope="col">Characteristic</th>
+						<th scope="col">Value</th>
+					</tr>
+				</thead>
+				<tbody>
+					<tr>
+						<th class="property-applicability-head" scope="row">Used in Roles:</th>
+						<td class="property-applicability">All elements of the base markup</td>
+					</tr>
+					<tr>
+						<th class="property-descendants-head" scope="row">Inherits into Roles:</th>
+						<td class="property-descendants">Placeholder</td>
+					</tr>
+					<tr>
+						<th class="property-value-head" scope="row">Value:</th>
+						<td class="property-value"><a href="#valuetype_string">string</a></td>
+					</tr>
+				</tbody>
+			</table>
+		</div>
 		<div class="property" id="aria-level">
 			<pdef>aria-level</pdef>
 			<div class="property-description">
