Accessibility guide

[callumacrae]

Obviously, very early days, but figured I'd keep a pull request open as I'm writing and do a bit every day. All comments welcome :)

Where should it be in the menu? Currently I haven't given it anywhere to go, which is breaking everything. In relation to the other documents, it feels like somewhere in the Advanced section would be the best place, but it's not an Advanced concept so I'm not sure I'd be comfortable putting it there.

[zivc]

Overall, a good effort for someone whose English isn't their first language.

[zivc]

..whose mouse has ran out of battery.

Should be run not ran.

[robbeman]

Also:
... a website that can be used be anyone ... => ... used by anyone...

[tiffmartindale]

"with limited hardware capabilities" or "whose hardware is old or broken" is broader than "whose mouse has ran out of battery"

[zivc]

...population have some form of disability,

Should be has not have.

[zivc]

...will help both your low-vision users, and your users

Remove the comma.

[zivc]

The W3C have published

Again, has not have

Also, find it a a bit dry, and

Remove one a

[chrisvfritz]

@callumacrae We can decide this later, so you can just put it anywhere for now. I'm playing with the idea of making this the final page in Essentials or perhaps part of a new section, maybe called Best Practices. The Advanced section has become a little cluttered to me and I've been playing with the idea of disbanding it into more specific categories anyway.

Regarding the content, I think it's great information, but I should mention I'm wary of reinventing what other resources already do very well. I prefer simply providing links, perhaps with a strong recommendation.

I also don't want to make this too general a resource. I do like that you reiterate some important concepts, such as the four general categories of disability, as I think that'll make it easier to digest and structure the content. In examples, however, I'd like to stay focused on common problems in JS-powered websites and only mention other tips when they're of incidental importance. So for example, alt text on images and subtitles on a video are probably out of scope, as they're more related to content than interaction.

Here's an example of what I was imagining from your outline. I put it together very quickly, so please forgive any sloppiness, but note the focus on interactive experiences from the start, even when addressing the Why question. Also note the emphasis on the code and live demos, with an example common enough (in this case, building a modal), so that users can easily relate to it. Only after grabbing the reader emotionally with the Why, do we then dive into What, providing a very brief definition of accessibility.

What are your thoughts on that kind of format? It's just occurred to me that there's probably a section missing between Why Accessibility Matters and Accessibility with Vue. Maybe something like How to Know Your Serving Everyone? That could be a good place to add your information about the various kinds of disabilities that we'll be keeping in mind - and to build up any other overarching vocabulary or concepts that could be helpful later on. Do you think that would work?

This really is a great start by the way, even if it seems like I'm tearing it apart. 😅 In my own editing process, it's not uncommon for me to rewrite most of a page multiple times before landing on something that works. Feel free to push back too, if you feel I'm missing something in terms of format, the kind of content we should include, etc. It's pretty rare that I'm fully grasping the ideal of the page, especially at this stage. 😊

[callumacrae]

The problem I've found in the past with trying to make people relate with the examples is that it only works for some types of impairments - it's easy to help people relate with keyboard-only users, it's much trickier to help people relate with colourblind users or users with ADHD. "Some people have ADHD, and so try to avoid constant animations" is a lot more effective than "Did that animation at the side distract you? Imagine it did!"

I also feel like the Why is missing something fundamental in your example - you've pointed out that the user can't use the page without a mouse, but not why that's a bad thing, or how many people it would affect. It almost feels like burying the hook - 15% of the population have a disability? Why didn't you say so at the start?

Agree with linking to other resources instead of duplicating for later sections such as the basic accessibility stuff like alt text, but don't really agree for the introduction—it's important information that is less likely to be read if it's somewhere else. I was thinking of keeping it short and linking somewhere else for a longer read, but keeping the important stuff there.

[chrisvfritz]

The limitations of examples for difficult-to-grasp impairments

The problem I've found in the past with trying to make people relate with the examples is that it only works for some types of impairments

Agreed, but wherever we can, I'd like to try. For example, we could use a simulator for color blindness, like this one. Being diagnosed with ADHD myself and having taught many distraction-sensitive students (of varying kinds and degrees), there are metaphors that can tie the experience to a more common one, and to some extent, even limited simulators.

For example, having even a single, constant animation on the screen can put a similar cognitive load as the exercise below, trying to say the color of each word while ignoring its content:

If you concentrate, you can do it, but it becomes exhausting pretty quickly. And that's why GIFs that autoplay are the bane of my existence when I'm trying to read an article. 😄

What do you think? Are examples and tools like that helpful? Or because of their inherent limits, are they more likely to lead to misunderstandings? Or are they useful, but just not useful enough to merit adding them? The provisional goals I outline below may help us answer these questions.

it's easy to help people relate with keyboard-only users

Exactly why I started with that one as a launching off point. 🙂

Re-focusing on the statistical impact of accessibility

I also feel like the Why is missing something fundamental in your example - you've pointed out that the user can't use the page without a mouse, but not why that's a bad thing, or how many people it would affect. It almost feels like burying the hook - 15% of the population have a disability? Why didn't you say so at the start?

Absolutely agreed. Another question that could be useful to (briefly) address: "If 15% of the population have a disability, why is everyone I know perfectly able? I don't think my users are actually disabled."

I've actually heard that and if I'm really honest, have previously thought it. Typically, I'll ask a question back, "Have you ever known someone for a while, then were shocked to discover that they were actually color blind, but just never mentioned it?" Most people seem to have had this or a similar experience. Poor accessibility also creates barriers that make it more difficult for people with disabilities to enter many fields, software development included, contributing to the illusion of non-existence.

And again, it could be useful to tie this back to something users are already used to caring about. For example, if you opened Google Analytics and realized that 15% of your customers were using a browser you just dropped support for, you'd probably drop everything to revert that change.

Identifying document goals

don't really agree for the introduction—it's important information that is less likely to be read if it's somewhere else

I think we're on the same page here. For example, even though information on the 4 major kinds of disabilities is elsewhere, I love that you included it, because it's foundational information for digesting information we'll cover later. It's just details that don't serve the primary content I'd like to leave out. So I guess the primary document goal I'm thinking of is:

Provide concrete accessibility strategies, specific to Vue-powered websites.

And some secondary goals that serve this one:

1. Help users understand why this work is important. This allows the content to hold emotional weight, so that they can better digest the information and are more likely to use it.
2. Provide the necessary contextual knowledge to understand the strategies we're deploying, so that users can more easily chunk information as they take it in.
3. Provide users the conceptual and technological tools to test and improve accessibility, so that they know when they've succeeded in building an accessible website.

So for example, while the importance and purpose of alt text on images is important information that users won't get unless they read it elsewhere, it probably doesn't serve one of the above goals, so is out of scope.

Naturally, some of this will still be subjective. Some information may help a little, but add too much to the length of the content or disrupt the pacing, but we can negotiate that here. What do you think about those goals though? Are they in line with your original intentions for this document? I'm open to revising them.

Possible personas

I've absorbed a little voice into my head from my UX expert wife, which is telling me now, "Perhaps as part of your goals, you should identify who you're actually serving - and in what priority order." She's probably right. 😄 Here's something we can start with, not necessarily in priority order at this point:

1. Current Vue developer without a disability, very slight proficiency in accessibility, looking to improve even more

• Has been using Vue for a little while and ready to dive deeper. Is more skimming the page than reading it and is probably not willing to spend more than 15 minutes here, looking for any low-hanging fruit or simple mistakes they may be making. Pays especially close attention to code and demos.
• Never read a book about accessibility and has maybe heard of WCAG or even glanced at it, but never read the standards fully. Learned everything they know from a few blog articles, plus examples in the Bootstrap documentation.
• Uses many semantic elements, but not always correctly. Adds alt text to images and occasionally uses attributes like aria-hidden and aria-label, because they don't want to be yelled at for not being accessible. Does sometimes test keyboard navigation, but usually only as an afterthought or if a project has accessibility requirements.
• Has never used a screen reader or other accessibility tools.

2. Relatively new web developer without a disability, no current development job or colleagues

• Just reading the Vue docs for the first time now and enjoying it, but running a little low on mental energy at this point. Has heard the word accessibility in the context of things like wheelchair access, but not as much in the context of web development, so not exactly sure what it means.
• Has never used semantic HTML elements or special attributes for accessibility. Knows enough CSS to create poor color combinations, but their knowledge is pretty basic. They may not even be familiar with properties such as max-width, line-height, cursor, or outline. They've used the hover state selector, but never focus.
• Has a friend who works in deaf education, who once showed them how difficult many games are without audio. Has a relative with very poor eyesight who uses some accessibility tools on an iPad, which they helped research and set up, but hasn't really been around when these tools are used, because the relative is worried that the screen reader would be annoying for other people.

3. Current Vue developer with ADHD and color blindness, at an institution that follows WCAG for all projects

• Already cares deeply about accessibility, especially as it relates to their specific disabilities. Has read through WCAG once, but not the latest revision and doesn't remember everything. They work for a university with strict accessibility guidelines, so discusses accessibility frequently and QA tests for accessibility specifically.
• At work, there's been resistance against too much client-side JS, because most people aren't sure how to switch paradigms and stay accessible. For example, how do you change the focusable elements when a modal pops up? How do you communicate to a blind user that a modal even appeared? Most co-workers have only learned to write accessible frontends by example, so aren't even sure it's possible. Eager for the opportunity to use more Vue at work, they followed this page from a tweet and are checking it out on their lunch break. They're looking to learn more and hoping for a simple resource that can answer common questions for colleagues.

What do you think? Are these personas sufficiently representative of the people we want to target with this page? If so, what do you think the priority order should be? For example, if adding to one persona's experience would significantly detract from another's, this can help us decide which experience to prioritize.

[callumacrae]

The limitations of examples for difficult-to-grasp impairments

I think a mixture of examples and statistics would be best. An example for every kind of impairment would create a very long document and would take far too long to read!

It's also worth noting that by adding bad examples, we'd be making the accessibility documentation inaccessible.

Re-focusing on the statistical impact of accessibility

Absolutely agreed. Another question that could be useful to (briefly) address: "If 15% of the population have a disability, why is everyone I know perfectly able? I don't think my users are actually disabled."

The actual reason for that is that the elderly are pushing up the statistics - a far higher percentage of them have some form of disability than the kind of people in our offices and using our websites. And, of course as you mentioned, there are lot of people (myself included!) with invisible disabilities.

Might be worth saying something along the lines of "none of your customers have disabilities because they left your website before they became customers", though.

Identifying document goals

Agree with not including information like alt text. The reason I included that in the introduction is that you can explain it in one sentence, while you can't explain stuff like why you need to announce page navigation that quickly.

Sounds like a good goal! Also agree with the personas and priorities.

[chrisvfritz]

Everything you said sounds great. 😄 I guess one more note:

It's also worth noting that by adding bad examples, we'd be making the accessibility documentation inaccessible.

Agreed, so similar to with an image, I think any counter-examples will need to be well-described in context and not interfere with interpreting the page.

[callumacrae]

just a fyi, i don't go back and change stuff until i'm done writing (or i'll spend 50% of the time on the introduction). comments on individual sections will be addressed once i'm done with the base content, they're not being ignored :)

[callumacrae]

some feedback on the section I just added would be great - I think this is the best format for the documentation.

[chrisvfritz]

@callumacrae I'll take a look - hopefully today, but possibly this weekend. Should I be looking at everything you have so far under Accessibility in JavaScript-rich websites? And are there any specific concerns you have, or questions I should keep in mind? For example, do you have doubts about a specific explanation/example? Is there an area where you're not sure if you've gone into too much (or too little) detail?

[callumacrae]

@chrisvfritz just the input elements section - I added examples to it, and I'm thinking making the rest of the documentation like that would be best

[chrisvfritz]

@callumacrae I really liked this example and the slow introduction of concepts as we made the checkbox more accessible:

You can’t just style a checkbox to look like that

It might be good to mention that it's because browsers don't support that level of styling for many native input elements.

Maybe you could do it like this:

What would you think about including not only the template, but also the JavaScript? I'm thinking for people who aren't very experienced with custom inputs, it could be helpful. Then for later examples, where only the template changes, we can leave out the JavaScript.

we could have a hidden checkbox input bound to the same variable, like this:

Should we show the code again here? I'm especially worried people might think input type="hidden" when you say hidden input.

ARIA attributes

It might be good to mention what ARIA stands for, to help people remember it.

It might also be good to link to a cheatsheet of aria attributes, noting that you can't just make them up. I've seen some weird stuff like aria-leaderboard-sorting="score, descending" - which I imagine is useless, right? I think some assume that any attribute starting with aria- means screen readers will read out the name and value of the attribute.

To make first example accessible using ARIA, we have to set the role to “checkbox” and use the aria-checked attribute

Again, let's show the code. Also, is this an alternative to what we just did with the hidden input? I've never used this strategy, so just learned something new. 😄 It might be good to make it clearer that these are two divergent ways of solving the same problem.

---

I didn't give feedback on grammar, spelling, flow, etc as it's typically easier for me to do a final pass at the end to make it consistent with the voice of the docs.

[callumacrae]

I have no idea why I didn't show the code - I'll add that

[chrisvfritz]

@callumacrae Just checking in on this. Anything you're blocked on that I can help with?

[callumacrae]

Sorry, been super busy with work and haven't had any time to work on this. Hopefully will have more time soon :D

[sdras]

This is a massive undertaking and I really appreciate the effort made here, because this is fantastic!
I'm really impressed with the start here, great job.

I have a couple of quick suggestions if you don't mind me jumping in. I would really appreciate if we define focus a little better- as well as some common input focus pitfalls. I notice that a lot of developers either don't understand what keyboard focus is at all, and what it means to someone using a keyboard, or if they do, they start applying focus() very liberally, throwing people around the page, which also sucks. Maybe we can cover some best practices here, and offer some clarification, since it's not a one-size-fits-all kind of scenario.

I kind of like the idea of providing a video like this: https://www.youtube.com/watch?v=lrXDulundpE. It helps people actually see what's going on if they've never used a screenreader before, and then maybe a code sample. Could also use the cookbook for a nice sample, too.

I made this color example for an article I wrote that talked about color accessibility, because the hard part of color is that a color is only a color in relationship to another color. You can use it if you like or I can help make you another, (or you don't have to include one at all) - this shows that this same color looks totally different encased in a different color context.

I agree with Chris that some links would be great! Deque systems makes a lot of tools.
Here are some for color:
Colorable
Text on a background image a11y check
Contrast-A
Accessible Colors

Anyways, I'm super excited for this! Please let me know if you need any help at all, I think what you're putting together is going to help a lot of people and it's a really great text so far! Super awesome job. 🎉

[mhewson]

"JavaScript allows us to make powerful, interactive websites and applications, with features from animations to client-side routing instead of having to hit the server every time the user goes to a new page. Unfortunately, some accessibility technology, especially screen readers, doesn't work so well with these websites. "

maybe something like

"JavaScript allows for powerful, interactive websites and applications. Its usage can be simple or complex. Unfortunately, some assistive technologies struggle to support this environment. With this in mind what can we do to accommodate these tools added needs?"

[stephenbelyea]

Added a comma to break up "With this in mind, what can we..."

[callumacrae]

I'm finally done with my book and with travelling, so have time to work on this again :)

I've just pushed a commit adding summaries of the missing sections with what I planned to write in them - if anyone wants to help, feel free to pick one of them up or add anything I've missed! I can either add you as a collaborator to my repo or you can send PRs to my branch (not really sure what the best approach to collaborating on a PR is, tbh)

also thanks @sdras and @mhewson for the comments, will address them sooon

[chrisvfritz]

@callumacrae Woohoo! I'm excited. 😄 It might be easiest to add users to your repo to collaborate - that way, we don't have to go through two layers of bureaucracy to get them in this PR. 😅

[callumacrae]

yup, if anyone wants to be added let me know 👍

[sdras]

I think axe-core is worth mentioning here

[stephenbelyea]

I also added WAVE, as it's one I use frequently (especially the browser extension).

[sdras]

I'm afraid what we've done is make it near-impossible for Callum to get this in with all the varied feedback. In the interest of unblocking him, perhaps we should make a to do list of what we feel needs to be included to get the PR in, and we can always improve it in the future with subsequent PRs. An "MVP" of this section, if you will. I'd honestly rather have this contribution be part of our guide than have it be perfect at first glance (I contributed to the PR pile-on, I know).

How about:

• fix inline suggestions
• address Chris' good suggestions of code examples here
• Provide a couple of external links for further reading, line 29 where there is a todo. There are a lot of them out there, one I particularly enjoy is Heydon Pickering's Inclusive Components, if you're open to suggestions. Marcy Sutton and Leonie Watson also have great resources and talks.
• rebase so that the checks for netlify pass

What do people think?

[chrisvfritz]

@sdras I agree 100%. 🙂 Thanks for your patience on this @callumacrae!

[meowsus]

@callumacrae Thank you for your efforts! Keep up the good work!

[zivc]

@callumacrae as aforementioned, keep up the good work. You are a valuable asset to our business.

[stephenbelyea]

@callumacrae Hi! I'd be happy to address some of @sdras's checklist above to get this documentation live. Can I be added to the PR?

[callumacrae]

@stephenbelyea awesome! done :)

[stephenbelyea]

It looks like some of @chrisvfritz's code sample suggestions were touched up by @callumacrae before my time here. Is there more to do for that comment?

I've rounded out links and examples in the ARIA section and added a first draft of some copy and links in the testing section. Unfortunately I can't check the checkboxes in @sdras' checklist :(

I'll keep adding touch-ups as I'm able to get time. Btw, good Global Accessibility Awareness Day, everyone!

[chrisvfritz]

It does look like those code sample suggestions might be addressed now. 🙂

[Jinjiang]

Hi everyone, how things going here. 😀
It's so nice to have an a11y guide for Vue. I have practiced some a11y issues recently. Please allow me to leave some advices here.

Thanks.

[Jinjiang]

I highly recommend adding the W3C aria practices page to guide developers to learn and follow. Because it supplies so many code cases that we can just copy-paste to start. Actually that's my very beginning way about supporting a11y in my personal project.

[Jinjiang]

How about add a section to introduce some a11y tools or component libs with good a11y support in Vue ecosystem. I heard some of them:

• VEUI - component lib
• Element - component lib
• eslint-plugin-vue-a11y - eslint plugin

And I personally just started a project called Vue A11y Utils to try supplying some a11y utilities for Vue. It's still wip, not finished. 😜

Thanks.

[poorgeek]

I'd suggest only including libraries that pass an accessibility review. For instance, I wouldn't include Element in this list as a quick spot check some of the Element components and there is still a bit of work to do. The same spot check on VEUI reveals that best practices are mostly being followed, but I found VEUI still needs some help with contrast and focus indicators.