Accessibility

Commitments

• Native elements first: <dialog>, <details>, the Popover API, real inputs. The browser supplies the semantics and the keyboard.
• APG patterns where the platform has nothing: listbox, combobox, menu, menubar, grid, tabs, window splitter. Arrow keys, Home and End, type-ahead, focus returned to the trigger.
• A visible 2px focus ring on every control, in ink, with offset. Never removed.
• Control boundaries at 3:1 against the ground through --control-border (WCAG 1.4.11). Hairlines stay decorative.
• Text at 4.5:1 or better in both schemes. Emphasis by weight and size; nothing is carried by colour alone, because there is only one.
• prefers-reduced-motion: transitions off, looping demos and unsolicited entry disabled.
• forced-colors: every control keeps a border and a state in system colours.
• Hit targets of 40px on the desktop and 44px at or under 640px.
• Every chart carries a screen-reader table of its data and a keyboard cursor with a status tooltip. Numbers format through Intl.NumberFormat with an optional locale.
• Every interactive component has an axe pass and a keyboard test in the suite.

Naming things

// Controls without visible text take a name
<Switch aria-label="Notifications" />
<Slider aria-label="Volume" />
<Progress label="Uploading" value={40} />
<Spinner label="Loading" />
<LineChart aria-label="Sheets per day" … />

// Field wires label, hint, and error to the control
<Field>
  <FieldLabel htmlFor="email">E-mail</FieldLabel>
  <Input plain id="email" type="email" />
  <FieldHint>We reply within a day.</FieldHint>
  <FieldError>Enter a valid address.</FieldError>
</Field>

// Dialog titles are h2 and name the dialog; the close button gets a label
<Dialog open={open} onClose={close} closeLabel="Close">
  <DialogTitle>Remove this item?</DialogTitle>
  <DialogBody>This can't be undone.</DialogBody>
</Dialog>

Components with visible text name themselves. Components without it (Switch, Slider, icon buttons, charts) accept aria-label or aria-labelledby and pass it to the element that carries the role. Field binds hint and error to its control with aria-describedby and sets aria-invalid while an error is mounted. Dialog, Sheet, and Drawer title themselves from their Title part and describe themselves from Body. Alert is a note by default; pass live only when it appears in response to something.

Testing

// vitest, jsdom
import { render } from "@testing-library/react";
import { axe } from "vitest-axe";
import { Select } from "@noorddev/vlak-react";

it("has no axe violations", async () => {
  const { container } = render(<Select options={cities} aria-label="City" />);
  expect(await axe(container)).toHaveNoViolations();
});

The package suite runs axe on every interactive component and walks the keyboard path for each pattern: open, move, select, dismiss, focus back on the trigger. The same setup works in your project. Test your composition, not the component: the name you passed, the order of fields, the focus target after a dialog closes.

Patterns by component

Each component page carries the full keyboard table and the accessibility notes for that component.