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.