Skip to content

Instantly share code, notes, and snippets.

@pete-murphy
Last active November 9, 2025 16:49
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment