Accessibility

Target

Every component aims for WCAG 2.2 AA in both themes and both materials: the WAI-ARIA Authoring Practices pattern for its role, full keyboard operation, a visible focus ring (focus-ring), names for icon-only controls, 4.5:1 text contrast, 24 px minimum targets for pointer controls, logical properties for right-to-left layouts and no motion when the user asks for less. Interactive primitives are built on Radix, which handles focus management and ARIA wiring for overlays, menus and tabs.

How it is tested

Component tests (Vitest + axe)

Each component has a test file next to it, run with Vitest, Testing Library and vitest-axe in jsdom. The shared helper expectNoA11yViolations() renders the component inside the providers and fails on any axe violation. Interaction tests drive the real keyboard through user-event.

Counted from the repository when this page was built. jsdom has no layout, so colour contrast is not part of the unit run; it is checked in the browser runs below.

Blocks, docs and example sites (Playwright + axe)

• 9 Playwright spec files run in Chrome; 8 of them call axe (@axe-core/playwright) and fail on any serious or critical violation.
• Every admin block and every page of every example site is checked at 1440 px and 390 px, together with one landmark, exactly one visible h1 on site pages, no console errors and no sideways scroll.
• Docs component pages are smoke-tested across the theme matrix: light and dark, glass and solid.
• Example sites run axe with colour contrast on. Component and block pages disable the contrast rule, because preview stages put components on decorative backgrounds; contrast for tokens is checked by hand (see known issues).
• Signature interactions (menus, dialogs, sortable lists, language switch) are driven with the keyboard in the browser.

Reduced motion

Motion in the kit (@vamos-ui/react/motion, overlay and collapse transitions) renders its final state under prefers-reduced-motion: reduce or data-motion="off". 2 spec files run whole suites with Playwright's reducedMotion: "reduce" and assert that every heading and section is visible immediately, at 1440 and 390 px. A separate test keeps layout shift on the animated home pages under the 0.1 CLS budget.

Keyboard support

Every interactive component is operable with the keyboard alone. The table lists the components whose docs page documents keys beyond the platform defaults (Tab, Enter, Space on buttons and fields), taken from each page's notes. Buttons, inputs, checkboxes and switches follow native behaviour.

Known issues

• Status colours as plain text. The light-theme success colour was darkened from #0f8a5f (4.36:1 on white) to #0b7d55 (5.15:1), and badges and alerts mix the status hue with the text colour, so their 11–13 px labels pass 4.5:1. The raw hues are still below 4.5:1 as small text directly on the light page background (--scene): success 4.48:1, danger 4.39:1, warning 3.41:1. Use them for icons, dots and large text, or use tone-soft / Badge / Alert for small text.
• Hydration id mismatch under load. A useId mismatch was seen twice on the development server under memory pressure (maintenance and list blocks). It has not reproduced in the static build that ui.vamos.ist serves. While it happens, an aria-labelledby can point at a stale id until React re-renders.
• Unlabelled tables in two blocks (a detail block and an app shell) log a console warning; they need a caption or aria-label.
• Floating contact dock can overlap the booking bar on the restaurant and spa example sites at phone width.
• Charts are images to assistive technology. Each chart frame has a table view and a text summary; the plot itself is not navigable.
• Hover cards do not open from the keyboard or on touch, by design. Their content must be reachable on the link target.
• No manual screen-reader pass (VoiceOver, NVDA, JAWS) has been recorded for every component yet. That is the next step before 1.0.

Your part

• Give every icon-only button a label or aria-label, and every field a visible label through Field.
• Keep one h1 per page and a <main> landmark; the app shell and site shell provide the others.
• A custom accent is contrast-checked by npx vamos-ui brand check; run npx vamos-ui verify in CI for the lint rules.
• Right-click and drag can never be the only path: pair context menus with an action menu and drag with keyboard moves (the kit's sortable parts do this).

Reporting a problem

Found a barrier? Open an issue on GitHub with the component, theme axes, browser and assistive technology. Accessibility bugs are treated like functional bugs.