[WIP] docs(a11y-cookbook) add accessibility (a11y) cookbook

[wardbell]

** DO NOT MERGE **

CLA Bot Note

Bot note on "CLA: No" - I created the PR, Almero is doing the work and is covered under the IdeaBlade CLA. The bot will never stop complaining but actually CLA compliance requirements have been met.

[wardbell]

(April 5) Great start!
I'll bring my red pencil to it later. Let's focus on content.

I like the pace and the unfolding of concepts.

I am unclear on when the techniques you show are wise and when the alternative isn't.

For example, the labeling section begins with a large group of implicit label components. These lock the control inside beyond the reach of developer control (binding and styling). Are you recommending that we create these a11y components for ourselves?

Why do I need these components? Once you tell me about wrapping a control in a label, do I really need them? Why and when is ...

<a11y-input>First Name:</a11y-input>

... better than ...

<label>First Name: 
  <input class="form-control" [(ngModel)]="person.firstName">
</label>

Even more important: how do I use <a11y-input> in an application? How do I bind the person.firstName to the input box within <a11y-input>?

I have the same questions about your explicit label controls. But before that, I'd like to when to choose implicit over explicit label controls. You have two sentences on the subject but they don't help me decide if I chose to do the layout myself rather than use your a11y wrapper components.

I'm so glad to learn about hidden labels. But do I need an entire suite of controls that duplicates your earlier ones just to restyle the label? Couldn't I just write

<label for="fn" class="hide">First Name: </label>
<input id="fn" class="form-control" [(ngModel)]="person.firstName">

And why bother with it at all when I could omit the label and use the cool aria-label that you taught me?

<input aria-label="First name" class="form-control" [(ngModel)]="person.firstName">

To sum it up:

1. I don't have a clear sense of when to use each alternative.
2. I'm not sold on the value of <a11y-...> controls; TBH, they feel more intrusive than helpful
3. I'm not convinced that <a11y-...> controls would work because I can't see how to bind to their inner form controls to the data properties of the components that would use them.

I don't mean to rain on the parade. You've have really good points in here and have taught me stuff that I didn't know and want to know!

Keep it going!

[AlmeroSteyn]

Thanks!

As for parade-raining, not at all. Please don't pull punches, this doc has to be as good as possible and that is the only way. And this is exactly the info I was looking for at this stage of the doc.

Hmm, the <a11y... components: I actually feel the same way. This is not something I would do in my applications. I love having free access to the inputs and when I want to decorate, I like doing it like this:http://almerosteyn.com/2016/03/angular2-form-validation-component

I took the `<a11y..' component line after looking at the examples in the doc Marcy shared with us. Got the message to focus more on Angular than just the HTML structure. Probably totally misunderstood.

This was also where all my form related questions came from last week as I had exactly the same questions about actually using these controls.

But after reading your comments I am convinced. For the vanilla examples I will be going back to just the HTML versions for basic constructs. For these no one should be creating a separate components, I think. Also actually falls in the first rule of ARIA: to use native HTML elements when you can.

Once this is clear I will provide some info on what to do IF you want to enrich your controls, like in my blogpost above, and how to tie it to a11y.

And maybe looking at what if the input is indeed inside the control. But the sheer amount of extra code you need with the ControlValueAccessor is much too much unless you really need to use it instead of the out-of-the-box value you get from using the native controls directly.

As for the other comments. Pure gold. Will be looking at those as well during the restructure.

[Foxandxss]

I love they way you sell the product. The problem is that the people is not aware of the problems of not having a11y and they just say "hey, it looks good, why do extra work?". I think that your cookbook covers that pretty well.

I agree with all that Ward said here so I won't be repetitive.

About the custom for control, I think that you could focus in something that is not, well, a control. I agree that having a component to wrap a label + input for a11y purposes is not appealing because it has no advantage over doing it directly.

What I would do personally is having a different example that is not related to a form control. For example, if you build a custom dropdown menu, you want to add a11y to say: "Hey, this has a popup and it is actually closed / open". For example, I have a dropdown toggle like:

@Directive({
  selector: '[myDropdownToggle]',
  host: {'class': 'dropdown-toggle', 'aria-haspopup': 'true', '[attr.aria-expanded]': '_dropdown.open'}
})

In this case, you don't expect people to write a custom dropdown directly but instead having a custom control for it, so teaching this good practices is something that works very well.

Leaving this aside, one of the features I like from the "hidden element" is to mirror a feature that is not available for everyone. If you have a rating component for example, something like (simplified):

<i class="glyphicon glyphicon-star"></i>

as a star, ok, visually you see the star, but it is a good idea of having something like:

 <span class="visually-hidden">(*)</span>

So having both you have the visual clue (star icon) and the non visual representation.

I love a11y so please, keep your good work of making people aware that this is a necessity.

[AlmeroSteyn]

Thanks for the comments Jesús! Brilliant examples that we need to show indeed.

For now we are focussing ons some basic big wins but it will be expanded in future releases. Still trying to see exactly what will be in the first but your first example is a great idea for the section on ARIA states and properties. And one of the classic failures with third party tools. Brilliant to touch upon.

Second is just as great! Here we'd need to link up the description to the field with aria-describedby, so will go in the section where we talk about that.

Keep the good ideas coming!

[AlmeroSteyn]

Lets put down the current planned sections for the cookbook for release 1 and also the backlog of items. Then we can track them, add/remove items and get them in the right order.

A lot of these are from Marcy's starter document. I have added a few to the list

Release 1:

• Using text as a label for a custom component
• Using keyboard shortcuts
• Component that knows its own role (ARIA roles)
• Managing focus
• Testing for accessibility (Unit tests for functionality, Integration tests with axe-core)

Current backlog with possible items for inclusion

• Developer support tools (WAVE, Tenon, aViewer, NVDA, aXe etc. - Avoiding doing a11y blindly. I think this could be great to already have in the first release.
• Coding accessible forms (labels, native inputs vs. custom ones) - many concepts already covered in the labelling section but need to still look at form integration and validation (aria-describedby).
• Live page area changes - notify the screen reader of changing content (aria-live).
• ARIA states and properties: Binding an aria attribute ( [attr.aria-whatever]="expression" ). Important to explain the difference between attributes and properties. Complex widgets and ARIA. This can get pretty big so probably needs further splitting up
• Always binding a11y attributes to the component host
• Color contrast.
• Avoiding keyboard traps.
• Testing: unit tests for keyboard support, integration tests with axe-core.
• Landmark roles and HTML semantics + components
• General a11y concepts: 'Show more' links, image alt, not relying only on color, etc.

Points to consider in multiple sections:

• Binding ARIA to a custom control

[Foxandxss]

Sounds exciting friend. I thought I knew some a11y but there are some stuff I never heard about, so I am expecting to see it :)

[marcysutton]

Why the href=""? Doesn't routerLink add it dynamically? I want to make sure there isn't a fix we need to do to routerLink itself since most people would leave that off.

[AlmeroSteyn]

This was purely my own OCD. Works 100% fine without adding it. Started doing this expecially for code metrics on the code base with checkers that do not understand Angular.

[googlebot]

We found a Contributor License Agreement for you (the sender of this pull request) and all commit authors, but as best as we can tell these commits were authored by someone else. If that's the case, please add them to this pull request and have them confirm that they're okay with these commits being contributed to Google. If we're mistaken and you did author these commits, just reply here to confirm.

[googlebot]

We found a Contributor License Agreement for you (the sender of this pull request) and all commit authors, but as best as we can tell these commits were authored by someone else. If that's the case, please add them to this pull request and have them confirm that they're okay with these commits being contributed to Google. If we're mistaken and you did author these commits, just reply here to confirm.

[googlebot]

CLAs look good, thanks!

[googlebot]

CLAs look good, thanks!

[AlmeroSteyn]

While creating content for the Keyboard Shortcuts section it became clear that valid examples, like menus and data tables, will make for pretty complex code.

However we could make the barrier smaller to start with a11y if we show how a developer can check his `a11y

I have discussed this with Marcy and we are changing the scope for Release 1:

Release 1:

• Accessible form control labels
• Managing focus
• Component that knows its own role (ARIA roles)
• Developer support tools (WAVE, Tenon, aViewer, NVDA, aXe etc.)
• Testing for accessibility (Unit tests for functionality, Integration tests with axe-core)

Keyboard shortcuts have been touched on in the Managing Focus section as this is part of managing the keyboard focus. We will relook at this later to see if more complex examples are required.

[naomiblack]

See #1181 with some extensive copyedits

[AlmeroSteyn]

This PR is outdated and should be closed for preference of #1625