You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
update Contributing to Docs on Alert and Expandable components (#12485)
* update guidelines on Alert and Expandable components
* Apply suggestions from code review
Co-authored-by: Alex Krawiec <[email protected]>
---------
Co-authored-by: Alex Krawiec <[email protected]>
Copy file name to clipboardExpand all lines: docs/contributing/pages/components.mdx
+82-35
Original file line number
Diff line number
Diff line change
@@ -6,38 +6,44 @@ sidebar_order: 40
6
6
7
7
## Alert
8
8
9
-
Render an alert callout.
9
+
Render an alert (sometimes called a callout) to highlight important information.
10
10
11
-
<Alerttitle="Watch out!">
12
-
This is an info alert. Use these for information that's critical to know; it's important for users to read, but won't cause a catastrophic problem if they don't read it. These include versions that introduce breaking changes or feature limitations. Use infrequently.
11
+
<Alerttitle="Note">
12
+
This is an info alert. Use this to emphasize information that users should
13
+
read.
13
14
</Alert>
14
15
15
16
<Alertlevel="warning"title="Important">
16
-
This is a warning alert. Use these for items that MUST be well understood before proceeding. These highlight information that could cause users to make catastrophic errors that break their applications in ways that are very difficult to fix or create liabilities for them, such as information needed to avoid leaking PII. These should be used very rarely.
17
+
This is a warning alert. Use this to alert users to potential risks they
18
+
should be aware of.
17
19
</Alert>
18
20
19
21
<Alertlevel="success"title="Tip">
20
-
This is a success alert. Use these when.... TODO?
22
+
This is a success alert. Use this to provide optional information that can
23
+
help users be more successful.
21
24
</Alert>
22
25
23
26
<Alert>
24
-
This is an alert without title.
27
+
This is an alert without a title. `warning` alerts should always have titles
28
+
to emphasize their importance.
25
29
</Alert>
26
30
27
31
<Alert>
28
-
This is a multi-line alert without title. Use these for information that's critical to know; it's important for users to read, but won't cause a catastrophic problem if they don't read it. These include versions that introduce breaking changes or feature limitations. Use infrequently.
32
+
This is a multi-line alert without a title. Keep information brief and to the
33
+
point. If this is challenging, consider whether the topic needs documentation
34
+
on another page or if using the [Expandable](#expandable) component would be a
- Make sure your alerts aren't breaking the flow of the content. For example, don't put an alert in between two paragraphs that explain a single concept. Use alerts sparingly; too many alerts on a single page can be overwhelming.
75
+
**When to use which alert level:**
76
+
77
+
-**Info**: Use this to emphasize information that users should read. For example:
78
+
- information needed for users to succeed
79
+
- information you'd typically wrap in a note callout
80
+
-**Warning**: Use this to alert users to potential risks they should be aware of. For example:
67
81
68
-
Use this for these types of content:
82
+
- warnings about potential errors, such as ones caused by common oversights in project configuration
83
+
- warnings regarding breaking changes
69
84
70
-
-**Important:** Use these for information that's critical to know; it's important for users to read, but won't cause a catastrophic problem if they don't read it. These include versions that introduce breaking changes or feature limitations. Use infrequently.
71
-
- Use this with or without a title
72
-
-**Warning:** Use these for items that MUST be well understood before proceeding. These highlight information that could cause users to make catastrophic errors that break their applications in ways that are very difficult to fix or create liabilities for them, such as information needed to avoid leaking PII. These should be used very rarely.
73
-
- Use with the title "Important"; do not use the title "Warning"
85
+
Best practices:
74
86
75
-
You can also omit the title of the alert.
87
+
- always use a title with this alert level
88
+
89
+
-**Success**: Use this to provide optional information that can help users be more successful. For example:
90
+
- information that helps improve an already successful task, such as a link to additional reading material
91
+
- tips for best practices
76
92
77
93
## Arcade embeds
78
94
79
95
Render an [Arcade](https://arcade.software) embed.
This is an expandable section in an `'info'` alert style.
104
133
</Expandable>
105
134
```
106
135
107
136
```markdown {tabTitle:Permalink}
108
-
<Expandable permalink title="With Permalink">
109
-
This is some content
137
+
<Expandable permalink title="With permalink">
138
+
This is an expandable section with a permalink.
110
139
</Expandable>
111
140
```
112
141
113
142
```markdown {tabTitle:Warning}
114
-
<Expandable level="warning" title="This is a title">
115
-
This is some content
143
+
<Expandable level="warning" title="This could be important to some users">
144
+
This is an expandable section in a `'warning'` alert style.
116
145
</Expandable>
117
146
```
118
147
119
148
```markdown {tabTitle:Success}
120
-
<Expandable level="success" title="This is a title">
121
-
This is some content
149
+
<Expandable level="success" title="Want some tips to improve something?">
150
+
This is an expandable section in a `'success'` alert style.
122
151
</Expandable>
123
152
```
124
153
125
154
Attributes:
126
155
127
156
-`title` (string)
128
-
-`permalink` (boolean) - optional: the title as a link and show it in the TOC.
157
+
-`permalink` (boolean) - optional: wraps the title in a link and shows it in the table of contents.
158
+
159
+
**When to use expandables:**
160
+
161
+
Expandables help keep our documentation clutter-free, allowing users to focus on important information while providing them the option to explore additional relevant details.
162
+
163
+
For example, use expandables to:
164
+
165
+
- offer information that is useful to some users but not all, like troubleshooting tips
166
+
- provide background information or insights into related concepts
167
+
168
+
**Best practices**
169
+
170
+
- Write the expandable title as a question or statement to clarify what users can expect from the content within:
171
+
- Do you want to learn more about these features?
172
+
- Are you using Node.js version 15 or lower?
173
+
- Advanced configuration options for XY use case.
174
+
- When you need to share important information that users should read, consider using an [alert](#alert) instead since its content is visible by default.
175
+
- Avoid overusing this component and make sure to provide valuable information that is relevant to the current topic.
0 commit comments