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

docs(cb-a11y): add accessibility (a11y) cookbook #1625

Open
wants to merge 6 commits into
base: master
from

Conversation

Projects
None yet
7 participants
@AlmeroSteyn
Contributor

AlmeroSteyn commented Jun 8, 2016

READY FOR REVIEW

Current and up to date PR for the a11y cookbook.

Also contains copy-edits from @naomiblack from #1181 .

Both #1049 and #1181 are now outdated in terms of content and should be closed, but conserved for comments therein.

Similarly, we need to provide quick in-page links to help users who rely on assistive
technology to navigate our page.
These are called `skiplinks` and remain completely hidden until focused through `keyboard navigation`.

This comment has been minimized.

@mattdistefano

mattdistefano Jun 8, 2016

I'm noting this here but it's more of a general question - are the code backticks appropriate for calling out technical terms or should some of these really be ems?

This comment has been minimized.

@AlmeroSteyn

AlmeroSteyn Jun 10, 2016

Contributor

These do provide a particular emphasis highlight that is used a lot inside the docs.

This comment has been minimized.

@mattdistefano

mattdistefano Jun 10, 2016

Right, but typically the code backticks are for actual snippets of code or commands - variable names, hex values, CLI commands, that sort of thing. Whereas technical terms get the em treatment.

This comment has been minimized.

@AlmeroSteyn

AlmeroSteyn Jun 10, 2016

Contributor

Agreed. However that is more an A2 doc wide discussion so will align this one to the styles of the other docs for now.

a button, regardless of the original design of the HTML element. More information on this later.
Setting the `tabindex` to `0` inserts the element in the default flow of`keyboard navigation` focus. This means that our
element also becomes accessible via the keyboard!

This comment has been minimized.

@mattdistefano

mattdistefano Jun 8, 2016

IMO this is a little misleading since it's really the combination of tabindex and the keydown bindings that make it accessible via keyboard. So I'm wondering if it'd be more effective to just walk through the whole implementation of the component vs. calling out these two items specifically.

This comment has been minimized.

@AlmeroSteyn

AlmeroSteyn Jun 17, 2016

Contributor

Valid point. Will add mention of this in the next commit. However a whole walkthrough of the implementation is perhaps not the best thing for the cookbook. In fact the cookbook is constantly trying to convince developers to rather use the native elements.

<div class="clearfix">
<a href="https://www.w3.org/TR/WCAG20/"
title="WCAG specification"

This comment has been minimized.

@mattdistefano

mattdistefano Jun 8, 2016

Any reason for different text in the title vs. aria-label?

This comment has been minimized.

@AlmeroSteyn

AlmeroSteyn Jun 17, 2016

Contributor

Will be aligned in the next commit.

:marked
We are setting focus on an `alert` that starts out hidden. As `hidden` and `disabled` elements cannot accept focus,
we first need this element to become visible again. To give the browser time to apply this change we set our focus using

This comment has been minimized.

@mattdistefano

mattdistefano Jun 8, 2016

Is there a better way to handle this than the timeout? I've typically done the same thing in my angular1 apps but it's always felt like a hack.

This comment has been minimized.

@AlmeroSteyn

AlmeroSteyn Jun 10, 2016

Contributor

If there is one I would love to hear about it. Due to the *ngIf the elements are not in the DOM at the time the focus is set, so the browser simply ignores it. Could be something to look at further.

it is as simple as:
code-example(language="html" escape="html" format="linenums").
<h2 role="alert">I am an alert.</h2>

This comment has been minimized.

@mattdistefano

This comment has been minimized.

@AlmeroSteyn

AlmeroSteyn Jun 10, 2016

Contributor

I don't see it doing that here. It is not changing the semantic meaning of the element itself buit indicating that it is important information. https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_alert_role

.l-sub-section
:marked
The names of these widget roles are self-explanatory. Visit the `W3C` to read more about

This comment has been minimized.

@mattdistefano

mattdistefano Jun 8, 2016

Would it be worth linking to the design patterns too? IMO they have a lot of value but aren't linked very well from the widget roles page.

This comment has been minimized.

@AlmeroSteyn

AlmeroSteyn Jun 17, 2016

Contributor

Good idea. Added in the next commit.

[Using JAWS to Evaluate Web Accessibility](http://webaim.org/articles/jaws/).
:marked
#### VoiceOver (Apple OS X integrated screen reader) in Safari

This comment has been minimized.

@mattdistefano

mattdistefano Jun 8, 2016

Worth calling out any mobile screen readers?

This comment has been minimized.

@AlmeroSteyn

AlmeroSteyn Jun 10, 2016

Contributor

I was actually thinking about it. But then decided that this was not the place for it. Wanted to home in on a few dev tools that can easily be used during development time, and especially to introduce developers to testing accessibility matters. The mobile screen readers, I feel, is one more step that naturally happens when someone gets into accessibility. Maybe it will show up in a doc in future.

This comment has been minimized.

@mattdistefano

mattdistefano Jun 10, 2016

I think it'd be worth mentioning somewhere.

Just acknowledging the fact that screen readers do exist for mobile devices would be beneficial, as I think there's a lay perception that screen reader users are always on a "desktop" device/browser/OS. Likewise, if you're building an angular mobile app without a web counterpart, advice about testing on Firefox and IE and whatnot probably doesn't do much for you.

This comment has been minimized.

@AlmeroSteyn

AlmeroSteyn Jun 17, 2016

Contributor

Sure! A mention is worth it.

:marked
You will not get the same experience in every `screen reader / browser combination`, so do not spend too much time
trying to fix *"errors"* in combinations not mentioned here. Often you will be trying to fix a technology
integration issue and not a problem on your page. Focus on the three combinations

This comment has been minimized.

@mattdistefano

mattdistefano Jun 8, 2016

Possible to cite a source for this? [Edit: by 'this' I mean the three combinations specified.]

This comment has been minimized.

This comment has been minimized.

@mattdistefano

mattdistefano Jun 10, 2016

That's what I figured - can you include that in the cookbook though? I think having that linked here would help justify the recommendations. Also - unrelated, but does the doc mention WCAG anywhere?

This comment has been minimized.

@AlmeroSteyn

AlmeroSteyn Jun 17, 2016

Contributor

I don't want to add this link to the docs. It is a survey that can be superseded at any stage and therefore adds more maintenance. Like many things in the cookbook we are simply suggesting it without references all over the place.

As for WCAG I honestly dunno if it should be added. The cookbook is about how to do accessibility in Angular and not supposed to be a full handbook on a11y. I find the doc extremely overbearing for a new developer for a11y. I think a dev learning about a11y for the first time from this cookbook will inevitably find his way to the WCAG, but I am scared of throwing the doc at everyone seeing it for the first time. I think webAIM and a11yproject have much more digestible material for the newbie and I'd like them to end up there first.

But I am still open to being convinced. Let me know what you think.

This comment has been minimized.

@mattdistefano

mattdistefano Jun 27, 2016

Sorry about the late response. I think the wording around the browser support recommendations is probably OK as-is. I just worry about offering that sort of guidance without having a source to back it up.

Re. WCAG... I think you're right that the material is pretty imposing and could be off-putting. So I don't disagree about not linking to it immediately as another source of information. That said, I almost would like to see WCAG woven a bit more into the cookbook, as I think a lot of people interested in this subject will be looking for info specifically on how to meet WCAG in angular (because of organizational policy, for instance). But that probably has the same risk of alienating newcomers, so maybe it's just something to consider for the future if other folks ask for it.

excellent introductory guides for getting started with `NVDA`. We recommend that you read either one or both of them.
:marked
#### JAWS (Most used screen reader) in IE 10+

This comment has been minimized.

@mattdistefano

mattdistefano Jun 8, 2016

Does 'IE 10+' leave some ambiguity around whether you mean just IE 10 and 11 or IE 10, 11, and Edge?

This comment has been minimized.

@AlmeroSteyn

AlmeroSteyn Jun 17, 2016

Contributor

Changed this to IE 10/11 in the next commit. Even though there are good things in the pipeline for Edge, there are too many warnings out there to not use Edge. Including the Freedom Scientific site itself. So let's limit to these two for now. The docs will evolve with the field as time passes.

@Foxandxss Foxandxss changed the title from docs(cb-a11y): add accessibility (a11y) cookbook [Ready for review] to docs(cb-a11y): add accessibility (a11y) cookbook Jun 9, 2016

@chalin

This comment has been minimized.

Collaborator

chalin commented Oct 26, 2016

@AlmeroSteyn - e2e tests are failing because the ts compiler is reporting errors. Can you investigate and fix the issues?

cc @naomiblack @wardbell

@chalin

This comment has been minimized.

Collaborator

chalin commented Oct 26, 2016

All: @AlmeroSteyn isn't currently available. As agreed discussed with @wardbell via slack: @Foxandxss or @filipesilva could you look into upgrading the code from use of ng beta/rc to 2.1.x?

@googlebot

This comment has been minimized.

googlebot commented Oct 26, 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 Oct 26, 2016

@googlebot

This comment has been minimized.

googlebot commented Dec 8, 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 Dec 8, 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.

@niceredfrog

This comment has been minimized.

niceredfrog commented Dec 14, 2016

I authored the most recent commit. I'm replying to confirm.

@marcysutton

This comment has been minimized.

Member

marcysutton commented Apr 7, 2017

What do we need to do to get this up to date and merged?

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