From 1a5a8a276f41ee5de9fd61d543ea0fd42ddf028a Mon Sep 17 00:00:00 2001
From: William Martin <contact@willmartian.com>
Date: Wed, 28 May 2025 11:00:51 -0400
Subject: [PATCH] update docs

---
 libs/components/src/item/item.mdx | 32 +++++++++++++++++++++++++++++--
 1 file changed, 30 insertions(+), 2 deletions(-)

diff --git a/libs/components/src/item/item.mdx b/libs/components/src/item/item.mdx
index eca8bc9dd57..fbfd1a56e1b 100644
--- a/libs/components/src/item/item.mdx
+++ b/libs/components/src/item/item.mdx
@@ -89,10 +89,10 @@ The content can be a button, anchor, or static container.
 Secondary interactive actions can be placed in the item through the `"end"` slot, outside of
 `bit-item-content`.
 
-Each action must be wrapped by `<bit-item-action>`.
-
 Actions are commonly icon buttons or badge buttons.
 
+Each action must be wrapped by `<bit-item-action>`.
+
 ```html
 <bit-item>
   <button bit-item-content>...</button>
@@ -111,6 +111,31 @@ Actions are commonly icon buttons or badge buttons.
 </bit-item>
 ```
 
+Each action should be a direct descendant of `<bit-item>`--do not wrap actions in another component,
+as this will break accessibility guarantees.
+
+Broken:
+
+```html
+<bit-item>
+  <button bit-item-content>...</button>
+
+  <some-component-that-contains-an-action slot="end"></some-component-that-contains-an-action>
+</bit-item>
+```
+
+Fixed:
+
+```html
+<bit-item>
+  <button bit-item-content>...</button>
+
+  <bit-item-action slot="end">
+    <some-component></some-component>
+  </bit-item-action>
+</bit-item>
+```
+
 ## Text Overflow Behavior
 
 The default behavior for long text is to truncate it. However, you have the option of changing it to
@@ -160,4 +185,7 @@ Use `aria-label` or `aria-labelledby` to give groups an accessible name.
 
 ### Virtual Scrolling
 
+To utilize virtual scrolling, `bit-item-group` should be placed inside of the virtual scroll
+viewport.
+
 <Canvas of={stories.VirtualScrolling} />