Draft how-to section about building custom widgets

[mcking65]

When working on this issue, there is some old content that may be useful in the file aria-practices-DeletedSectionsArchive.html. The relevant section can be seen here: https://rawgit.com/w3c/aria-practices/master/aria-practices-DeletedSectionsArchive.html#accessiblewidget

[Jefferydo]

Where can I find the discussion about removing that now-archived section from APG 1.1, "General Steps for Building an Accessible Widget with WAI-ARIA"? I'm contemplating something similar for internal training, and wondering what problems people identified with the approach. The new how-to section is structured quite differently.

[mcking65]

I don't know that we have a record of discussion that would be very enlightening. At that time, we removed large chunks of content that required significant revision in order to be accurate. Rewriting that content has not bubbled up the priority list over the last 6 years. It would be a significant effort, and we would need someone with the desire, time, and knowledge to take on the project.

If you would like to work on it, the APG task force could support the work with feedback and reviews. Given the size of the project, I'd recommend starting with an outline before drafting content so we could first align on the objectives and structure.

[Jefferydo]

Thanks. I'm guessing it's not a priority since the steps don't don't reflect how people actually use APG.

1. Pick the widget type (role) from the WAI-ARIA taxonomy
2. From the role, get the list of supported states and properties
3. Establish the widget structure in the markup (parent/child)
4. Repeat steps 1-3 for the children of the parent
5. Establish keyboard navigation of the widget and plan for how it will be navigated to within the document
6. Apply and manage needed WAI-ARIA states in response to user input events
7. Synchronize the visual UI with accessibility states and properties for supporting user agents
8. Showing and Hiding Sections in a Widget
9. Support basic accessibility, such as alternative text on images
10. Establish WAI-ARIA relationships between this widget and others
11. Review widget to ensure that you have not hard coded sizes
12. Compensate for Background Images when in High Contrast Mode
13. Test with User agent, Assistive Technology, and People with disabilities

Users still need step 1 (what is this thing) but once they're at the APG pattern there's no concept of steps and I'm not sure it's helpful. The Custom Component Ally Development Checklist from Using ARIA has the same goal without prescribing a workflow.

Perhaps it's necessary for edge cases, like a variant of a role with some additional features? Thing is, I have yet to come across a widget that isn't defined in APG. I'd kill to read a discussion re the completeness of APG's coverage of widgets, and which scenarios require extending the pattern recipes. I recall a guru at a conference saying something like "if you can't find your widget in APG, you need to reconsider your widget". It's a grey area for me.

[JAWS-test]

I would like it very much if there was this content again. I do not think that every widget is present in the APG. Besides, there are still widgets without example implementation in the APG.

I have one comment on item 12:

• Background graphics are now displayed by all relevant browsers, to my knowledge, when High Contrast Mode is on.
• but it would be important that the element is displayed correctly in High Contrast Mode (i.e. use of colors should be checked, also use of HTML elements like a with href or button or other visual markers indicating controls)

[Jefferydo]

I would like it very much if there was this content again. I do not think that every widget is present in the APG.

Well step one is picking an existing role.