tip, hint, and important admonition colors

[stevepiercy]

I think the tip and hint admonitions are OK as green, but I think blue would be a better color. The color green has an international context of "go", whereas blue has a context of "information".

Additionally I think important should be yellow, not green, as it is similar in purpose and context to caution.

See currrent examples:

https://pydata-sphinx-theme.readthedocs.io/en/stable/examples/kitchen-sink/admonitions.html

See also original discussion:

executablebooks/sphinx-book-theme#597 (comment)

I would be happy to submit a PR, upon consensus.

[12rambau]

I don't have a strong opinion on admonition colors, what are the other themes doing ?

[stevepiercy]

Here are a few of the popular themes:

• https://sphinx-themes.org/sample-sites/sphinxawesome-theme/kitchen-sink/admonitions/
• https://sphinx-themes.org/sample-sites/sphinx-rtd-theme/kitchen-sink/admonitions/
• https://sphinx-themes.org/sample-sites/sphinx-material/kitchen-sink/admonitions/
• https://sphinx-themes.org/sample-sites/insipid-sphinx-theme/kitchen-sink/admonitions/

Other themes:

• https://sphinx-themes.org/#themes

Bootstrap 5:

• https://getbootstrap.com/docs/5.2/components/alerts/#examples

Bootstrap 4:

• https://getbootstrap.com/docs/4.6/components/alerts/

Some themes might use different CSS frameworks, too. There are not always clear and obvious style mappings from Sphinx admonitions to Bootstrap alerts. I don't know whether authors considered the meaning of color in admonitions, especially with the recent development of beautiful modern themes and the options they offer.

[12rambau]

I would say RDT is the most common one so anything they select is considered as standard for the Python community.

Maybe we could align on the colors they selected and be fancier on the icons?

[drammock]

we are basically already aligned with what RTD theme does as far as colors (material is also the same as RTD on colors). The only deviation is that we color our versionadded, versionchanged, and deprecated messages. As far as icons goes, RTD uses one icon for all of them, we already use 5 different icons (material uses 4). Here's how it shakes down:

we define these colors:

• primary, info (blue)
• secondary, warning (orange)
• success (green)
• danger (red)

and these icons:

• default, note (info-circle)
• attention, important (exclamation-circle)
• warning, caution, danger (exclamation-triangle)
• error (times-circle)
• hint, tip (lightbulb)

which admonition types get which combination of icon+color is defined here

• default, note (info color, note icon)
• hint, tip (success color, hint icon)
• important (success color, attention icon)
• attention (warning color, attention icon)
• caution, warning (warning color, warning icon)
• danger (danger color, warning icon)
• error (danger color, error icon)

To me this is actually pretty good. Everything has a different combo of color+icon except for:

• hint & tip
• caution & warning
• note & default

...and to me it makes sense to treat hint & tip as "roughly the same", and to treat caution & warning as "rougly the same" --- e.g., if pressed to say how I would use "hint" differently than "tip" in my own docs, I'm not sure I'd have a clear answer. I'm not crazy about "note" and "default" being identical, perhaps because "default" allows a custom admonition title which means it might not necessarily be suited to an "info" icon.

Turning to the OP's proposals: I can see the argument for attention & important being "roughly the same" semantically (in the way that hint & tip or caution & warning are "roughly the same") --- though I disagree about "important" being most similar to "caution"; in this case the result would be the same (important would get warning color). However, unifying them would break with the pattern used by RTD & material themes. So if we're taking our cue from RTD then we should probably leave the colors alone.

As for the proposal to make hint & tip use the info color, I'm definitely -1 on that. Partly because I don't see the problem / confusion with "green means go" here --- hints and tips are meant to make things easier, speed users along their way, etc. Sure, they're informative, but all of the admonitions are informative in some sense. That doesn't mean they should all have the info color. The other reason not to change hint & tip to the info color is that if we do that and we accept the OP's other proposal (which is IMO the better idea) then we wouldn't be using our success color for any admonitions, which seems suboptimal.

Aside: If we are going to break with RTD/material on colors, I'd be open to the idea of adding a fifth and even sixth color (purple? pink? brown?) and (partially?) decoupling the primary/secondary colors (used for website structural elements) from the semantic colors (used for admonitions). If others are interested in that, feel free to pull out this paragraph into a separate issue.

[stevepiercy]

I don't assume the RTD theme authors analyzed the meaning of color and icons for admonitions. A quick search into their history reveals there was not much, if any, thought put into it. If they had, then it would make sense to follow their lead. As it is, it makes sense to remedy the oversight. In fact there are some open issues in the RTD theme to resolve some problems with their admonition styles.

Do we have consensus to remedy the oversight of admonition icon and color combination meanings, and not just copy another theme?

[drammock]

Do we have consensus to remedy the oversight of admonition icon and color combination meanings, and not just copy another theme?

Well, as you've seen above, @12rambau says he doesn't have strong feelings about it, and I've expressed my opinion (that I'm in favor of one of your proposed changes and against the other, and open to other ideas about color changes). @choldgraf do you want to weigh in?

[choldgraf]

After thinking about it a bit, a few quick thoughts

• Given that RTD wasn't particularly thoughtful about this I think it's fine for us to define our own groupings.

• I like how the Furo theme does their admonitions...I'd be fine basically following the same approach.

• Here's how I personally think the above admonitions are naturally categorized:

  General information (blue...should not draw attention)
  default, note

  Extra ideas that might be helpful (green...should not draw attention)
  hint, tip, seealso

  You should pay attention to this (yellow...should draw attention)
  important, attention

  You should slow down because of this information (orange...should draw attention)
  caution, warning

  Something important might go or has gone wrong (red...should draw attention)
  danger, error

• Finally, I feel that this topic is at risk of bikeshedding, we should just make a decision and go forward, color is a very subjective thing so I don't think we should assume there is a "right" answer.

[12rambau]

let me update the PR including these modifications as it sounds reasonable to me (I'll check what we can do with yellow (as it's not a predefined color anymore)

[12rambau]

@stevepiercy did the merge of #1043 solved your issue ?

[stevepiercy]

@12rambau no. Caution should be yellow.

I get it that PyData chose admonition colors based on its palette, and that the majority thinks distinct color/icon combinations are a good thing. I think the theme has too many admonition colors, which makes it difficult to design considering dark/light and accessibility. I'll just override colors in our theme to simplify things, eliminating orange. At least it is easy to override. I will close this as "won't fix".