Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[material-ui][docs] Create ADA compliance documentation #14187

Open
jmadson opened this issue Jan 15, 2019 · 25 comments
Open

[material-ui][docs] Create ADA compliance documentation #14187

jmadson opened this issue Jan 15, 2019 · 25 comments
Labels
accessibility a11y docs Improvements or additions to the documentation

Comments

@jmadson
Copy link

jmadson commented Jan 15, 2019

It would go a long way to help pitch Material UI as a solution if I could link to documentation covering the library's support for ADA compliance.

I know Material UI does have at least some support for ADA/WCAG compliance, for instance through the use of "aria-" and "role" html attributes throughout the codebase to assist screen readers and the support for keyboard navigation such as in the Select component.

Meanwhile, Material Design itself seems to lend itself nicely to following the WCAG guideline, for instance with regards to readability, navigation and high contrast text.

However, without being a core contributor myself, I cannot speak to the library's compliance overall. I searched the material-ui.com website as well as past/present GitHub tickets and could not find a page in the documentation whose sole purpose was to outline what it does and does not do to be ADA compliant. Therefore, I am opening this ticket as a feature request to please create said documentation.
@oliviertassinari
Copy link
Member

We are doing our best to make Material-UI accessible, following the WCAG guideline. Now, we have never passed or tried to pass the ADA certification. Could you find any specific problem?

@jmadson
Copy link
Author

jmadson commented Jan 15, 2019

@oliviertassinari Thanks for the fast reply. I have definitely noticed attention to following the WCAG guideline within the Material UI codebase. There is no specific problem, just a desire to share a documentation link with my employer covering a high-level overview of Material UI's compliance with the WCAG guideline. I imagine this could be useful for others as well.

@josgraha
Copy link
Contributor

josgraha commented Jan 15, 2019 •
edited
Loading

Today I learned from our accessibility expert that most big companies publish a VPAT (Voluntary Product Accessibility Template) which lists all of the known issues. Here is the download link for the VPAT one of Microsoft's products.
https://www.microsoft.com/en-us/download/details.aspx?id=8937

Basically it just provides a date and lists all of the known issues against the success criteria. This VPAT is old and newer products would use the 38 success criteria in WCAG-2.0.

Maybe an actionable item of this issue would be to create a WCAG-2 VPAT for MUI?

@eps1lon
Copy link
Member

eps1lon commented Jan 15, 2019

It would be more helpful to have a checklist against we can verify our components. Knowing unknown issues is somewhat harder than verifying that something is working.

Many of those guidelines are not really actionable for us since we can't always verify what DOM attributes have to be set and where. Maybe we can improve/document integration with eslint-plugin-jsx-a11y.

@eps1lon eps1lon added the accessibility a11y label Jan 15, 2019
@bramick
Copy link

bramick commented Jan 23, 2019 •
edited
Loading

I'm actually in the process of reviewing MUI for WCAG 2.0 AA as we speak. Mostly notating aria and role. After that I plan to go to each component and see what's missing from compliance. I'd be interested in contributing to this if we can figure out an acceptable documentation process.

For clarity, ADA does not have a web/interactive compliance. It does however state

The ADA encourages self-regulation of accessibility standards and the Department of Justice is currently developing regulations to provide specific guidance to the entities covered by the ADA. Organizations are encouraged to use the WCAG 2.0 level AA guidelines as a guide on how to become accessible until the DOJ defines the regulations.

@mbrookes
Copy link
Member

mbrookes commented Jan 23, 2019 •
edited
Loading

if we can figure out an acceptable documentation process

We already have an accessibility section in some demo pages, so it would be good to have consistent documentation across the board as to what accessibility MUI provides out of the box, and which ones the developer needs to address.

We do show this in the examples, but it would be good to call it out explicitly.

@Mobilunity-Com
Copy link

Hello! I'm really glad to join this thread about ADA. I found great article about WCAG & ADA web compliance. If you want you can read it and share your thoughts after reading. Hope you like it! Because I found it really useful.

@oliviertassinari
Copy link
Member

oliviertassinari commented May 15, 2019 •
edited
Loading

Does anyone know an audit accessibility company that could audit all our components for the ADA compliance? Bonus point if the company can sponsor it for a popular OSS project.

@bramick
Copy link

bramick commented May 16, 2019 via email

@oliviertassinari
Copy link
Member

@bramick I'm looking for manual tests.

@bramick
Copy link

bramick commented May 16, 2019 via email

@bramick
Copy link

bramick commented May 16, 2019 via email

@oliviertassinari oliviertassinari added the priority: important This change can make a difference label Jun 21, 2019
@oliviertassinari oliviertassinari mentioned this issue Jun 25, 2019
Merged
@oliviertassinari oliviertassinari removed the priority: important This change can make a difference label Dec 1, 2019
@eps1lon
Copy link
Member

eps1lon commented Jan 16, 2020

Going to dedicate part of the next week to this which will include:

  • loose pass over WCAG 2.0
  • how does our current a11y statement look?
  • prototyping how these could be included into our docs e.g. "component meets WCAG 2.0", "the following demo meets WCAG 2.0. Do not alter the code until you know what you're doing", "these are common patterns that violate WCAG 2.0"
  • (dynamic/static warnings about misuse which might require some upstream changes in jsx-a11y)
  • (WCAG 2.1 outlook which is required to pass by law for public sector. This will impact the private sector sooner than later)

@eps1lon eps1lon self-assigned this Jan 16, 2020
@oliviertassinari oliviertassinari mentioned this issue Jul 16, 2020
Closed
@eps1lon
Copy link
Member

eps1lon commented Sep 10, 2020

Our components won't meet WCAG by default. The look&feel are more important (see #22541). It's not viable to document all possible techniques to makes the components meet WCAG 2.1. We'll revisit this in the future once we have the bandwidth for it.

@eps1lon eps1lon closed this as completed Sep 10, 2020
@eps1lon
Copy link
Member

eps1lon commented Sep 10, 2020

oliviertassinari reopened this in 1 hour

@oliviertassinari Did you change your mind after #22541? Could you explain why you want to follow ADA but not WCAG?

@oliviertassinari
Copy link
Member

oliviertassinari commented Sep 10, 2020 •
edited
Loading

@eps1lon From what I understand this issue is about providing a list of all the known issues around accessibility. With such a list, developers can then evaluate each component and decide if they want to use it or not, individually.

With a comprehensive list, we could then prioritize work on the most important items. So I think this should stay open until we can provide a comprehensive list. I think it's where an a11y audit with severity for each failure would help a lot. I would be leaning toward doing both an internal and external audit.

Regarding the Rating, I believe that by using different shapes (in addition to the different existing colors) we can address 1.4.1: #22554.

Can somebody confirm that ADA compliance is reached with the AA level of WCAG 2.1?

Regarding the look & feel, I don't think that great looking application makes it impossible to have them accessible. However, it makes it harder, and I don't t think that it's something we should trade.
Why? Because it seems that most product teams make the same tradeoff. If Material-UI isn't used, whatever improvements we bring to the a11y won't have as much impact as it could have.

@bramick
Copy link

bramick commented Sep 11, 2020 via email

@oliviertassinari oliviertassinari mentioned this issue Sep 24, 2020
Closed
1 task
@oliviertassinari oliviertassinari added the docs Improvements or additions to the documentation label Sep 24, 2020
@oliviertassinari
Copy link
Member

oliviertassinari commented Sep 24, 2020 •
edited
Loading

A benchmark of the type of outcome we can expect from this issue:

Note that I could only find that on paid UI libraries, and considering we are pushing in this direction, it makes sense to move forward on this issue too. In the public roadmap, we have an item on this matter.

Out of this benchmark, I would propose the following plan:

@josgraha J.P. Morgan has been proposing to help on this, do you know if there is any development?

@josgraha
Copy link
Contributor

I will look into it and report back here what (if anything) has evolved from a MUI centric effort. Soon after my post here the focus shifted to feature based compliance which makes more sense and closing gaps with middleware (internal api library) which can also be faulted for being too opaque and breaking a11y features supported by MUI. Another downside to the middleware approach is the massive version gap (major versions behind). The biggest issues we found in our own features where the following

  • keyboard navigation and tab focus indicator (sliders, tabs, menus, floating menus, drawers, modals, clickable toasts, popover focus, chip adornments)
  • color contrast ratio (purely design issue) 5:1 is pretty stark
  • high contrast mode (partially blind)
  • lots of grid keyboard navigation issues particularly around headers, grouped headers, footer and embedded footer components (not MUI)
  • label targeting (example label-for must be an id and thusly global)
  • mostly lots of issues with screen reader but without a JAWS license you can't even test this as it is the de-facto standard for blind users on desktop, don't even bother with NVDA
    since then MUI has come a very long way indeed supporting most (if not all the issues mentioned) but now you have a grid so welcome to that world of pain

@chaance
Copy link

chaance commented Sep 25, 2020 •
edited
Loading

Just seeing this because I was tagged, but:

  • mostly lots of issues with screen reader but without a JAWS license you can't even test this as it is the de-facto standard for blind users on desktop, don't even bother with NVDA

I believe this is a mistake. NVDA has gained significant market adoption in the past several years. This survey by WebAIM was in 2019 and showed NVDA actually overtaking JAWS for the #1 spot. https://webaim.org/projects/screenreadersurvey8/

NVDA is available for free. It is very much worth getting a JAWS license and testing on both platforms if at all possible, given their large user base.

@mbrookes
Copy link
Member

It is very much worth getting a JAWS license and testing on both platforms

It really does need to be tested by someone who uses these tools on a daily basis though. Getting a license isn't necessarily the issue, it's having the experience to know whether the output "makes sense" to a regular screen reader user.

@petermikitsh
Copy link
Contributor

Would a11y audits be performed for both styled and unstyled components (something to consider as v5 is being planned)?

@eps1lon
Copy link
Member

eps1lon commented Sep 28, 2020

It is very much worth getting a JAWS license and testing on both platforms if at all possible, given their large user base.

My problem is that this is a one-year license that I still don't even know how to get in Germany. After that you're stuck with an older version. I don't know how upgrades are handled by actual users. Do they upgrade every year? Every 5 years? If almost everybody is on the latest version then how useful is testing for 1-2 year old versions?

It really does need to be tested by someone who uses these tools on a daily basis though.

While I agree with that generally I don't think you need it for component testing. Most of SR related bugs are components flat out not working.

For testing UI itself app devs are responsible. We're also not testing usability of our components with actual users.

Would a11y audits be performed for both styled and unstyled components

Styled for now. For unstyled we first would need to determine what kind of properties we want to audit. For example, it wouldn't make much sense to audit "use of color" for the unstyled variant since the color is most certainly changed when people use the unstyled variant.

@josgraha
Copy link
Contributor

josgraha commented Sep 28, 2020 •
edited
Loading

FWIW I think unstyled components are likely more a11y compliant than styled because the contrast ratio doesn't come into play (just user defaults) and fewer edge cases to worry about wrt specificity for user defined styles (at least from a component level standpoint, granted the intended use case is for application defined styles and not so much user but from an opt-in perspective, supports user defined better)

@eps1lon
Copy link
Member

eps1lon commented Sep 28, 2020

FWIW I think unstyled components are likely more a11y compliant than styled because the contrast ratio doesn't come into play (just user defaults)

Sure but what is an audited component worth if it's never used in its default state? Styled components are much more likely to be used as-is or with little changes.

We're not choosing the version that is more likely to pass but the version where an audit is useful to the end-user.

This was referenced Nov 9, 2020
Merged
Closed
@eps1lon eps1lon removed their assignment Sep 30, 2021
@oliviertassinari oliviertassinari mentioned this issue Mar 14, 2022
Closed
@samuelsycamore samuelsycamore changed the title ADA Compliance documentation [material-ui][docs] Create ADA compliance documentation Nov 28, 2023
@samuelsycamore samuelsycamore mentioned this issue Nov 28, 2023
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
accessibility a11y docs Improvements or additions to the documentation
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
9 participants
@josgraha @mbrookes @petermikitsh @jmadson @chaance @oliviertassinari @bramick @eps1lon @Mobilunity-Com