Remove coloring from in-line code blocks

[choldgraf]

We currently use a pink/red/purple-ish color for in-line literal code blocks. This is because we're using a combination of the Bootstrap default in-line text behavior along with a "greyed out background" that is more common in other projects that use in-line literals.

For example:

However, a more common way of denoting in-line literal text is to simply use a variation of the black font color + a greyed background. For example, this matches Docusaurus, Furo, GitBook, and GitHub.

For example, I find the docusaurus in-line literal pops out nicely without using color:

I suggest that we change our default in-line literal color to follow a pattern similar to these examples, and use a variation of black + a grey background (for the light theme). The color can still be customized by downstream users, but this feels like a less-opinionated and safer approach from an a11y perspective.

[drammock]

this feels like a less-opinionated and safer approach from an a11y perspective.

Can you unpack this for me a bit? There are 2 things I don't understand here:

1. Why is gray more accessible than pink? I would have thought that if the gray and the pink are chosen to have equal contrast ratio versus the background, then pink would actually be preferable (because for those with no colorblindness there is an additional redundant cue marking the contrast between normal text and code).
2. What does it mean for one color to be "more opinionated" than another? Is it simply more conformist / common to use gray here? I happen to hold the opinion that pink looks better than gray, others hold the opposite opinion; am I somehow more opinionated simply due to the content of my view on this issue?

[choldgraf]

Some quick responses below:

Why is gray more accessible than pink

I don't think it's inherently more accessible, but I think there's less degrees of freedom and uncertainty around grey hues, given that they only differ by a saturation dimension, not hue, and given that color perception is weird and not something that many people have an intuition for re: a11y unless they are trained in this.

What does it mean for one color to be "more opinionated" than another

The way I think about it: most of us do not have formal training in design or accessibility, nonetheless everybody has an opinion about design because it is very subjective. So how do you make design decisions without the shared training that gives you a framework for making decisions?

Ideally, you delegate these decisions to professional UI/UX and designers, or people that have formal training and experience in these issues. However we don't have the resources to do this, and to my knowledge none of our maintainers have this training. (Correct me if I'm wrong)

Given that, I think the next best thing is to follow the patterns of similar products that do have these resources and use them to help us make decisions. It's a combination of "trust the experts" mixed with "wisdom of the crowds". To me, an "opinionated" decision here is one that deviates from common UI practices for trusted products (and if we decide to do this, we should have a principled rationale for why it's worth being different).

This is why we have the "projects we get inspiration from" section - to help us make semi-arbitrary decisions about design. To me, the fact that GitHub, Docusaurus, and Tailwind behave this way suggests to me that their (considerably greater) design expertise is something to follow, rather than deviate from.

I am also curious what @trallard thinks here, as I get the impression that she has experience in accessibility and design!

[drammock]

I think there's less degrees of freedom and uncertainty around grey hues, given that they only differ by a saturation dimension, not hue, and given that color perception is weird and not something that many people have an intuition for re: a11y unless they are trained in this.

I don't follow the logic; it seems like this would imply that we should not use color for any meaningful UI/UX distinctions anywhere in our theme?

My view is that the guidelines say "make sure contrast ratio is at least X" and "if you use color to signal UI/UX difference, make sure there is another, redundant cue". There are tools to check the contrast ratio, and we have redundant cues in place (typeface and background). We don't need to rely on intuition to make the theme accessible.

to my knowledge none of our maintainers have this training. (Correct me if I'm wrong)

I have 4 years of industry experience in graphic arts/design, plus a few years moonlighting as a designer during grad school. I don't have formal training in accessible design --- I have been attempting to stay somewhat informed about it, though I'm far from an expert.

To me, the fact that GitHub, Docusaurus, and Tailwind behave this way suggests to me that their (considerably greater) design expertise is something to follow, rather than deviate from.

That's certainly a perspective to keep in mind. Two other things I'm trying to keep in mind here:

1. If we copy their decisions on everything our theme will become redundant.
2. Changes to colors might annoy users. Sure they can change it back in their css, but we're creating extra work for them in order to use the next release.

What if we checked each of the sites in our gallery and see if they override the inline code color? If most of them are using our default pink, I'd say we should leave it alone or at most tweak slightly

[choldgraf]

We don't need to rely on intuition to make the theme accessible.

If we have good practices for doing this objectively then I am not as worried about it. My concern is that historically we have just taken the bootstrap defaults and made tweaks as people thought it looked reasonable (that's why we have pink inline code w a grey background). As a result we've made decisions that seemed reasonable enough but we're inaccessible, thus the changes in #1086 .

I'd expect almost all of the users of this (or any) theme to just use the defaults. So if we want to base a decision on their perspective, I think it'd be better to do a set of interviews or lightweight questionnaires rather than look at whether they override them in the code.

I think using questionnaires or interviews would actually be great, but don't have time to conduct them myself. I don't have the graphic design experience to debate whether we should take one decision over another (thus my heuristic of just mimicking what other well-resourced themes do). If you feel strongly about this then I think we should just close this as unplanned unless there is a clear preference from others.

[drammock]

sorry @choldgraf I don't mean to bikeshed this issue to death; what I'm hoping to get out of this line of inquiry is a clear articulation of how we (should) make design decisions like this one, so that in future when someone says "inline code should be green" we can quickly close as wontfix and avoid long back-and-forths. I see that you're also thinking along these lines in https://github.com/pydata/pydata-sphinx-theme/issues/1079#issuecomment-1359035128.

So if I may summarise the discussion so far, here are proposed reasons why we might go with color X (in this case gray) over color Y (in this case our current pink, or a tweaked version of it from #1086):

1. I think it looks better. This is the reason that @choldgraf and others are calling "opinionated" and I agree it's not a good basis for decisions on its own.
2. Some other theme that I like uses it. To me this is no better than the previous reason, it's like saying "I like it and someone else likes it too."
3. Some other theme uses it, and they've probably thought about it more so let's follow their lead. This is a tempting line of reasoning, and it's come up previously and in that case it did not stand up to scrutiny. Of course it will be different case-by-case, but my feeling is we want to be careful about simply appealing to authority ("GitHub does it") and instead rely on evidence that the authority has actually done due diligence (as @choldgraf has done here).
4. it is more accessible. This IMO should be our primary concern. But as I've said above, this doesn't mean we should avoid using color at all simply because it's hard to intuit whether our chosen colors will work well for folks with color vision deficiency. If someone wants to do the work of using color vision deficiency simulators to come up with a color theme that will truly work for everyone, I'm open to that, but in the meantime I think our goal should be to make sure we don't rely only on color for UI/UX distinctions.
5. if we just copy what others are doing, we'll become redundant. Item 3 above covers this ground well enough: we should copy others when we're convinced that they've done their homework and made a good choice.
6. our users will be annoyed if we keep changing things. I'm not sure how much weight to give this, but I seem to give it much more weight than others do. My feeling is that if people tend to have strong feelings about color, and people tend to stick with the defaults, then aren't we bound to annoy them when we change the color defaults? IDK, maybe I should not think so much about theme stability given that we're still in 0.X version territory.

My hope is that after #1086 and #1079 we can just stop thinking about color for a long time. While those are going on seems like the right time to think hard about what reason(s) we are going to count as good reasons for going with one or another choice.

[trallard]

Hey peeps - I missed the notification before, so I am chiming in (this is a long read - I am trying to give plenty context on design decision making).

I am also curious what @trallard thinks here, as I get the impression that she has experience in accessibility and design!

You are right here (though I would not say I am a subject matter expert but I have a combination of self and formal learning + practical experience).

My 2c regarding colour (and its use in design) - while there are several methodologies and scientific basis to select and mix colours, plenty of artistry and subjective elements play a part in the design process (preferences and opinions being two of these), and these can't be entirely decoupled.

So how do we make sound design decisions even if we are not experts? Some methods I (and others) use to describe and make decisions are:

• Understanding and adopting industry-wide principles and patterns, for example, I centre a lot of my work around Inclusive design principles. Another example would be if looking at creating a CLI, I will ensure I follow common design patterns or conventions.
• Use data to support design decisions, whether from user testing, research-backed or evidence-based practices (I would love to do more user research but resources can be limited).
• Adopt standards: For accessibility, I would refer to the WCAG standards and their success criteria.
• Gut feelings and preferences

For example, the first part of this statement:

I think it looks better. This is the reason that @choldgraf and others are calling "opinionated" and I agree it's not a good basis for decisions on its own.

would have less weight in my decision-making process vs ensuring that the colours we are using are WCAG conformant to ensure what I am building is accessible to many and non-exclusionary. Of course, these guidelines have limitations (like not considering colourblindness nor considering cognitive or learning disabilities). Still, they help with my higher-level goal of building inclusive and accessible products/tools.

if we just copy what others are doing, we'll become redundant. Item 3 above covers this ground well enough: we should copy others when we're convinced that they've done their homework and made a good choice.

Agree, and it ties in with adhering to data or evidence-backed practices - and this does not necessarily mean we should do exactly what they are doing, but adopting the practices while still being able to make decisions on what would serve our community best (and why not, what we find aesthetic without this being the sole decision-making factor).

our users will be annoyed if we keep changing things

This is a potential scenario, but I also agree that the project is still pretty young, and we are still in a "discovery" phase on what works for our users and what needs to / could be improved.

My hope is that after https://github.com/pydata/pydata-sphinx-theme/pull/1086 and https://github.com/pydata/pydata-sphinx-theme/issues/1079 we can just stop thinking about color for a long time.

This is my hope, too, so I decided instead to take a step back and ensure we can lay the correct foundations. Looking at colour palettes, contrast ratios, and colour theory is overwhelming and a big task, but it is worth looking at this pretty early on to avoid having more colour discussions in the future and help with maintainability. It also allows us to ensure that all those users that use the defaults will have enough accessibility affordances without requiring specialist accessibility knowledge. And if they want to customise the theme based on brand guidelines or preference, they still can do that (which is a good design/implementation decision, i.e. let the user customise the tool).

Also, it helps us with this kind of scenario that @drammock mentions:

so that in future when someone says "inline code should be green" we can quickly close as wontfix and avoid long back-and-forths.

If it is a 'preference' (i.e. this particular shade of green is my favourite one) and we have established, for example, that accessibility is one of our priorities, we are better equipped to explain why we won't make a change.

While those are going (https://github.com/pydata/pydata-sphinx-theme/pull/1086 and https://github.com/pydata/pydata-sphinx-theme/issues/1079) on seems like the right time to think hard about what reason(s) we are going to count as good reasons for going with one or another choice.

I agree, and that is also why I am trying to provide as much context (and resources/references) as I go and provide evidence of where I am doing my due diligence. So y'all can make an informed decision.

⚪ Now, circling back to the discussion regarding removing colour from the inline code. From a WCAG conformance POV, we need to ensure enough contrast between the inline code colour and the background, plus not relying solely on colour (i.e. different typeface, surrounding box, different background colour).

From a readability and scannability point of view - I find it much more helpful when the text is also a different enough (contrast-wise) colour from the surrounding text (like for hyperlinks) or when the inline code background colour is visually distinct from the surrounding background. In the case of the examples added in the first comment. The inline code background has very little contrast:

• #FFFFFF vs #F5F5F5 1.1:1
• #FFFFFF vs #F6F7F8 1.1:1 so it does not meet the contrast requirement for non-text elements, which is 3:1, so the reader has to rely on other cues (hint: the border colour does not meet the contrast criteria either). So even if that pink shade does not meet the 4.5:1 criteria, I find it easier to read.

And this holds even if using a filter to simulate partial monochromacy.

So we need to 1) ensure we meet the WCAG criteria and 2) how we will meet these criteria - improve the existing pattern (coloured text + box) or remove the colour and make some improvements to the background contrast. Maybe looking at the proposals in Figma for #1079 can help?

I have not seen a rationale on why others decide to use grey for their inline code. It might be a way to reduce a complexity dimension (another colour contrast to check, colour blind complexity). So this might be a case were we have to factor in design preferences.

[choldgraf]

This sounds good to me - I looked in the issue and didn't see a Figma link, so assume that is coming in the future. I think that, unless @trallard wants to focus inline text conversation in this issue, we see how #1079 pans out and decide if the actions taken there should supercede or close this.

[trallard]

Sorry just added an edit to the other issue - lost control of my schedule so did not have as much focus time as anticipated 😔

[trallard]

Proposals added in #1079 in case we want to carry on the discussion here

[jorisvandenbossche]

As a reference, we indeed inherited this pink color from the first version of this theme that was based on the bootstrap docs (https://getbootstrap.com/docs/4.6/getting-started/introduction/). In the meantime, also Bootstrap revamped their docs theme, but it seems they kept the coloring of inline code, although with a slightly less bright color now (https://getbootstrap.com/docs/5.1/getting-started/introduction/)

A potential argument for using no color for inline code is that, in my experience, if you have a text with a lot of inline code, this can become "heavy" or distracting with all the coloring. See for example https://pandas.pydata.org/docs/whatsnew/v1.5.0.html#other-deprecations (which is even worse here because there is a lot of mixing of inline code and links, so two different colors, and then also some inline code has become bold (a third style) because that's a broken link (pandas' fault, not the theme). Of course, this is a quite extreme example, and one could also argue that you not write text that is that heavy with inline code and links ;) (I regularly try to argue in the pandas project to use less inline code for common words like DataFrame or Series)

[trallard]

From #1079 and discussions here it seems this issue can be closed