[accessibility] Accessibility Audit - 2026-08-29

Audit Summary

• Workflow run: §33253285274
• Standard: WCAG 2.2 Level AA (axe-core 4.13.0 plus manual browser checks)
• Pages audited: 8
• Color schemes audited: light, dark
• Blockers: 1 · Serious: 2 · Advisory: 1

Overview

I served the prebuilt Astro documentation site with npm run docs:preview, derived the published base path from astro.config.mjs (/central-agentic-ops), confirmed the browser preflight log was healthy, and audited the rendered experience in Playwright on a representative sample of eight generated pages:

• /
• /getting-started/
• /configuration/
• /operations/
• /architecture/
• /catalog/
• /catalog/dashboard/
• /deployment-and-governance/

All pages were checked in both light and dark color schemes. Manual checks included keyboard traversal, skip-link behavior, focus visibility, heading/landmark structure, image alternatives, 320px reflow, and reduced-motion handling. The most important issue is a persistent unlabeled theme-toggle button in the site header.

Key Findings

• Blocker: The theme toggle button is keyboard-focusable but has no accessible name on every audited page in both light and dark modes.
• Serious: Starlight aside variants (note, tip, caution, danger) use foreground/background color combinations that fail 1.4.3 contrast thresholds in rendered docs content.
• Serious: Wide tables on the configuration reference page create horizontally scrollable regions that are not keyboard focusable.
• Advisory: Several docs pages render the “On this page” heading before the main h1, which is a confusing heading order even though each page still contains a single h1.

Blockers

• Unlabeled theme toggle button in the global header
  • Affected pages: /, /getting-started/, /configuration/, /operations/, /architecture/, /catalog/, /catalog/dashboard/, /deployment-and-governance/
  • Affected schemes: light and dark
  • Selector: .astro-nvrn6o6l / .right-group > theme-toggle > .astro-nvrn6o6l[type="button"]
  • WCAG: 4.1.2 Name, Role, Value
  • Observed evidence: axe reported button-name with critical impact on all 16 audited page/scheme combinations. Example failing node HTML: <button type="button" class="astro-nvrn6o6l">. In manual keyboard testing, this control receives visible focus after the GitHub repository link, but the focused element exposes no discernible text or label.
  • User impact: Screen-reader and speech-input users cannot identify or reliably operate the color-scheme toggle.
  • Concrete remediation: Give the button a stable accessible name that updates with state, for example aria-label="Switch to dark theme" / aria-label="Switch to light theme", and expose pressed/selected state if appropriate.

Serious Issues

• Insufficient text contrast in Starlight aside variants

  • Affected pages:
    • /getting-started/
    • /configuration/
    • /operations/
    • /architecture/
  • Affected schemes:
    • Light: multiple failures in note/tip/caution/danger callouts
    • Dark: note and danger callouts still miss AA by small margins
  • Representative selectors: .starlight-aside--note > .starlight-aside__title, .starlight-aside--tip > .starlight-aside__title, .starlight-aside--caution > .starlight-aside__title, .starlight-aside--danger > .starlight-aside__title, .starlight-aside__content > p > a
  • WCAG: 1.4.3 Contrast (Minimum)
  • Observed evidence:
    • /getting-started/ light: note title contrast 3.38:1, linked text inside note 3.38:1, caution title 2.01:1.
    • /configuration/ light: tip title 2.36:1, note title 3.38:1.
    • /operations/ light: danger title 3.43:1, tip title 2.36:1, note title 3.38:1, caution titles 2.01:1.
    • Dark mode still fails on some pages, e.g. note title 4.43:1 and danger title 4.37:1, both below the required 4.5:1 threshold.
  • User impact: Low-vision users may not be able to read instructional or warning content embedded in callout boxes, including linked actions.
  • Concrete remediation: Adjust the aside token palette in both schemes so text and interactive content meet AA against their rendered backgrounds; test all semantic aside variants rather than only the default note style.

• Horizontally scrollable tables are not keyboard accessible

  • Affected pages: /configuration/
  • Affected schemes: light and dark
  • Selectors: table:nth-child(17), table:nth-child(31), table:nth-child(47), table:nth-child(54)
  • WCAG: 2.1.1 Keyboard, 2.1.3 Keyboard (No Exception)
  • Observed evidence: axe reported scrollable-region-focusable with serious impact in both schemes. At a 320px viewport the overall page did not overflow the document width, which indicates the tables are contained inside their own horizontal scroll regions; however those regions are not focusable, so keyboard users cannot move focus to the scroll container to explore clipped columns.
  • User impact: Keyboard-only users and some screen magnifier users can miss table content that requires horizontal scrolling.
  • Concrete remediation: Make each scrollable table wrapper focusable (tabindex="0") with an accessible name/instructions if needed, or provide an alternate stacked/table-responsive presentation that preserves access to all columns without requiring pointer scrolling.

Recommended Next Steps

1. Fix the shared header theme-toggle component first, because it is a cross-site blocker affecting every audited page and both themes.
2. Update the Starlight/Galaxy callout design tokens in docs/styles/branding.css or the relevant theme override so all aside variants meet AA in both light and dark schemes; specifically retest note, tip, caution, and danger headings plus inline links.
3. Make responsive table containers keyboard focusable in the docs content renderer and retest /configuration/ at narrow widths with keyboard-only navigation.
4. Review the docs layout component that injects the “On this page” heading so the main h1 is encountered first in heading navigation.
5. After remediation, rerun an accessibility pass on the same eight URLs in both schemes to confirm the shared-component fixes remove the repeated failures site-wide.

network:
  allowed:
    - defaults
    - "mtalk.google.com"
    - "www.gstatic.com"

Generated by ♿ Accessibility Expert · pi · gpt54 · 26.7 AIC · ⌖ 6.82 AIC · ⊞ 4.6K · ◷

• expires on Sep 12, 2026, 12:57 PM UTC