-
Notifications
You must be signed in to change notification settings - Fork 317
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.
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
Accessibility Colour Contrast Issues #1052
Comments
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:
|
Thank you @trallard for the clarifications. 👍 for just using a WCAG-compliant pygments theme. |
+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:
|
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. |
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. I am more than happy to help with moving this forward in either direction. Also can we label this with 'accessibility' too? |
I was asking myself: By doing so you ensure that the default is ready to use and neutral and we show in the doc a customization example |
Two quick thoughts here:
(I don't think 2 needs to preclude 1, or other iterative improvements though) |
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) |
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 |
I'm +1 for applying a neutral color system by default and overwriting it in our documentation to meet the pydata brand |
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 |
Hey folks - I am working on a couple of proposals for the theme, but I wanted to double-check:
|
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. |
We normally did extensive work to track down every color definition of the theme and normally they are all stored there.
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
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. |
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 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 |
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" |
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. |
Hey folks - I am working on the colour palettes for the theme, and so far, I am here:
Notes on the colour palettes above:
Let me know your thoughts/ideas.
Appendix:
|
Thanks for working on this!
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 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. |
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 |
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). |
Yup - or maybe have both themes shipped for folks to choose from |
A couple quick thoughts from me -
|
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:
<code>
element:<code>
element. Due to the font size and weight in these, the required contrast ratio is only 3.0..headerlink
permalinks when the user hovers over the heading.<code>
element.<code>
element.Dark theme:
.headerlink
permalinks when the user hovers over the heading.The text was updated successfully, but these errors were encountered: