From 25fb5cbdead26570ab8991680a49f3f45b8eefdb Mon Sep 17 00:00:00 2001
From: Eric Liu <ericyl.us@gmail.com>
Date: Sat, 3 May 2025 11:04:15 -0700
Subject: [PATCH] docs(toast-notification): improve docs

---
 .../pages/components/ToastNotification.svx    | 30 ++++++++++++-------
 1 file changed, 19 insertions(+), 11 deletions(-)

diff --git a/docs/src/pages/components/ToastNotification.svx b/docs/src/pages/components/ToastNotification.svx
index d924de80..4dc44e8e 100644
--- a/docs/src/pages/components/ToastNotification.svx
+++ b/docs/src/pages/components/ToastNotification.svx
@@ -1,30 +1,32 @@
+---
+components: ["ToastNotification"]
+---
+
 <script>
   import { ToastNotification } from "carbon-components-svelte";
   import Preview from "../../components/Preview.svelte";
 </script>
 
-Toasts are non-modal, time-based window elements used to display short messages;
-they usually appear at the top of the screen and disappear after a few seconds.
+`ToastNotification` displays non-modal, time-based messages that appear at the top of the screen and automatically disappear. It supports various notification types, custom content, and accessibility features.
 
-See [detailed
-usage](https://carbondesignsystem.com/components/notification/usage).  
+See [detailed usage](https://carbondesignsystem.com/components/notification/usage).  
 See also: [InlineNotification](InlineNotification)
 
 ## Default (error)
 
+Display a basic error notification with title, subtitle, and timestamp.
+
 <ToastNotification title="Error" subtitle="An internal server error occurred." caption="{new Date().toLocaleString()}" />
 
 ## Autoclose
 
-By default, `ToastNotification` does not automatically close.
-
 Specify the `timeout` prop to automatically close the notification after a specified duration (in milliseconds).
 
 <FileSource src="/framed/ToastNotification/ToastNotificationTimeout" />
 
 ## Prevent default close behavior
 
-`ToastNotification` is a controlled component. Prevent the default close behavior using the `e.preventDefault()` method in the dispatched `on:close` event.
+Prevent the default close behavior using `e.preventDefault()` in the `on:close` event handler.
 
 <ToastNotification title="Error" subtitle="An internal server error occurred." caption="{new Date().toLocaleString()}" on:close={(e) => {
   e.preventDefault();
@@ -33,12 +35,14 @@ Specify the `timeout` prop to automatically close the notification after a speci
 
 ## Full width
 
-Set `fullWidth` to `true` for the notification to span the full width of its containing element.
+Set `fullWidth` to `true` for the notification to span the full width of its container.
 
 <ToastNotification fullWidth title="Error" subtitle="An internal server error occurred." caption="{new Date().toLocaleString()}" />
 
 ## Slottable title, subtitle, caption
 
+Customize the notification content using slots for more flexibility.
+
 <ToastNotification>
   <strong slot="title">Error: </strong>
   <strong slot="subtitle">An internal server error occurred.</strong>
@@ -47,9 +51,7 @@ Set `fullWidth` to `true` for the notification to span the full width of its con
 
 ## Accessible icon descriptions
 
-The status icon and close button icon descriptions appear on cursor hover and are read
-by assistive technology. Default descriptions are provided in English and can be
-overridden via `statusIconDescription` and `closeButtonDescription`.
+Provide custom descriptions for icons to improve accessibility.
 
 <ToastNotification 
   title="错误"
@@ -60,10 +62,14 @@ overridden via `statusIconDescription` and `closeButtonDescription`.
 
 ## Hidden close button
 
+Create a persistent notification by hiding the close button.
+
 <ToastNotification hideCloseButton kind="warning" title="Scheduled maintenance" subtitle="Maintenance will last 2-4 hours." caption="{new Date().toLocaleString()}" />
 
 ## Notification variants
 
+The component supports different notification types:
+
 <ToastNotification kind="error" title="Error" subtitle="An internal server error occurred." caption="{new Date().toLocaleString()}" />
 <ToastNotification kind="info" title="New updates" subtitle="Restart to get the latest updates." caption="{new Date().toLocaleString()}"  />
 <ToastNotification kind="info-square" title="New updates" subtitle="Restart to get the latest updates." caption="{new Date().toLocaleString()}" />
@@ -73,6 +79,8 @@ overridden via `statusIconDescription` and `closeButtonDescription`.
 
 ## Low contrast
 
+Use low contrast variants for less prominent notifications.
+
 <ToastNotification lowContrast kind="error" title="Error" subtitle="An internal server error occurred." caption="{new Date().toLocaleString()}" />
 <ToastNotification lowContrast kind="info" title="New updates" subtitle="Restart to get the latest updates." caption="{new Date().toLocaleString()}" />
 <ToastNotification lowContrast kind="info-square" title="New updates" subtitle="Restart to get the latest updates." caption="{new Date().toLocaleString()}" />