This repository has been archived by the owner. It is now read-only.

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

Closed
wants to merge 11 commits into
base: master
from

Conversation

Projects
None yet
6 participants
@wardbell
Contributor

wardbell commented Apr 5, 2016

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

@googlebot googlebot added CLA: yes CLA: no and removed CLA: yes labels Apr 5, 2016

@wardbell

This comment has been minimized.

Contributor

wardbell commented Apr 5, 2016

(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!

@googlebot googlebot added CLA: yes and removed CLA: no labels Apr 5, 2016

@AlmeroSteyn

This comment has been minimized.

Contributor

AlmeroSteyn commented Apr 6, 2016

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

This comment has been minimized.

Member

Foxandxss commented Apr 7, 2016

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

This comment has been minimized.

Contributor

AlmeroSteyn commented Apr 8, 2016

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

This comment has been minimized.

Contributor

AlmeroSteyn commented Apr 8, 2016

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

This comment has been minimized.

Member

Foxandxss commented Apr 8, 2016

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 :)

<nav role="navigation">
<ol>
<li>
<a href="" [routerLink]="['FormControls']"><h2>Accessible form control labels</h2></a>

This comment has been minimized.

@marcysutton

marcysutton Apr 9, 2016

Member

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.

This comment has been minimized.

@AlmeroSteyn

AlmeroSteyn Apr 10, 2016

Contributor

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.

.l-sub-section
:marked
`ARIA`, or `Accessible Rich Internet Applications` refers to bringing `a11y` concepts into

This comment has been minimized.

@marcysutton

marcysutton Apr 9, 2016

Member

Worth mentioning that it is a standard set of attributes for adding accessibility information to HTML and SVG.

This comment has been minimized.

@AlmeroSteyn

AlmeroSteyn Apr 10, 2016

Contributor

Added.

the two should become clear as you progress through this cookbook. However, `ARIA Properties` are not
actual `HTML` element properties but decorating attributes refering to properties. When we refer to setting an
`ARIA Property` in the code you will **HAVE** to do
it with an Angular&nbsp;2 attribute binding. This is simply a terminology clash.

This comment has been minimized.

@marcysutton

marcysutton Apr 9, 2016

Member

Great callout! 👍

A nightmare right? Users will leave so fast the bouncerate counter will be able to power a small town it will be
spinning *THAT* fast.
We can avoid this from ever happening by simply adding a label for each field. Generaly this is not out problem,

This comment has been minimized.

@marcysutton

marcysutton Apr 9, 2016

Member

Typos: "Generaly this is not out problem," should be "Generally this is not a problem,"

Is it generally not a problem though?

This comment has been minimized.

@AlmeroSteyn

AlmeroSteyn Apr 10, 2016

Contributor

Fixed.

.l-sub-section
:marked
So why not simply always use `aria-label`? This is because adding the `label` element not only provides the visual
label, but linking a `label` to a `form control` also means that clicking on the `label` will select the

This comment has been minimized.

@marcysutton

marcysutton Apr 9, 2016

Member

add: native form control.

This comment has been minimized.

@AlmeroSteyn

AlmeroSteyn Apr 10, 2016

Contributor

Added.

How would you go about making these custom form controls accessible?
Fear not, there is a way! We introduce the next addition to our `ARIA` toolkit, and that is `aria-labeledby`.

This comment has been minimized.

@marcysutton

marcysutton Apr 9, 2016

Member

Typo: aria-labelledby (two l's)

This comment has been minimized.

@AlmeroSteyn

AlmeroSteyn Apr 10, 2016

Contributor

Fixed.

implement the basics of functionality to make it function as an `input` i.e. adding the machinery to make it play nice
with `ngModel`. This implementation would need to become
even larger and more complex before it can be used in an enterprise application. We hope that this illustrates
further why native `HTML` elements should preferably be used.

This comment has been minimized.

@marcysutton
[Component that knows its own role](#component-roles)
[Managing focus](#managin-focus)

This comment has been minimized.

@marcysutton

marcysutton Apr 9, 2016

Member

Missing a g here in the link, I think it won't link you to that section currently

This comment has been minimized.

@AlmeroSteyn

AlmeroSteyn Apr 10, 2016

Contributor

Fixed.

Once again the answer is no.
So how do we solve it?

This comment has been minimized.

@marcysutton

marcysutton Apr 9, 2016

Member

I feel like a graphic of valid and invalid form control labels in the accessibility tree would help a developer see how to debug it. The Safari Accessibility inspector is one option, or the Accessibility Inspector in Chrome Canary. I think Edge just shipped with an Accessibility Tree view as well.

Here is the Angular.io search field, with a label of "Search Docs"
Angular search field in Safari Web inspector

This comment has been minimized.

@AlmeroSteyn

AlmeroSteyn Apr 10, 2016

Contributor

Yes. This is why I think it would be great to also add a section on dev tools to use. One of the hardest things for me getting started with accessibility was flying blind. Giving a few options will also make it easier for someone who does not have that specific version of the browser installed to test accessibility.

This comment has been minimized.

@AlmeroSteyn

AlmeroSteyn Apr 10, 2016

Contributor

And added.

@googlebot

This comment has been minimized.

googlebot commented Apr 11, 2016

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.

1 similar comment
@googlebot

This comment has been minimized.

googlebot commented Apr 11, 2016

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 googlebot added CLA: no and removed CLA: yes labels Apr 11, 2016

@googlebot

This comment has been minimized.

googlebot commented Apr 11, 2016

CLAs look good, thanks!

1 similar comment
@googlebot

This comment has been minimized.

googlebot commented Apr 11, 2016

CLAs look good, thanks!

@googlebot googlebot removed the CLA: no label Apr 11, 2016

@googlebot googlebot added CLA: yes and removed CLA: no labels Apr 11, 2016

@AlmeroSteyn

This comment has been minimized.

Contributor

AlmeroSteyn commented Apr 16, 2016

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

This comment has been minimized.

Member

naomiblack commented Apr 26, 2016

See #1181 with some extensive copyedits

@AlmeroSteyn

This comment has been minimized.

Contributor

AlmeroSteyn commented Jun 8, 2016

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

@Foxandxss Foxandxss closed this Jun 9, 2016

@Foxandxss Foxandxss deleted the IdeaBlade:cb-a11y branch Jun 10, 2016

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.