Clarify the meaning of button in the docs

[gabalafou]

This pull request seeks to clarify the relationship between Sphinx Design buttons and HTML buttons.

It updates the language in the docs. It also fixes an issue where some of the button examples were not inclued in the accompanying code snippet.

---

Here's the backstory. This came up for us over at Pydata Sphinx Theme (PST) as we were fixing accessibility issues. We realized that the PST buttons were not actually being output in HTML as <button>s. When I dug in, I realized that the buttons in PST were actually from Sphinx Design. Then I realized that the Sphinx Design buttons were not actually buttons, not in the HTML sense; they're actually links, and therefore it makes sense to use <a> tags rather than <button> tags. That said, I felt there was room for improvement in the docs to make this point clearer, so I created this PR.

There is a separate, related accessibility question about whether links should be styled to look like buttons, but that would require backwards-incompatible changes.

For more information, please refer to Ashlee M Boyer's post, Should I Use a Button or a Link?

[welcome]

Thanks for submitting your first pull request! You are awesome! 🤗

If you haven't done so already, check out EBP's Code of Conduct and our Contributing Guide, as this will greatly help the review process.

Welcome to the EBP community! 🎉

[codecov]

Codecov Report

All modified lines are covered by tests ✅

see 1 file with indirect coverage changes

📢 Thoughts on this report? Let us know!.

[chrisjsewell]

There is a separate, related accessibility question about whether links should be styled to look like buttons

Heya cheers, the reason they are links, is because sphinx does not have a "concept" of buttons, i.e. no built-in nodes for them.
The button roles/directives use the built-in reference and pending_xref nodes: https://github.com/executablebooks/sphinx-design/blob/18fe5dfb025204f0d797ddde3d220e9682e9db70/sphinx_design/badges_buttons.py

It may be difficult to work around this limitation, without any upstream changes in sphinx

[gabalafou]

Added some inline comments to help with review

[gabalafou]

I removed the link to Material Design here because I couldn't actually figure out how it was related to this section. I mean, I understand that Sphinx Design either depends on or takes inspiration from Material Design, but I just couldn't figure out how the information on the page about Material Buttons was supposed to help me use the SD directives, button-link and button-ref, documented here.

I moved the link to Bootstrap buttons up near the top and in a context that I'm hoping makes it seem more like an optional and auxiliary reference than it does here.

I also got feedback from one of my colleagues that these links (which take you to docs about buttons) made it harder to determine from this section of the SD docs if SD buttons were supposed to be buttons or links.

[gabalafou]

Had to add this in order to get the tests to pass, otherwise I would get:

WARNING: 'any' reference target not found: buttons

[gabalafou]

Ditto for this. Added to make tests pass. Patterned after the card-link snippet

[chrisjsewell]

Looks like some change in sphinx is messing up all the tests, I'll have a look

[gabalafou]

Looks like some change in sphinx is messing up all the tests, I'll have a look

Thank you 🙏

[gabalafou]

Heya cheers, the reason they are links, is because sphinx does not have a "concept" of buttons, i.e. no built-in nodes for them.

Yeah, but I actually think it would be a mistake to output either of Sphinx Design's button-link or button-ref as <button>. Both of these represent a thing you can activate to take you to a new location, therefore from my point of view (see the blog post I linked earlier), they are in fact links and should be output as <a> tags, exactly as Sphinx Design is currently doing.

The question I'm getting at is whether it's a good idea for these components to even exist. From an accessibility standpoint, especially when we think of cognitive accessibility and making intuitive, standards-based graphical interfaces, if there is a clear and valid semantic distinction between links and buttons and we want to keep that semantic distinction clear (a lot of assumptions here), then I think it's a mistake to make links look like buttons, or vice versa, to make buttons look like links. Their visual styles should be respectively distinct so as to reenforce the semantic and UX/behavioral distinctions between the two.

My cynical take is that links that look like buttons on the web are more the result of marketing teams wanting to increase click-through rates rather than careful usability considerations.

Granted, I can imagine that there are edge cases where one could argue for making a link look like a button.

I tried to use language in the docs that accords with all of this without going too deep into the details.

[gabalafou]

Gentle bump. Is there anything I can do to help this along?

[chrisjsewell]

The documentation improvements from this PR have now landed on main via #287, with your commit authorship preserved — the "buttons are styled links" introduction and the accessibility guidance now lead the buttons section, replacing the old Material-Design framing.

The snippet/fixture changes that were also in this branch were superseded in the meantime by the broader test-suite and docs rewrites (#281 and friends), so there was nothing further to carry over.

Closing now that everything here is on main — thanks @gabalafou for the contribution, and apologies it took so long to get it in!

---

Generated by Claude Code