Review/fix examples for accessibility #a11y

[patrickhlauke]

With apologies for a rather high-level/vague issue (compared to more specific listings / PRs with proposed fixes), but: having skimmed a few of the examples provided on https://htmx.org/examples/ I'd note that the majority of the ones I've checked seem to lack at least a few basic keyboard accessibility requirements.

For demos involving buttons, there is currently no actual visible focus indication for when a button has/hasn't got focus.

Beyond that, a few specific issues:

• the tab example is not keyboard-accessible (those <a> elements, since they lack an actual href, don't receive keyboard focus)
• the reordering example can only be operated with the mouse

I was hoping to be able to jump in and evaluate the examples further for screen reader support (and in particular checking that focus is handled correctly/isn't lost and reset when fragments are reloaded/replaced), but these initial keyboard access problems are already an early-warning sign that there's likely further / more fundamental problems here that need to be addressed first, before even going down the SR testing/improvements route.

[patrickhlauke]

more bits/context here https://mastodon.social/@sil/110340406008743130 including

• progress bar demo: after activating the button, focus is lost (as the button is replaced wholesale with the progress indicator, removing the currently focused element from under keyboard users' feet, which - in combination with some screen readers - results in focus being reset to the start of the page). this would be a great excuse to show how authors should actually handle focus programmatically in these cases...

[dz4k]

Possible mitigations:

• Find/write good JS-based headless UI components that integrate well with htmx (emit events)
• Experiment with implementing keyboard interactions with hx-on
• Log console errors for common pitfalls:
  • if focus moves the the body after swapping
  • if an with htmx attributes lacks an href (we could also automatically add one)
  • ...

[MarcusMorba]

I totally agree. Especially all examples in the "documentation" with "div-buttons" should use "button"-tag instead or add the required role and aria-attributes. Details and examples can be found on the ARIA Authoring Practices Guide (APG): https://www.w3.org/WAI/ARIA/apg/patterns/button/

Examples I viewed: https://htmx.org/docs/#introduction

[hibachrach]

I'd also note that the modal dialog examples fail in at least a few ways:

• Esc does not hide the modal dialog
• Tab navigation is not trapped inside of the dialog
• Initial focus is not set on something sensible (e.g. the exit button)

In terms of impact, note that "examples" are often interpreted by developers as "the right way to do X" or "copy this source code", so this could have consequences for websites built by folks new to HTMX.

[Telroshan]

PRs are always welcome to improve documentation btw, if you feel like it!