Fix color contrast issues

[manuhabitela]

Describe the problem to be solved

:wave:

The goal of this issue is to track all color contrasts issues according to WCAG, the international accessibility guidelines, so that everyone can correctly distinguish text, UI elements, etc.

Context is:

• the color contrast ratio between a text and its background color should be at least 4.5:1,
• for large texts (font size larger than 24px, or bold font weight and font size larger than 18.5px), the minimum ratio is not 4.5:1 but 3:1. I argue we should try to meet 4.5:1 all the time, as those 3:1 requirements are pretty specific. If we start to target them in some parts of the app, it's easy to reuse same logic later on smaller texts, forgetting the requirements
• one less known requirement is this: UI elements with colors required to understand the page have a 3:1 ratio with colors adjacent to them. For example, a form input having a white #fff background, itself on a webpage having a gray #ddd background, doesn't meet the requirement (1.35:1 ratio between the gray and white). This can lead to people not noticing the boundaries of the input, and in the end, not understand this thing is an interactive element. The same form input, with a 1px #555 border around it, meets the requirement (5.48:1 ratio between the border and the webpage background).

Sources:

• https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html
• https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html

There are lots of tools to test color contrast ratio issues:

• one example is https://www.siegemedia.com/contrast-ratio,
• https://contrast-grid.eightshapes.com is a great tool to test complete color palettes as a whole

Describe the solution you would like

Here are the issues I noticed for now:

• the green primary color of Grist can causes lots of color issues because of its low contrast with white background/text. This is the main issue. The better way to fix it would be to… basically change the brand color of Grist 😭. This is not such a crazy idea (Vinted did it a few years ago for example). We could also create a "high contrast" theme as an alternative (like a light/dark theme), but this is extra long-term work to keep in mind
• the gray used in the header (the document path)
• the gray used in the table/column sidebar in some places (in Table > Data > Data table > "Source Data" for example), or used in the light sidebar for icons (in the bottom)
• the white on gray filter buttons
• the gray used to distinguish columns, or checkboxes, that has too low contrast to make sure everybody can distinguish them. Here for example (screenshot below) checkboxes can easily be missed because the gray and white are too close, and the border differencing them is not contrasted enough

Screenshots:

• 
• 
• 
• 
• 
• 

Choosing more visible gray variants would fix lots of the issues as, besides the green Grist color, most color issues are tied to the white/gray combined usage.

Will add examples to this issue when I encounter more.

[manuhabitela]

To help better understand, here is a big picture view of potential contrast issues thanks a tool that allows to cross reference all colors of a complete color palette:

• main colors overview a curated view with the main colors I noticed,
• complete theme overview I just copied all theme colors defined in the css :root and went along. Not that useful with so much info but that gives a complete view :)

You can filter out the grid on the left side with the AAA, AA, AA18 and DNP buttons.

What do the buttons mean you ask?

• AAA means a contrast ratio of 7:1 between a text color and a background color. It means the colors have very big contrast between them. It matches the triple A level of WCAG guidelines. Note that this level is often not legally enforced in countries having legislation based on WCAG. For example, in France, we don't target this level. This level of ratio is often matched with specific high contrast themes, as it's hard to end up with a complete theme with every necessary color fitting the requirement. We can more or less ignore this level, at least for now.
• AA means a contrast ratio of 4.5:1 between a text color and a background color. It's the level we should target for texts+backgound duos. In France, we are legally obliged to follow this recommendation.
• AA18 means a contrast ratio of 3:1. On paper, it's an acceptable level for text+bg duos for big texts. In practice, I'd recommend against being ok with texts having this lower ratio, as in a design system, without being careful, it's easy to mix and match stuff, forget about the subtleties, and end up with small text with this ratio. But! This 3:1 ratio must be the minimum for UI element colors. The thing I mentioned when opening this issue (one less known requirement is this…)
• DNP means Do not pass. Meaning this color combination contrast ratio is too low for any use case.

:information_source: Note that for actually disabled elements on a page (like a disabled button that we can't click on), or for purely decorative things on a page, color contrast ratio requirements can be ignored. Basically the rule is: if I could remove the element from the page and still completely understand everything I need, we don't care about color issues.

---

This contrast grid tool is not the best one to quickly test new color combinations on the fly, so you can try lots of other ones online. This one for example.

Here is a really quick test with an OK-green (with white), just lowered luminance of the theme color enough to match 4.5:1 ratio.

@dsagal

[lusebille]

I've made some mocks applied those rules https://www.figma.com/design/wcpetFt6aOKzTszcvPPWLQ/%5B05%2F24%5D-Grist-Design?node-id=2202-97849&t=qyem49MNdu9SdpUT-1

[tayflo]

I agree with this issue, thanks for pointing it out! I also feel like better contrast would be more comfortable even for users without colorblindness or such.

I've made some mocks applied those rules: figma link

If I may share my personal opinion on those, I would say among the two I prefer the left one, more greeny and less bluish – it's quite personal, but to me it feels more "living" and less "cold".

PS: Thanks @manuhabitela for the contrast-grid.eightshapes.com tool! It's great, I did not know about it.

I was going to also mention the coolors.co tool but just saw you did it already :-) One advantage it has over the eightshapes tool is it has a built-in color selector which allows for quick tweaking, and one advantage over the siegemedia tool is it display both <AA, >AA and >AAA levels for both small and large text in a clear way (tho, it allows for comparison between only two colors (no grid), and is not open-source).

[dsagal]

That article mentioned in https://github.com/gristlabs/grist-core/issues/1244#issuecomment-2435505433 (this article) is interesting. In particular, according to this new APCA effort, the Grist "green" is very close to being accessible. With a small adjustment (from #16B378 to #16a16b) it passes their "60%, minimum for normal-sized text" threshold, both for white-on-green and for green-on-white: https://www.myndex.com/APCA/?BG=16a16b&TXT=ffffff&DEV=G4g&BUF=A22

[manuhabitela]

Yep! Beware though :)

• the Advanced Perceptual Contrast Algorithm is very interesting work but not yet adopted by WCAG. It certainly will be a while before WCAG 3 are released, and we are not even sure those will include the APCA. Most countries having web accessibility-related laws follow the calculations of WCAG 2.
• APCA relies on more than "are those two colors compatible". With this algorithm, a green background + white text is not the same as a white background + green text. And text size and font weights also matter more than with the WCAG 2 algorithm. So it's not as straightforward to design a complete design system color palette.

So it's a good tool but I don't think we should take it as "no need to target WCAG 2 requirements".

[dsagal]

Got it @manuhabitela. So looking through the mockups, I see as most visible difference to users the following changes:

• Green color changing #16B378 -> #208156
• Grey borders around inputs, widgets, panels changing #D9D9D9 -> #B1B1B1 (mostly) or #8C8C8C (around widgets), though only the latter satisfies the 3:1 contrast ratio

White-on-green would satisfy 4.5:1 ratio, but green foreground would satisfy it on white background and light-grey (#F7F7F7), but not on "salad green" (#DCF4EB) from some other proposed designs.

What do you think of this adjustment:

• Green color for white-on-green elements (like buttons): #16B378 -> #12875C (slightly closer to today's, just meeting 4.5:1 contrast)
• Green color as foreground: #16B378 -> #0F7B51 (slightly darker than proposed, meeting 4.5:1 contrast even on light grey and on salad green)

Separately, we should be considering a project of opt-in themes to support a high-contrast theme. Another nice-to-have opt-in theme would be "Grist classic" theme with today's colors. Having such an option would make it much easier to switch the default colors, since any users who miss today's colors could keep them. @manuhabitela , am I right that this would be entirely OK, as long as the default is accessible?

Related question to @manuhabitela : does the dark-mode theme need to be adjusted for a11y? It is the default when the OS/browser is set to a dark mode preference.

For any themes, I know @georgegevoian had some thoughts about drastically reducing the number of CSS variables that we have today, which should make multiple themes easier to maintain (e.g. as new components are added). @manuhabitela , let me know if you are interested in looking into that -- that sounds like more work upfront, but may save work later.

[manuhabitela]

What do you think of this adjustment:

• Green color for white-on-green elements (like buttons): #16B378 -> #12875C (slightly closer to today's, just meeting 4.5:1 contrast)
• Green color as foreground: #16B378 -> #0F7B51 (slightly darker than proposed, meeting 4.5:1 contrast even on light grey and on salad green)

Sounds great for me! @lusebille?

Note that the "salad green" ratio, for currently suggested mockups, does not need the 4.5:1 contrast ratio as its used for non-text UIs (icon buttons). So only 3:1 is needed for now. But it's a good idea on paper to target 4.5:1, this will allow us to use this combination for text UIs later.

Separately, we should be considering a project of opt-in themes to support a high-contrast theme. Another nice-to-have opt-in theme would be "Grist classic" theme with today's colors. Having such an option would make it much easier to switch the default colors, since any users who miss today's colors could keep them. @manuhabitela , am I right that this would be entirely OK, as long as the default is accessible?

It's entirely OK as long as one theme is accessible. If the default is not accessible, on paper, it's OK as long as we give the option to enable an accessible theme.

My main advice would be, make the default theme the most WCAG-compliant as we can. And for the few cases we conclude it's not ideal by default, because the UI shows a lot of stuff at once, and having sharp contrasts might make things harder, "heavier" to read here and there; we leave them as not WCAG-compliant on the default theme, but handle them correctly in a specific high contrast mode.

From my personal point of view I wouldn't make any exception and have the default theme follow all WCAG rules, but I can understand this can feel too much sometimes haha, especially in a UI like Grist.

Related question to @manuhabitela : does the dark-mode theme need to be adjusted for a11y? It is the default when the OS/browser is set to a dark mode preference.

It would be obviously better if adjustments were made to the dark mode so that it fixes all contrast issues too, but again, it doesnt need to be WCAG-compliant if we have one alternative theme that fixes all issues.

For any themes, I know @georgegevoian had some thoughts about drastically reducing the number of CSS variables that we have today, which should make multiple themes easier to maintain (e.g. as new components are added). @manuhabitela , let me know if you are interested in looking into that -- that sounds like more work upfront, but may save work later.

Yeah that seems like a good idea to tackle that first, I can check that up.

[lusebille]

Maybe my figma is clear only in my head (anyway github is so unclear for me 😅 ) :

• Grey borders around inputs, widgets, panels changing #D9D9D9 -> #B1B1B1 (mostly) or #8C8C8C (around widgets), though only the latter satisfies the 3:1 contrast ratio

**>>The rule is more :

• Widgets borders , checkbox, radio buttons, switch : #D9D9D9` -> #8C8C8C (matching the 3:1)
• Inputs, separators between zones : #D9D9D9` -> #B1B1B1 (not matching the 3:1 because it's used in very dense areas , it's for having more distinguished fields and zones but still digest, use the 8C8C8C only in High Contrast mode )**

White-on-green would satisfy 4.5:1 ratio, but green foreground would satisfy it on white background and light-grey (#F7F7F7), but not on "salad green" (#DCF4EB) from some other proposed designs.

What do you think of this adjustment:

• Green color for white-on-green elements (like buttons): #16B378 -> #12875C (slightly closer to today's, just meeting 4.5:1 contrast)
• Green color as foreground: #16B378 -> #0F7B51 (slightly darker than proposed, meeting 4.5:1 contrast even on light grey and on salad green)

>> Ok for me ( I've made those changed in the mocks) @manuhabitela with the Blue DSFR no need the have 2 colors , notice that I've added also a new 'dark- green' on figma file, and dark green will replace both dark and darker green , so #009058 and #007548 >> #196C47