feat: aria-brailleroledescription #924

pkra · 2019-04-03T16:04:18Z

joanmarie · 2019-04-03T16:27:48Z

(This was edited to update the link to the latest location within the spec.)
https://raw.githack.com/pkra/aria/braille-props-roledesc/index.html#aria-brailleroledescription

jasonjgw · 2019-04-03T17:10:48Z

I have the same comment as in #923.

johnfoliot · 2019-04-03T19:09:28Z

(Duplicate from #923)

I have a small concern about introducing a new "pattern" into the aria lexicon - specifically "double-hyphenated" attributes (i.e. aria-label-braille and aria-roledescription-braille). A quick check of the existing ARIA attributes, and this will be the first time that this WG would be introducing that pattern, and so more than anything else - why?

Previously, even "multi-name" attributes have all been concatenated into one string (ref: Position In Set = aria-posinset), and I would strongly encourage the ARIA WG to maintain that pattern (aria-labelbraille, aria-roledescriptionbraille) if these new attributes are to move forward.

Additionally, if the only reason for the double-hyphen is "readability", the values can always be presented (instructionally) in CamelCase, as elements and attributes are case insensitive: (aria-LabelBraille, aria-RoleDescriptionBraille - although that goes counter to existing attributes as well)

pkra · 2019-04-04T07:50:42Z

I've responded at #923 (comment)

charmarkk · 2019-04-04T14:33:18Z

Responsed on #923.

As per WG discussions.

@johnfoliot

Rename to aria-brailleroledescription as per suggestion from @johnfoliot

* add note on braille conversio of roledescription. * require roledescription different from (implicit) role

Replace plain text aria-brailleroledescription with Unicode braille.

NSoiffer · 2019-07-17T05:22:57Z

Apologies if this has already been discussed...

The spec currently has these two clauses about the value of aria-brailleroledescription:

The value of aria-brailleroledescription is not empty or does not contain only whitespace characters.

The value of aria-brailleroledescription SHOULD consist of a string of Unicode Braille Patterns (U+2800..U+28FF).

These seem partially redundant as '3' says whitespace characters should not be part of the value.
These two clauses can be consolidated into just:

The value of aria-brailleroledescription SHOULD consist of a non-empty string of Unicode Braille Patterns (U+2800..U+28FF).

Also, I'm a little dubious that the phrase "Unicode Braille Patterns" is proper. The block is called "Braille Patterns" and the characters have names that include that phrase, but technically, a string consists of characters, so "Unicode Braille Pattern characters" would be more correct. Also correct would be "characters from the Unicode Braille Patterns block". I suggest the current two clauses should be replaced with:

The value of aria-brailleroledescription SHOULD consist of a non-empty string of Unicode Braille Pattern characters (U+2800..U+28FF).

pkra · 2019-07-17T07:47:13Z

@NSoiffer:

These seem partially redundant as '3' says whitespace characters should not be part of the value.

Happy to change if the WG agrees but they don't seem redundant to me. Point 2 is (essentially) a MUST (cf. also AT guidance to ignore it otherwise), point 3 is a SHOULD.

"characters from the Unicode Braille Patterns block"

Sounds good to me but happy to get more feedback.

@joanmarie

Avoids RFC-2119 key words. Addresses feedback from @joanmarie.

* removes (redundant) SHOULD * adds clarification to treat u+2800 like whitespace

* value can now be either all non-braille or all-braille * UA SHOULD's: translate non-braille and pass all-braille through * adjust example

pkra · 2019-09-24T08:39:58Z

@joanmarie I've incorporated the changes from TPAC (as per #765 (comment)). Please take a look.

cookiecrook · 2019-09-24T19:56:38Z

At TPAC we agreed that this should not require (and should actively discourage) using "characters from the Unicode Braille Patterns block" because, in almost all instances, the web author will not know what these should be, even if they are an expert in braille.

As the simplest example, the web author has no way of knowing whether the user reads uncontracted (Grade 1) or contracted (Grade 2) braille, so this attribute would be formatted as a non-braille unicode string. For example, the screen reader could translate aria-roledescription= "denomination" aria-brailleroledescription="den" into the user's preferred Grade 1 (⠙⠊⠝) or Grade 2 (⠙⠔) braille rendering.

Other examples author-encoded braille strings include when a user is fluent in multiple languages, but only fluent in one variant of braille. For example, a member of my team is fluent in reading, typing, and speaking English, but only reads braille using his native German braille table. VoiceOver can provide that to him, but a web author cannot.

cookiecrook · 2019-09-24T20:01:58Z

We also agreed that it may be okay to allow unicode braille with sufficient warnings, and no examples of this usage. The only context I can think of where this is necessary is testing, where a user may be learning tactile braille through remote instruction. E.g. a student learning the differences between US English versus UEB, in Grade 1 or 2.

cookiecrook · 2019-09-24T20:05:04Z

I am skeptical of suggesting the unicode braille block is necessary even in the case of Math polyfills like MathJax. For the same reasons listed above, the polyfill can't know whether the user prefers to read Math in Nemeth, UEB Math, or Computer Braille.

pkra · 2019-09-25T07:25:13Z

@cookiecrook thanks for re-iterating those points from TPAC. Is there a particular change you have in mind for the latest changes in this PR?

zorkow · 2019-09-25T17:55:58Z

@cookiecrook It does make a difference for polyfills like MathJax.
As of v3, MathJax exposes both speech and Braille via Unicode in its accessibility extension. As aria-label however we can currently only expose speech. Its language depends on the localisation the user (or page author) chooses, as we also don't know if the user wants to read their maths in English, French, or Spanish. So selecting a Braille dialect is just another l10n option choice.
The aria-label depends on that choice, so will the aria-braille.
I think the last thing readers will want is the maths speech translated into Braille, whatever grade.

* fix html markup * change "user agents should" to "assistive technologies should" * move below the first AT SHOULD * move Note * add warnings on aligning lanugage, alertin user and avoiding braille patterns

cookiecrook · 2019-10-14T23:16:14Z

index.html

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


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."

Perhaps "abbreviated role description"

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

cookiecrook · 2019-10-14T23:20:37Z

index.html

+			<div class="property-description">
+				<p>Defines a human-readable, author-localized Braille description for the <a>role</a> of an <a>element</a>.</p>
+				<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>


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.

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

cookiecrook · 2019-10-14T23:21:35Z

index.html

+				<p>Defines a human-readable, author-localized Braille description for the <a>role</a> of an <a>element</a>.</p>
+				<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>
+				<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>


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

cookiecrook · 2019-10-14T23:26:12Z

index.html

+					<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>.


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.

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.

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.

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

cookiecrook · 2019-10-14T23:28:43Z

index.html

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


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.

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.

cookiecrook · 2019-10-14T23:30:02Z

index.html

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


I don't understand the relevance of the example.

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

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…]"

Thanks, @cookiecrook. I'll add that.

cookiecrook · 2019-10-14T23:32:24Z

index.html

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


"the following two examples"

"the following example"

* rephrase opening line - w3c#924 (comment) * Braille/braille capitalization - w3c#924 (comment) * suffice => overly verbose - w3c#924 (comment) * two examples show => example shows - w3c#924 (comment)

pkra · 2019-10-15T08:47:44Z

@cookiecrook I've created #1097 with the first couple of changes.

NSoiffer · 2019-12-05T04:56:46Z

I commented on the use of the phrase "Unicode Braille Patterns" earlier and the distinction between the block name and an individual character -- strings consist of characters not patterns, symbols, or glyphs. I'm happy to see that in one instance that distinction is properly used. However, since the time of my comment, there have been several changes to text and I think improper usage has creeped in again.

Examples where I think changes are warranted so that the sentence is technically correct:

The value of aria-brailleroledescription 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).
If the value of aria-brailleroledescription consists only of Unicode characters that are not Unicode Braille Patterns, translate the value according to the user's preferred translation table

I suggest these become:

The string value of aria-brailleroledescription does not contain any characters in Unicode Braille Patterns (U+2800..U+28FF) or consists of only characters in the range U+2801..U+28FF (Unicode Braille Pattern block excluding dots-0).

Note: the previous statement mentioned it must contain "either Unicode or...". In HTML, all attributes value strings much contain Unicode values, so that statement is not a restriction. In fact, not all Unicode values are legal, so it isn't even correct.

If the value of aria-brailleroledescription does not contain Unicode Braille Pattern characters, translate the value according to the user's preferred translation table.

Note: The above is the first clause. I think the second clause would be better written as "Otherwise, pass the value to the user without translation." I don't think it is helpful to write a condition on the second clause as there is no alternative third clause (i.e., AT should do one of those two things).

pkra · 2019-12-05T18:45:00Z

@NSoiffer copied to #1097 (comment)

* rephrase opening line - w3c#924 (comment) * Braille/braille capitalization - w3c#924 (comment) * suffice => overly verbose - w3c#924 (comment) * two examples show => example shows - w3c#924 (comment)

feat: aria-roledescription braille, first draft

47de3e9

jnurthen added the WIP label Apr 9, 2019

aria-roledescription-braille: remove mention of ascii.

5220217

As per WG discussions.

pkra added the Agenda label Jun 14, 2019

pkra added 3 commits June 27, 2019 19:26

aria-roledescription-braille: rename property

19a4375

Rename to aria-brailleroledescription as per suggestion from @johnfoliot

aria-brailleroledescription: add restrictions and notes

dd056dd

* add note on braille conversio of roledescription. * require roledescription different from (implicit) role

aria-brailleroledescription: update example

0e77136

Replace plain text aria-brailleroledescription with Unicode braille.

aria-brailleroledescription: minor rephrase to note

2d32018

Avoids RFC-2119 key words. Addresses feedback from @joanmarie.

jnurthen removed the Agenda label Jul 30, 2019

pkra mentioned this pull request Aug 20, 2019

AccName trims whitespace but doesn't define which code points are whitespace w3c/accname#55

Closed

aria-brailleroledescription: tweaks after WG discussion

c9f305c

* removes (redundant) SHOULD * adds clarification to treat u+2800 like whitespace

pkra changed the title ~~feat: aria-roledescription braille, first draft~~ feat: aria-brailleroledescription Aug 28, 2019

joanmarie added the F2FCandidate Candidate topics for F2F (or Virtual F2F) meeting label Sep 2, 2019

joanmarie mentioned this pull request Sep 2, 2019

Agenda for TPAC 2019 #1001

Closed

aria-brailleroledescription: changes after TPAC

8bd7219

* value can now be either all non-braille or all-braille * UA SHOULD's: translate non-braille and pass all-braille through * adjust example

joanmarie added Agenda and removed F2FCandidate Candidate topics for F2F (or Virtual F2F) meeting labels Sep 24, 2019

aria-brailleroledescription: update telco Sept 26

2579a05

* fix html markup * change "user agents should" to "assistive technologies should" * move below the first AT SHOULD * move Note * add warnings on aligning lanugage, alertin user and avoiding braille patterns

jnurthen requested a review from cookiecrook October 3, 2019 17:19

jnurthen removed the WIP label Oct 3, 2019

jnurthen merged commit 2048cb5 into w3c:master Oct 14, 2019

cookiecrook reviewed Oct 14, 2019

View reviewed changes

pkra mentioned this pull request Oct 15, 2019

brailleroledescription update #1097

Merged

carmacleod pushed a commit that referenced this pull request May 7, 2020

feature: add aria-brailleroledescription (#924)

1d54654

jnurthen removed the Agenda label Nov 5, 2020

pkra added this to the ARIA 1.3 milestone Jan 10, 2022

pkra mentioned this pull request Jan 10, 2022

FPWD of ARIA 1.3 #1331

Closed

feat: aria-brailleroledescription #924

feat: aria-brailleroledescription #924

Conversation

pkra commented Apr 3, 2019 • edited by pr-preview bot Loading

joanmarie commented Apr 3, 2019 • edited Loading

jasonjgw commented Apr 3, 2019

johnfoliot commented Apr 3, 2019

pkra commented Apr 4, 2019

charmarkk commented Apr 4, 2019

NSoiffer commented Jul 17, 2019

pkra commented Jul 17, 2019

pkra commented Sep 24, 2019

cookiecrook commented Sep 24, 2019

cookiecrook commented Sep 24, 2019

cookiecrook commented Sep 24, 2019

pkra commented Sep 25, 2019

zorkow commented Sep 25, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pkra commented Oct 15, 2019

NSoiffer commented Dec 5, 2019

pkra commented Dec 5, 2019

pkra commented Apr 3, 2019 •

edited by pr-preview bot

Loading

joanmarie commented Apr 3, 2019 •

edited

Loading