From 1ae738286df3ec49098cee61d4d965f7ea0f3589 Mon Sep 17 00:00:00 2001
From: gabalafou <317883+gabalafou@users.noreply.github.com>
Date: Wed, 15 Jul 2026 10:56:35 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20Clarify=20that=20buttons=20are?=
 =?UTF-8?q?=20styled=20links?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Carried from PR #158, updated for the current docs: explains that
button-link/button-ref render as styled <a> tags (not <button>), when to
prefer plain link syntax, and the accessibility implications.
---
 docs/badges_buttons.md | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

diff --git a/docs/badges_buttons.md b/docs/badges_buttons.md
index b222e8c..9564dda 100644
--- a/docs/badges_buttons.md
+++ b/docs/badges_buttons.md
@@ -102,7 +102,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
 ```
@@ -176,8 +198,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)