这是indexloc提供的服务，不要输入任何密码
Skip to content

feat: aria-brailleroledescription #924

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

Merged
merged 9 commits into from
Oct 14, 2019
Merged

feat: aria-brailleroledescription #924

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
47de3e9
feat: aria-roledescription braille, first draft
pkra Apr 3, 2019
5220217
aria-roledescription-braille: remove mention of ascii.
pkra Jun 13, 2019
19a4375
aria-roledescription-braille: rename property
pkra Jun 27, 2019
dd056dd
aria-brailleroledescription: add restrictions and notes
pkra Jun 27, 2019
0e77136
aria-brailleroledescription: update example
pkra Jun 27, 2019
2d32018
aria-brailleroledescription: minor rephrase to note
pkra Jul 17, 2019
c9f305c
aria-brailleroledescription: tweaks after WG discussion
pkra Aug 28, 2019
8bd7219
aria-brailleroledescription: changes after TPAC
pkra Sep 24, 2019
2579a05
aria-brailleroledescription: update telco Sept 26
pkra Sep 27, 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
58 changes: 58 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11053,6 +11053,64 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
</tbody>
</table>
</div>
<div class="property" id="aria-brailleroledescription">
<pdef>aria-brailleroledescription</pdef>
<div class="property-description">
<p>Defines a human-readable, author-localized Braille description for the <a>role</a> of an <a>element</a>.</p>
Copy link
Contributor

Choose a reason for hiding this comment

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

I think this could be better described as: "Defines a human-readable, author-localized short description for the role of an element, which is intended to be converted into Braille."

Copy link
Contributor

Choose a reason for hiding this comment

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

Perhaps "abbreviated role description"

Copy link
Member Author

Choose a reason for hiding this comment

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

Thanks, @cookiecrook, I'll make a new PR to address this.

<p>Some <a>assistive technologies</a>, such as screen readers, present the role of an element as part of the user experience. Such assistive technologies typically localize the name of the role, and they may customize it as well. Users of these assistive technologies depend on the presentation of the role name, such as "region," "button," or "slider," for an understanding of the purpose of the element and, if it is a widget, how to interact with it.</p>
<p>The <code>aria-brailleroledescription</code> property gives authors the ability to override how <a>assistive technologies</a> localize and express the name of a role in Braille. Thus inappropriately using <code>aria-brailleroledescription</code> may inhibit users' ability to understand or interact with an element on Braille interfaces. Authors SHOULD limit use of <code>aria-brailleroledescription</code> to clarifying the purpose of non-interactive container roles like <rref>group</rref> or <rref>region</rref>, or to providing a <em>more specific</em> description of a <rref>widget</rref> in a Braille context.</p>
Copy link
Contributor

Choose a reason for hiding this comment

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

Editorial nit: The proper nouns: Braille, Web, Internet, should be capitalized, however, their adjective counterparts should not. E.g. "A web page on the Web." "She read Braille on a braille display." IOW, the first use of the word on this line ("…the role in Braille.") is capitalized correctly. The second instance ("…in a Braille context.") should be lowercased.

Copy link
Contributor

Choose a reason for hiding this comment

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

There are a bunch of other instances of this throughout the PR.

Copy link
Member Author

Choose a reason for hiding this comment

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

Thanks.

<p>Authors MUST NOT use <code>aria-brailleroledescription</code> without providing a <em>more specific</em> <code>aria-roledescription</code>. In general, <code>aria-brailleroledescription</code> should only be used in rare cases when a <code>aria-roledescription</code> does not suffice.</p>
Copy link
Contributor

Choose a reason for hiding this comment

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

s/does not suffice/is excessively verbose when rendered in Braille./

Copy link
Member Author

Choose a reason for hiding this comment

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

Thanks.

<p> When using <code>aria-brailleroledescription</code>, authors SHOULD also ensure that:</p>
<ol>
<li>The element to which <code>aria-brailleroledescription</code> is applied has a valid <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> role or has an implicit WAI-ARIA role semantic.</li>
<li>The value of <code>aria-brailleroledescription</code> is not empty or does not contain only whitespace characters.</li>
<li>The value of <code>aria-brailleroledescription</code> consists of a string of either Unicode with no Unicode Braille Patterns (U+2800..U+28FF) or consists of a string of only Unicode Braille Patterns (U+2800..U+28FF) while not only containing Braille Pattern dots-0 (U+2800).</li>
</ol>
<p class="note">Note that <a>Assistive Technologies</a> with Braille support can convert <code>aria-roledescription</code> content to Braille. In addition, assistive technologies will be able to customize such Braille output according to user preferences. Using only <code>aria-roledescription</code> is <strong>almost always</strong> the better user experience and authors are <strong>strongly discouraged</strong> from using <code>aria-brailleroledescription</code> to replicate <code>aria-roledescription</code>. Instead, <code>aria-brailleroledescription</code> is meant be used only when <code>aria-roledescription</code> 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-brailleroledescription</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-brailleroledescription</code>.
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 really understand this note. It seems to be burying the fact that most authors should never use EITHER aria-roledescription OR aria-brailleroledescription.

Copy link
Member Author

Choose a reason for hiding this comment

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

This note has been expanded several times over the lifetime of this PR. I agree it's a bit long-winded. I'll think about possible improvements (first guess: moving the second part to the front), but I'd be happy for any suggestions.

Copy link
Contributor

Choose a reason for hiding this comment

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

What about:

As a general rule, representing an object's role is a job best left to the assistive technologies which have been configured by the user based on their specific needs and preferences. Because aria-roledescription overrides this representation, it should only be used when absolutely necessary.

aria-brailleroledescription makes it possible for authors who are knowledgeable about Braille in general, and about their users' needs in particular, to provide a better experience than would be had from a braille translation of the aria-roledescription value. Authors who lack this knowledge should not use aria-brailleroledescription because a long, but correctly-translated, braille string is preferable to a shorter, but incorrect one.

Authors are also strongly discouraged from using Unicode Braille Patterns. Providing the value of aria-brailleroledescription as text makes it possible for assistive technologies to apply the user's preferred translation tables thus increasing the likelihood that the result will be closer to what the user expects.

Copy link
Member Author

Choose a reason for hiding this comment

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

Sounds good to me. @cookiecrook what do you think?

</p>
<p>User agents MUST NOT expose the <code>aria-brailleroledescription</code> property if any of the following conditions exist:</p>
<ol>
<li>The element to which <code>aria-brailleroledescription</code> is applied does not have a valid WAI-ARIA <code>role</code> or does not have an implicit WAI-ARIA role semantic.</li>
<li>The value of <code>aria-brailleroledescription</code> is empty or contains only whitespace characters or contains only Braille Pattern dots-0 (U+2800).</li>
<li>The element to which <code>aria-brailleroledescription</code> is applied does not have a valid WAI-ARIA <code>aria-roledescription</code>.</li>
<li>The element to which <code>aria-brailleroledescription</code> is applied has a valid WAI-ARIA <code>aria-roledescription</code> that is identical to a WAI-ARIA <code>role</code> or an implicit WAI-ARIA role semantic.</li>
Copy link
Contributor

Choose a reason for hiding this comment

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

This line invalidates using img as a short braille description. Was that intentional? Same thing with "toc" if that one makes it from the DPUB module into the core spec.

Copy link
Member Author

Choose a reason for hiding this comment

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

I admit I struggle to answer that. The relevant commit is from June and the commit message explicitly mentions this change. I would have said I added it after feedback from the group, but I can't find any minutes around the time that match this idea.

</ol>
<p><a>Assistive technologies</a> SHOULD use the value of <code>aria-brailleroledescription</code> when presenting the role of an element in Braille, but SHOULD NOT change other functionality based on the role of an element that has a value for <code>aria-brailleroledescription</code>. For example, an assistive technology that provides functions for navigating to the next <rref>region</rref> or <rref>button</rref> SHOULD allow those functions to navigate to regions and buttons that have an <code>aria-brailleroledescription</code>.</p>
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 understand the relevance of the example.

Copy link
Member Author

Choose a reason for hiding this comment

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

This was copied from aria-roledescription. Does it make sense there but not here?

Copy link
Contributor

Choose a reason for hiding this comment

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

Okay, I think I understand now. I might suggest something that references the comment in the context of the non-braille roledescription. ~"As with aria-roledescription, [change the role presentation, but don't change the functionality…]"

Copy link
Member Author

Choose a reason for hiding this comment

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

Thanks, @cookiecrook. I'll add that.

<p><a>Assistive technologies</a> SHOULD expose the <code>aria-brailleroledescription</code> property as follows:</p>
<ol>
<li>If the value of <code>aria-brailleroledescription</code> consists only of Unicode characters that are not Unicode Braille Patterns, translate the value according to the user's preferred translation table.</li>
<li>If the value of <code>aria-brailleroledescription</code> consists only of Unicode Braille Patterns characters, pass the value to the user without translation.</li>
</ol>
<p>The following two examples show the use of <code>aria-brailleroledescription</code> to indicate that a button's description has a particular Braille contraction.</p>
Copy link
Contributor

Choose a reason for hiding this comment

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

"the following two examples"

"the following example"

Copy link
Member Author

Choose a reason for hiding this comment

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

Thanks.

<pre class="example highlight">&lt;button aria-roledescription="planet" aria-brailleroledescription="pln" id="jupiter" aria-label="jupiter"&gt;
&lt;img alt\="" src\="images/jupiter.jpg"/&gt;
&lt;/button&gt;</pre>
<p>In the previous example, a Braille display may display "Jupiter, pln" in Braille rather than the verbose "Jupiter, planet".</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-rowcount">
<pdef>aria-rowcount</pdef>
<div class="property-description">
Expand Down