Accessibility docs

[callumacrae]

React just added a section to their docs on accessibility, and it's pretty nice: https://facebook.github.io/react/docs/accessibility.html

I think Vue should have a page too! (and I'm happy to write it)

Proposed structure:

• Introduction - why accessibility matters
• Basic accessibility measures
  • Introduce the WCAG guidelines
  • Highlight a few of the important ones
• Accessibility in SPAs
  • Content that relies on the mouse (menu bars, dropdowns, controls on mouseover)
  • Extended input elements
  • Dynamic content (notifications, error messages) and aria-live
  • Announcing page navigation
• How to test accessibility

Very high-level overview of what I think we should have - any thoughts before I start writing?

[znck]

You should go ahead with a PR and @chrisvfritz would help you shape it.

[chrisvfritz]

@callumacrae YES! That sounds fantastic. 😄 Exactly as @znck said, you can open a PR (even with incomplete work) and I'll be happy to answer questions, help with tone, etc. My only note on your proposed structure is that I think it'd be good to avoid tying these recommendations to SPAs specifically, as any kind of website that uses Vue will probably be able to benefit.

A place I often start when developing a new page is with examples I know I want to cover, then I figure out a way to weave them together with case studies / stories. We like to keep the tone conversational in the docs, but generally avoid jokes/sarcasm, as it often doesn't work cross-culturally.

Also, once your talk is live, I think it'd be great to link to it for those that prefer video content.

[robdodson]

Btw if it's any help we have a bunch of accessibility docs available at https://developers.google.com/web/fundamentals/accessibility/ and I do a video series where I try to cover common topics https://www.youtube.com/watch?v=JS68faEUduk&list=PLNYkxOF6rcICWx0C9LVWWVqvHlYJyqw7g.

Really excited to see you all working on this!

[chrisvfritz]

Thanks @robdodson! @callumacrae ^^^

[callumacrae]

@robdodson hadn't seen that before - it's such a well written document! Thanks for sharing :)

[callumacrae]

@chrisvfritz how do I add a new page in hexo?

[chrisvfritz]

@callumacrae To add a new page to the guide, create a new .md file in src/v2/guide/. Each page has some metadata at the top, then it's just markdown below. 🙂

[callumacrae]

Opened a PR here: #1002

[sherbinkodet]

vuejs will never be WCAG 2.0 complaint because its vue-* attributes do not pass HTML5 validation and you guys denied to fix that:

vuejs/vue#273

[robdodson]

@sherbinkodet which WCAG conformance rule relies on HTML validation?

[sherbinkodet]

https://www.w3.org/TR/2016/NOTE-WCAG20-TECHS-20161007/H75

[sdras]

I think, could be wrong here- but the confusion lies in understanding that what the screenreader thinks of the DOM is different than the code that is written before compilation. The target for screenreaders is not to remove directive (which are not vue-* but v-*, yes that's pedantic), but to understand what it's compiled to. Just like React or Angular, there are ways to implement that care for accessibility, and ways to ignore it. Pointing to this doc seems oversimplified to me.

[sherbinkodet]

There are no way to ignore WCAG 2.0 recommendations if they are required. A site is either accessible or not. In order to be accessible it must satisfy all criteria. user-agent normally look at the content after running java-script, but if HTML is not valid it increases risk of not passing an accessibility audit.

[robdodson]

If anyone is curious, there's a very lengthy discussion on relaxing the custom attributes restriction here: whatwg/html#2271.

For what it's worth, the custom attribute validation rules are relaxed for custom elements. So while <div planet="mars"> is not allowed, <x-foo planet="mars"> is allowed. At least according to https://validator.w3.org :)

I know it's a little hand wavy, but I would also question if violating this rule actually has any negative impact on assistive technology. I guess it also depends on how strictly folks are interpreting WCAG during the audit.

[sherbinkodet]

If vue ignores W3C standards developers may ignore vue. There are many reasons why it is better to write HTML right. For instances, search engines might rank valid sites higher.

[robdodson]

If vue ignores W3C standards developers may ignore vue. There are many reasons why it is better to write HTML right. For instances, search engines might rank valid sites higher.

Is there evidence to support this? Specifically, that including v-* or non standard attributes hurt search ranking? I can't imagine search doing this because the practice is already pretty widespread and doesn't have obvious negative user impact.

[sherbinkodet]

Citation:

Since repair techniques vary among user agents, authors cannot assume that content will be accurately parsed into a data structure or that it will be rendered correctly by specialized user agents, including assistive technologies, unless the content is created according to the rules defined in the formal grammar for that technology. In markup languages, errors in element and attribute syntax and failure to provide properly nested start/end tags lead to errors that prevent user agents from parsing the content reliably. Therefore, the Success Criterion requires that the content can be parsed using only the rules of the formal grammar.

[robdodson]

Yep, like I said, it depends on how strictly folks are interpreting this rule.

Forgetting a closing tag can literally change the structure of the DOM and possibly break the page. In Vue's case, they know that what they're doing isn't breaking the structure of the page. And I haven't seen any evidence that it actually harms assistive technology.

[sherbinkodet]

as I wrote even if it does not harm assistive technology (in some specific case, for some specific browsers/screenreaders ) it might still harm WCAG 2.0 compliance.

[robdodson]

as I wrote even if it does not harm assistive technology (in some specific case, for some specific browsers/screenreaders )

I don't believe those attributes end up in the accessibility tree generated by the browser. So I don't see any evidence to support the claim that they harm any assistive technology, in any case, in any browser. That doesn't mean that don't, I just haven't seen any evidence supporting that.

it might still harm WCAG 2.0 compliance.

Yes it might. My understanding is that it's up to the firm doing the audit to interpret the rule and say whether it's an actual violation or not. 4.1.1 seems like its intent is to prevent developers from accidentally breaking the page structure with unclosed tags or typos. If what Vue is doing does not actually have any negative, or even perceivable, impact on the user experience, then the auditors may decide that it's not a violation. Again, it's up to how strictly those folks wish to interpret the rule.

[sherbinkodet]

If I want to choose between angular or vue I am not going to investigate source code of all existing browsers to find some "evidence".

As a developer I am looking if the framework requires not valid HTML. vue encourage using not valid HTML -> that causes problems: with IDE, with WCAG compliance, with validation tools etc etc etc

So that means I would prefer to avoid using vue until HTML attributes are fixed.

And vue cannot say they are "accessible" until they satisfy all formal criteria.

[robdodson]

That's fair and totally up to you. I wanted to discuss the issue because it's interesting and worth exploration.

[callumacrae]

I don't believe those attributes end up in the accessibility tree generated by the browser.

Unless you're using the DOM as your template instead of string templates or render functions (which from what I've seen, most of people don't), the attributes don't even end up in the DOM anyway—as pointed out by Evan in the issue @sherbinkodet linked to.

I don't think Vue's custom attributes are an issue, accessibility-wise.

A site is either accessible or not.

I'd dispute this. Some websites are more accessible than others. Also, you can follow all the WCAG 2.0 guidelines and have a website that still isn't accessible.

[marcysutton]

axe-core developer here. Custom attributes like the ones in Vue and Angular don't pose accessibility barriers, nor should they be called out as a failure of WCAG 4.1.1. This is an interpretation of the guideline, sure, but I'm going off of the feedback from the team of experts at Deque. They do not fail webpages for accessibility simply because they have custom attributes (not including ARIA attributes, however, which are limited to the standard set). If there is no barrier posed to users and the user agent can safely parse the page with the attributes actually rendered, why would you call it a failure? axe-core does not call these out as violations because they aren't accessibility problems. NuValidator does, but most accessibility subject matter experts wouldn't. I don't think this is an issue.

From my colleague John Foliot:

Non-valid code is not 'forbidden' by WCAG; the requirement is that the code meets the following:

• General - Elements must be coded using proper formatting.
• HTML - Elements must have complete start and end tags.
  Pedants will also note that this refers to elements (), and not attributes (alt="").

I would suggest that non-standard or 'custom' attributes are not forbidden (and in fact the W3C acknowledges and does not forbid vendor-prefixed attributes, most commonly in Style sheets: https://www.w3.org/TR/CSS21/syndata.html#vendor-keywords).

Secondly:

A site is either accessible or not.

I would also dispute this. Accessibility is a continuum, not a checkmark. There are varying degrees of accessibility and marking up custom attributes as failures does a service to no one. We have a hard enough time getting adoption of accessibility as it is. I would recommend relaxing your definition of how to meet 4.1.1 and move on to problems with actual user impact.

[sherbinkodet]

Yes I agree that issue is not serious in practice and some WCAG requirements are not perfect and sometimes they even not possible to implement (but they often have grounds which you even may not suspect about). I can also agree it probably does not affect assistive technologies (in most cases). However I would like to mention accessibility != WCAG 2.0. and I have wrote the citation from that page:

https://www.w3.org/TR/UNDERSTANDING-WCAG20/ensure-compat-parses.html

"In markup languages, errors in element and attribute syntax and failure to provide properly nested start/end tags lead to errors that prevent user agents from parsing the content reliably. Therefore, the Success Criterion requires that the content can be parsed using only the rules of the formal grammar."

I would also dispute this. Accessibility is a continuum, not a checkmark. There are varying degrees of accessibility ...

I am not sure what you mean while talking about accessibility, but WCAG 2.0 is landmark

There are requirements for government organisations in NSW to be WCAG 2.0 AA complaint. And organisation's sites are either complaint or not.
It would be risky to fix all issues and at the end find out the main framework causes problems by design.
What if some company decide an application does not pass 4.1.1? Should we rewrite everything then? Or create some patches modifying attributes before vue is loaded?

Also, you can follow all the WCAG 2.0 guidelines and have a website that still isn't accessible.

Really? I can hardly imagine that.

axe-core developer here.

Thank you for the nice tool

[marcysutton]

I don't understand what your end goal is here. They're talking about adding a doc for accessibility, which is absolutely a positive and necessary move. Use data-* attributes if you're that concerned about meeting 4.1.1, and let's move this issue forward instead of blocking it.

Note: these attributes are also not rendered. So this is a serious non-issue.

[sherbinkodet]

I don't understand what your end goal is here. They're talking about adding a doc for accessibility, which is absolutely a positive and necessary move

We are discussing accessibility documentation here do not we? The documentation is supposed to contain section about attributes problem, so people who are considering using vue will be aware of that.
And also it would be confusing to see the "accessibility" documentation in case if the framework is not accessible by design. People may think vue is WCAG complaint until they stuck in 4.1.1.

Adding doc about is a positive move especially if the doc honestly describe all details

[sdras]

We're going back and forth and it's pretty clear at this point that some of the conversation is not helpful to the end goal which is creating an accessible experience for our users, especially given the lack of testing and sufficient reporting using assistive technologies.

I want to sincerely thank Callum for making this document, I know it came at a personal cost to him and I think it will help people make Vue applications in the future. We'll close this out when we reach a consensus on the PR, which should be soon.