diff --git a/site/src/content/docs/components/pagination.mdx b/site/src/content/docs/components/pagination.mdx
index 07710af072..063c14eef7 100644
--- a/site/src/content/docs/components/pagination.mdx
+++ b/site/src/content/docs/components/pagination.mdx
@@ -42,11 +42,33 @@ Looking to use an icon or symbol in place of text for some pagination links? Be
`} />
-## Disabled and active states
+## Active
-Pagination links are customizable for different circumstances. Use `.disabled` for links that appear un-clickable and `.active` to indicate the current page.
+Add `.active` to indicate a `.page-item` is the one currently being viewed. If using an `` on the current page, `aria-current="page"` should be added for assistive technologies.
-While the `.disabled` class uses `pointer-events: none` to _try_ to disable the link functionality of ``s, that CSS property is not yet standardized and doesn’t account for keyboard navigation. As such, you should always add `tabindex="-1"` on disabled links and use custom JavaScript to fully disable their functionality.
+
+
+ `} />
+
+If using a non-interactive element, like a `` for the current page, you may omit the `aria-current` attribute.
+
+```html
+
+ 2
+
+```
+
+## Disabled
+
+Add `.disabled` to a `.page-item` to make it appear un-clickable. While `.disabled` uses `pointer-events: none` to disable the link‘s interactivity, that CSS property is not yet standardized and doesn’t account for keyboard navigation. As such, you should always add `tabindex="-1"` on disabled links and use custom JavaScript to fully disable their functionality.
`} />
-You can optionally swap out active or disabled anchors for ``, or omit the anchor in the case of the prev/next arrows, to remove click functionality and prevent keyboard focus while retaining intended styles.
+And just like active page items, you can swap out the disabled `` for a `` to remove click functionality and prevent keyboard focus while retaining intended styles.
-
-
- `} />
+```html
+
+ Previous
+
+```
## Sizing
@@ -88,8 +100,8 @@ Fancy larger or smaller pagination? Add `.pagination-lg` or `.pagination-sm` for