docs(list-item): add ux docs

docs/components/lists-tables-trees/list-item.md

@@ -1,9 +1,77 @@
 # List item
 
+The **list item** is the building block used to compose lists.
+Each item represents a single row of content and can contain a heading,
+description, timestamp, metadata, indicators, and actions.
+
 ## Usage ---
 
+List items are designed to be flexible
+and can be used in different containers depending on the context. For example:
+
+- With [cards](../layout-navigation/cards.md)
+  to stack related information together in a compact space.
+- With [popovers](../status-notifications/popover.md)
+  to show items inside a floating container.
+- With [side panels](../layout-navigation/side-panel.md),
+  used when the list is part of the application frame, or contextual to the current page.
+- With [list groups](../lists-tables-trees/list-group.md),
+  to represent a single-column layout that behaves like a simplified table.
+
+The list item can be **read-only** or **support interactions**.
+
+![List item](images/list-item.png)
+
+### When to use
+
+- To construct the [notification pattern](../../patterns/notifications.md).
+- To construct the chat history pattern.
+- When content needs to be shown as a repeatable, scannable row.
+
+### Best practices
+
+- For complex data, use a [table](../lists-tables-trees/overview.md) instead of a list.
+- Keep structure consistent across all list items in the same list.
+
 ## Design ---
 
+### Anatomy
+
+![List item anatomy](images/list-item-anatomy.png)
+
+> 1\. Indicator, 2. Timestamp, 3. Heading, 4. Description, 5. Primary action, 6. Metadata, 7. Quick actions
+
+With the exception of the heading, all items are optional.
+
+### Indicator
+
+The indicator can support icons, [circle status](../status-notifications/circle-status.md),
+or an [avatar](../status-notifications/avatar.md), depending on the content needs.
+
+It also supports an unread state, typically used for
+[notifications](../../patterns/notifications.md).
+
+![List item indicator](images/list-item-indicator.png)
+
+### Actions
+
+The list item supports a primary action aligned with the heading, or quick
+actions placed below the description. 
+Actions can use any button style needed. When there are too many to show inline, condense them into an overflow menu.
+
+![List item actions](images/list-item-actions.png)
+
+### Metadata
+
+It is typically displayed as text-based informational attributes.
+Icons may be added when they improve recognition.
+[Badges](../status-notifications/badges.md) can be used for explicit states or applied labels that should stand out visually.
+
+The metadata does not include an intrinsic overflow behavior.
+How overflow is handled should change according to the layout constraints and information priorities.
+
+![List item metadata](images/list-item-metadata.png)
+
 ## Code ---
 
 ### Example