We have five admonitions, which you can see in the UI Preview.
Currently, they have the following colors and icons:
Note - Green, info circle (like ℹ️)
Tip - Green, 💡
Important - Red, 🛑 with exclamation point.
Caution - Muted orange, info circle
Warning - Red, ⚠️
Issue
The perceived importance conveyed by the colors and icons alone doesn't align with the weight of the labels for each type.
For example, the color and icon for Caution make it seem less impactful than Important, which is red with the "stop" octagon.
Proposal
Our current use of admonitions is not fully aligned, but I recently wrote up some guidelines on when and how to use each type.
It would be good to align the colors and icons with the intended use for each type.
Here are my proposals for each each admonition type along with an explanation of my reasoning.
Hex code color samples are representative of dark mode only.
Caution and Warning - #330003 - ⚠️
Caution and Warning are similarly severe, so I feel that it's acceptable to have the same style for these.
This minimizes the cognitive effort required to determine the severity when these have almost the same meaning.
Red/⚠️= Danger regardless of it being less severe or more severe danger.
Additionally, the icon for Caution needs to change to the triangle exclamation point, which Warning currently has, instead of the info circle.
Tip - #003325 -💡
I recommend the current styling for Tip because it's optional "friendly" or "helpful" information. Green = Go/Good.
Important - #0347A0/#9657A1 - info circle
At this point I suggest introducing a 3rd color that is not orange.
We should have at least 3 colors, possibly 4, but orange is too close to red.
Important must be a different color than Tip and Caution/Warning because Important is valuable information that is not dangerous, like Caution/Warning, but more valuable than Tip.
It is sometimes not optional.
Therefore, I suggest either blue or purple instead of orange.
I could entertain an argument for yellow, but orange is too much like "traffic cone", and yellow might not work well in light mode.
Additionally, the icon needs to change for Important.
I suggest the info circle instead of the stop sign exclamation point.
Note - #003325, #0347A0/#9657A1, or border only - info circle
I suggest making Note either green or blue/purple for now.
This is because Note is currently widely used as a catchall, non-specific admonition, and it seems to be quite frequently used for content that does not belong in an admonition at all.
Ideally, we should stop using Note for the majority of admonitions, and then change the Note color to something that more or less blends into the background, such as simple black/white border with a clear fill/background.
However, this requires us to audit all Notes and change them to some other more appropriate type wherever applicable.
If we don't want to audit all Notes at this time, we need to survey some of the Notes to find out what content they contain, and then decide whether Note should match Tip or Important.
To determine which course of action to take for Note, I suggest the following steps:
Find out how many instances of Note there are across all docs.
If there are less than 200-300 Notes, change those Notes to a more appropriate type or remove the content from the admonition block. Then, change the Note color to the "fade away" color (black/white outline).
If there are more than a reasonable number of Notes, then gather a selection of those notes (~75-100) and review their content. If the notes are overwhelming Tips, keep the green color for Note. If the notes are overwhelmingly Important, change the color to blue/purple to match whatever color is chosen for Important.
Background
This discussion started from a Slack thread.
We have five admonitions, which you can see in the UI Preview. Currently, they have the following colors and icons:
Issue
The perceived importance conveyed by the colors and icons alone doesn't align with the weight of the labels for each type. For example, the color and icon for Caution make it seem less impactful than Important, which is red with the "stop" octagon.
Proposal
Our current use of admonitions is not fully aligned, but I recently wrote up some guidelines on when and how to use each type. It would be good to align the colors and icons with the intended use for each type.
Here are my proposals for each each admonition type along with an explanation of my reasoning. Hex code color samples are representative of dark mode only.
Caution and Warning -
#330003- ⚠️Caution and Warning are similarly severe, so I feel that it's acceptable to have the same style for these. This minimizes the cognitive effort required to determine the severity when these have almost the same meaning. Red/⚠️= Danger regardless of it being less severe or more severe danger.
Additionally, the icon for Caution needs to change to the triangle exclamation point, which Warning currently has, instead of the info circle.
Tip -
#003325-💡I recommend the current styling for Tip because it's optional "friendly" or "helpful" information. Green = Go/Good.
Important -
#0347A0/#9657A1- info circleAt this point I suggest introducing a 3rd color that is not orange. We should have at least 3 colors, possibly 4, but orange is too close to red.
Important must be a different color than Tip and Caution/Warning because Important is valuable information that is not dangerous, like Caution/Warning, but more valuable than Tip. It is sometimes not optional.
Therefore, I suggest either blue or purple instead of orange. I could entertain an argument for yellow, but orange is too much like "traffic cone", and yellow might not work well in light mode.
Additionally, the icon needs to change for Important. I suggest the info circle instead of the stop sign exclamation point.
Note -
#003325,#0347A0/#9657A1, or border only - info circleI suggest making Note either green or blue/purple for now. This is because Note is currently widely used as a catchall, non-specific admonition, and it seems to be quite frequently used for content that does not belong in an admonition at all.
Ideally, we should stop using Note for the majority of admonitions, and then change the Note color to something that more or less blends into the background, such as simple black/white border with a clear fill/background. However, this requires us to audit all Notes and change them to some other more appropriate type wherever applicable.
If we don't want to audit all Notes at this time, we need to survey some of the Notes to find out what content they contain, and then decide whether Note should match Tip or Important.
To determine which course of action to take for Note, I suggest the following steps: