diff --git a/docs/badges_buttons.md b/docs/badges_buttons.md
index 9eeaace..9a4c6ac 100644
--- a/docs/badges_buttons.md
+++ b/docs/badges_buttons.md
@@ -60,7 +60,29 @@ See [Bootstrap badges](https://getbootstrap.com/docs/5.0/components/badge/) for
 
 ## Buttons
 
-Buttons allow users to navigate to external (`button-link`) / internal (`button-ref`) links with a single tap.
+Buttons in Sphinx Design are actually links:
+
+- Links that can be styled to look like
+  [Bootstrap buttons](https://getbootstrap.com/docs/5.0/components/buttons/)
+- Links that are either external (`button-link`) or internal (`button-ref`)
+
+Most of the time, you should create links using the link syntax for the language
+you've chosen:
+
+- [Markdown/MyST links and cross-references](https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#examples)
+- [rST links and cross-references](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#hyperlinks)
+
+Sometimes, though, you may want to call attention to a particular link or set of
+links, or set them apart visually from other links on the site.
+
+:::{admonition} Note on accessibility
+
+Despite the name, `button-link` and `button-ref` do **not** convert to
+`<button>` tags in HTML. They are output as `<a>` tags and use CSS to achieve
+the button look. This has important accessibility implications. For example,
+assistive tech will include Sphinx Design "buttons" when asked to present a list
+of all the links on the page.
+:::
 
 ```{button-link} https://example.com
 ```
@@ -139,8 +161,6 @@ Use the `click-parent` option to make the button's parent container also clickab
 
 :::
 
-See the [Material Design](https://material.io/components/buttons) and [Bootstrap](https://getbootstrap.com/docs/5.0/components/buttons/) descriptions for further details.
-
 ### `button-link` and `button-ref` options
 
 ref-type (`button-ref` only)
diff --git a/docs/snippets/myst/button-link.txt b/docs/snippets/myst/button-link.txt
index ed372cf..13303a6 100644
--- a/docs/snippets/myst/button-link.txt
+++ b/docs/snippets/myst/button-link.txt
@@ -1,3 +1,6 @@
+(buttons)=
+## Buttons
+
 ```{button-link} https://example.com
 ```
 
@@ -19,3 +22,13 @@ Button text
 :color: secondary
 :expand:
 ```
+
+```{button-ref} buttons
+:color: info
+```
+
+```{button-ref} buttons
+:color: info
+
+Reference Button Text
+```
diff --git a/docs/snippets/rst/button-link.txt b/docs/snippets/rst/button-link.txt
index d6817f3..106b2d9 100644
--- a/docs/snippets/rst/button-link.txt
+++ b/docs/snippets/rst/button-link.txt
@@ -1,3 +1,8 @@
+.. _buttons:
+
+Buttons
+.......
+
 .. button-link:: https://example.com
 
 .. button-link:: https://example.com
@@ -15,3 +20,11 @@
 .. button-link:: https://example.com
     :color: secondary
     :expand:
+
+.. button-ref:: buttons
+    :color: info
+
+.. button-ref:: buttons
+    :color: info
+
+    Reference Button Text
diff --git a/tests/test_snippets/snippet_post_button-link.xml b/tests/test_snippets/snippet_post_button-link.xml
index b0e1a79..defcce4 100644
--- a/tests/test_snippets/snippet_post_button-link.xml
+++ b/tests/test_snippets/snippet_post_button-link.xml
@@ -2,24 +2,36 @@
     <section ids="heading" names="heading">
         <title>
             Heading
-        <paragraph>
-            <reference classes="sd-sphinx-override sd-btn sd-text-wrap" refuri="https://example.com">
-                <inline>
-                    https://example.com
-        <paragraph>
-            <reference classes="sd-sphinx-override sd-btn sd-text-wrap" refuri="https://example.com">
-                <inline>
-                    Button text
-        <paragraph>
-            <reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-primary sd-shadow-sm" refuri="https://example.com">
-                <inline>
-                    https://example.com
-        <paragraph>
-            <reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-outline-primary" refuri="https://example.com">
-                <inline>
-                    https://example.com
-        <paragraph>
-            <inline classes="sd-d-grid">
-                <reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-secondary" refuri="https://example.com">
+        <target refid="buttons">
+        <section dupnames="buttons" ids="buttons id1" names="buttons">
+            <title>
+                Buttons
+            <paragraph>
+                <reference classes="sd-sphinx-override sd-btn sd-text-wrap" refuri="https://example.com">
                     <inline>
                         https://example.com
+            <paragraph>
+                <reference classes="sd-sphinx-override sd-btn sd-text-wrap" refuri="https://example.com">
+                    <inline>
+                        Button text
+            <paragraph>
+                <reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-primary sd-shadow-sm" refuri="https://example.com">
+                    <inline>
+                        https://example.com
+            <paragraph>
+                <reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-outline-primary" refuri="https://example.com">
+                    <inline>
+                        https://example.com
+            <paragraph>
+                <inline classes="sd-d-grid">
+                    <reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-secondary" refuri="https://example.com">
+                        <inline>
+                            https://example.com
+            <paragraph>
+                <reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-info" internal="True" refid="buttons">
+                    <inline classes="std std-ref std std-ref">
+                        Buttons
+            <paragraph>
+                <reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-info" internal="True" refid="buttons">
+                    <inline classes="std std-ref std std-ref">
+                        Reference Button Text
diff --git a/tests/test_snippets/snippet_pre_button-link.xml b/tests/test_snippets/snippet_pre_button-link.xml
index b0e1a79..d73af94 100644
--- a/tests/test_snippets/snippet_pre_button-link.xml
+++ b/tests/test_snippets/snippet_pre_button-link.xml
@@ -2,24 +2,36 @@
     <section ids="heading" names="heading">
         <title>
             Heading
-        <paragraph>
-            <reference classes="sd-sphinx-override sd-btn sd-text-wrap" refuri="https://example.com">
-                <inline>
-                    https://example.com
-        <paragraph>
-            <reference classes="sd-sphinx-override sd-btn sd-text-wrap" refuri="https://example.com">
-                <inline>
-                    Button text
-        <paragraph>
-            <reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-primary sd-shadow-sm" refuri="https://example.com">
-                <inline>
-                    https://example.com
-        <paragraph>
-            <reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-outline-primary" refuri="https://example.com">
-                <inline>
-                    https://example.com
-        <paragraph>
-            <inline classes="sd-d-grid">
-                <reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-secondary" refuri="https://example.com">
+        <target refid="buttons">
+        <section dupnames="buttons" ids="buttons id1" names="buttons">
+            <title>
+                Buttons
+            <paragraph>
+                <reference classes="sd-sphinx-override sd-btn sd-text-wrap" refuri="https://example.com">
                     <inline>
                         https://example.com
+            <paragraph>
+                <reference classes="sd-sphinx-override sd-btn sd-text-wrap" refuri="https://example.com">
+                    <inline>
+                        Button text
+            <paragraph>
+                <reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-primary sd-shadow-sm" refuri="https://example.com">
+                    <inline>
+                        https://example.com
+            <paragraph>
+                <reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-outline-primary" refuri="https://example.com">
+                    <inline>
+                        https://example.com
+            <paragraph>
+                <inline classes="sd-d-grid">
+                    <reference classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-secondary" refuri="https://example.com">
+                        <inline>
+                            https://example.com
+            <paragraph>
+                <pending_xref classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-info" refdoc="index" refdomain="" refexplicit="False" reftarget="buttons" reftype="any" refwarn="True">
+                    <inline>
+                        buttons
+            <paragraph>
+                <pending_xref classes="sd-sphinx-override sd-btn sd-text-wrap sd-btn-info" refdoc="index" refdomain="" refexplicit="True" reftarget="buttons" reftype="any" refwarn="True">
+                    <inline>
+                        Reference Button Text