diff --git a/.changeset/quiet-walls-walk.md b/.changeset/quiet-walls-walk.md
new file mode 100644
index 0000000000..bded20978a
--- /dev/null
+++ b/.changeset/quiet-walls-walk.md
@@ -0,0 +1,5 @@
+---
+"@primer/css": minor
+---
+
+Refactors NavigationList to better handle accessibility. Backwards compatible for TreeView CSS.
diff --git a/docs/content/components/action-list.md b/docs/content/components/action-list.md
index 79b1955d56..1296346e2f 100644
--- a/docs/content/components/action-list.md
+++ b/docs/content/components/action-list.md
@@ -7,11 +7,11 @@ bundle: action-list
storybook: https://primer.style/css/storybook/?path=/story/components-actionlist-actionlistitem--playground
---
-Reference the [Action list interface guidelines](https://primer.style/design/components/action-list) for details on where and how to use Action List.
+Reference the [Action list interface guidelines](https://primer.style/design/components/action-list) for details on where and how to use Action list.
## Action list
-Action List is a `ul` list designed to contain Action List Items.
+Action list is a `ul` list designed to contain list items.
### Variants
@@ -20,6 +20,7 @@ Action List is a `ul` list designed to contain Action List Items.
| `ActionList` | Default styles |
| `ActionList--divided` | Show dividers between items |
| `ActionList--subGroup` | If Action List is nested as a sub-list |
+| `ActionList--tree` | Tree-view specific styles |
#### Default
@@ -27,12 +28,12 @@ Action List is a `ul` list designed to contain Action List Items.
- Item label
+ Action list item
- Item label
+ Action list item
@@ -41,21 +42,21 @@ Action List is a `ul` list designed to contain Action List Items.
#### Item dividers
```html live
-
```
@@ -63,30 +64,41 @@ Action List is a `ul` list designed to contain Action List Items.
#### Nested sub list
```html live
-
-
-
- Action list item
-
-
-
-
- Sub menu label
-
-
-
-
- Sub menu item
-
-
-
-
- Sub menu item
-
+
-
+
```
@@ -106,7 +118,11 @@ List item `li` for separating groups of content
```html live
-
+
```
@@ -114,65 +130,71 @@ List item `li` for separating groups of content
```html live
-
+
```
### Divider with label text
-When using a section label for a group, give the `li` an id to be referenced by the group `ul`
+When using a section label for a group, give the `h3` an id to be referenced by the group `ul`
#### Filled with section label
```html live
-
```
@@ -190,79 +212,10 @@ List item `li` handling semantics, state and interactions
| `ActionList-item--navActive` | Nav item and `aria-current` |
| `ActionList-item--danger` | Item is destructive |
-Kitchen sink
-
-```html live
-
-
-```
## Action list item content
-Contains and places all child content within Action List Item. Can be either an `a href` tag for list link items, or a `span` for items that provide an event on Action List Item `li`.
+Contains and places all child elements within action list item. Can be either an `a href` tag for list link items, or a `button` for items that provide an event on Action List Item `li`.
### Variants
@@ -274,6 +227,7 @@ Contains and places all child content within Action List Item. Can be either an
| `ActionList-content--visual16` | Creates left padding for sub list if leading visual exists |
| `ActionList-content--visual20` | Creates left padding for sub list if leading visual exists |
| `ActionList-content--visual24` | Creates left padding for sub list if leading visual exists |
+| `ActionList-content--hasActiveSubItem` | Handles active nav state if child item is active |
| `ActionList-item-action` | min-height + default styles for visual slot |
| `ActionList-item-action--leading` | Slot: multi/single select |
| `ActionList-item-action--trailing` | Slot: Button, collapse icon |
@@ -373,7 +327,7 @@ Contains and places all child content within Action List Item. Can be either an
```html live