Skip to content

Instantly share code, notes, and snippets.

@pete-murphy
Last active December 31, 2025 20:52
Show Gist options
  • Select an option

  • Save pete-murphy/71b5da4478bacbcc9f1e962b0013ed00 to your computer and use it in GitHub Desktop.

Select an option

Save pete-murphy/71b5da4478bacbcc9f1e962b0013ed00 to your computer and use it in GitHub Desktop.
Notes on Sara Soueidan Practical Accessibility course

Practical Accessibility

6 Semantic HTML

Importance of marking up tabular data as a <table>, NVDA for example exposes keyboard shortcuts: image

https://download.nvaccess.org/documentation/en/keyCommands.html

6.1 Creating hierarchy and aiding user navigation with HTML (Part 1): Headings structure

Microsoft has an entertaining video depicting a screen-reader user trying to navigate an inaccessible bakery website BingO Bakery: Headings, Landmarks, and Tabs

Why use <section> element?

At one point there was a proposal for a Document Outline Algorithm. Never implemented by any browsers, but it would have used <section> to calculate heading level. Still preferable to use <section> over <div> where appropriate to signal intent and in case of future AT affordance/support for <section> elements (allowing for progressive enhancement is a core principle of web platform).

Interesting note about WCAG conformance and heading hierarchy

All of this means that, technically:

  • You could use more than <h1> and be WCAG-conformant.
  • You could skip heading levels and still be WCAG-conformant.
  • You could not provide a page heading (<h1>) at all, and still be conformant.
  • You could not use headings on your page at all, and still be WCAG Level AA conformant, because Level AA doesn’t mandate the use of headings.

"Content-first design"

A content-first design strategy is often a more bulletproof approach to designing for accessibility

https://stephaniewalter.design/blog/a-designers-guide-to-documenting-accessibility-user-interactions/

Screenshots of landmarks Screen Shot 2025-11-08 at 22 34 58 Screen Shot 2025-11-08 at 22 38 54 Screen Shot 2025-11-08 at 22 39 41 Screen Shot 2025-11-08 at 22 40 11 Screen Shot 2025-11-08 at 22 41 12 Screen Shot 2025-11-08 at 22 41 28 Screen Shot 2025-11-08 at 22 41 45 Screen Shot 2025-11-08 at 22 42 04

I was surprised that hidden wouldn't prevent this name from being exposed:

<body>
  <header>
    ...
    <search aria-labelledby="site-search">
        <span id="site-search" hidden></span> 
      ...
    </search>
  </header>
  <main>
    ...
  </main>
</body>

6.3 Buttons vs. Links: Semantics and Usability

Should you choose a link or button

  • Does the element take the user to another page or a section within the page? If the URL changes when the element is clicked, then what you want is a link.
  • Does the element change something on the current page? If the answer is yes, you probably want a button.
  • Can you right-click the element to open it in a new Window? If not, then it's probably not a link
  • Does the element do anything without JavaScript? (If not, then a button)

Legitimate use cases for "enhancing a link into a button"?

If you use progressive enhancement to enhance static content into interactive widgets, enhancing a link into a button is something you may find yourself doing every now and then.

implicit semantics activated via
<button> button Space, Enter
<a href=..> link Enter only

6.4 Practical semantics: site-wide navigation

Labeling <nav> (navigation landmarks): Don't use "navigation" in the name, because that would be duplicative/redundant

image

7.2 Responsible ARIA: The Rules of ARIA Use in HTML

ARIA is a polyfill for HTML semantics

I hadn't heard it put that way before, but that's a useful quote / way of framing discussion about ARIA use!

[..] Polyfills are a last resort, not a tool to reach for by default.

7.3 The ARIA Authoring Practices Guide (is not a copy-paste cookbook)

Not a spec!

You see, the APG is not a specification. It is, therefore, non-normative. It does not list requirements that you must follow in your work. You may implement a switch component for example or an accordion widget using markup that is different from the markup suggested in the APG. (I do that!) In fact, in some cases, it may even be better if you don’t follow the patterns provided in the APG. It really comes down to what you’re building.

So then, what is the point of APG?

The purpose of these patterns is to demonstrate how to interpret and implement the features of the ARIA specification; so part of their purpose is for testing to see where implementation gaps may be (in browsers or Assistive Technologies (AT)).

Importantly, it doesn't prescribe how to work around lack of support. (Adrian Roselli, for example, has noted that some APG examples use HTML attributes that have no support whatsoever(!))

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment