update Contributing to Docs on Alert and Expandable components

docs/contributing/pages/components.mdx

@@ -6,38 +6,44 @@ sidebar_order: 40
 
 ## Alert
 
-Render an alert callout.
+Render an alert (sometimes called a callout) to highlight important information.
 
-<Alert title="Watch out!">
-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.
+<Alert title="Note">
+  This is an info alert. Use this to emphasize information that users should
+  read.
 </Alert>
 
 <Alert level="warning" title="Important">
-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.
+  This is a warning alert. Use this to alert users to potential risks they
+  should be aware of.
 </Alert>
 
 <Alert level="success" title="Tip">
-This is a success alert. Use these when.... TODO?
+  This is a success alert. Use this to provide optional information that can
+  help users be more successful.
 </Alert>
 
 <Alert>
-This is an alert without title.
+  This is an alert without a title. `warning` alerts should always have titles
+  to emphasize their importance.
 </Alert>
 
 <Alert>
-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.
+  This is a multi-line alert without a title. Keep information brief and to the
+  point. If this is challenging, consider whether the topic needs documentation
+  on another page or if using the [Expandable](#expandable) component would be a
+  better fit.
 </Alert>
 
 <Alert title="List">
-<ul>
-<li>Item 1</li>
-<li>Item 2</li>
-</ul>
+  <ul>
+    <li>You can create lists</li>
+    <li>and **format** _your_ `text`</li>
+  </ul>
 </Alert>
 
-
 ```markdown {tabTitle:Info}
-<Alert title="Watch out!">
+<Alert title="Note">
 This is an info alert.
 </Alert>
 ```
@@ -56,27 +62,37 @@ This is a success alert.
 
 ```markdown {tabTitle:No Title}
 <Alert>
-This is an alert without title.
+This is an info alert without a title.
 </Alert>
 ```
 
 Attributes:
 
 - `title` (string) - optional
-- `level` (string: `'info' | 'warning' | 'success') - optional, defaults to `'info'`
+- `level` (string: `'info' | 'warning' | 'success'`) - optional, defaults to `'info'`
+
+**When to use which alert level:**
+
+- **Info**: Use this to emphasize information that users should read. For example:
+  - information needed for users to succeed
+  - information you'd typically wrap in a note callout
+- **Warning**: Use this to alert users to potential risks they should be aware of. For example:
+
+  - warnings about potential errors, e.g., caused by common oversights in project configuration
+  - warnings regarding breaking changes
 
-Use this for these types of content:
+  Best practices:
 
-- **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.
-  - Use this with or without a title
-- **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.
-  - Use with the title "Important"; do not use the title "Warning"
+  - always use a title with this alert level
 
-You can also omit the title of the alert.
+- **Success**: Use this to provide optional information that can help users be more successful. For example:
+  - information that helps improve an already successful task, e.g., link to additional reading material
+  - tips for best practices
 
 ## Arcade embeds
 
 Render an [Arcade](https://arcade.software) embed.
+
 <Arcade src="https://demo.arcade.software/v7uhzmdV6Q5PDzoVPAE6?embed&show_copy_link=true" />
 ```markdown {tabTitle:Example}
 <Arcade src="https://demo.arcade.software/v7uhzmdV6Q5PDzoVPAE6?embed&show_copy_link=true" />
@@ -88,44 +104,74 @@ Attributes:
 
 ## Expandable
 
-Render an expandable section.
+Render an expandable section to provide additional information to users on demand.
 
-<Expandable title="This is a title">This is some content</Expandable>
+<Expandable title="Here's something worth noting">
+  This is an expandable section in an `'info'` alert style. Use this to provide
+  additional information that is good to know.
+</Expandable>
 
-<Expandable permalink title="With Permalink">This is some content</Expandable>
+<Expandable permalink title="With permalink">
+  This is an expandable section in an `'info'` alert style with a title wrapped
+  in a link.
+</Expandable>
 
-<Expandable title="Warning" level="warning">This is some warning content</Expandable>
+<Expandable title="This could be important to some users" level="warning">
+  This is an expandable section in a `'warning'` alert style. Use this to warn
+  users about potential risks.
+</Expandable>
 
-<Expandable title="Success" level="success">This is some success content</Expandable>
+<Expandable title="Want some tips to improve something?" level="success">
+  This is an expandable section in a `'success'` alert style. Use this to
+  provide optional information that can help users be more successful.
+</Expandable>
 
 ```markdown {tabTitle:Example}
-<Expandable title="This is a title">
-  This is some content
+<Expandable title="Here's something worth noting">
+  This is an expandable section in an `'info'` alert style.
 </Expandable>
 ```
 
 ```markdown {tabTitle:Permalink}
-<Expandable permalink title="With Permalink">
-  This is some content
+<Expandable permalink title="With permalink">
+  This is an expandable section with a permalink.
 </Expandable>
 ```
 
 ```markdown {tabTitle:Warning}
-<Expandable level="warning" title="This is a title">
-  This is some content
+<Expandable level="warning" title="This could be important to some users">
+  This is an expandable section in a `'warning'` alert style.
 </Expandable>
 ```
 
 ```markdown {tabTitle:Success}
-<Expandable level="success" title="This is a title">
-  This is some content
+<Expandable level="success" title="Want some tips to improve something?">
+  This is an expandable section in a `'success'` alert style.
 </Expandable>
 ```
 
 Attributes:
 
 - `title` (string)
-- `permalink` (boolean) - optional: the title as a link and show it in the TOC.
+- `permalink` (boolean) - optional: wraps the title in a link and shows it in the table of contents.
+
+**When to use expandables:**
+
+Expandables help keep our documentation clutter-free, allowing users to focus on important information while letting others explore additional relevant details.
+
+For example, use expandables to:
+
+- offer information that is useful to some users but not all, like troubleshooting tips
+- provide background information or insights into related concepts
+
+**Best practices**
+
+- Write the expandable title as a question or statement to clarify what users can expect from the content within:
+  - Do you want to learn more about these features?
+  - Are you using Node.js version 15 or lower?
+  - Advanced configuration options for XY use case.
+- When you need to share important information that users should read, consider using an [alert](#alert) instead since its content is visible by default.
+- Avoid overusing this component and make sure to provide valuable information that is relevant to the current topic.
 
 ## Code Blocks