Colour improvements to themes - create a scalable and accessible design system

[trallard]

Originally discussed in gh-1052

Summary

It was discussed in gh-1052 and gh-1043 that the current theme is constrained by the PyData brand colours, which makes these themes considerably opinionated.

A proposed enhancement is creating a more neutral (less opinionated) default theme (light and dark) for the PyData Sphinx theme.

Follow-up

Update: After working on #1086 I discovered the following issues and challenges:

• Buttons: current colour + text combinations are not accessible (in the default state, I did not check for hover or focus states, but I assume they will have similar problems)
• Yellow and orange: The colour palette currently has yellow and orange for admonitions (recently discussed in #1043: these two colours are incredibly problematic for accessible (WCAG conformant) design systems:
  • Yellow is, by default, a challenging colour to work with to ensure this meets WCAG contrast criteria.
  • A workaround is to shift the yellow hue towards green (making it more like an ochre colour) or towards red (making it quite close to orange - which we use as brand colour and for other context situations like warning buttons and admonition). Such an example can be found in the Stripe writeup about making an accessible design system . I have added an image from the said write-up in which the yellow and orange are almost identical. While these two meet contrast requirements, they would be incredibly hard for colourblind and low-vision folks to distinguish from each other.
  • Since orange conveys the warning meaning, I wonder if keeping this as one of our default brand colours is the best option. I am worried that this might add some cognitive load for folks by using this for links and other structural elements and strong meaning in context. This aligns with the discussion in #1052 about adopting more neutral defaults.
• Elevation: I am unsure how the elevation (shadows) + background colours (background, surface, on-surface colours) were chosen, but I have found that the shades (or changes in shades) are inconsistent across dark and light themes.
• Contrast: while working on #1086 @choldgraf mentioned that he was finding it harder to parse the links. This is a limitation of the WCAG colour criteria since it only looks at colour contrast and not at perceived contrast/colour (colour and eyes are an exciting thing, and I could talk about this for days). For example, in the image below: the combination on the left meets WCAG contrast criteria, but many folks would find that the one on the right has a "better-perceived contrast" even when this combination would not satisfy WCAG contrast criteria.

Moving forward

Suggestions to work towards an accessible and consistent design system

• I would argue it is best to look at the design system now. I fear that if I only tweak the colours in #1086 then I will look into buttons, then elevation, and so on, and every time will require small tweaks to multiple colours to meet WCAG conformance because the design system is not coherent.
• I'd suggest ditching yellow for context/meaning and keeping orange only. This will help with the design system. For example, Docusaurus does not have a yellow and orange state. GitLab does not use yellow/orange, and I know Stripe has guidelines on not using yellow/orange for context as per the above-mentioned issues (edit: most of the examples discussed in #1043 have only yellow or orange) If interested, this blog talks in detail about the issue with dark yellow in UX.
• I started working on a design system over the weekend. This aims to provide consistent colours and colour use guidelines throughout. Some considerations:
  • I looked at colours suitable for light and dark themes and would meet WCAG contrast criteria.
  • I also used a Perceptually uniform colour system approach to help ensure that colours would be consistent.
  • I really struggled to keep yellow and orange and would not find a pair that would be within the same lightness range and that would be at the same visually distinctive.

First iterations for colour systems

1. Extended palette - mostly to show a large number of colours - (this includes the yellow-orange pair I added two oranges to try and have options, but no matter how many tweaks I did, I could not find a distinct combination that would result in a perceptually uniform system without modifying the yellow hue too much):

This system keeps the pink colour, as we currently use this for inline code.

2. I also experimented by adding two more colours: purple and magenta. Which could be used to replace the orange currently used as secondary in the theme.

• Based on this design system, I created this matrix for proposed foreground and background colours.

3. Muted extended colour palette - still keeping the orange and yellow (now all the colours are within the same lightness ranges and less saturated throughout so the yellow is definitely more of an ochre/mustard colour). This has the periwinkle, lilac/purple, a violet, and pink colour. As well as two sliglightly different neutral colour scales (greys, we only need to choose one).

Having a colour system like this helps to build scalable and coherent light and dark themes and this is basically the standard across the industry (see Atlassian, GitHub primer, GitLab, Stripe)

Need to do

• Decision: do we move forward with looking at the design system at a whole now? (I would strongly advise to do this otherwise we will be having these discussions every time we need to tweak/improve a specific component to meet accessibility requirements, for example)
• Decision: shall we keep orange and yellow as semantic colours? or get rid of one (I already added my suggestion above but I will defer to the rest of the team)
• Decision: do we want to move in the direction of a vibrant palette (2 which is an improved version of 1) or a more muted one (such as option 3).
• Colours in context: I will work on a tiny design system in Figma show how these colours would look along with the typography and in button/badges. With this we can make a decision on colours to keep: for primary,secondary, and accent (light blue, purple, magenta, pink).

[choldgraf]

A few responses below:

Decision: do we move forward with looking at the design system at a whole now? (I would strongly advise to do this otherwise we will be having these discussions every time we need to tweak/improve a specific component to meet accessibility requirements, for example)

It isn't clear to me what exactly is entailed in "look at the design system as a whole". If this just means "making a collection of suggested adjustments all at once, instead of proposal by proposal", then that sounds good to me (but if you want to significantly alter the structural layout or major UX those should be standalone proposals).

If that is the case, I suggest we follow these decision-making guidelines around the process in order to avoid a never-ending discussion spiral about minor design decisions:

• Follow a consent-based decision making process around this. Whatever is proposed, after one or two iterations, maintainers only raise an objection if we think that a change poses a major strategic risk to the project. If not, then we trust the proposal to be sound and do not debate small points about design preference. We decide "yes" on the proposed changes as long as there are no objections.

Note: If there are still objections at the end of this process that are unresolveable, then we need a way to decide on a path forward nonetheless. We have no formal governance for this right now.

Decision: shall we keep orange and yellow as semantic colours? or get rid of one (I already added my suggestion above but I will defer to the rest of the team)

I'm fine getting rid of one. I guess the question would then be do we stop distinguishing the color between caution, warning, etc? (whichever two semantic directives we were using this color to distinguish between)

Decision: do we want to move in the direction of a vibrant palette (2 which is an improved version of 1) or a more muted one (such as option 3).

It is really hard for me to have opinions about this without seeing what they look like in the docs. All of the palettes are visually appealing to me. If you had to push me I'd say number 3 (more muted), but I do not have strong feelings (maybe that'd be different but it's very abstract to just look at a grid of colors 🤷 ).

Colours in context: I will work on a tiny design system in Figma show how these colours would look along with the typography and in button/badges. With this we can make a decision on colours to keep: for primary,secondary, and accent (light blue, purple, magenta, pink).

This would certainly help (me, at least)

[trallard]

Right now I am proposing a review and maybe changes to the colours used in the themes, but from a holistic point of view. That is looking at the semantic, background, brand, and foreground colours to ensure we have a palette designed with accessibility and coherence in mind. Instead of making small adjustments for text, then potentially look at more colour adjustments to fix the buttons/badges contrast issues, and so on, which most of the time results in having too many slightly different colours scattered around and usually it's harder to do accessibility remediation work.

I think that is enough an improvement/change - and from a user experience perspective it's always best to make iterative, self contained changes. UX or structural changes (if any) should be done separately and in a way that are minimally disruptive to the user experience and workflow.

It is really hard for me to have opinions about this without seeing what they look like in the docs

Agree, seeing colours in context is 💯 more helpful. But I needed to start somewhere to ensure we had enough shades for each colour.

There is no need to make a decision right now as this is just a first proposal but I wanted to get a feel in case anyone felt strongly about muted palettes or more vibrant ones. I started working on a Figma file yesterday so should have this done today and can share this with y'all for discussion.

Edit: ended being dragged into some unexpected tasks so will get this throughout the week 🤦‍♀️

Design work in the open can be slightly tricky as it's still very visual heavy (and design tools do not play nicely with GitHub) so I am trying to share as much context and intermediate steps so that these discussions also serve as a record and documentation on how this process happened and how decisions are made. So please let me know if there is a way I can make this work easier for y'all or if there is too much noise.

[drammock]

This is great progress, thanks @trallard!

Given the various complexities mentioned by @trallard I think it's probably expedient for us to drop the color distinction between attention/important and caution/warning/versionchanged admonitions (much as I'd like to keep them distinct). That would simplify our current system to 7 colors, plus some whites/grays/blacks for backgrounds, shadows, todo-admonitions, etc:

1. primary (teal)
2. secondary (orange)
3. inline code (pink)
4. generic admonition, note (blue)
5. hint, tip, seealso, versionadded (green)
6. attention, important, caution, warning, versionchanged (yellow)
7. danger, error, deprecated (red)

Of course these groupings are not set in stone; if we really needed to we could consider e.g. re-using one of the admonition semantic colors for inline code. But let's not go there unless we really get stuck.

As far as the hues that we want/need: I suggest that we keep:

• reddish -> danger, error, deprecated
• greenish -> hint, tip, seealso, versionadded
• yellow or orangeish -> attention, important, caution, warning, versionchanged

The other four hues are more malleable IMO --- primary and secondary could be anything as long as they complement each other, and inline code and generic admonition/note could likewise be anything in principle. That said, if we can keep the code pinkish and the notes bluish to avoid too shocking of a change, I think we should do that. Consequently, that would mean primary/secondary are "whatever 2 colors are left" after assigning the others as above.

Relating that reasoning back to your 3 color system ideas, here is what I see:

• system 1 assuming we keep only one of the orange columns, we would end up with primary/secondary colors of teal and orange (or teal and yellow if we use orange for the attention/warning/etc admonitions). This is pretty similar to the pydata brand system, which I thought this pallete was supposed to move us away from? So maybe option 1 is not the best direction.
• system 2 here if we assign red/green/orangey-brown to the admonitions as above, and pink for inline code, that leaves us 4 hues all in the blue-to-purple range, of which we need 3 to serve as primary, secondary, and generic-admonition colors. My hunch is that those colors are too close together in hue to work well as primary/secondary?
• system 3 here if we assing red/mustard/green to the admonitions and pink to the inline code, that leaves orange, turquoise, blue, periwinkle, lilac/purple, and violet (6 colors) from which we need only 3 (primary, secondary, and generic-admonition). This makes me wonder if primary should be more straight-ahead blue, and the generic-admonitions should be the more turquoise/teal-like color?

I think for a next step I would suggest making a system palette that has only 7 hue columns (plus a column of neutrals), so we can get closer to a clear picture of "this would be primary, this would be danger" etc. To summarize the above, I think those 7 hues should be red, orange-or-yellow, green, pink, and 3 others.

[12rambau]

sorry for not participating in this debates even though I'm a big fan of what you did so far @trallard but I lost control of my time in November and completely dropped FOSS for a while. let me just drop few comments that may be useful:

I agree with the latest comment of @drammock on keeping color-ish whenever possible. We modified a lot of the colors recently and some documentation and users depending on default don't keep up (see the panda doc, it's now a mix of teal and dark purple)

Elevation: I am unsure how the elevation (shadows) + background colours (background, surface, on-surface colours) were chosen, but I have found that the shades (or changes in shades) are inconsistent across dark and light themes.

@trallard I made the coloring for the dark theme in https://github.com/pydata/pydata-sphinx-theme/pull/540. The elevation/background color is inconsistent between the 2 themes by design. I followed guidelines from css-trick website which is highly suggesting NOT to use shadows to convey depth in a dark theme. The only solution is to have shadows in the light theme and different levels of lightness in the dark one as backgrounds.

[trallard]

Hey folks - now that I am back from some time off, I can share this with you. I have put together three proposals based on discussions we have had:

1. Option 1 - this is a muted palette with teal as the primary colour
2. Option 2 - this uses the same colour palette as the previous option, but the overall colours are much more vibrant, and I rebalanced the grayscale
3. Option 3 - this one is the most different one - with the Primary and Secondary being blue and violet. I left the accent as pink/magenta, but it could easily be swapped to a coral or teal and would look good.

I added plenty of notes to add more context and clarify some decisions. Some things to notice:

• There is an Example - Kitchen sink page where you can see the components together and get an idea of how the colours and font scale work together.
• I added some improvements to buttons, links, and navbar items (not only colour) to help with meeting the WCAG Focus visible success criteria. While this is not the main focus of the proposal, I added this as I was already going over many components and colours. So any changes like this should ideally (or I can ideally) add them in a separate PR to the colour one to keep changes and reviews focused.
• Since I am sharing the Figma files, I marked these as view only, so if you have any questions/comments, do let me know.
• I followed @drammock criteria for the admonitions and removed the yellow colour from the palette. So now green, red, orange are reserved semantic colours.
• I built on @12rambau work and slightly improved the shadows and elevations.

EDIT: thanks to @choldgraf for reminding me that not everyone is a Figma user so there are multiple pages: the Example - Kitchen sink has variants of the components in context and the other pages have all the variants of the components plus more notes on when one would be used over the other and additional observations

To discuss:

• Is there a clear direction in which to go/no go?
• Are there any questions you'd like me to answer?

[12rambau]

thank you very much for your proposals. I'm personally a big fan of the 3rd option. It's less opinionated than teal and will work better (in my opinion) as default colors. Also, we could illustrate the color customization in the demonstration documentation to align it on pydata theme.

I have 1 question and 1 comment though:

• I assume we will drop all the transparency tricks that we created to use real colors instead?
• regarding the target color I will strongly advocate against using violet. to give you an example of use case, it's used to underline the target word when using a search: https://pygadm.readthedocs.io/en/latest/usage.html#find-names and more importantly it's used to underline code sources when using the source code extension and violet is widely used for code itself: https://pygadm.readthedocs.io/en/latest/_modules/pygadm.html#get_items. TBH yellow is one of the few colors that is never used in code highlights in light mode.

[trallard]

Thanks for the comments @12rambau

Also, we could illustrate the color customization in the demonstration documentation to align it on pydata theme.

This is a great idea and I am sure folks will find this very useful

I assume we will drop all the transparency tricks that we created to use real colors instead?

yes, working with transparencies is convenient from a dev point of view, but it can be quite challenging when looking at WCAG conformance (accessibility), so I'd like to use "true colours" as much as possible

regarding the target color I will strongly advocate against using violet

I had not thought about this. You are absolutely right here; we can keep the yellow then (it will not be used anywhere else) and might just do a small tweak to align with the other colours in the theme

[choldgraf]

Quick thoughts

I think that number 3 looks quite nice as well. I left a few comments in there.

How to use Figma

I didn't realize that there were multiple pages, or that we could leave comments in figma at first. In case anybody else is relatively new to Figma like me, here is a GIF of me clicking through a few pages and leaving a comment so you know how it works in the UI:

[12rambau]

yes, working with transparencies is convenient from a dev point of view, but it can be quite challenging when looking at WCAG conformance (accessibility), so I'd like to use "true colours" as much as possible

Ok then I have a technical question: In the current implementation of dark and light themes, we have 2 color sets defined in _color.scss. It is super convenient as in the other files we are always calling the same colors (e.g. --pst-color-primary). In the color palette presented here you have 1 color palette and you change the shade from one theme to another (e.g. --pst-color-primary-100 to --pst-color-primary-600). Is there a way to remain compatible with the previous paradigm (1 file to control color for all) ?

[trallard]

Definitely! There will be some work needed to use the correct variables but we should still be able to have all the colours defined in a single file.

[drammock]

I'm conflicted between option 2 and option 3. Is it a crazy idea to use the teal color from option 2 as the "dark" primary, and the more bluish color from option 3 as the "light" primary? IMO the teal looks good in dark mode but not light, and the converse is true of the option 3 primary color. If that idea doesn't fly, here are the other considerations in my mind:

Possible point in favor of option 2:

• the primary color is more distinct from all the other colors. In option 3, primary is fairly close to info and is even somewhat close to secondary. As I mentioned in a figma comment, the similarity of primary/secondary is a trade-off: it makes links (primary) on announcement banners (secondary) look harmonious, but it also means that links everywhere don't change as obviously on hover.

Possible point in favor of option 3:

• the primary color won't actually get used much. There seems to be consensus to not use it for headings, so that means it mostly shows up in links. IMO option 3's primary color looks slightly better on links (e.g., the link in the "danger" box is where it stands out most to me).

[trallard]

Is it a crazy idea to use the teal color from option 2 as the "dark" primary, and the more bluish color from option 3 as the "light" primary?

Not crazy - but it would cause more issues with maintainability and consistency (more colours to keep track of). I can see folks scratching their heads about why the light and dark themes differ. And such a pattern could also be incredibly confusing or overwhelming for folks with cognitive and learning disabilities. There is a very early draft of recommendations from the newly created Cognitive disability WCAG taskforce, and consistency, usability, and reducing cognitive stress are fundamental principles towards making content accessible for these readers/users.

Agree that the Option 3 feels the most harmonious as the colours are adjacent in the colour wheel.

Intermediate agreements/decisions made so far:

• inline code: keep the border and the accent colour
• admonitions: keep the TODO (need to agree on colour) and preserve the existing left margin on desktop
• buttons: give them a consistent min-width
• links and buttons: it seems like folks like the proposed default, hover, and focus states
• So far Option 3 seems like the most popular (nobody made any comments about option 1, so we can consider this disregarded)

To discuss & agree:

• headings: will our default be the Primary or a monochrome colour?
• links: @choldgraf suggested looking at links (default state) with the underline in the same colour as the text. I added this to the Figma file, so we need to decide on link styling.
• lastly: I created another option (basically, Option 3 shifted along the wheel), so we need to decide between these
  • Option 3: so far the favourite made by blue, violet, and, pink
  • Option 4: made by blue, teal, and violet

Both proposals are suitable for red-green and yellow-blue colour blindness and partial monochromacy (actually, the themes with the filter for the latter look pretty good). There are some issues with full monochromacy, but we are adding other cues to not rely entirely on colour.

Again, feel free to add comments to the files or ask questions.

[drammock]

headings: will our default be the Primary or a monochrome colour?

+1 for monochrome. Users can override if they want to.

links (default state) with the underline in the same colour as the text.

-1 on this from me. I agree with @trallard that it looks very strange on the dark background, and even on the light background I'm not enamored. Although maybe I misunderstood, I thought @choldgraf was suggesting that the underline be a medium gray (not the same value as the text)? As a way of making the underline less prominent?

I created another option (basically, Option 3 shifted along the wheel), so we need to decide between these

I like option 3 better than option 4

[choldgraf]

links (default state) with the underline in the same colour as the text

Let's just drop my proposal - we can discuss in a future issue if we like, but I was actually suggesting something even more minimal than what is here, something like this:

However, I think that this would violate accessibility constraints because we'd rely too much on just color to denote the links.

I like option 3 better than option 4

+1 for option 3 as well

[jorisvandenbossche]

Drive-by comment from an old contributor: this is really amazing work!!

I like the different options, especially option 3 or 4 as well.

While here, a few questions:

• In the current theme (released/main), it is the "primary" color that is used for "navigation highlighting" (i.e. indicating on which page you are, highlighting in the right sidebar where you are on the page while scrolling). While in the examples here it seems that the secondary color is used for this? Is that an intentional change? (I didn't read through all past discussion on this topic, so this might already have been discussed before. I also don't have a strong opinion about it)
• Related, if we will no longer use the primary color for h1 headers (which seems like a good idea to me) and if we use the secondary color for navigation UI, what is the primary color actually used for? (only for links and buttons/badges, right?) What I was wondering then is to what extent it is necessary to have two different colors for that. Looking at some other examples (Furo, Docusaurus, GitBook, MDN), they seem to often use the same (or slight different shade of similar color) for both urls and navigation elements.

(maybe the general comment is that it is not super clear to me what "primary" and "secondary" colors are meant to be / what they will be used for)

[jorisvandenbossche]

In the current theme (released/main), it is the "primary" color that is used for "navigation highlighting" .... While in the examples here it seems that the secondary color is used for this?

I mostly looked at it yesterday evening, and I see that now in Option 3 you added a "Navigation item (active)" element that actually uses the primary color.

[trallard]

Hey @jorisvandenbossche thanks for popping by

In the current theme (released/main), it is the "primary" color that is used for "navigation highlighting" (i.e. indicating on which page you are, highlighting in the right sidebar where you are on the page while scrolling). While in the examples here it seems that the secondary color is used for this?

I did notice yesterday that I forgot to add the "active" state to the nav bar and added this later in the Option 3 file.

So basically, the links and navigation items (nav bar, TOC, pagination, drop-down, etc.) should follow these patterns:

• Default, active (i.e current page or item in the TOC): primary colour
• Hover, focus: secondary colour

So here, the primary colour denotes an interactive element in a "passive state" - i.e. not being interacted with by default.

On the other hand, the secondary colour denotes an "interaction state," so if the user hovers, clicks or navigates through a keyboard or screen reader. This interaction is shown in the secondary colour.

These states are accompanied by other non-colour cues also to meet accessibility conformance.

Also, having these colours can help denote hierarchy or add some visual sugar. For example, if having buttons or tags - the primary colour could be considered the default or most important action/option (while not being destructive or confirmation, in which case the green/red/orange semantic colours should be used). So while we are moving towards a monochrome heading colour, keeping these distinct primary and secondary colours still makes sense from an interaction POV.

Docusaurus (and GitHub for links) do not swap colours, but these state distinctions certainly help highlight user interaction and, in general, is better suited to meet some of the WCAG success criteria (WCAG 2.1 and upcoming 2.2). Also - note I used inspiration interactions from sites focused on accessibility (like the a11y project) or from organisations and individuals I know who have done solid research and design work around accessibility and user interaction (Eric Bailey and gov.uk to name a few).

Also - I have yet to add sidebars to the Figma file (as I noticed, for example, that the left sidebar has no cue for hover or active states other than the colour right now). These should match the other "link" like components and states we already defined (to ensure all the interactions and states are consistent and follow Gestalt principles).

[trallard]

thought @choldgraf was suggesting that the underline be a medium gray (not the same value as the text)? As a way of making the underline less prominent?

oops, I completely misunderstood this, but having a quite muted gray might be tricky as we'd need to ensure this meets at least 3:1 contrast, not impossible but might need tweaking

[trallard]

Hey folks, I am circling back here - as per @choldgraf comment it would be best to follow a consent decision-making approach for this work.

So far, we have done the following:

• [x] Initial proposal(s) + quick reactions
• [x] Questions/follow-ups + improvements

From this, it seems the team would like to move with Option 3. So I would like, in turn, to move to the proposal ratification phase. Here is what I am proposing:

1. We adopt Option 3 as the proposal for implementation. I moved this to another file titled "Proposal for implementation". Items to note:
   • I recorded the decisions made in previous iterations/revisions in this file
   • I made my best effort to document all the components, styles, building blocks (including elevation and borders), and references (GitHub issues)
   • ❓ only decision/question I have now is about the accent colour: it seems to be only used for inline code. As per #1087, we agreed to keep the colour inherited from Bootstrap. However, I am unsure if we should only keep the pink colour for the inline code. So we can either:
     1. Keep the accent colour (for the inline code) - and we could reuse it also for announcement banners
     2. Get rid of the accent colour - use the secondary colour for the inline code (or grey) and keep announcement banners in the primary and secondary colours Both proposals are in the Figma document, and I have no strong feelings about any of these directions.
2. Implement the proposal in incremental steps; each should be a separate PR to try and keep things manageable for reviews, fixes, and the such:
   1. New colour scheme - (this should include shadows) + updated documentation (this will supersede #1086
   2. Improvements to links and navigation styles
   3. Improvements to other components - buttons (min-width) and the such + update relevant Examples sections

So at this point, I would like to ask the following:

• Are there any objections to this proposal?
• Do you need any help understanding this proposal?
• Are there any follow-up questions from any of you?

Not sure how long should this consultation period be open so I will defer to the judgement of @choldgraf @drammock and @12rambau. Also not sure if other folks should be brought into this discussion since I have only tagged those participating in the discussions so far.

[drammock]

Keep the accent colour (for the inline code) - and we could reuse it also for announcement banners

+1 from me. The announcement banner is meant to be attention-grabbing; IMO the accent color is a bit "louder" than primary or secondary so it better fulfills that requirement anyway.

Are there any follow-up questions from any of you?

I want to make sure we don't lose track of @12rambau's point about the target color. It's used for highlighting search matches and for changing the background color of code blocks. It's not clear to me what (if anything?) was proposed to do about that.

Not sure how long should this consultation period be open

let's give it a week? tagging @jorisvandenbossche and @bollwyvl to see if they want to weigh in. But anyone in the community is welcome to do so! I'll pin this issue to make it more prominent.

[drammock]

Are there any objections to this proposal?

I'm going to push back one last time on the "teal is too opinionated" issue. I thought I had let it go, but it continues to bother me, and when I look back at Option 2 I am still quite drawn to it, and I still struggle a bit with the choice of primary color for options 3 / 4.

IIUC, "opinionated" here means "chosen for aesthetic (not functional) reasons" and we're trying to let usability / functionality drive this process. But it seems to me that a pretty good functional argument was raised in support of using teal as the primary color, but it wasn't really accepted:

• it was mentioned here that using teal as the primary color would make the primary color more distinct from the other colors in the palette. This wasn't really responded to AFAICT.
• it came up again in this now-resolved figma comment that the primary/secondary/info colors are quite close together. The response by @trallard was "I'm not too worried about primary/info confusion" because info is not "critical" (I think this means "info boxes are not warning/error boxes, so therefore it's not a problem if they're hard to tell apart from the primary UI color"?) The response by @choldgraf was "I like the complementarity" so as long as there's no a11y-based objection, let's keep the colors as-proposed.

I would have thought that "I like the complementarity" would be seen as opinionated reasoning (this comes up in my own comments too, saying option 3 was "more harmonious"). I also would have thought that "more distinct" -> "easier to tell apart info boxes from interactable UI elements like clickable tabs/links" -> "a more usable design". But it seems like that line of reasoning didn't get any traction. I guess I'm wondering why not? Do people just hate teal? Why isn't the not-quite-violet-not-quite-periwinkle in option 3 and 4 considered an opinionated choice the way that teal is?

The impression that I'm getting is that it's really hard to set aside aesthetic judgments and let non-aesthetic considerations drive our choices, so when we like the results, we're more willing to say "LGTM!" and when we don't like the results, we try to find reasons to disqualify a proposed change (or non-change). I think I'm doing exactly this right now: I like how teal looks as primary color, and I don't like the currently-leading proposal quite as much. So I'm taking the time to come up with reasons why we should stick with teal.

So how do we proceed? As I said above, I think some (many?) of the arguments in favor of option 3 (including my own points in support of it) seem to be based on aesthetics. And I think the reason I've raised in support of teal is based on perception / discriminability, not aesthetics. Yet nobody besides me seems to find it compelling. I'm not going to take my ball and go home if option 3 wins, but I do want to understand what others are thinking / considering when they make these judgments --- am I missing something? Maybe the answer is "opinions don't matter until they do"; in which case maybe we can agree that there's nothing especially bad about teal and I'm content to have been out-voted on a question of aesthetics.

As an aside, one could also argue that keeping the primary color as teal is a good idea because it is consistent, and "consistency, usability, and reducing cognitive stress are fundamental principles towards making content accessible for these readers/users" with cognitive disabilities. I.e., for those users who don't customize the colors already, it represents a smaller change from what they're used to.

[trallard]

Hey @drammock, thanks for keeping the conversation going

I want to make sure we don't lose track of @12rambau's https://github.com/pydata/pydata-sphinx-theme/issues/1079#issuecomment-1370831093. It's used for highlighting search matches and for changing the background color of code blocks. It's not clear to me what (if anything?) was proposed to do about that.

No changes to using yellow - but will slightly tweak the shades used

The impression that I'm getting is that it's really hard to set aside aesthetic judgments and let non-aesthetic considerations drive our choices

I agree; it is hard to set these aside when it comes to colours and aesthetics; unfortunately, it tends to drag design discussions (at least in my experience). I have tried to set aside my personal preferences as much as possible (and thus my biases), and it seemed folks were leaning more towards Option 3 than 2 (so that is what I used as a compass, and maybe I misread something).

it was https://github.com/pydata/pydata-sphinx-theme/issues/1079#issuecomment-1371184528 that using teal as the primary color would make the primary color more distinct from the other colors in the palette. This wasn't really responded to AFAICT.

Apologies, I completely skipped/missed this. But yes, from a purely colour perception POV, the teal is more distinct from the violet as there is more distance between their corresponding hues. So this will not only be reflected in states (hover/default) distinction but reducing ambiguity regarding context-specific colours (info/warning/success).

TLD;R

The main goals for this work are:

• Improving the theme's accessibility by meeting colour contrast requirements -> ensure users have a more WCAG-conformant theme by default for our users who are not accessibility experts
• Improving maintainability
• Avoid ad-hoc improvements to colours (one or two at a time) and stop discussing colours (at least for a long while)

1. Option 2:
   • primary (#0A7D91) and secondary (#894DEF) have more distinct hues, so there is a more noticeable change in states
   • primary (#0A7D91) is more distinct to the semantic info(#276BE9) colour
   • primary (#0A7D91) is closer to the current primary colour (#459DB9), which will help with keeping things consistent for existing users (see colour wheel)
   • colour psychology: teal -> individuality, practical, calming, welcoming, edgy

2. Option 3:
   • primary (#4F6AD5) and secondary (#894DEF) are closer together in terms of hues which gives that feeling of "cohesion" but can also be a disadvantage in the sense of making the change in states less noticeable
   • colour psychology: blue -> trust, calming, reliable, conservative (IMO, this conservative feeling and the fact that it is the most popular brand colour is what has been translated into "less opinionated" over teal)

Both themes:

• the colour palettes were designed with visual accessibility in mind (enough colour contrast in both themes, plenty of shades to support the structural elements), colourblind friendly (not bulletproof tho)
• any theme would be a significant improvement, and as they were put together from the ground up, they are far more cohesive than the existing colours
• have distinct brand and semantic colours, which makes it easier for folks to customise and, at the same, use contextual information effectively (also why we settled in ditching yellow)
• use yellow/orange/red sparingly as these are usually related to attention/warning/error messages and can be overwhelming for neurodiverse folks
• have also style proposals to not only rely on colour

My personal preference: I like both proposals - but I would lean towards Option 2 (I like bold colours). Also, the teal/purple combination does work slightly better for certain types of red-green colour blindness (Deuteranopia and Protanopia - I did extensive research on colourblindness and the cognitive impact of colour when working on a colourblind friendly syntax highlighting theme). The latter can be balanced (in Option 3) with the non-colour cues in the rest of the system, but for fully abled readers, this will be the most striking colour combination.

Note: The links in this comment will redirect you to the "proposal for implementation" Figma files of the two themes

➡️ How to move from here?

Since it was proposed to use a consent decision-making process this seems this is the point where we balance our preferences (i.e. making a decision by yourself for yourself) and our range of tolerances (i.e. not your preference but also not something you'd object to).

We are seeking consensus on which proposal to choose: Option 2 or Option 3

1. So, looking at the proposals (Figma files) and arguments in this comment (from TLD;R onwards), each of us would register any main objections for Option 2 and/or Option 3 (as comments here). Same if there are no objections so that we could add something like:

   - Fish: no objection
   - Bird: I believe this falls short on...

   (helpful questions to ask to determine if this is a paramount objection: "Will this option better serve the disabled users?" "Can I live with this proposal?" "Will this proposal cause harm?")

2. No objections == consent

Does this sound like a plan forward? As per this comment a 1 week period seems reasonable to me.

[choldgraf]

A few quick thoughts:

• Thanks @drammock for your thoughtfulness and for layout out all of your reasoning. And thanks @trallard for breaking down the major points above.
• I also think that Option 2 is perfectly reasonable as well. I won't push back at all if folks prefer that direction.
• It's unclear where we are supposed to respond with the fish and the birds, but consider me a fish 🐟 .
• I've also found that I almost always come to like a design over time, even if I am initially not satisfied with it. For this reason I suspect that whatever we go with, most people will come to like it as long as it follows good design principles (which all of these proposals do, IMO).

[trallard]

Ooops I was trying not to lean folks in a specific direction with the 🐟 and 🐦 examples, but it might have ended up being more confusing. So here is what I was suggesting as a format to capture individual's objections or lack thereof

My response to the proposals:

• Option 2: no objection
• Option 3: while adhering to design and accessibility best practices, this might be a big change for users on the current theme (with no customisations of their own); this could be perhaps an alternative theme

(so I explicitly state if I have any/no objections - aligning to the goals and removing personal preferences)

[drammock]

My response:

• Option 2: no objection
• Option 3: I worry about primary and info colors being too similar, which might give the confusing impression that info elements are interactable.

[jorisvandenbossche]

I have no clear preference between Option 2 and Option 3. I think both look great and would be a nice improvement, and would be happy with either.

(I think the blue primary color of Option 3 is more "standard", so with the benefit that people are used to this from other sites, while the teal primary color of Option 2 is more unique, with the benefit of giving a more distinct character to our theme. But no idea which of those benefits are "best" ;))

[12rambau]

• option 2: "Blue" is the standard everywhere: rdt theme, incipid, furo, bootstrap, mkdocs so using "teal" makes us stand out a lot for a "default" theme. That's what I meant by opinionated but maybe I'm just to shy.
• option 3: I also worry that primary and info look the same. info admonitions are used everywhere and they will look the same as custom admonition (that are in primary)

[choldgraf]

So to summarize quickly, it seems that nobody has an objection to option 2 or 3, though in general there are more concerns with 3 than with 2.[^1]

It sounds like the main concern with 2 is:

• The teal color is very distinct from what most themes use as a blue hue (though as @12rambau and @jorisvandenbossche notes this isn't necessarily a bad thing)

[^1]: assuming here that the concerns people shared were not "objections" - I think in this context "objection" means that you think it would be a major mistake to move forward w/ the proposal, not a general comment.

[jorisvandenbossche]

I think that's a fair summary.

A note on both concerns:

The teal color is very distinct from what most themes use as a blue hue

BTW, docusaurus is also not using blue, but something greenish (that is not that far from teal): https://docusaurus.io/docs/installation

worry about primary and info colors being too similar,

Also other themes we compare with seem to have this issue. For example, for furo (https://pradyunsg.me/furo/reference/admonitions/) the "note" color is also blue but a different blue as the primary color for navigation/links (and same for metaflow).
Although furo uses a totally different color for custom admonitions (purple-like), and not the primary color, so doesn't have the issue of confusing those two kinds of admonitions (for option 3, it would thus also be an option to use the secondary color for custom admonitions, which is more distinct from the info color).

[trallard]

The problem with Furo is that there are too many admonition colours - purple, red, orange, teal, blue 1, blue 2, green, grey.

Also, note that blue 1 and blue 2 are different from the main blue, making at least three very similar colours (also, the green and teal are pretty similar). This proposal tries to minimise the number of ad-hoc or otherwise colours and provide a consistent colour palette for the whole theme.

[drammock]

nobody has an objection to option 2 or 3, though in general there are more concerns with 3 than with 2.

so far it seems like 2 might be winning, but as promised let's give it a full week to see if any other objections emerge. I think that means waiting until EOD Tuesday 17 Jan.

[choldgraf]

Agreed - my feeling is that if nobody objects by then we should go with option 2

This also makes me feel like we'd benefit from some slightly more structured decision making guidelines, now that the contributors have grown a bit.

The jupyterhub team has PR merging guidelines that try to balance inclusion and efficiency, and have two groups for making decisions (a larger one for most decisions, based on lazy consent, and a smaller steering council that decides on majority vote for when we have an objection but still need to move forward)... I wonder what folks think about adopting something similar (it's basically what we already do informally but with the addition of a tie breaking mechanism). Should I open an issue about this?

[trallard]

I like @choldgraf proposal re decision making - also I acknowledge I am pretty new to the project so my opinion might not have too much weight.

But having these processes defined and ideally documented for new contributors would be extremely helpful to set expectations and fair/equitable processes. LMK if I can help with this at all.

[drammock]

I like the Jupyterhub guidelines. +1 for adopting something similar here.

[trallard]

Hey folks, I am back after some focused time on other work items. As per the above, we are moving in the option 2 direction. So I will start working on the colour improvements next week.

[trallard]

Hey folks - I know I need to finish this PR (almost there, and I should be able to do so now that the infinite loop in docs has been fixed 🎉 thanks, @drammock)

Also, I am super happy to inform you that we have hired an excellent designer at Labs @smeragoel who will work on accessibility design and our grant deliverables for PyData Sphinx.