Accessibility

Accessible by default.

Svelte Atoms components are built with accessibility in mind, following WCAG 2.1 guidelines and best practices.

Overview

All components follow the WAI-ARIA Authoring Practices Guide — keyboard, ARIA, and focus management built in.

@svelte-atoms/core follows the WAI-ARIA Authoring Practices Guide (APG) to ensure components are accessible to assistive technology users. Every component includes proper ARIA attributes, keyboard navigation, focus management, and semantic HTML by default — you do not need to add these manually.

Keyboard Navigation

All interactive components support full keyboard navigation with intuitive key bindings.

ARIA Attributes

Components automatically apply proper ARIA attributes for screen reader compatibility.

Focus Management

Focus is automatically managed in modals, dialogs, and other overlay components with focus trapping.

Semantic HTML

Components use semantic HTML elements and can be customized with the "as" prop.

Screen Reader Support

All components work seamlessly with popular screen readers like NVDA, JAWS, and VoiceOver.

Color Contrast

Default theme colors meet WCAG AA contrast requirements (4.5:1 minimum).

Reduced Motion

Components respect the prefers-reduced-motion user preference.

Keyboard navigation

All interactive components support standard keyboard interactions out of the box.

Universal

Tab Move focus to the next focusable element

Shift+Tab Move focus to the previous element

Enter Activate buttons and links

Space Activate buttons, toggle checkboxes

Escape Close dialogs, drawers, and popovers

Lists & Menus

↑ ↓ Navigate menu and list items

Home Jump to first item

End Jump to last item

Tabs

← → Navigate between tabs

Home Jump to first tab

End Jump to last tab

ARIA attributes

Components automatically manage ARIA attributes for roles, states, and element relationships.

All ARIA state attributes are managed reactively by the Bond system — they update whenever component state changes without any manual wiring. You can override them when needed by passing the attribute directly as a prop.

aria-expanded Collapsed / expanded state

aria-selected Selection state (tabs, menu items)

aria-checked Checkbox state, including mixed

aria-disabled Disabled state

aria-haspopup Triggers a popup element

aria-controls Links trigger to controlled element

aria-labelledby Associates a visible label

aria-describedby Associates a description

aria-hidden Hides decorative elements

aria-live Announces live region updates

Focus management

Automatic focus trapping, restoration, and visible indicators for keyboard navigation.

Focus Trap

Modal components (Dialog, Drawer) trap focus within their boundaries. Tab and Shift+Tab cycle through focusable elements without leaving the overlay.

Focus Restoration

When a modal closes, focus automatically returns to the trigger element. Users never lose their place in the document.

Initial Focus

Overlays focus the first focusable element when opened, or the overlay itself if no focusable children are present.

Visible Focus Indicators

All interactive elements use :focus-visible for clear keyboard focus rings that do not appear on mouse click.

Focus trap example

Focus restoration example

Semantic HTML

Components use proper semantic elements and can be overridden with the as prop.

Semantic elements convey meaning to screen readers, search engines, and browser accessibility APIs. All components default to the semantically correct element. Use the as prop to override when needed while preserving all behavior.

Screen reader support

Proper labeling, announcements, and semantic structure for assistive technologies.

Accessible Names

Use aria-label or aria-labelledby for icon-only buttons and controls without visible text.

Live Regions

Use role="alert" or aria-live for dynamic content that should be announced immediately.

Descriptions

Associate help text with inputs via aria-describedby for richer context.

State Announcements

State attributes like aria-expanded update reactively and are announced automatically.

Custom ARIA attributes

Extend components with custom ARIA attributes via variants, presets, or direct props.

While components provide sensible ARIA defaults, you can add or override them using the variant system (for state-dependent attributes), the preset system (for global defaults), or by passing them directly as props (for one-off cases).

Disabled states

Consistent disabled handling with proper ARIA attributes and visual cues.

Custom elements use aria-disabled (preserves focus for screen reader announcement) while native form inputs use the HTML disabled attribute (excludes from form submission). Visual opacity is applied in both cases.

Focus indicators

Visible focus rings for all interactive elements using :focus-visible.

All interactive components use :focus-visible so focus rings appear for keyboard navigation but not on mouse click. Customize the ring color via the --ring CSS custom property.

Reduced motion

Components respect the prefers-reduced-motion user preference automatically.

When users enable "Reduce motion" in their OS settings, component animations are disabled or significantly reduced. Follow the same pattern in any custom animations you write.

Color contrast

Default theme colors meet WCAG AA standards — 4.5:1 for normal text, 3:1 for large text.

Normal text

4.5:1 minimum

All foreground/background pairs

Large text (18px+)

3:1 minimum

Headings and bold text

Interactive elements

3:1 minimum

Borders and focus rings

Disabled states

Reduced intentionally

Still visually distinct

Accessibility testing

A five-step checklist for verifying accessibility before shipping.

Keyboard navigation

Tab through every interactive element. Verify all are reachable and activatable using Tab, Enter, Space, and Arrow keys.

Screen reader testing

Test with NVDA (Windows), JAWS (Windows), or VoiceOver (macOS/iOS) to verify announcements and navigation.

Automated scanning

Run axe DevTools, Lighthouse, or WAVE to catch common issues programmatically before manual testing.

Color contrast

Verify all text color pairs meet WCAG AA ratios using browser DevTools or a contrast checker extension.

Focus visibility

Navigate with only the keyboard and confirm focus indicators are clearly visible on every interactive element.

Best practices

Guidelines for building accessible applications with @svelte-atoms/core.

Use semantic HTML

Prefer <button>, <nav>, <main> over generic <div> elements with ARIA roles. Native semantics are more reliable.

Provide accessible labels

Every interactive element needs an accessible name. Use visible labels, or aria-label for icon-only buttons.

Don't override automatic ARIA

The Bond system manages ARIA attributes reactively. Only override them when you have a specific, well-understood reason.

Test with real assistive technology

Automated tools catch common issues, but real screen reader testing (NVDA, JAWS, VoiceOver) finds usability problems they miss.

Maintain logical focus order

Tab order should follow the visual flow. Never use positive tabindex values — they disrupt the natural reading order.

Ensure sufficient contrast

Verify all text meets WCAG AA: 4.5:1 for normal text, 3:1 for large text. The default theme passes both.

Support keyboard for everything

Every interaction reachable by mouse must be reachable and operable by keyboard alone — no exceptions.

Respect user preferences

Honor prefers-reduced-motion, prefers-color-scheme, and prefers-contrast system settings.