[core] Accessibility - increase default contrastThreshold for WCAG AA compliance #34901

kennethbigler · 2022-10-26T23:51:31Z

I have followed (at least) the PR section of the contributing guide.

Updating documentation to guide people towards WCAG 2.1 AA compliance, but removed any actual code changes. See below description and comments for context.

Below was for original PR and context, but this has all been reverted

Hello!
My name is Ken Bigler and I am the Accessibility Engineering Leader at Intuit.
I work on the Intuit Design System (internal to Intuit), and I am a big fan of your products.
Anyway, to the point of this PR:

TDLR - the default contrastThreshold needs to be increased.

Ok, now let me go into why.
I use MUI for my personal website, and when I was adding lighthouse tests, I noticed that I started getting a lot of color contrast errors. I know that MUI has wonderful accessibility, but then I read your accessibility page and it sounds like you wanted contribution from experts, so I thought I could step in.

Verify the problem

The easiest way to do this is to run lighthouse or Axe on your documentation website, and you will see:

Oh no! Ok, we have some contrast issues.

But we have a contrast ratio of 3:1, aren't we WCAG 2.1 Rule 1.4.3 compliant?

Well, not exactly. That is only for large text, for smaller text (which is all over not only your documentation site, but the entire internet), we need a ratio of 4.5:1.

Fixing the problem

So, this PR increases the ratio from 3:1, to 4.5:1, did that fix anything?

Why yes it did! See the results!

Why not fix everything?

Well, great question, in an effort to keep this PR small, I wanted to keep the scope limited.

Visual Updates

You can kind of see this in the argo CI, but here it is slightly easier to see.

Before

After

mui-bot · 2022-10-26T23:54:04Z

	Messages
📖	Netlify deploy preview: https://deploy-preview-34901--material-ui.netlify.app/

No bundle size changes

Generated by 🚫 dangerJS against 465ec94

kennethbigler · 2022-10-27T01:17:22Z

Argo CI failures are expected (improving contrast)

kharrop · 2022-10-27T23:05:37Z

Wow, these results are super impressive from just a few files changed. This is great, looking forward to seeing this one merged.

mnajdova · 2022-11-07T08:22:33Z

Thanks for the comprehensive description! This is not something we often see :) The changes look good, however, some people may consider them a breaking change, especially if some of the components that depend on them have additional style overrides. I would personally merge the changes as they are improving the accessibility of the components, but I am tagging @michaldudak and @siriwatknp for a second opinion.

michaldudak · 2022-11-07T09:02:13Z

Thanks for bringing this topic in!
Looking at Argos diffs, I wouldn't agree that the changed colors are more readable. This is especially visible for blue:

before:

after:

To me, the white text is much more readable than the black one.

So, why do the a11y tools report this as a problem? WCAG 2.1 uses a color contrast algorithm that has flaws. W3C is considering replacing it with another algorithm, APCA, in WCAG 3.0 (https://colorjs.io/docs/contrast.html#accessible-perceptual-contrast-algorithm-apca). I found a good summary of cases where APCA gives better results: Myndex/SAPC-APCA#30

I checked several of the color combinations changed in this PR, and they scored worse according to APCA (and my subjective view).

I don't think we should optimize for tools (especially if they are imperfect) but for people.

kennethbigler · 2022-11-08T03:19:49Z

Thanks for bringing this topic in! Looking at Argos diffs, I wouldn't agree that the changed colors are more readable. This is especially visible for blue:

before:

after:

To me, the white text is much more readable than the black one.

So, why do the a11y tools report this as a problem? WCAG 2.1 uses a color contrast algorithm that has flaws. W3C is considering replacing it with another algorithm, APCA, in WCAG 3.0 (https://colorjs.io/docs/contrast.html#accessible-perceptual-contrast-algorithm-apca). I found a good summary of cases where APCA gives better results: Myndex/SAPC-APCA#30

I checked several of the color combinations changed in this PR, and they scored worse according to APCA (and my subjective view).

I don't think we should optimize for tools (especially if they are imperfect) but for people.

Hey @michaldudak, thank you so much for your reply.
I certainly am not trying to optimize for a tool, not sure where you got that impression, but yes the goal of this PR is to optimize for people under what Material UI is currently using as their evaluation standard.

I see what you are saying about the imperfectness of the current WCAG 2.1 standards. Sadly I think the WCAG 3 standards are at least several years out, as we have not even seen the finalization of the 2.2 standards yet.

But, all that being said, again I am not trying to just optimize around a tool.
I think standardizing on APCA could be good, BUT, I don't think it makes sense to use that as a standard of rejection here, when Material UI uses the WCAG 2 algorithm currently, and doesn't meet the standards it is actively following.

I could easily change the contrast evaluation method to APCA and set the minimum value to 60.
Would that be preferable?
We could have it support either algorithm, and auto determine the algorithm based on provided value (WCAG < 30 <= APCA). Although something like that would take a bit more thought.

NateBaldwinDesign · 2022-11-09T16:48:41Z

@michaldudak it is true that the APCA formula is more perceptually accurate. However, APCA is still not finalized, and WCAG 3 is still in progress as well. I would recommend adhering to current standards, especially with a library like this.

siriwatknp · 2022-11-10T03:14:04Z

I propose a simple solution to this, we can provide a copy-paste snippet in the docs for the theme to enhance the contrast ratio so that anyone who strictly follows the contrast ratio can opt-in.

This workaround should make everyone happy!

For those who rely on the standard WCAG 2.1, those issues are fixed.
For those who want to wait for APCA, they won't need to deal with breaking changes.

kennethbigler · 2022-11-10T04:05:40Z

I propose a simple solution to this, we can provide a copy-paste snippet in the docs for the theme to enhance the contrast ratio so that anyone who strictly follows the contrast ratio can opt-in.

This workaround should make everyone happy!

For those who rely on the standard WCAG 2.1, those issues are fixed. For those who want to wait for APCA, they won't need to deal with breaking changes.

So @siriwatknp the end recommendation would be to keep it currently failing compliance to WCAG 2.1, and provide documentation on how to meet WCAG 2.1 standards within one's own config?

kennethbigler · 2022-11-10T05:15:59Z

@siriwatknp @michaldudak @mnajdova I have updated the PR to be non-breaking, and just adding documentation.
Please review the wording, add any suggestions, and let me know if there is anything else you need from me.

mnajdova

This looks much better to me. I am tagging @samuelsycamore for reviewing the docs.

michaldudak

@michaldudak it is true that the APCA formula is more perceptually accurate. However, APCA is still not finalized, and WCAG 3 is still in progress as well. I would recommend adhering to current standards, especially with a library like this.

That's true. But leaving standards aside for a moment, do you think users prefer reading texts that look like this?

I don't mean to say that APCA is the silver bullet, but it's pretty clear that the WCAG formula is flawed.

Fortunately, there is a solution that should make everyone happy. Thanks, @siriwatknp for the suggestion!

docs/data/material/customization/palette/palette.md

michaldudak · 2022-11-11T08:14:59Z

@kennethbigler Could you please rebase on the latest master? This should solve the argos errors.

Co-authored-by: Michał Dudak <michal.dudak@gmail.com> Signed-off-by: Ken Bigler <kennethbigler@gmail.com>

kennethbigler · 2022-11-14T02:52:58Z

@michaldudak can we merge this now?

siriwatknp · 2022-11-14T04:34:54Z

@michaldudak can we merge this now?

Yep, we will merge it today.

siriwatknp

👍 Thanks! pushed some changes to shorten the sentence.

… compliance (mui#34901) Signed-off-by: Ken Bigler <kennethbigler@gmail.com> Co-authored-by: Ken Bigler <ken_bigler@intuit.com> Co-authored-by: Michał Dudak <michal.dudak@gmail.com> Co-authored-by: siriwatknp <siriwatkunaporn@gmail.com>

kennethbigler changed the title ~~feat(accessibility): increase default contrast ratio for WCAG AA compliance~~ [core] Accessibility - increase default contrastThreshold for WCAG AA compliance Oct 27, 2022

zannager added the core label Oct 27, 2022

zannager requested a review from mnajdova October 27, 2022 07:04

shriuken approved these changes Oct 27, 2022

View reviewed changes

mnajdova added the accessibility label Nov 7, 2022

mnajdova approved these changes Nov 10, 2022

View reviewed changes

michaldudak reviewed Nov 10, 2022

View reviewed changes

docs/data/material/customization/palette/palette.md Outdated Show resolved Hide resolved

Ken Bigler and others added 4 commits November 11, 2022 14:00

feat: increase base contrast ratio for WCAG AA compliance

Unverified

No user is associated with the committer email.

Learn about vigilant mode

1b44f2c

fix: unit tests as color changed

Unverified

No user is associated with the committer email.

Learn about vigilant mode

9c6b151

fix: revert wcag 2.1 fix, and just add docs

Unverified

No user is associated with the committer email.

Learn about vigilant mode

624e047

Update docs/data/material/customization/palette/palette.md

Unverified

No user is associated with the committer email.

Learn about vigilant mode

b683333

Co-authored-by: Michał Dudak <michal.dudak@gmail.com> Signed-off-by: Ken Bigler <kennethbigler@gmail.com>

kennethbigler force-pushed the improve-contract-ratio branch from a2e9872 to b683333 Compare November 11, 2022 08:30

update content

465ec94

siriwatknp approved these changes Nov 14, 2022

View reviewed changes

michaldudak merged commit 2ac5de5 into mui:master Nov 14, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[core] Accessibility - increase default contrastThreshold for WCAG AA compliance #34901

[core] Accessibility - increase default contrastThreshold for WCAG AA compliance #34901

kennethbigler commented Oct 26, 2022 •

edited

Loading

mui-bot commented Oct 26, 2022 •

edited

Loading

kennethbigler commented Oct 27, 2022

kharrop commented Oct 27, 2022

mnajdova commented Nov 7, 2022

michaldudak commented Nov 7, 2022

kennethbigler commented Nov 8, 2022 •

edited

Loading

NateBaldwinDesign commented Nov 9, 2022

siriwatknp commented Nov 10, 2022

kennethbigler commented Nov 10, 2022 •

edited

Loading

kennethbigler commented Nov 10, 2022

mnajdova left a comment

michaldudak left a comment •

edited

Loading

michaldudak commented Nov 11, 2022

kennethbigler commented Nov 14, 2022

siriwatknp commented Nov 14, 2022

siriwatknp left a comment

[core] Accessibility - increase default contrastThreshold for WCAG AA compliance #34901

[core] Accessibility - increase default contrastThreshold for WCAG AA compliance #34901

Conversation

kennethbigler commented Oct 26, 2022 • edited Loading

Below was for original PR and context, but this has all been reverted

TDLR - the default contrastThreshold needs to be increased.

Verify the problem

Fixing the problem

Why not fix everything?

Visual Updates

Before

After

mui-bot commented Oct 26, 2022 • edited Loading

kennethbigler commented Oct 27, 2022

kharrop commented Oct 27, 2022

mnajdova commented Nov 7, 2022

michaldudak commented Nov 7, 2022

kennethbigler commented Nov 8, 2022 • edited Loading

NateBaldwinDesign commented Nov 9, 2022

siriwatknp commented Nov 10, 2022

kennethbigler commented Nov 10, 2022 • edited Loading

kennethbigler commented Nov 10, 2022

mnajdova left a comment

Choose a reason for hiding this comment

michaldudak left a comment • edited Loading

Choose a reason for hiding this comment

michaldudak commented Nov 11, 2022

kennethbigler commented Nov 14, 2022

siriwatknp commented Nov 14, 2022

siriwatknp left a comment

Choose a reason for hiding this comment

kennethbigler commented Oct 26, 2022 •

edited

Loading

mui-bot commented Oct 26, 2022 •

edited

Loading

kennethbigler commented Nov 8, 2022 •

edited

Loading

kennethbigler commented Nov 10, 2022 •

edited

Loading

michaldudak left a comment •

edited

Loading