Accessibility

Every interactive component is built on React Aria Components, Adobe's library of accessible primitives. Desyne adds styling; the behaviour (roles, keyboard interaction, focus management, announcements) comes from React Aria, which is tested across browsers, screen readers and input methods.

What you get for free#

Focus#

The focus ring only appears for keyboard users. React Aria sets data-focus-visible when focus arrives from the keyboard, and components style that state:

export const focusRing =
  "outline-none data-focus-visible:ring-[3px] data-focus-visible:ring-ring/25";

Fields show focus on the group (data-focus-within) with a brand-colored border and glow, so the ring wraps prefixes and suffixes too.

Overlays manage focus for you. A Dialog or Sheet moves focus inside when it opens, keeps Tab inside while open, closes on Escape and returns focus to the trigger. Use autoFocus on a field to choose where focus starts:

<DialogContent>
  <DialogHeader>
    <DialogTitle>Rename project</DialogTitle>
  </DialogHeader>
  <TextField label="Name" defaultValue="Atlas" autoFocus />
</DialogContent>

Keyboard reference#

Screen readers#

Components announce the right thing as long as each control has a name.

• Prefer visible labels. Pass label to fields. It renders a real <label> linked to the input.
• Name controls without a visible label with aria-label: icon-only buttons, search fields in toolbars, sliders in compact layouts.
• Name collections and groups. Tables, list boxes, tag groups, radio groups and toggle groups need aria-label (or a label) so users know what they're in.
• Write good descriptions. description is read after the label; keep it to one short sentence.
• Announce async results. Use toast() for confirmations and background results; the toast region is a live region.

<SearchField aria-label="Search invoices" size="sm" />

<Table aria-label="Invoices" selectionMode="multiple">…</Table>

<ToggleButtonGroup aria-label="Text alignment">…</ToggleButtonGroup>

What you still own#

React Aria makes each component accessible. A page also needs:

• Structure. One <h1>, headings in order, and landmarks (<header>, <nav>, <main>, <footer>).
• Contrast. The default tokens meet WCAG AA for text. If you change --primary, --brand or --muted-foreground, re-check text at 4.5:1 and UI parts at 3:1.
• Text alternatives. alt on meaningful images, alt="" on decorative ones.
• Link and button text that makes sense out of context ("Download invoice", not "Click here").
• Target size. The smallest controls (xs, 24px) meet WCAG 2.2's 24×24px minimum. Use md or lg sizes for primary actions on touch screens.
• Errors you can find. For long forms, move focus to the first invalid field on submit (React Aria's Form does this for native validation) or show a summary.
• No nested interactive elements. Don't put a button inside a clickable card; use the card's own href or a single link that covers it.

Testing#

By hand (5 minutes per screen)#

1. Unplug the mouse. Tab through the page: is the order logical, is focus always visible, can you reach and operate everything?
2. Open and close every overlay with the keyboard. Does focus return to where it was?
3. Zoom to 200% and check nothing overlaps or is cut off.
4. Turn on a screen reader (VoiceOver: ⌘ + F5; NVDA on Windows) and move through the main flow. Does every control announce a name, role and state?

Automated#

axe-core catches missing names, contrast issues and invalid ARIA. Run it in end-to-end tests:

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

test("settings page has no detectable a11y violations", async ({ page }) => {
  await page.goto("/settings");
  const results = await new AxeBuilder({ page }).analyze();
  expect(results.violations).toEqual([]);
});

Test behaviour the way users reach it, by role and name, with Testing Library:

import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { Select, SelectItem } from "@/components/ui/select";

test("picks a plan with the keyboard", async () => {
  const user = userEvent.setup();
  render(
    <Select label="Plan" placeholder="Choose a plan">
      <SelectItem id="free">Free</SelectItem>
      <SelectItem id="pro">Pro</SelectItem>
    </Select>,
  );

  await user.tab();
  await user.keyboard("{ArrowDown}");
  await user.click(screen.getByRole("option", { name: "Pro" }));

  expect(screen.getByRole("button", { name: /Plan/ })).toHaveTextContent("Pro");
});

Automated tools find roughly a third of issues. Keep the manual pass.