Web accessibility: the accessibility tree, ARIA, focus and testing

HOW IT FITS TOGETHER

KEY TERMS

Semantic HTML first

Use the element whose built-in role and behavior match: button for actions, a href for navigation, real form controls with label, headings in order, landmarks (header, nav, main, footer), lists and tables for lists and tables. One <main> and a logical heading outline give screen reader users the navigation that sighted users get from layout.

The rules of ARIA

Do not use ARIA if a native element or attribute does the job. Do not change native semantics unless you must. Every interactive ARIA control must be keyboard operable. Never put role="presentation" or aria-hidden="true" on a focusable element. Interactive elements need an accessible name. The ARIA Authoring Practices summarize it as "No ARIA is better than bad ARIA": a role is a promise of behavior.

Accessible names

The name is what is announced and what voice control users say. Visible text is the best source; for icon buttons use visually hidden text or aria-label. The name of an input should contain its visible label (WCAG 2.5.3). Placeholders and title are poor names. aria-describedby adds secondary information such as hints and errors after the name.

Focus management and keyboard patterns

Tab moves between widgets; arrow keys move within composite widgets (tabs, menus, listboxes, grids) using roving tabindex or aria-activedescendant. Focus must be visible (:focus-visible, at least 3:1 contrast) and never fully hidden behind sticky content (WCAG 2.2 Focus Not Obscured). Move focus deliberately when context changes: into a dialog, back to the trigger on close, to the new page heading after a client-side route change.

Live regions

Changes that do not move focus (toasts, search result counts, save status, async validation) are only announced through a live region: role="status" or aria-live="polite" for most updates, role="alert" for urgent ones. The region must already exist in the DOM before its content changes; injecting a region together with its text is often not announced.

Color contrast and WCAG 2.2 AA

Text needs 4.5:1 against its background, large text (24px, or about 18.7px bold) 3:1, and UI component boundaries, focus indicators and meaningful graphics 3:1 (1.4.11). Color must not be the only cue. WCAG 2.2 (W3C Recommendation, current edition December 2024) adds at levels A and AA: focus not obscured, target size of at least 24 by 24 CSS pixels or equivalent spacing, alternatives to dragging, consistent help, no redundant entry and accessible authentication; it removes 4.1.1 Parsing.

Testing and the law

Automated tools such as axe-core find a minority of issues (missing names, contrast, invalid ARIA); keyboard-only passes and screen reader testing (NVDA or JAWS with Chrome or Firefox, VoiceOver with Safari, TalkBack on Android) find the rest. The European Accessibility Act (Directive 2019/882) applies since 28 June 2025 to products placed on the EU market and to services such as e-commerce, banking, e-books, transport ticketing and communications; microenterprises providing services are exempt, and existing service contracts may continue for at most five years. Conformance is assessed in practice against EN 301 549: the harmonised V3.2.1 mirrors WCAG 2.1 AA, and V4.1.1 (published September 2026, not yet cited in the Official Journal) adopts WCAG 2.2 AA, so WCAG 2.2 AA is the sensible target.

IN YOUR STACK

<button commandfor="delete-dialog" command="show-modal">Delete project</button>

<dialog id="delete-dialog" aria-labelledby="delete-title" aria-describedby="delete-desc">
  <h2 id="delete-title">Delete "Website redesign"?</h2>
  <p id="delete-desc">This removes 42 files for everyone. It cannot be undone.</p>
  <form method="dialog">
    <button value="cancel" autofocus>Cancel</button>
    <button value="confirm">Delete</button>
  </form>
</dialog>

<script>
  const dialog = document.getElementById("delete-dialog");
  dialog.addEventListener("close", () => {
    if (dialog.returnValue === "confirm") deleteProject();
  });
  // Without invoker commands: openButton.onclick = () => dialog.showModal();
</script>

function Disclosure({ title, children }: { title: string; children: React.ReactNode }) {
  const [open, setOpen] = useState(false);
  const panelId = useId();
  return (
    <div>
      <h3>
        <button
          type="button"
          aria-expanded={open}
          aria-controls={panelId}
          onClick={() => setOpen((o) => !o)}
        >
          {title}
        </button>
      </h3>
      <div id={panelId} hidden={!open}>
        {children}
      </div>
    </div>
  );
}
// No-JS alternative with the same semantics:
// <details><summary>Shipping</summary>...</details>

// Rendered once at app start and kept mounted, so screen readers
// register it before any message is written into it.
function StatusRegion({ message }: { message: string }) {
  return (
    <div role="status" aria-live="polite" aria-atomic="true" className="visually-hidden">
      {message}
    </div>
  );
}

function SearchResults({ query, results, loading }: SearchProps) {
  const message = loading ? "" : `${results.length} results for ${query}`;
  return (
    <>
      <StatusRegion message={message} />
      <ul>{results.map((r) => <li key={r.id}>{r.title}</li>)}</ul>
    </>
  );
}

// Urgent, interrupting messages only:
// <div role="alert">Payment failed. Your card was not charged.</div>

// First focusable element on every page.
// .skip-link { position: absolute; translate: 0 -200%; }
// .skip-link:focus { translate: 0 0; }
export function Layout({ title, children }: { title: string; children: React.ReactNode }) {
  const headingRef = useRef<HTMLHeadingElement>(null);
  const { pathname } = useLocation();
  const firstRender = useRef(true);

  useEffect(() => {
    document.title = `${title} | Acme`;
    if (firstRender.current) { firstRender.current = false; return; }
    headingRef.current?.focus(); // announce the new page, reset tab position
  }, [pathname, title]);

  return (
    <>
      <a className="skip-link" href="#main">Skip to content</a>
      <Header />
      <main id="main" tabIndex={-1}>
        <h1 ref={headingRef} tabIndex={-1}>{title}</h1>
        {children}
      </main>
    </>
  );
}

function SignupForm() {
  const [errors, setErrors] = useState<Record<string, string>>({});
  const summaryRef = useRef<HTMLDivElement>(null);
  function onSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault();
    const data = new FormData(e.currentTarget);
    const found = validate(data); // e.g. { email: "Enter an email like name@example.com" }
    setErrors(found);
    if (Object.keys(found).length === 0) return void signUp(data);
    requestAnimationFrame(() => summaryRef.current?.focus()); // after the summary renders
  }
  const count = Object.keys(errors).length;
  return (
    <form noValidate onSubmit={onSubmit}>
      {count > 0 && <div ref={summaryRef} tabIndex={-1} role="group" aria-labelledby="err-title">
        <h2 id="err-title">Fix {count} problem(s)</h2>
        <ul>{Object.entries(errors).map(([f, m]) => <li key={f}><a href={`#${f}`}>{m}</a></li>)}</ul>
      </div>}
      <label htmlFor="email">Email</label> <input id="email" name="email" type="email" autoComplete="email"
        aria-invalid={!!errors.email} aria-describedby={errors.email ? "email-error" : undefined} />
      {errors.email && <p id="email-error">{errors.email}</p>}
      <button>Create account</button>
    </form>
  );
}

import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";

test("checkout has no automatically detectable WCAG A/AA violations", async ({ page }) => {
  await page.goto("/checkout");
  await page.getByRole("button", { name: "Continue to payment" }).click();
  await page.getByRole("heading", { name: "Payment" }).waitFor(); // let the UI settle

  const results = await new AxeBuilder({ page })
    .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"])
    .exclude("#third-party-chat") // excludes the subtree from every rule
    .analyze();

  expect(results.violations).toEqual([]);
});

test("dialog is keyboard operable", async ({ page }) => {
  await page.goto("/projects/1");
  await page.getByRole("button", { name: "Delete project" }).press("Enter");
  await expect(page.getByRole("dialog", { name: /Delete/ })).toBeVisible();
  await page.keyboard.press("Escape");
  await expect(page.getByRole("button", { name: "Delete project" })).toBeFocused();
});

WHERE IT BITES

• Clickable divs and spans: no role, no focus, no Enter or Space, invisible to voice control. Use button or a href.
• Removing focus outlines (outline: none) without a replacement :focus-visible style, or letting a sticky header cover the focused element.
• Adding ARIA that lies: role="menu" on navigation, aria-hidden on content that is visible or contains focusable elements, aria-label that differs from the visible label.
• Single-page apps that change routes without moving focus or updating document.title, so screen reader users get no sign that anything happened.
• Toasts and inline async errors rendered without a live region, or with a live region mounted at the same moment as its text.
• Treating a clean axe report or an overlay widget as compliance. Neither covers keyboard flows, reading order, meaningful names or the EAA's documentation duties.

WHEN IT BREAKS IN PRODUCTION

• Keyboard and screen-reader users get lost after navigation or a modal
• A modal or dropdown hides behind other content despite a huge z-index

SOURCES

• W3C: Web Content Accessibility Guidelines (WCAG) 2.2 (opens in new tab)Checked 2026-11-06
• WAI-ARIA APG: Read Me First (opens in new tab)Checked 2026-11-06
• MDN: ARIA live regions (opens in new tab)Checked 2026-11-06
• Playwright: Accessibility testing (opens in new tab)Checked 2026-11-06
• AccessibleEU: The EAA comes into effect in June 2025 (opens in new tab)Checked 2026-11-06
• Deque: EN 301 549 v4.1.1 is final (opens in new tab)Checked 2026-11-06
• Directive (EU) 2019/882, Article 4 (opens in new tab)Checked 2026-11-06