---
title: "Accessibility"
description: "What every component guarantees, and what your app still has to provide."
section: guides
slug: accessibility
url: /docs/accessibility
---

# Accessibility

What every component guarantees, and what your app still has to provide.

Every component ships with the same contract: accessible names, keyboard operation, visible focus, and reduced-motion handling. The library covers the mechanics; you provide the meaning.

## Contract

- **Keyboard complete** — Every control is reachable with Tab and operable with Enter, Space, or arrow keys.
- **Focus is visible** — Focus rings use `--iv_ring` and are never removed. Overlays trap focus and restore it on close.
- **Names come from content** — Labels, `aria-label`, and `aria-labelledby` are wired internally where the component renders text.
- **Reduced motion is respected** — Transitions collapse to 0.01ms when `prefers-reduced-motion: reduce` is set.
- **State is announced** — `aria-expanded`, `aria-selected`, `aria-busy`, `aria-invalid`, and live regions are set by the components.

## Your responsibilities

- Icon-only buttons need an `aria-label` — there is no text to derive a name from.
- Images and avatars need `alt`; decorative icons should be `aria-hidden="true"`.
- Color is never the only signal: badges and alerts also carry text.
- One `h1` per page, and headings in order. Component titles are `h2` in docs, but your app controls its own outline.

## Testing

The standalone Vitest browser suite renders components in Chromium, checks them with axe, and exercises their primary interactions with Testing Library. Violations fail the run; Storybook is only for browsing stories.

```sh
bun run test        # axe + interaction tests
bun run storybook    # inspect manually at :6006
```

## Reduced motion

Component transitions read the `reducedMotion` store. When you build custom motion, do the same with the CSS media query or the store.

```css
@media (prefers-reduced-motion: reduce) {
	.animated {
		transition: none;
	}
}
```

## Related

- [Installation](/docs/installation.md)
- [For agents](/docs/for-agents.md)