-
-
Notifications
You must be signed in to change notification settings - Fork 1.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve callouts #12053
Comments
@inventarSarah What would be the difference to the |
@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! |
@inventarSarah thanks!
|
👍
That would be great!
Sounds good to me -- the prop to hide it would provide a bit more flexibility when needed
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. |
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:
level
(string:'info' | 'warning' | 'danger' | 'success'
)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
--accent-4
instead of--accent-2
helps a lot already--blue-3
instead of--blue-2
helps a lot alreadyEmphasize 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:
Clarify usage
We should rework the Alert and Note component descriptions in "Contributing to the docs" to document their usage.
What I suggest:
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)
The text was updated successfully, but these errors were encountered: