Stronger support / testing / best practices text on every example

[aardrian]

Because these patterns are often referenced via direct links to the example pages, users do not encounter the warnings that come at the start of the overall document. While there is a link at the start of each pattern, in my experience users are not clicking (or reading) before copying patterns into their own projects.

I recommend placing a very obvious warning at the start of each pattern that it is not tested with users, not tested across all browser/AT combinations (linking to 2.2 and 2.3), intentionally ignores the First Rule of ARIA (linking to the First Rule of ARIA), and is only a hypothetical application of ARIA (linking to 2.1).

I see from the 24 September call that some language has been discussed, but I feel it is not strong enough and reads only as a standard disclaimer.

This has overlap with #1150, but I feel goes further.

Proposed text:

Warning: This widget may have support gaps that can only be filled by the development of new technologies. This widget is not tested across all browser and AT combinations, in particular mobile/touch devices, and represents hypothetical uses of ARIA, not necessarily best practices. This widget is not production-ready. Additionally, consult the First Rule of ARIA prior to choosing a pattern.

[carmacleod]

I agree that this would help authors make an informed decision before copy/pasting an example into production code. Unfortunately, authors often need this type of information right at point of use.

I think the proposed text is close. I'd like to deconstruct it a bit, if I may, so that I can comment in detail. :)

1. Warning: This widget may have support gaps that can only be filled by the development of new technologies.

   • Agree

2. This widget is not tested across all browser and AT combinations, in particular mobile/touch devices,

   • Agree, and the links into APG sections 2.2 and 2.3 are useful

3. and represents hypothetical uses of ARIA, not necessarily best practices.

   • I find this clause a bit harsh. I'd like to soften it up a bit. :)
   • Perhaps we can incorporate some words from APG section 2.2: "the purpose of this guide is to illustrate appropriate use of ARIA [1.1] as defined in the ARIA specification"
   • The word "hypothetical", while technically true in some cases, has an unstated implication that these uses of ARIA may never be real. And although that may be (remotely) true as well (for some uses), that is certainly not the intent. (Case in point: html menu, html dialog, and other deprecated and/or reinstated elements may never be real either, but they are or have been in the html spec, and may have been used in production code).
   • These examples really do intend to show best practices - albeit in some cases, future ones.

4. This widget is not production-ready.

   • Agree

5. Additionally, consult the First Rule of ARIA prior to choosing a pattern.

   • This is a nice summary/intro for Consider listing "Related Concepts" for each pattern #633 which we hope to address some day.
   • Perhaps the link to APG 2.1 from clause 3 could be moved into this clause as well.

We could use a shorter form of the warning (with only clauses 2 and 5 from above) for mature examples, which do not need to use the longer form.

[aardrian]

@carmacleod, words follow...

3. and represents hypothetical uses of ARIA, not necessarily best practices.
   • Perhaps we can incorporate some words from APG section 2.2: "the purpose of this guide is to illustrate appropriate use of ARIA [1.1] as defined in the ARIA specification"

Strike "appropriate" and I am on board with that text. Or replace it with "idealized".

3. […]
   • These examples really do intend to show best practices - albeit in some cases, future ones.

The problem is that today some of these will result in broken UIs and confusing experiences. Any code that relies on future feature development cannot be a best practice, it can only be aspirational.

5. Additionally, consult the First Rule of ARIA prior to choosing a pattern.
   • This is a nice summary/intro for Consider listing "Related Concepts" for each pattern #633 which we hope to address some day.

I forgot about #633. I like #633..

5. […]
   • Perhaps the link to APG 2.1 from clause 3 could be moved into this clause as well.

Linking to the same resource twice feels like overkill, but if the text is different then I get a 2.4.4 Link Purpose panic.

Regardless of the text we choose, I want to be careful not to make it any longer than I already have proposed. If possible.

[ZoeBijl]

Strike "appropriate" and I am on board with that text. Or replace it with "idealized".

A fair amount of research goes into the APG design patterns and their code examples. I’d appreciate it if you didn’t undermine all of that work quite as much as you’re doing.

Aside from that, we definitely should warn people. And all the work that’s going into the ARIA AT project will help us do that with a bit more poise than the warning crafted in this issue.

[aardrian]

@ZoeBijl,

Strike "appropriate" and I am on board with that text. Or replace it with "idealized".

A fair amount of research goes into the APG design patterns and their code examples. I’d appreciate it if you didn’t undermine all of that work quite as much as you’re doing

I do not feel I am undermining anyone's work with this request. I am suggesting pointing to the document's own language in a warning.

As a word, "appropriate" is a relative term with a meaning that shifts depending on perspective of the reader. "Idealized" tracks with what APG strives to be, meaning that word is less disputable regardless of the perspective of the reader.

I am open to other language.

[carmacleod]

@ZoeBijl

we definitely should warn people. And all the work that’s going into the ARIA AT project will help us do that

Agree completely that ARIA AT will be extremely helpful, but - correct me if I am wrong - isn't that a fair ways down the road? I'm sorry if I am wrong - I haven't been following it closely.

I also agree that we should warn people, and I think a warning "in situ" would be the best way to ensure that authors see it. We could even call it a Note (and not a warning), because that's basically the same thing but doesn't sound so dire. :) We don't want to chase people away, we just want them to note that certain patterns may not work "today".

@aardrian

Strike "appropriate" and I am on board with that text.

Ok! So, "The purpose of this example is to illustrate use of ARIA as defined in the ARIA specification."

I forgot about #633. I like #633..

👍

Linking to the same resource twice feels like overkill, but if the text is different then I get a 2.4.4 Link Purpose panic.

Different sections. Clause 2 links to APG 2.2 and 2.3, clause 5 to APG 2.1 and possibly the First Rule (although I am not sure if we usually link into other spec docs directly, but we may be able to refer to the document itself in the "References" appendix as [Using-ARIA]).

Any code that relies on future feature development cannot be a best practice, it can only be aspirational.

Ok. So those (few?) widgets/examples that rely on "future features" can have the longer form of the warning. I just don't think we need to say "not necessarily best practices". :)

The problem is that today some of these will result in broken UIs and confusing experiences.

Can we revisit this thought? I looked quickly at the APG table of contents, and the ones I think may need more UA/AT support before being production ready are: ARIA 1.1 combo, feed, maybe treegrid? Possibly slider & spinbutton in VO (mentioned in #1150) and maybe others that are missing specific UA or AT support? So maybe there are fewer than I first thought? Are there any patterns in particular that you had in mind?

[aardrian]

@carmacleod

Ok! So, "The purpose of this example is to illustrate use of ARIA as defined in the ARIA specification."

[ animated thumbs up emoji ]

Different sections. Clause 2 links to APG 2.2 and 2.3, clause 5 to APG 2.1 and possibly the First Rule (although I am not sure if we usually link into other spec docs directly, but we may be able to refer to the document itself in the "References" appendix as [Using-ARIA]).

Ah. Oops. WFM.

Ok. So those (few?) widgets/examples that rely on "future features" can have the longer form of the warning. I just don't think we need to say "not necessarily best practices". :)

While I am looking at "not necessarily best practices" not as a negative statement, but as a null statement, I understand your concern. Making the longer form on the future-feature widgets works for me as well. It just involves more effort to identify which those are and I suspect that is additional effort no one wants to spend (unless it is tracked already).

Can we revisit this thought? I looked quickly at the APG table of contents, and the ones I think may need more UA/AT support before being production ready are: ARIA 1.1 combo, feed, maybe treegrid? Possibly slider & spinbutton in VO (mentioned in #1150) and maybe others that are missing specific UA or AT support?

Yes, and definitely treegrid.

Are there any patterns in particular that you had in mind?

Non-data grid as well (I just opened an issue, and it touches on the need for the application role, fails to mention lack of Esc support). I would have to go back and review some (I recall running into issues with the alert dialog, but that may have been a couple years ago now).

[carmacleod]

Some potential words.

Note: The purpose of this example is to illustrate use of ARIA as defined in the ARIA specification. There may be support gaps in some browser and AT combinations, in particular mobile/touch devices, that can only be filled by the development of new technologies. Authors should fully test with assistive technologies before considering incorporation into production systems. Authors are reminded to use appropriate semantic html when possible and review No ARIA is better than Bad ARIA prior to choosing a pattern.

Problems with the above note are:

• too many words
• I don't know which patterns/examples warrant the full note
  • candidates mentioned in previous comments: feed, layout grid(s), treegrid?, alertdialog?
  • mobile slider, multi-thumb slider, spinbutton?, tree?, submenu? will now be covered by the special note in PR Slider patterns: Provide warning about inability to operate with touch-based assistive technologies due to lack of needed APIs #1186
  • ARIA 1.1 combo is no more!
  • still may want a shortened note for mature/stable examples (to remind authors about 1st rule...)
  • the navigation menu example warrants its own special note
• I'd like to include a sentence about ARIA-AT. Something like:
  "One of the goals of the ARIA-AT project is to provide support tables for these examples."
  • but that will just add more words (also, not sure when it will be available)
  • Background: ARIA-AT initial proposal and ARIA-AT on github
  • After ARIA-AT is ready, we may be able to remove some of the words, and instead say something like:
    "Current cross-platform test data for this example is available at [link to relevant aria-at data]."

[JAWS-test]

I don't see the problems:

• Better more words than less on such an important subject
• I think the warning applies to all patterns. ARIA-AT will never be able to test all combinations of UA and AT, so we will never know which patterns work everywhere and which do not
• When ARIA-AT is finished, one more sentence can be added: "Current cross-platform test data for this example is available at..."

[aardrian]

Fewer words:

Note: This example shows idealized ARIA use as defined by the ARIA specification. Expect support gaps across browser and AT combinations, especially mobile/touch devices, that requires the development of new technologies. Authors must test with AT before use in production systems. Use appropriate semantic html when possible and review No ARIA is better than Bad ARIA prior to choosing a pattern.

I just removed the fluffy bits.

[carmacleod]

Thanks! Authors are more likely to read the note if there are fewer words. ;)

Converging...

Note: This example shows ARIA use as defined by the ARIA specification. There may be support gaps in some browser and AT combinations, especially mobile/touch devices, that require the development of new technologies. Authors must test with AT before considering use in production systems. Use appropriate semantic html when possible and review No ARIA is better than Bad ARIA prior to choosing a pattern.

• removed "idealized"
  • I prefer "no adjective" here; just a straight-up statement
• went back to "There may be support gaps in some" instead of "Expect support gaps across"
  • most of the examples do not have support gaps, so expecting them everywhere sounds too dire
• put "considering" back
  • i.e. asking authors to consider whether to use the pattern or not

[mcking65]

I agree with most of this:

Note: This example shows ARIA use as defined by the ARIA specification. There may be support gaps in some browser and AT combinations, especially mobile/touch devices, that require the development of new technologies. Authors must test with AT before considering use in production systems. Use appropriate semantic html when possible and review No ARIA is better than Bad ARIA prior to choosing a pattern.

Here are some thoughts to chew on.

Sentence 1

Note: This example shows ARIA use as defined by the ARIA specification.

This statement feels a little too close to 1=1. Might the following, by including the phrases "illustrative example" and "one way", better convey the purpose of the note:

Note: This is an illustrative example of one way of using certain ARIA attributes that conforms with the ARIA specification.

Sentences 2 and 3:

There may be support gaps in some browser and AT combinations, especially mobile/touch devices, that require the development of new technologies. Authors must test with AT before considering use in production systems.

As discussed in #1150 and #1186, the only patterns where the development of new technologies are necessary are slider and possibly multi-select trees and tree grids. All other support gaps are due to one of the following:

1. Browser bugs. The ARIA WG tests for these on Windows, Mac, and Linux, but not iOS or Android. This is a critical gap.
2. Screen reader bugs: These will be covered by the ARIA-AT project. Where they uncover a previously unknown browser dependency, they will trickle back to ARIA WG and browser developers.
3. The APG example implementation has not yet been engineered and tested for use in iOS or Android. This is a known APG backlog gap (issue Guidance for touch devices #8).
4. There is a lack of useful mappings to existing native mobile accessibility APIs in mobile browsers. This is a gap in core-AAM.

Would the following be as effective?

There may be support gaps in some browser and assistive technology combinations, especially for mobile/touch devices. So, testing any code that is based on this example with assistive technologies is essential before considering use in production systems. The ARIA-AT project plans to enhance this example with measurements of assistive technology support for it by the end of 2020.

Sentence 4

Use appropriate semantic html when possible and review No ARIA is better than Bad ARIA prior to choosing a pattern.

If the intent of this sentence is to get people to consider alternatives to the example, such as implementing an HTML-only variant, I don't feel like this will help. The sentence starts with the imperative to use semantic HTML, as if the example does not use semantic HTML. Perhaps we could be more clear about the reason for reading the material behind those links.

Robust accessibility can be further optimized by choosing implementation patterns that maximize use of semantic HTML and heed the warning that No ARIA is better than Bad ARIA.

Complete proposal

Note: This is an illustrative example of one way of using certain ARIA attributes that conforms with the ARIA specification. There may be support gaps in some browser and assistive technology combinations, especially for mobile/touch devices. So, testing any code that is based on this example with assistive technologies is essential before considering use in production systems. The ARIA-AT project plans to enhance this example with measurements of assistive technology support for it by the end of 2020. Robust accessibility can be further optimized by choosing implementation patterns that maximize use of semantic HTML and heed the warning that No ARIA is better than Bad ARIA.

One other point ... it is a little long. But, clarity is very important. One way we could keep the length from bing a problem is to collapse it with a summary/details element. Then, we could give it a more prominent ttreatment. The summary could be something like "Critical Note about Use of This Example". Perhaps that could be styled in a very prominent way. Then, we could place it right after the list of similar examples.

[carmacleod]

Pruning a few words (from 106 words in 8 lines down to 98 words in 7 lines 😄 ):

Note: This is an illustrative example of one way of using ARIA that conforms with the ARIA specification. There may be support gaps in some browser and assistive technology combinations, especially for mobile/touch devices. So, testing code based on this example with assistive technologies is essential before considering use in production systems. The ARIA-AT project plans to provide measurements of this example's assistive technology support by the end of 2020. Robust accessibility can be further optimized by choosing implementation patterns that maximize use of semantic HTML and heeding the warning that No ARIA is better than Bad ARIA.

Just for comparison purposes, here's the identical pruned content using bullets instead of a paragraph:

Note: This is an illustrative example of one way of using ARIA that conforms with the ARIA specification.

• There may be support gaps in some browser and assistive technology combinations, especially for mobile/touch devices. So, testing code based on this example with assistive technologies is essential before considering use in production systems.
• The ARIA-AT project plans to provide measurements of this example's assistive technology support by the end of 2020.
• Robust accessibility can be further optimized by choosing implementation patterns that maximize use of semantic HTML and heeding the warning that No ARIA is better than Bad ARIA.

I think the bulleted list is easier to read, but either the paragraph or the bulleted list would work as details if a "Critical Note about Use of This Example" summary is preferred.

[mcking65]

Important Note About Use of This Example

Note: This is an illustrative example of one way of using ARIA that conforms with the ARIA specification.

• There may be support gaps in some browser and assistive technology combinations, especially for mobile/touch devices. So, testing code based on this example with assistive technologies is essential before considering use in production systems.
• The ARIA-AT project plans to provide measurements of this example's assistive technology support by the end of 2020.
• Robust accessibility can be further optimized by choosing implementation patterns that maximize use of semantic HTML and heeding the warning that No ARIA is better than Bad ARIA.

[mcking65]

Proposal in prior comment ... this might be a kind of subtle point but wondering if we are implicitly endorsing copy/paste into production with that wording. instead of saying "considering use in production systems", should we say something like "considering emulating it in production code"? Or, maybe, before "basing production code on it?"

[carmacleod]

@mcking65

wondering if we are implicitly endorsing copy/paste into production with that wording

I don't think so? ... we did say:

code based on this example

PS: Cool use of markup in a github comment! I thought comments had to be in markdown only. :)

[aardrian]

There may be support gaps in some browser and assistive technology combinations, especially for mobile/touch devices. So, testing code based on this example with assistive technologies is essential before considering use in production systems.

Remove "So,", and I am fine with this. The summary/details is fine IMO too.

[carmacleod]

I deleted and retyped that "So," about 6 times. 😄
It sounded awkward to me, but I think the idea was to tie those 2 sentences together, so I left it.

However, now that we seem to be converging on having bullet points instead of a paragraph of text, those 2 sentences are tied together by the fact that they are under the same bullet.

Here it is again without the "So,":

Important Note About Use of This Example

Note: This is an illustrative example of one way of using ARIA that conforms with the ARIA specification.

• There may be support gaps in some browser and assistive technology combinations, especially for mobile/touch devices. Testing code based on this example with assistive technologies is essential before considering use in production systems.
• The ARIA-AT project plans to provide measurements of this example's assistive technology support by the end of 2020.
• Robust accessibility can be further optimized by choosing implementation patterns that maximize use of semantic HTML and heeding the warning that No ARIA is better than Bad ARIA.

[aardrian]

@carmacleod My thumbs-up was meant to indicate that I am good with the language and suggested implementation.

[carmacleod]

Thanks, @aardrian.

Now that we have consensus, @a11ydoer has volunteered to submit a PR. :)
Jemma, here's the code you can use for the template. Thanks!!

<details>
  <summary>Important Note About Use of This Example</summary>
  <p>Note: This is an illustrative example of one way of using ARIA that conforms with the ARIA specification.</p>
  <ul>
    <li>
      There may be support gaps in some
      <a href="https://www.w3.org/TR/wai-aria-practices-1.1/#browser_and_AT_support">browser and assistive technology combinations</a>,
      especially for <a href="https://www.w3.org/TR/wai-aria-practices-1.1/#mobile_and_touch_support">mobile/touch devices</a>.
      Testing code based on this example with assistive technologies is essential before considering use in production systems.
    </li>
    <li>
      The <a href="https://github.com/w3c/aria-at/">ARIA-AT project</a>
      plans to provide measurements of this example's assistive technology support by the end of 2020.
    </li>
    <li>
      Robust accessibility can be further optimized by choosing implementation patterns that
      <a href="https://www.w3.org/TR/using-aria/#rule1">maximize use of semantic HTML</a>
      and heeding the warning that
      <a href="https://www.w3.org/TR/wai-aria-practices-1.1/#no_aria_better_bad_aria">No ARIA is better than Bad ARIA</a>.
    </li>
    </ul>
</details>

[a11ydoer]

I didnot notice you mentioned me. I will submit a PR today. Thanks so much for all your hard work on this, @aardrian @carmacleod @JAWS-test @mcking65

[ZoeBijl]

I've done some work on the implementation of this in branch 1228-support-notice.

Things that work:

• The notice template is loaded
• The template notice is added to the page
• The summary/details thingamabob works

Things that don't work:

• Pages with multiple example headings (do we still have any?)
• The notice is added as child of the example heading (which is wrong)
• Relative links don’t work (in neiither the HTML or JS)

Things that need to be done:

• Append notice in the right place
• Check styling
• Move code into a separate function and call that on load
• Make relative URLs work
• Profit??

I'm not entirely sure how to insert a node after a selected node in vanilla JS. Right now this is done on line 19 of app.js Can anyone help out there? @smhigley maybe?

Relative URLs

Can anyone help out with the relative URLs? The current setup doesn’t work due to the many different situations this document runs in:

w3.org/TR/aria-practices/examples/app.js
w3c.github.io/aria-practices/examples/app.js
localhost:1988/examples/app.js

In addition, app.js is loaded from different levels of nesting in the examples folder:

examples/button/button.html
examples/tabs/tabs-1/tabs.html

This is for both the fetch()and the relative URLs in the notice itself.

[carmacleod]

@ZoeBijl
Try this - it should? work.

var exLabel = document.getElementById('ex_label');
exLabel.parentNode.insertBefore(fragment, exLabel.nextSibling);

I know it's really weird that you can use insertBefore to insertAfter... but if you "insert before an element's next sibling", that will actually insert after the element. And if there's no next sibling, it works like append. Hope this helps!

[ZoeBijl]

@carmacleod woohoo, thanks! That did the trick.

[mcking65]

@ZoeBijl, thank you for all your work on this!! @zcorpan is going to work on wrapping it up tomorrow.

[zcorpan]

@ZoeBijl I've ticked off the remaining things to be done per your comment above and fixed some more stuff: #1404