EAA compliance for Astro: WCAG 2.1 AA checklist & fixes

What the EAA actually requires from a Astro site

Astro's zero-JS-by-default, content-first architecture ships complete semantic HTML before any client JavaScript runs, so under the EAA the obligation is narrow and concentrated on its two interactive features. EN 301 549 conformance forces you to treat each hydrated island as a mini-app whose aria-state can be stale until hydration finishes, and to add explicit focus management to View Transitions, which swap the DOM in place and leave focus on an element that may no longer exist. The static content itself is largely accessible by construction, so the requirement is essentially island and transition hygiene.

Astro is chosen for content-heavy sites, marketing pages, and documentation by developer-led teams, so in-scope Astro sites span small startup marketing surfaces and larger content operations. Fine exposure tracks the operator: a small startup faces fixed national penalties, while a large content or commerce business built on Astro could reach turnover-percentage territory. The favourable architecture means the realistic risk is limited to specific interactive components rather than a site-wide failure, so audit findings tend to be few and targeted.

Remediation is a developer task in the codebase: add a handler on the astro:page-load event that moves focus to main on every View Transition, and give each interactive island (React, Vue, Svelte, etc.) its own accessibility review with the appropriate lint plugin. Scan after a hard reload since islands behave differently on first versus subsequent navigations. Because the surface area is small, closing the Astro-specific gaps is usually a quick, well-scoped piece of work.

Top WCAG failures we see on Astro sites

Across hundreds of Astro scans, the same handful of issues show up over and over. None of them require ripping the theme apart — most are fixable in a few hours by someone comfortable in the platform's editor or template files.

• Islands hydrating after assistive tech has already read the page

  Interactive controls inside an island can have stale aria-state until hydration finishes.

  4.1.2, 4.1.3 — Level A/AA

• View Transitions without focus management

  Astro's SPA-style navigation needs explicit focus-on-route-change handling.

  2.4.3 — Level A

Concrete code fixes for Astro

Below are copy-paste fixes for the most common Astro issues. They assume you have access to your theme code or the platform's custom-code injection panel. If you cannot edit code directly, share these snippets with whoever maintains the site — every one of them is a ten-minute change.

<script>
document.addEventListener('astro:page-load', () => {
  const main = document.querySelector('main');
  if (main instanceof HTMLElement) {
    main.setAttribute('tabindex', '-1');
    main.focus();
  }
});
</script>

Tools and plugins worth installing first

• Astro a11y integration

• eslint-plugin-jsx-a11y for islands written in React/Vue

How to scan a Astro site without missing anything

Automated scanners catch about 30–40% of WCAG issues; the rest need manual review. The good news is that the 30–40% includes the most expensive issues to remediate after the fact, so an automated scan is the cheapest way to get unstuck. Run one before you change a line of theme code.

• Scan after a hard reload; islands behave differently on first vs second navigation.