From 10c20907f8013c1bb5257b634109e1e4abec5e13 Mon Sep 17 00:00:00 2001
From: Gabriel Fouasnon <gabriel@fouasnon.com>
Date: Tue, 3 Oct 2023 16:32:07 +0300
Subject: [PATCH 1/2] call them button-links

---
 docs/user_guide/web-components.rst | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/docs/user_guide/web-components.rst b/docs/user_guide/web-components.rst
index 54bae0db5..f6dddd6d5 100644
--- a/docs/user_guide/web-components.rst
+++ b/docs/user_guide/web-components.rst
@@ -17,8 +17,8 @@ Below you can find some examples of the components created with the :code:`sphin
 
 .. _badges-buttons:
 
-Badges and buttons
-==================
+Badges and button-links
+=======================
 
 Here are some of the available badges:
 
@@ -29,7 +29,7 @@ Here are some of the available badges:
 :bdg-secondary-line:`secondary outline`
 :bdg-success-line:`success outline`
 
-Here are some of the available buttons, also using semantic colors:
+Here are some of the available button-style links, also using semantic colors:
 
 .. grid:: auto
 
@@ -96,6 +96,15 @@ Here are some of the available buttons, also using semantic colors:
 
             Dark
 
+.. note::
+
+   `Sphinx Design buttons
+   <https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html>`__
+   are actually links, meaning they are rendered in HTML with ``<a>`` tags
+   instead of ``<button>``. Use them if you need a link to look like a button,
+   but we discourage this usage because it is not considered good practice for
+   accessibility.
+
 If in your site's `custom CSS file <custom-css>`_ you override the `CSS custom properties <css-variables>`_ ``--pst-color-*`` (where ``*`` is one of the semantic color names, such as ``primary``, ``danger``), badges and buttons will automatically use the custom color.
 
 Cards

From 25b15aa954bc809c83249f9f30d7abdb7182daf0 Mon Sep 17 00:00:00 2001
From: Gabriel Fouasnon <gabriel@fouasnon.com>
Date: Tue, 3 Oct 2023 17:07:58 +0300
Subject: [PATCH 2/2] copy edit

---
 docs/user_guide/web-components.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/user_guide/web-components.rst b/docs/user_guide/web-components.rst
index f6dddd6d5..7a96cb355 100644
--- a/docs/user_guide/web-components.rst
+++ b/docs/user_guide/web-components.rst
@@ -102,8 +102,9 @@ Here are some of the available button-style links, also using semantic colors:
    <https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html>`__
    are actually links, meaning they are rendered in HTML with ``<a>`` tags
    instead of ``<button>``. Use them if you need a link to look like a button,
-   but we discourage this usage because it is not considered good practice for
-   accessibility.
+   however, be aware that they do not follow accessibility best practices for
+   native button components such as using the correct `ARIA attributes
+   <https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/button_role>`__.
 
 If in your site's `custom CSS file <custom-css>`_ you override the `CSS custom properties <css-variables>`_ ``--pst-color-*`` (where ``*`` is one of the semantic color names, such as ``primary``, ``danger``), badges and buttons will automatically use the custom color.