Improve callouts

[inventarSarah]

Problem Statement

Callouts are visual elements used a lot in documentation to highlight information, add tips, provide additional context, or warn the user about potential risks.

We already have and use callout boxes in our SDK documentation (the <Alert /> component and the <Note /> component).
However, when I first explored the docs, I had problems understanding what information these boxes included (what's a yellow box vs a grey box?). I also find some of the colored boxes very hard to see in light-mode, which is not ideal since they should not be missed.

After looking more into the Alert and Note components we have and how we recommend to use them, I also found that the respective sections in "Contributing to the docs" could provide more helpful information. Writers may struggle to understand when to use which alert type.

Currently, we support the following:

• Alert: level (string: 'info' | 'warning' | 'danger' | 'success')
• Note

Some questions that pop into my mind as a docs creator:
-> When should you use Note, and when should you use Alert info?
-> When should you use Alert warning, and when should you use Alert danger?
-> What content would we typically wrap in a success alert?

So I want to suggest visually reworking the components a bit to make them clearer and then later also update the Contributing to docs to be more helpful when using these components.

Solution Brainstorm

Increase visibility

• the Note box is very hard to see (especially in light mode) -> for example, using backgroundcolor --accent-4 instead of --accent-2 helps a lot already
• The Alert info box is also hard to see in light mode -> for example, using backgroundcolor --blue-3 instead of --blue-2 helps a lot already
• the font-size is a bit smaller than outside the boxes -- I suggest increasing the size to be consistent

Emphasize purpose

As a user, I may not be familiar with the different alert types and the associated colors. Also, some boxes have headings and others do not. For example, it may be intuitive to some that a yellow box contains a warning but it could just also be a happy color for a note. thus, it may be tricky for users to estimate how important the info in that box is at first glance.
Naturally we want to make things as easy as possible for the user -> that's why the different alert types should be easily recognizable. If there's a yellow box with a warning inside, the user should know that before even reading the content.

Here's what I propose to achieve this:

• display an icon in the top left (pre-defined for each type) For example: https://github.com/orgs/community/discussions/16925
• display a title; this can be either a custom string or, if not provided, the default title for the alert level;

Clarify usage

We should rework the Alert and Note component descriptions in "Contributing to the docs" to document their usage.
What I suggest:

• describe the purpose of the note and each alert level; provide example use cases
• add an example for each Alert level box so writers see how these will look like
• simplify title usage -- all boxes have a title (either custom or default if not provided)
  • notes should also have a title to be consistent and to help differentiate between different types of notes (note, tip, example, summary)

Considerations

Expandable content boxes

I will also create an issue to create expandable content boxes. If we want to implement both suggestions, we need to make sure the new components are distinguishable. #12055

Existing callouts

If we implement new/upgrade existing callouts what do we do about the already existing ones (how will they be affected by the change)

[chargome]

@inventarSarah What would be the difference to the <Alert /> component here?

[inventarSarah]

@chargome thanks for the question -- it actually helped to clarify some things for me.

I've reworked the issue description completely -- hope this makes more sense now!

[chargome]

@inventarSarah thanks!

• I think we can actually get rid of <Note /> and replace it with <Alert /> to avoid confusion and inconsistency.
• I like the idea of adding icons but would implement a prop to hide it.
• Maybe we could even extend this component to make it collapsible (Create/improve expandable content boxes #12055)

[inventarSarah]

👍

• I think we can actually get rid of <Note /> and replace it with <Alert /> to avoid confusion and inconsistency.

That would be great!

• I like the idea of adding icons but would implement a prop to hide it.

Sounds good to me -- the prop to hide it would provide a bit more flexibility when needed

• Maybe we could even extend this component to make it collapsible (Create/improve expandable content boxes #12055)

If we could implement the alerts in a way that allows for this additional feature to be added later on (if we decide to do it), it would be great.

[inventarSarah]

The team has designed and implemented new Alerts with #12422 🎉

I've created a subtask for me to update the Contributing to the Docs with information on how and when to use these (#12466)

Note:
Re: do we need a "Danger" alert:
I agree with mydea: we can always add it back when needed.
For example, you would use the "danger" type to warn users of actions that could lead to data loss or other serious consequences that are difficult to reverse and potentially cause damage.

[mydea]

Feel free to close this issue when you updated the contributing docs - thank you!