Closed scmmmh closed 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:
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).Thank you @trallard for the clarifications.
:+1: 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:
conf.py
(with explicit mention of contrast / accessibility)--pst-color-primary-text
or similar)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. 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?
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
Two quick thoughts here:
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)
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)
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.
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.
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.
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. 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.
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
#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)
#6468db
secondary #32b7c0
and accent (in-line code for example) #a075e2
#6373b6
secondary #9f5bb0
accent #398557
#2c7cb0
secondary #9f5bb0
accent #6373b6
#2c7cb0
secondary #a26a09
accent #6373b6
(note this is not an orange but more of a golden colour)Notes on the colour palettes above:
Let me know your thoughts/ideas. As next steps would be
I will then adjust the theme colours and incorporate @drammock work
Appendix:
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.
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
- 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).
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.