search

pydata / pydata-sphinx-theme

A clean, three-column Sphinx theme with Bootstrap for the PyData community
https://pydata-sphinx-theme.readthedocs.io
BSD 3-Clause "New" or "Revised" License
609 stars 317 forks source link

Accessibility Colour Contrast Issues #1052

Closed scmmmh closed 1 year ago

scmmmh commented 1 year ago

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:

Dark theme:

trallard commented 1 year ago

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:

scmmmh commented 1 year ago

Thank you @trallard for the clarifications.

:+1: for just using a WCAG-compliant pygments theme.

drammock commented 1 year ago

+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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 https://github.com/Quansight-Labs/jupyter-a11y-mgmt/issues/26 and https://github.com/Quansight-Labs/jupyter-a11y-mgmt/issues/30)

trallard commented 1 year ago

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:

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

12rambau commented 1 year ago

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

drammock commented 1 year ago

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 commented 1 year ago

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

choldgraf commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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:

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 commented 1 year ago

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 commented 1 year ago

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:

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 commented 1 year ago

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

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:

drammock commented 1 year ago

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 commented 1 year ago

Per this comment and other discussions:

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 commented 1 year ago
  • 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 commented 1 year ago

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

choldgraf commented 1 year ago

A couple quick thoughts from me -