Accessibility

Contract

Apply these requirements when adding or changing installable UI under the registry. Prefer native HTML semantics before ARIA.

• Keyboard navigation. All interactive behavior is reachable with a keyboard. Tab order follows visual order.
• Focus visibility. Focused controls show a visible focus-visible ring (or equivalent).
• Focus management. Overlays move focus into the surface on open and restore it to the trigger on close when appropriate.
• Escape. Dismissible overlays close on Escape without trapping the keyboard.
• Enter / Space. Buttons and button-like controls activate with Enter and Space where native semantics require it.
• ARIA roles and states. Prefer native elements. When custom widgets are required, expose correct roles, states, and properties.
• Accessible name. Every control has an accessible name (label, aria-label, or labelled-by).
• Disabled state. Disabled controls are not operable and communicate the disabled state to assistive technology.
• Loading state. Loading UI exposes polite status text or an equivalent accessible announcement when it matters.
• Touch targets. Primary interactive targets aim for comfortable hit areas (about 44×44 CSS px where practical).
• Reduced motion. Non-essential motion respects prefers-reduced-motion.
• No keyboard trap. Users can always move focus away from a component with standard keys.

Testing convention

• Prefer Testing Library queries by role and accessible name.
• Cover keyboard activation for primary interactions.
• For overlays, assert Escape closes and focus returns when applicable.
• Assert disabled controls cannot be activated.
• Do not require axe or a dedicated a11y runner for every component.