Accessibility Colour Contrast Issues

[scmmmh]

I've done a bit of an assessment of colour contrast accessibility issues. The testing was done using a mix of tota11y and Firefox's accessibility audit.

For the majority of issues listed below the required contrast ratio is >4.5. Where different I have added that below. I have tested both the light theme and the dark theme, with the results separated here. As can be seen, the dark theme has significantly less issues:

Light theme:

• Text links
  • Primary colour on white (--pst-color-link/#ffffff) has a contrast ratio of 3.1.
  • Secondary colour on white (--pst-color-link-hover/#ffffff) has a contrast ratio of 2.41. This applies to the hover/focus state of all normal text links.
• Links in a <code> element:
  • Primary colour on gray (--pst-color-link/#f5f5f5) has a contrast ratio of 2.8. Due to the font size and weight in these, the required contrast ratio is only 3.0.
  • Secondary colour on gray (--pst-color-link-hoverf5f5f5) has a contrast ratio of 2.21. This applies to the hover/focus state of all links that include a <code> element. Due to the font size and weight in these, the required contrast ratio is only 3.0.
• Header permalinks:
  • Custom colour combination (#f8d3b3/#ffffff) has a contrast ratio of 1.41. This applies to all .headerlink permalinks when the user hovers over the heading.
• Code blocks:
  • Custom colour combination (#949494/#f5f5f5) has a contrast ratio of 2.8. Line numbers in code blocks. Due to the font the required contrast ratio is 3.0.
  • Custom colour combination (#99997f/#ffffcc) has a contrast ratio of 2.85. Line numbers in code blocks where the line has been highlighted. Due to the font the required contrast ratio is 3.0.
• Inline code:
  • Inline code colour on white (--pst-color-inline-code/#ffffff) has a contrast ratio of 3.82. This applies to inline code that is not inside a <code> element.
  • Inline code colour on gray (--pst-color-inline-code/#f5f5f5) has a contrast ratio of 3.5. This applies to inline code that is inside a <code> element.
• Admonition icons. The admonition titles are fine, this just applies to the illustrative icons. One limitation here is that due to the positioning the background colour calculation is not correct, so the contrast ratios are likely to actually be lower.
  • Information (--pst-color-info) has a contrast ratio of 3.10.
  • Warning (--pst-color-warning) has a contrast ratio of 2.41.
  • Success (--pst-color-success) has a contrast ratio of 3.13.

Dark theme:

• Header permalinks:
  • Custom colour combination (#f8d3b3/#ffffff) has a contrast ratio of 2.21. This applies to all .headerlink permalinks when the user hovers over the heading.
• Admonition icons:
  • Error (--pst-color-danger) has a contrast ratio of 3.6.
  • Success (--pst-color-success) has a contrast ratio of 3.87.

[trallard]

Hey @scmmmh, thanks for opening this issue and working on making the theme more accessible.

To support those folks in the project that might be less familiar with the contrast requirement; the 4.5 ratio mentioned above comes from the WCAG AA criteria for colour contrast.

Now onto the fixes or path forward:

• code blocks: the colours come from the Sphinx pygments theme; a workaround to ensure the whole theme meets the criteria instead of manually fiddling with the colours would be to use WCAG-compliant themes like accessible pygments. Such an approach should fix all the issues encountered (and maybe some others missed as part of your audit for code elements).
• for the rest of the colours in the theme, it would be worth looking at the whole colour system as a whole to ensure maintainability and WCAG compliance throughout.

[scmmmh]

Thank you @trallard for the clarifications.

👍 for just using a WCAG-compliant pygments theme.

[drammock]

+1 for accessible-pygments (great work on that @trallard, I didn't know about it!)

It's on my list to look at the rest of the theme colors too. As @choldgraf mentioned in this comment we're a bit constrained by the fact that the primary and secondary colors of the theme are coming from pydata branding, and neither one of them is very good in terms of contrast against white. But I'll take a closer look; a few options that spring to mind are:

1. live with it, and in our docs encourage users to override primary and secondary colors in their conf.py (with explicit mention of contrast / accessibility)
2. tweak the primary and secondary colors to harmonize with pydata brand colors but have acceptable contrast ratios
3. abandon use of the pydata brand colors for text elements but still use them for structural elements of the page (i.e., define new vars --pst-color-primary-text or similar)

[scmmmh]

From my perspective, the preferred order of that is 2-3-1. Obviously 2 is the ideal case, but the contrasts are pretty low, so tweaking them to achieve both contrast and harmonisation with the brand colours may be tricky. It all depends on how much divergence from the brand colours is ok before we end up in 3.

The difficulty I see with option 1 is that a) I think it is unlikely that mane users will actually do this and b) where the pydata project uses the theme directly, the accessibility issue remains.

[trallard]

My thoughts: I would prefer 2 or 3.

When thinking about design and accessibility I prefer the approach of adopting good defaults while allowing for customisation. In this case the good defaults would be colours that meet the contrast requirements rather than expect that our users will take on the task of making their docs accessible (mentioned above).

Re the PyData brand - something we should consider: such brand was more than likely not developed for use-as-is on web media but more for printing (thinking stickers, flyers, and the such). Thus adhering strictly to it does not translate to accessible web design.
A good approach would be to use the PyData brand as a starting point to generate a web suitable and accessible colour theme - though we will more definitely end with different colours (thinking in terms of hues, saturation, luminance), and I am ok with this in the favour of increased accessibility and usability.

I am more than happy to help with moving this forward in either direction.

Also can we label this with 'accessibility' too?

[12rambau]

I was asking myself:
Forcing users to work with the pydata brand by default is very opinionated. Could we instead use a more default color set (that respects all the a11y features) and overwrite these colors in our doc ?

By doing so you ensure that the default is ready to use and neutral and we show in the doc a customization example

[choldgraf]

Two quick thoughts here:

1. I have no problem tweaking the default colors to be different from the pydata theme
2. We should define a sustainable, and ideally automated, but maybe semi-automated way to define our "bar" for accessible. Right now that is just "as long as lighthouse passes in our CI/CD", but if we're going to use other services like tota11y we need to find a way to make this as low-maintenance as possible or it won't stay updated.

(I don't think 2 needs to preclude 1, or other iterative improvements though)

[trallard]

Agree with @choldgraf - and we can work on 2 and 1 simultaneously or one after the other.

In the spirit of transparency - through one of our newest awarded grants and the existing Jupyter + friends accessibility grant, we (some folks at Quansight Labs) have some work/deliverables planned aimed not only at accessibility improvements but also helping with long-term maintenance and best practices. So we are definitely thinking about the maintenance burden, but thanks for raising this 🙏🏽 (also, I have some issues to open here and there, and this is sitting on my to-do list because I am juggling with too many spinning plates atm)

(some examples at Quansight-Labs/jupyter-a11y-mgmt#26 and Quansight-Labs/jupyter-a11y-mgmt#30)

[trallard]

To resurface this - I would be more than happy to look at the colour system in the theme and propose a more accessible and maintainable colour system moving forward.

Still TBD:

• Do we want to stick to the PyData brand colours? - note that as per my other comments, the resulting theme might be "loosely" inspired by this as there would be changes needed to meet the WCAG requirements
• Do we want to rethink the colour system and generate a more neutral theme that meets WCAG out of the box?

FYI: I am taking time off for a week starting tomorrow so will be offline during that time

[12rambau]

I'm +1 for applying a neutral color system by default and overwriting it in our documentation to meet the pydata brand

[drammock]

I made some initial progress (not pushed) on this but then got sick with COVID. @trallard if I haven't got back to it by the time you're off holiday perhaps you could take over

[trallard]

Hey folks - I am working on a couple of proposals for the theme, but I wanted to double-check:

• Currently, all the theme-specific colours are defined in https://github.com/pydata/pydata-sphinx-theme/blob/f217d821bc7e1181e2acc8f76b0bcf545dc6e3b0/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
• Are there any other colours not defined there that are somehow inherited from another upstream dependency?
• Are there any colours you'd particularly like to avoid for the proposed themes?

[choldgraf]

Those are the ones that I know of but @12rambau is the one with the most knowledge there since he refactored the color / light / dark theme stuff most recently.

[12rambau]

Currently, all the theme-specific colours are defined in https://github.com/pydata/pydata-sphinx-theme/blob/f217d821bc7e1181e2acc8f76b0bcf545dc6e3b0/src/pydata_sphinx_theme/assets/styles/variables/_color.scss

We normally did extensive work to track down every color definition of the theme and normally they are all stored there.

Are there any other colors not defined there that are somehow inherited from another upstream dependency?

Not in our example documentation but when people use some extra sphinx extensions that are not covered by the theme, surprises may arise. the list of covered extention is more or less what you will find in https://github.com/pydata/pydata-sphinx-theme/tree/main/src/pydata_sphinx_theme/assets/styles/extensions

Are there any colours you'd particularly like to avoid for the proposed themes?

In the good old days, links were pink which seemed to be a no-go for the community. Apart from that I have 0 a priori on colors.

[drammock]

we also inherit everything in https://github.com/executablebooks/sphinx-design/blob/main/style/_colors.scss but AFAIK we don't use any of them. My only color prior is that I like the idea of keeping the pydata brand colors available for structural elements, and defining --pst-color-primary-text and --pst-color-secondary-text that are lightened/darkened/otherwise-adjusted versions of those colors to make the headings/links WCAG compliant. But if that introduces big challenges I won't complain.

I've pushed the WIP stuff that I did a couple weeks ago to a branch, so you can cherry-pick stuff as desired. it's just the top 2 commits here: https://github.com/drammock/pydata-sphinx-theme/commits/wip-a11y-colors

FWIW: I found these two sites helpful:

• https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Colors/Color_picker_tool
• https://color.adobe.com/create/color-contrast-analyzer

and I also found that both plugin and built-in browser a11y tools weren't quite up to handling our admonitions, because of how we set opacity on them in either a ::before or ::after selector. In other words, it may be necessary to somewhat manually compute what the admonition background color actually is (i.e., what is the result of: 10% opacity of the dark version of our "warning" color with our dark bkgd beneath it), in order to assess text contrast on admonitions.

[choldgraf]

As a part of this could we document this project's policies around how to define "accessible" and the guidelines we follow for making decisions like these? I'd also love to see a little "helpful resources" section that includes links like the ones that @drammock shared above. Though importantly, we should distinguish between "this is a helpful resource" and "we treat this resource as a source of truth"

[trallard]

Adding more details here, but this might need to be part of a larger conversation regarding accessibility.

The source of truth for technical accessibility compliance should be the WCAG standards - so for colour contrast, we would refer to the corresponding standard and meet the relevant criteria.

Ideally - the theme would have an accessibility statement detailing how this meets or not the WCAG criteria; some examples:

• gov.uk template statement
• gov.uk accessibility statement
• JLab accessibility statement

Complemented with user and dev accessibility docs - including a list of useful resources and testing techniques.

Larger picture - and maybe better at the community level.

All the above covers technical compliance, but a site or a document can be technically compliant and still not accessible. Hence, we also need to look at how content is created and displayed.
The gov.uk site has guidance on how to publish accessible documents, but we have also been experimenting with adding content accessibility checklists in Pull Requests templates and accessibility guidelines in projects' style guides. Admittedly this is a much larger lift, but working on guidelines like these (and other access-centred practices) are deliverable items for the CZI common infrastructure grant.

[trallard]

Hey folks - I am working on the colour palettes for the theme, and so far, I am here:

• Tweaked the existing colours to #e06d10 and #35a0b1-> using these as a base for a colour palette works well for WCAG-compliant colour combinations

  • Question: it was mentioned that the pink was not very well received (right now the theme uses #e83e8c); how would you feel about replacing this with a green such as #46a46c or indigo such as #6373b6?

• For a more neutral default, I have the following proposals (again based on colours that would lead to WCAG-compliant combinations)

  • Option 1: primary #6468db secondary #32b7c0 and accent (in-line code for example) #a075e2
  • Option 2: primary #6373b6 secondary #9f5bb0 accent #398557
  • Option 3: primary #2c7cb0 secondary #9f5bb0 accent #6373b6
  • Option 4: primary #2c7cb0 secondary #a26a09 accent #6373b6 (note this is not an orange but more of a golden colour)

Notes on the colour palettes above:

1. Each colour palette is within the same range of perceived brightness -> right now, the colours (blue and orange are not perceptually uniform colours)
2. Depending on the colour palette chosen, I might need to tweak the other semantic colours (alert, info, and so on) to match
3. I intentionally avoided using orange, red or yellow as dominant colours, as these colours can be quite overwhelming/stimulant for neurodiverse readers
4. Options 2-4 are also more muted palettes as this help avoid over-stimulation, yet Option 1 is not too saturated

Let me know your thoughts/ideas.
As next steps would be

1. Select the colour palettes
2. I will then adjust the theme colours and incorporate @drammock work

Appendix:

• for those interested in perceptually uniform colours, this source from observable is pretty good
• a great resource for creating systematic colours

[drammock]

Thanks for working on this!

• it was mentioned that the pink was not very well received (right now the theme uses #e83e8c); how would you feel about replacing this with a green such as #46a46c or indigo such as #6373b6?

I think pink was poorly received as a link color. Nowadays we have inline preformatted text as pink, and I haven't heard any complaints about it. My personal taste is that the current pink or your suggested indigo #6373b6 are both better than green #46a46c specifically for inline preformatted text.

I'm not following exactly what the proposal(s) are though. Specifically, you say you tweaked the orange and teal "pydata brand" colors, but then options 1-4 don't include them. So are the pydata brand colors included? What element(s) will they be used for? (the link to experia.co.uk only mentions red and yellow as problematic colors for people with autism, not orange. Is orange problematic too, and that's why it's not included?)

Of the 4 options, I think I like number 4 best.

[trallard]

Per this comment and other discussions:

• The PyData colours are pretty opinionated so
  • We could have a default - less opinionated theme (proposals 1-4)
  • For the PyData-theme itself, we could stick to the PyData colours

I am not sure how easy or hard it would be to ship two themes by default - one based on the PyData colours and a more neutral one (though each would need light and dark variants, so technically, these are four)

Let me know if this did not help clarifying things

[drammock]

• We could have a default - less opinionated theme (proposals 1-4)
• For the PyData-theme itself, we could stick to the PyData colours

ah, right, I forgot about that aspect of the plan. Thanks for the reminder. So we'll have something like your option 4 built into the theme, and override it just for our docs site with pydata brand colors (or suitably tweaked approximations of them).

[trallard]

Yup - or maybe have both themes shipped for folks to choose from

[choldgraf]

A couple quick thoughts from me -

• the pydata brand color changes look good to me. Maybe we should adjust the pink to be complementary to the two colors you proposed, but I don't think it needs to be changed to a non pink color. I think the fewer things we drastically change the better, as in my experience big design changes tend to confuse users.
• for the 4 proposals / changing the defaults, it's hard for me to have an opinion without seeing what those changes look like on example pages (eg in our documentation). Perhaps we can split this into two different steps - one on changing the pydata brand colors quickly and another to decide on a different default out of the box? I suspect that this second topic will be a more complex discussion because it would be a big change for users. I'd suggest opening a separate issue for the defaults, because this one is already getting quite long