ENH: simplify color variables

[12rambau]

summary

Reduction of the color variables from 79 to 17, respecting the guidelines from material colors.

• classic 7 colors (primary ... danger) palette
• 2 text colors (base, muted)
• 4 depth levels: background, on-background, surface, on-surface (in depth order)
• 1 border and 1 shadow
• I kept the inline code color (it's kinda the theme signature to me)
• I kept the custom link color as well
• I kept the target color as it's well designed and never conflicts with anything

FIx #623, Fix #279

customization

These modifications required some adjustments, in the directive color scheme:

• "kbd" directives are now the negative of the background and text-base (https://pydata-sphinx-theme--659.org.readthedocs.build/en/659/demo/kitchen-sink/paragraph-markup.html#inline-markup)
• Preformatted uses the text-base color
• Header links are in danger color
• Guilabel in info and the background is treated as the admonition one (https://pydata-sphinx-theme--659.org.readthedocs.build/en/659/demo/kitchen-sink/paragraph-markup.html#inline-markup)
• Switcher theme component keeps its border on hover (that was looking weird)
• Remove never used colors (e.g. --pst-color-alert-link)
• blockquote border will be the same as all the other borders
• targeted code is now using the target and border colors (https://pydata-sphinx-theme--659.org.readthedocs.build/en/659/_modules/asyncio/events.html#AbstractEventLoop)
• the previous trick is maintained, surface color is the same as background on light theme (depth is performed by shadows), and surface color is the same as on-background in dark theme

question

Why is there a transition in admonition css (https://pydata-sphinx-theme--659.org.readthedocs.build/en/659/demo/kitchen-sink/paragraph-markup.html#admonitions) ? It creates a funny behavior when switching from light to dark theme (ref). Let me know if you think it should be removed

finally

What do you think ?

[choldgraf]

This looks really nice - in general the style seems to still look good (IMO) and I really like reducing the number of configuration options to expose.

a few quick thoughts from me:

Header links are in danger color

Why not make these the same color as other links on the page? That way link style within the page is the same for all elements.

Why is there a transition in admonition css

I did a quick look and it seemed fine to me - note that most people are not going to be regularly switching light/dark mode, so IMO it is OK.

code block CSS

there doesn't seem to be any background or shadow for code blocks, which makes it feel much more "flat" on dark mode:

variable naming

What do you think about switching the variable prefix from --pst to --theme. That would make it a bit less clunky to sub-theme this one and extend or add your own variables. We could do a deprecation cycle to keep the --pst variables around if we wanted to.

[12rambau]

Why not make these the same color as other links on the page? That way link style within the page is the same for all elements.

Because the titles are already blue (primary) so it would be confusing From what I read in the issues, the Pandas theme will be progressively dropped so titles will be blue in both themes eventually. I like the contrast between these 2 items.

Why is there a transition in admonition css ?

My question was more, "I think it's useless can we remove it ?". As you mentioned people are rarely jumping from light to dark so I think this is some legacy code from the inspiration.

What do you think about switching the variable prefix from --pst to --theme?

I actually like --pst- it's easily identified, makes sure that nobody is going to use the same one and overwrite ours by accident, and it's shorter to write than "theme". What is the use case you have in mind ?

[choldgraf]

I think it's useless can we remove it ?

Ah yeah - I thin that's fine

What is the use case you have in mind ?

My use case is themes that sub-theme this one. In my case, the sphinx book theme (https://sphinx-book-theme.readthedocs.io/). It feels weird to ask users to define some variables as --pst- and others as --sbt-. Though I guess now that the number of unique variables is much smaller, it wouldn't be so bad to just copy each of them over to an --sbt- value.

[choldgraf]

Anything else you're hoping to tackle in this one? Or are we just waiting for approval and merge @12rambau ?

One quick thing: can we update the docs on the theme variables page so it's clearer which variables are the ones we'd like people to update?

[12rambau]

I've updated the documentation with color variables.

question: Is it in normal that the other variables are still stored in _static and not in style/_base ?

[choldgraf]

I made some quick updates to the docs, but they look good to me!

I am not sure why the other variables are in the static folder instead of assets with the other CSS variables / rules. My preference would be to keep them all together, rather than have some in assets and others in static. I think that @pradyunsg elected to leave the variables in static when he converted over the theme builder infrastructure in:

• Switch to sphinx-theme-builder and improve webpack.config.js #514

@pradyunsg I couldn't find a rationale for leaving some variables in the static folder, any chance you could provide guidance here? Would you object to having all CSS variables in assets and use static only for programmatically generated files?

[jarrodmillman]

@12rambau Should we merge this before releasing 0.9rc1 later today? If so, would you mind resolving the merge conflicts?

[choldgraf]

I'm happy with @jarrodmillman's suggestion in #675 to:

• Open an issue to discuss and decide on how to standardize the CSS variables
• Merge this in and iterate from there

[12rambau]

I resolved the conflicts in the GitHub editor, I hope linter will not complain. But after that we are good to merge

[choldgraf]

issue to track moving the color CSS variables: #676

[12rambau]

DO NOT merge, the navbar is transparent.

I'm correcting it and merging as I have already 2 approvals

[jarrodmillman]

Good catch! I didn't even notice when I scrolled down the page.