Aria-practices: Consider listing "Related Concepts" for each pattern

[carmacleod]

The WAI-ARIA spec lists "Related Concepts:" for each role.
For example, the spec for checkbox role lists HTML input[type="checkbox"] as a related concept.

It would be nice if the APG patterns could do the same, wherever possible, so that authors reading the APG might consider trying out the related html element first, before implementing the pattern.

[ZoeBijl]

Although I think it’s good to teach people related concepts in HTML, I don’t think the APG is the place to do it. That said, perhaps it is. I’m not sure how many of our patterns have a HTML equivalent though.

Here’s what I could come up with:

• Button / <button>
• Checkbox / <input type="checkbox">
• Dialog (Modal) / <dialog>
• Disclosure (Show Hide) / <details><summary>
• Link / <a href="…">
• Radio Group / <fieldset> + <legend> + <input type="radio">
• Slider / <input type="range">
• Spinbutton / <input type="number">
• Table / <table>

If we deice to do this we would need a consistent way to add this information to all patterns—would a note be enough?

[carmacleod]

Also:

• Accordion / <details> + <summary>
  (a11y is not perfect - SRs don't speak state changes - but if we keep pushing, it will improve)
• ComboBox (editable) / <label> + <input list="id"> + <datalist id="id"> + <option>
  (see this little datalist test - Note: ok a11y in ff; sort-of ok a11y in chrome; doesn't work yet in Safari)
• ComboBox (read-only) / <label> + <select> (no multiple or size attribute) + <option>
• Listbox / <label> + <select multiple="true" | size="> 1"> + <option>
  or perhaps: Listbox for input / <label> + <input list=id> + <datalist id=id> + <option>
  or maybe Definition+Term: <dl> + <dt> [+ <dfn>] + <dd>
• Menu (used for navigation) / <nav> + <button aria-expanded="true"> + <ul> + <li>
  with aria-current="page" on one of the <li>s
• Status / <label> + <output>
• Tooltip / title attribute Note: This one absolutely deserves a warning such as the one for title attribute in the html spec
• Plus landmark roles (some of which need aria-label[ledby])
• Possibly some others from here: http://html5doctor.com/html-developers-please-consider/

Also, add " + <label>" (or "<label> + ") to those Checkbox, Radio Group, Slider, and Spinbutton inputs. :)
Also, for Link, say <a href="..."> + either text content or <img alt="...">
Also, for Table, be sure to say <table> <caption> <th scope="row|column"> because authors need those semantic reminders. ;)

Yes, I think a note would be good enough, as long as it is placed near the beginning of a pattern, and has the same title in each pattern... perhaps "Related Concepts Note:" or similar. I notice that the Landmark roles each have a section called "HTML5 Techniques". Not sure if we want to restrict our "Related Concepts" to html, though - it seems useful to have a broader category, like the ARIA spec does. For example, the Related Concepts for tablist lists "DAISY Guide".

We could even include CSS thoughts, like display:table; in related concepts for table, and display:grid; in related concepts for grid, along with a note about css being for layout only or something.

Javascript has some related concepts, too, like:

• window.alert("Oh noes!") for Alert Dialog
• window.confirm("Are you sure?") or window.prompt('Nickname?', 'Car') for Message Dialog

I think the APG is a good place to bring this to the author's attention, because I have seen folks implement an APG pattern without realizing that there was a semantically equivalent (or similar) html solution. Also, people reading the APG tend to jump right to the patterns. They don't read the section at the beginning about No ARIA is better than Bad ARIA, and they have probably never read the First Rule of ARIA Use in the Using ARIA doc:

If you _can_ use a native HTML element [HTML51] or attribute with the semantics and behavior you require already built in, instead of re-purposing an element and adding an ARIA role, state or property to make it accessible, then do so.

Adding "Related Concepts" info to the APG reminds authors to consider "going native". As an added bonus, if an APG-aware author finds an accessibility problem in a "related" native element, then that problem is more likely to be reported to the user agents and ATs, which would help to move the web forward and make it more accessible for everyone.

[carmacleod]

Might also consider finding somewhere to talk about a few "Semantic Mini-Patterns", such as:

• unordered list, the "semantic workhorse" element: if you have a _list of things_ (tiles, tools, tree parts, cards, clocks, cows!), then _put the things in a list_ (not in a bunch of divs and spans), i.e.

<div class="thing-list">
  <ul>
    <li><thing></li>
    <li><thing></li>
    <li><thing></li>
  </ul>
</div>

• 4 more points on the list of things...

  • if you don't want the bullets, style the <ul> with "list-style-type:none; margin:0; padding:0;"
  • if your list of things is horizontal, style the <li>'s with display:inline;
  • you can use lists of things to create many of the patterns in the APG, such as breadcrumb, listbox, menubar, menu, tabs, toolbar, and tree view.
  • WCAG Techniques for lists

• associate a <label> element with <input> (any type except hidden, submit, reset, button), <meter>, <output>, <progress>, <select>, and <textarea> elements, either by placing the control element inside the <label> element, or by using the <label> element's for attribute to point to the control element's id. This has the added benefit of increasing the click area of the associated control because clicking on the label raises a click event for the control.

• give every image an alt, whether it's a textual description of the image, or alt="" to signify that the image is just decorative.

• if you have a bunch of related checkboxes (or any inputs), put them in a <fieldset> with a <legend> to tie them together visually and semantically (i.e. fieldsets aren't just for radios)

• if you have a chart, diagram, illustration, photo, code snippet, etc, either stand-alone or made up of graphic-y bits, put them in a <figure> and give them a <figcaption>

I realize that the things in this comment are not strictly "ARIA Practices" _(or are they?)_, however having advice like this all in one place contributes to the greater good.

[ZoeBijl]

Adding "Related Concepts" info to the APG reminds authors to consider "going native".

Agreed, I think this is something positive. I’m just not entirely sure to what extent we need to do this.

[carmacleod]

I have been told by a screen reader user that many of our developers "use way too much ARIA".
That is where I'm coming from on this.

[mcking65]

I agree with this, and I really appreciate all the analysis here!! Thank you both!!!

I would love to see this done. But, in terms of priority, it is definitely lower than closing all our coverage gaps for ARIA itself. Even entertaining PRs for this at this time would take away from getting our high pri work done. I want to keep all contributors as focused as possible on the highest priority work.

So, I would prefer to put this off until later.

[carmacleod]

Understood, and thanks - I appreciate the explanation.
No worries, the analysis will still be here waiting for you when you have the time. ;)

[plweil]

I think the APG is a good place to bring this to the author's attention, because I have seen folks implement an APG pattern without realizing that there was a semantically equivalent (or similar) html solution. Also, people reading the APG tend to jump right to the patterns.

I strongly agree with this. A lot of developers will appropriate these patterns without realizing that there are simpler, more straightforward ("and "native") ways of accomplishing what they want. I fear that by not at least including a short explanatory note in a prominent place, the APG patterns are sending the wrong message to developers regarding how to code accessibly. And I think this is the place to do it.

[mcking65]

The long term direction I'm still hoping for, as we discussed at TPAC, is that we expand the ARIA authoring practices to become something more general, not just in support of ARIA. At some point, this means forming a joint task force with other working groups so that every example can have a version that uses as little ARIA as possible.

When discussing this with the WAI chairs, there is a lot of support for getting away from siloed accessibility practice guidance resources. There is strong agreement that it is rather ridiculous that we expect people to look in so many different places for the information necessary to accomplish a single goal just because that accessibility information happens to span the boundaries of multiple related specifications.

Realistically, an expanded task force and scope for authoring practices is a 2021 project. This year, our plan includes:

1. Develop support tables for each widget via the w3c/aria-at project.
2. Provide a light-weight integration of aria-at into APG.
3. (Not yet funded) Start the conversion of APG from a W3C Note, which has a ton of format and architectural limitations, into a section of the W3C WAI web site. This will enable:
   
   
   
   1. Full integration of APG and ARIA-AT.
   
   
   2. Continuous publication without versioning the entire APG.
   
   
   3. Much more user friendly information architecture and design.
   
   
   4. A place where we can easily consolidate information and guidance from multiple existing resources. Project 1 will be to collaborate with the E&O WG to integrate the WAI tutorials. And, of course, those are the perfect resources to emphasize over and over the basic rules of using ARIA.
   
   

A good question is, in the meantime, what could we readily do for say the July 2019 release that would support the objective of this issue and align well with this longer term direction.

In the long term, I imagine the first example in each pattern is the one that uses the least ARIA. Because this would impact the way the roles, states, and properties section is written, I imagine we will also have a slightly different IA for the sections that have this type of example.

I agree a related concepts section in some patterns could be a step in that direction. I would imagine that it would need to be more than just a simple list in order to be very useful. Perhaps one approach could be for someone to take a couple of the above listed suggestions, e.g., button and select, and make a branch or two and play around with some ideas for modifying the button and listbox patterns. That would give us something concrete to noodle on.