Accessibility audit with several findings (serious and best practise)

[markteekman]

What version of starlight are you using?

Latest

What version of astro are you using?

Latest

What package manager are you using?

pnpm

What operating system are you using?

Mac

What browser are you using?

Chrome and Firefox

Describe the Bug

Accessibility audit

As promised a while ago here: #1950 (comment) I spent a couple of hours to do a thorough audit of the Astro Starlight theme accessibility wise. The theme is really solid already, so this list consist mainly of findings to further improve the accessibility:

⚠️ Serious

• Elements must meet minimum color contrast ratio thresholds.
  • Found on: https://starlight.astro.build/guides/authoring-content/ (in dark mode).
  • Comments in examples in dark mode just mis a tiny bit to meet the minimal requirement of 4.5:1. Although I would suggest to aim a little higher, 6:1 for example.
  • Screenshot:
    
• Heading structures should follow the numerical flow (h1 > h2 > h3 etc.)
  • Found on: https://starlight.astro.build/getting-started/
  • There is an h2 before the h1 on the page ("On this page" in the sidebar)
  • Screenshot:
    
• Interactive elements should have at least one or more visual indicators (besides color).
  • Found on: https://starlight.astro.build/.
  • The buttons and link in the hero have no hover/focus effect, consider for example:
    • Changing the underline on hover/focus.
    • Changing te background color on hover/focus.
    • Animating the icons on hover/focus.
    • Screenshot:
      
• Links opening in a new tab should announce it to the screen reader.
  • Found on: https://starlight.astro.build/.
  • Normally when a link opens in a new tab you would want to visually and textually represent that. Visually can be done through an icon and textually is normally done with an sr-only span that says "Opens in a new tab". On the homepage however there is a link with such an icon but it doesn't open in a new tab. Consider opening in a new tab or removing the icon so it's not potentially confusing.
  • Screenshot:
    
• Provide screen reader feedback when using "Copy to clipboard".
  • Found on: https://starlight.astro.build/getting-started/.
  • When using the screen reader and when copying code from a terminal example, a popup shows up with "Copied!" but this isn't communicated to the screen reader. Consider using an aria-live region for this.
  • Visual side note: there's a little gap between the arrow and the box.
  • Screenshot:
    
• Search bar.
  • Found on: https://starlight.astro.build.
  • When using the keyboard to navigate and pressing enter on "Load more results" the focus should be set on the first item of the newly loaded results. Instead, the focus is set back on the window forcing the user to tab back into the search and through all the previous results to get to the new results. Video: https://github.com/user-attachments/assets/e16f157f-fa12-45a5-a162-46fe342c1b32
  • Consider improving the "Load more results" button by saying "Load more results for {search input}".
  • When typing in a search query it would be benificial for screen reader users to hear what the search query gives back on results. So you visually see "10 results for npm" for example. This should be announced to the screen reader as well, using an aria-live region.
  • Consider improving the screen reader only text for the clear button from "Clear" to "Clear search input".
  • Consider using a role="combobox" for a better screen reader experience and provide arrow key up/down interaction on the results list for an improved keyboard experience. Example setup I made for another project:

<search>
  <form action="/search">
    <label for="search-field" class="sr-only">Search documentation</label>
    <div>
      <input
        type="text"
        autocomplete="off"
        placeholder="Search documentation"
        aria-controls="search-results-list"
        aria-autocomplete="list"
        aria-expanded="false"
        role="combobox"
      >
      <button type="button" aria-label="Clear search input">×</button>
      <div>
        <kbd>⌘</kbd>
        <kbd>K</kbd>
      </div>
      <button type="submit" aria-label="Search">🔍</button>
    </div>
    <div hidden>
      <div>
        <p>No results found</p>
      </div>
      <ul id="search-results-list" role="listbox"></ul>
      <div>
        <div>
          <kbd>Enter</kbd> <span>to select</span>
        </div>
        <div>
          <kbd>↓</kbd> <kbd>↑</kbd> <span>to navigate</span>
        </div>
        <div>
          <kbd>Esc</kbd> <span>to close</span>
        </div>
      </div>
    </div>
  </form>
</search>

• When on a resolution of 1280x1024 and zoomed in 400%, the fixed elements on the page block a lot of the pages content.
  • Found on: https://starlight.astro.build/getting-started/.
  • Consider maybe hiding the main menu when scrolling down and showing it when scrolling up.
  • Screenshot:
    

♿ Best practices

• Tabs.
  • Found on: https://starlight.astro.build/guides/authoring-content/.
  • Use button instead of a for tab buttons.
  • Further improve relationship by using aria-controls="tabpanel-id" on the tab button.
  • Consider moving the focus to the first item when the focus is on the last item and the user presses the left arrow key and vice versa.
  • Example: https://www.w3.org/WAI/ARIA/apg/patterns/tabs/examples/tabs-automatic/.
  • Astro example: https://accessible-astro.netlify.app/accessible-components/ (down the page).
  • Screenshot:
    
• Header social icons.
  • Found on: https://starlight.astro.build/.
  • Consider improving screen reader text to "Visit GitHub repository" and "Open Discord server" respectively.
  • Screenshot:
    
• Text styled as heading not marked up as heading.
  • Found on: https://starlight.astro.build/.
  • Text that is made to look like a heading benefits from being marked up as a heading as well, it's also better for SEO. The features on the homepage would benefit if the span is replaced with an h2.
  • Screenshot:
    
• Distinct landmarks using aria-label.
  • Found on: https://starlight.astro.build/getting-started/.
  • To help screen reader users navigate, label your landmarks if there are more then one of the same on the page, such as for the right sidebar, which could be <aside aria-label="On page navigation"> for example.
  • Screenshot:
    
• General.
  • Don't use color alone to provide visual cues for links and other interactive elements. Many links use only color to indicate interactivity, which might not be enough for visually impaired users.
  • Consider using extra visual cues such as underlines or animating an icon that's associated with a link. For links that already have an underline you can remove the underline. You can also give underlines visual appeal / transitioning effects using text-underline-offset and text-decoration-thickness for example.
  • The same is true for the link in the banner: "Updating to Astro 5? Learn how to upgrade".
    • Examples:
      
      
  • Consider not relying on the browsers focus outline but instead provide one to be consistent across browsers and color schemes. For example, here's the difference between Firefox and Chrome:
    • Firefox:
      
    • Chrome:
      
  • Using something like the code below gives a consistent focus outline for interactive elements:

@mixin outline {
 outline: 2px dotted black;
 outline-color: black;
 outline-offset: 0;
 -webkit-box-shadow: 0 0 0 2px white;
 box-shadow: 0 0 0 2px white;
}

*:focus,
*:focus-visible {
 @include outline;
}

*:focus:not(:focus-visible) {
 outline: none;
 box-shadow: none;
}

• Consider improving the logo's sr-only to "Starlight logo - Go to homepage".
• Consider adding an accessibility statement: https://www.w3.org/WAI/planning/statements/.

Also, I don't want this list to come over like a complaint, because Starlight is really, really well made accessibility wise! These are just some of my findings and a deep dive audit of how I normally audit projects at my work. Let me know if these will be taken in consideration, I'll be happy to assist by submitting a PR, especially since I'll be using the theme in the near future and need it as accessible as possible 🙂

Link to Minimal Reproducible Example

https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics?file=README.md

Participation

• I am willing to submit a pull request for this issue.

[delucis]

Thank you @markteekman! Appreciate you taking the time to share these.

Would you mind also sharing some resources around how you determined what is serious, what is a best practice, etc.? There are some of these where I don’t necessarily agree with the analysis/recommendation, so I’m curious to learn more about the reasoning behind them. For example, are there specific WCAG success criteria that you feel are not met? If so, which ones? That kind of thing would be super helpful.

[delucis]

Quick responses to the “serious” items:

• Elements must meet minimum color contrast ratio thresholds.

Definitely. Should be fixed by #2708.

• Heading structures should follow the numerical flow (h1 > h2 > h3 etc.)

This recommendation usually applies to the page’s main content. Use of heading levels that don’t start at h1 (such as the h2 you highlighted) is allowable outside of the primary content.

• Interactive elements should have at least one or more visual indicators (besides color).

These buttons have a clear visual indication from their context and the background colour on the “Get started” link. Hover/focus styles would be nice but not an accessibility fix as they don’t help users who can’t hover/focus.

• Links opening in a new tab should announce it to the screen reader.

That link doesn’t open in a new tab.

• Provide screen reader feedback when using "Copy to clipboard".

Agreed. This will need fixing upstream in Expressive Code. I’ll try to find time to make a PR there — the fix shouldn’t be too hard I don’t think.

• Search bar.

I’d definitely love to improve things here. On top of the items you highlighted, basic QoL keyboard navigation is also not that great.

The current implementation is the default UI provided by the Pagefind library. In all likelihood, we need to build our own UI entirely from scratch to get everything we need. It’s something @HiDeoo and I have discussed and want to get to eventually, but obviously it’s also a pretty major undertaking.

• When on a resolution of 1280x1024 and zoomed in 400%, the fixed elements on the page block a lot of the pages content.

This is a known issue, reported in #316.

[markteekman]

Hey Chris, my apologies, I should have provided more context to why I marked something as serious vs best practice. To be honest, I tend to mark more findings as serious which is purely subjective because I believe in building the most accessible experience possible, not just meeting minimum requirements. While complying with WCAG success criteria is important, we can often improve the UX for people with disabilities even further by implementing additional best practices. With that said, let me distill this list further, as most items should actually be categorized as best practices 🙂

Also, I removed the point about headings. I learned something new here - I didn't realize heading hierarchy was specific to landmarks! I was misled by an outdated tool I use (HeadingsMap) that flags these as errors. So thanks for that 😄

Anyway, here's a more accurate list of the findings:

⚠️ Serious

Elements must meet minimum color contrast ratio thresholds

• Found in: Dark mode code comments
• Required: Yes
• Success criteria: 1.4.3 Contrast (Minimum)
• Note: The contrast ratio must be at least 4.5:1 for regular text (like you mentioned that should be fixed in Fixes code example colour contrast #2708)

Fixed elements blocking content at 400% zoom

• Found in: Navigation at 1280x1024 resolution
• Required: Yes
• Success criteria: 1.4.10 Reflow
• Note: Content must be readable and functional when zoomed to 400% (as you've mentioned reported in Sticky navigation consumes too much vertical space when zoomed in #316)

♿ Best Practices

Interactive elements visual indicators

• Found in: Hero buttons and links
• Required: No, but recommended
• Related success criteria: 1.4.1 Use of Color
• Note: While not strictly required, visual indicators improve usability

Links opening in new tab announcement

• For this one I actually know it doesn't open in a new tab, but the visual icon used suggests it does which can (but doesn't have to be) confusing for some people as to what they're expecting.

Copy to clipboard feedback

• Found in: Code block copy buttons
• Required: No, but recommended
• Related success criteria: 4.1.3 Status Messages
• Note: Status updates improve screen reader user experience

Search bar improvements

• Found in: Global search functionality
• Required: No, but recommended
• Related success criteria: 2.4.3 Focus Order
• Note: Suggested improvements for better keyboard and screen reader experience

Tabs implementation

• Found in: Content tabs
• Required: No, but recommended
• Related success criteria: 4.1.2 Name, Role, Value
• Note: Following ARIA patterns improves usability

Header social icons improved labeling

• Found in: Header navigation
• Required: No, but recommended
• Related success criteria: 2.4.6 Headings and Labels
• Note: More descriptive labels improve understanding

Text styled as heading markup

• Found in: Homepage features section
• Required: No, but recommended
• Related success criteria: 1.3.1 Info and Relationships
• Note: Semantic markup improves document structure

Distinct landmarks using aria-label

• Found in: Page navigation areas
• Required: No, but recommended
• Related success criteria: 1.3.1 Info and Relationships
• Note: Labeled landmarks improve navigation

General improvements

• Found in: Throughout the site
• Required: No, but recommended
• Related success criteria: Multiple
• Note: Includes focus styles, underlines, and consistent visual indicators

[delucis]

Thanks for the extra links — that is super helpful! Will make some time to look at these in more detail.