From 297cb641825e54b199d1f0f1ee55a4cfb8da186c Mon Sep 17 00:00:00 2001
From: Eric Liu <ericyl.us@gmail.com>
Date: Sat, 3 May 2025 10:24:19 -0700
Subject: [PATCH] docs(ordered-list): improve docs

---
 docs/src/pages/components/OrderedList.svx | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/docs/src/pages/components/OrderedList.svx b/docs/src/pages/components/OrderedList.svx
index 40fe78b1..784f118d 100644
--- a/docs/src/pages/components/OrderedList.svx
+++ b/docs/src/pages/components/OrderedList.svx
@@ -7,14 +7,18 @@ components: ["OrderedList", "ListItem"]
   import Preview from "../../components/Preview.svelte";
 </script>
 
+`OrderedList` provides a structured way to display numbered lists of items. It supports nested lists, native browser styles, and expressive typography for enhanced visual hierarchy.
+
 <InlineNotification svx-ignore lowContrast title="Tip:" kind="info" hideCloseButton>
   <div class="body-short-01">
     Consider using the <Link href="/components/RecursiveList#ordered">RecursiveList</Link> component for rendering tree structured data.
-   </div>
+  </div>
 </InlineNotification>
 
 ## Default
 
+Create a basic ordered list by wrapping `ListItem` components within `OrderedList`.
+
 <OrderedList>
   <ListItem>Ordered list item</ListItem>
   <ListItem>Ordered list item</ListItem>
@@ -23,6 +27,8 @@ components: ["OrderedList", "ListItem"]
 
 ## With links
 
+Add interactive elements like `Link` components within list items.
+
 <OrderedList>
   <ListItem>
     <Link href="#">Ordered list item</Link>
@@ -37,6 +43,8 @@ components: ["OrderedList", "ListItem"]
 
 ## Nested
 
+Set the `nested` prop to `true` to create hierarchical lists with proper indentation and numbering.
+
 <OrderedList>
   <ListItem>
     Ordered list level 1
@@ -57,7 +65,7 @@ components: ["OrderedList", "ListItem"]
 
 ## Native list styles
 
-Use the `native` attribute to enable default browser list styles. This is useful for large lists (i.e., 1000 or more items) where the list number may overlap with the list item text.
+Enable native browser list styles by setting the `native` prop to `true`. This is useful for large lists where the list number may overlap with the list item text.
 
 <OrderedList native>
   <ListItem>
@@ -79,7 +87,7 @@ Use the `native` attribute to enable default browser list styles. This is useful
 
 ## Expressive styles
 
-Set `expressive` to `true` to use Carbon's expressive typesetting.
+Use Carbon's expressive typesetting by setting the `expressive` prop to `true`.
 
 <OrderedList expressive>
   <ListItem><Link size="lg" href="#">Ordered list item</Link></ListItem>