Accessibility

Vanilla Breeze is built with accessibility as a core principle, not an afterthought. This guide covers the accessibility features built into components and how to use them effectively.

Our Commitment

Vanilla Breeze targets WCAG 2.1 Level AA compliance. All components are designed to be:

Perceivable: Content can be presented in different ways without losing meaning
Operable: All functionality is available from a keyboard
Understandable: Content and operation are predictable
Robust: Content works with current and future assistive technologies

Report Accessibility Issues

Found an accessibility problem? Please open an issue on GitHub with the label "accessibility". We take these reports seriously and prioritize fixes.

Keyboard Navigation

All interactive components support full keyboard navigation. Here are the patterns used:

Global Keys

Key	Action
`Tab`	Move focus to next focusable element
`Shift` + `Tab`	Move focus to previous focusable element
`Enter` / `Space`	Activate focused button or link
`Escape`	Close dialogs, dropdowns, and popovers

Component-Specific Keys

Tabs (`tabs-wc`)

Key	Action
`Arrow Left` / `Arrow Right`	Navigate between tabs (horizontal)
`Arrow Up` / `Arrow Down`	Navigate between tabs (vertical orientation)
`Home`	Go to first tab
`End`	Go to last tab

Accordion (`accordion-wc`)

Key	Action
`Enter` / `Space`	Toggle accordion section
`Arrow Down`	Move focus to next accordion header
`Arrow Up`	Move focus to previous accordion header
`Home`	Move focus to first accordion header
`End`	Move focus to last accordion header

Dropdown (`drop-down`)

Key	Action
`Enter` / `Space`	Open dropdown, activate menu item
`Arrow Down`	Open dropdown / move to next item
`Arrow Up`	Move to previous item
`Escape`	Close dropdown

Focus Management

Vanilla Breeze components manage focus appropriately:

Focus trapping: Modal dialogs trap focus within themselves
Focus restoration: When a dialog closes, focus returns to the trigger
Focus visible: All focusable elements have visible focus indicators
Skip links: Use <a href="#main">Skip to content</a> for keyboard users

ARIA Patterns

Vanilla Breeze follows established ARIA patterns from the ARIA Authoring Practices Guide (APG).

Component ARIA Roles

Every interactive web component in Vanilla Breeze manages its own ARIA roles and states internally. The table below shows what each component handles for you and what you need to provide yourself.

Component	Pattern	Roles & States (managed internally)	Developer provides
`tabs-wc`	Tabs	`role="tablist\|tab\|tabpanel"`, `aria-selected`, `aria-controls`, `aria-labelledby`	—
`accordion-wc`	Accordion	`role="region"`, `aria-expanded`, `aria-controls`, `aria-labelledby`	—
`combo-box`	Combobox	`role="combobox\|listbox\|option"`, `aria-expanded`, `aria-autocomplete`, `aria-controls`, `aria-selected`, `aria-activedescendant`. With `[data-multiple]`: adds `aria-multiselectable`, `aria-live`	`<input>` + `<ul>` with `<li data-value>` items
`drop-down`	Menu Button	`role="menu\|menuitem\|separator"`, `aria-haspopup`, `aria-expanded`, `aria-controls`	Trigger button + `<menu>` with items
`context-menu`	Menu	`role="menu\|menuitem\|separator\|presentation"`	Element with `data-trigger` + `<menu>`
`tool-tip`	Tooltip	`role="tooltip"`, `popover="hint"`, `aria-describedby`	Trigger element as first child
`toast-wc`	Alert	`role="region\|alert"`, `aria-live="polite"`, `aria-label="Notifications"`	—
`carousel-wc`	Carousel	`role="region\|group\|tablist\|tab"`, `aria-roledescription="carousel\|slide"`, `aria-selected`, `aria-live`, `aria-label`	Slide content as children. Optional: `aria-label`
`data-table`	Grid	`aria-sort`, `aria-expanded`, `aria-hidden`, `aria-current="page"`	Standard `<table>` markup + `data-sort` on sortable headers
`command-palette`	Listbox	`role="listbox\|option\|presentation"`, `aria-label`	`<command-group>` and `<command-item>` elements
`site-search`	Dialog + Listbox	`role="dialog\|listbox\|option"`, `aria-haspopup`, `aria-expanded`, `aria-autocomplete`, `aria-label`	—
`split-surface`	Window Splitter	`role="separator"`, `aria-orientation`, `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, `aria-label`	Two child panels
`star-rating`	Radio Group / Image	`role="img"` (readonly), `aria-label` (e.g. "Rating: 4 out of 5")	—
`slide-accept`	Slider	`role="slider"`, `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, `aria-label`	—
`dialog`	Modal Dialog	Native `<dialog>` semantics via `showModal()`	`aria-labelledby` or `aria-label`

Live Regions

Dynamic content changes are announced to screen readers using ARIA live regions:

<div aria-live="polite"> Loading complete. 42 results found. </div>  <div role="alert"> Error: Please fix the form errors before submitting. </div>  <div role="status"> Saving... </div>

Labels and Descriptions

Always provide accessible names for interactive elements:

<label for="email">Email address</label> <input type="email" id="email" />  <button aria-label="Close dialog"> <icon-wc name="x"></icon-wc> </button>  <section aria-labelledby="section-title"> <h2 id="section-title">User Settings</h2> ... </section>  <input type="password" aria-describedby="password-hint" /> <p id="password-hint">Must be at least 8 characters</p>

Color and Contrast

Vanilla Breeze design tokens are designed to meet WCAG contrast requirements.

Contrast Ratios

WCAG 2.1 AA requires:

4.5:1 for normal text
3:1 for large text (18pt or 14pt bold)
3:1 for UI components and graphical objects

Built-in Contrast

The semantic color tokens maintain appropriate contrast in both light and dark modes:

/* These automatically meet contrast requirements */ color: var(--color-text); /* Primary text */ color: var(--color-text-muted); /* Secondary text */ background: var(--color-surface); /* Backgrounds */ /* Interactive states maintain contrast */ background: var(--color-interactive); background: var(--color-interactive-hover);

Don't Rely on Color Alone

Color should never be the only way to convey information:

Good: Error state uses color, icon, and text

Email Please enter a valid email address

Good: Links are underlined, not just colored

Visit our documentation for more information.

Testing Contrast

Tools to verify contrast:

WebAIM Contrast Checker
Color Contrast Accessibility Validator
Browser DevTools (Lighthouse audit)
axe DevTools browser extension

Accessibility Themes

For users who need enhanced contrast, Vanilla Breeze provides dedicated accessibility themes:

High Contrast

WCAG AAA (7:1+) contrast ratios with enhanced focus indicators.

Large Text

25% larger fonts with 44px touch targets.

Dyslexia-Friendly

Atkinson Hyperlegible font with optimized spacing.

These themes are composable - combine them with any decorative theme: data-theme="forest a11y-high-contrast"

Motion and Animation

Animations can cause discomfort for users with vestibular disorders. Vanilla Breeze respects user preferences.

Respecting prefers-reduced-motion

All animations in Vanilla Breeze check the user's motion preference:

/* Animations are enabled by default */ .accordion-content { transition: height var(--duration-normal) var(--ease-default); } /* Disabled when user prefers reduced motion */ @media (prefers-reduced-motion: reduce) { .accordion-content { transition: none; } }

What Gets Reduced

Accordion open/close animations
Tab panel transitions
Toast slide-in animations
Dropdown reveal animations
Hover and focus transitions

Testing Reduced Motion

To test reduced motion in your browser:

Open DevTools
Press Cmd/Ctrl + Shift + P to open command palette
Type "reduced motion" and select "Emulate CSS prefers-reduced-motion: reduce"

Accessible Forms

Forms are critical for accessibility. Vanilla Breeze provides patterns that work for everyone.

The form-field Component

The <form-field> custom element ensures proper label association and error handling:

<form-field> <label for="username">Username</label> <input type="text" id="username" required aria-describedby="username-hint" /> <span id="username-hint" class="help"> Letters and numbers only, 3-20 characters </span> </form-field>

Error States

When validation fails, provide clear feedback:

<form-field> <label for="email">Email</label> <input type="email" id="email" required aria-invalid="true" aria-describedby="email-error" /> <span id="email-error" class="error" role="alert"> Please enter a valid email address </span> </form-field>

Form Best Practices

Always use labels: Every input needs an associated <label>
Group related fields: Use <fieldset> and <legend>
Indicate required fields: Use required attribute and visual indicator
Provide help text: Use aria-describedby for hints
Announce errors: Use role="alert" for error messages
Don't rely on placeholder: Placeholders disappear and have poor contrast

Testing Accessibility

Regular testing helps catch issues early. Use a combination of automated and manual testing.

Automated Testing

Tools that catch common issues:

axe DevTools: Browser extension for page audits
WAVE: Web accessibility evaluation tool
Lighthouse: Built into Chrome DevTools
Pa11y: Command-line accessibility testing

Manual Testing Checklist

Can you navigate all interactive elements with only the keyboard? Is focus always visible when navigating? Do all images have meaningful alt text (or empty alt for decorative)? Are form errors clearly communicated? Does the page make sense when zoomed to 200%? Are headings in logical order (h1, h2, h3...)? Is there sufficient color contrast? Does information rely on more than just color?

Screen Reader Testing

Test with actual screen readers:

Platform	Screen Reader	Browser Pairing
macOS / iOS	VoiceOver (built-in)	Safari
Windows	NVDA (free)	Firefox or Chrome
Windows	JAWS	Chrome
Android	TalkBack (built-in)	Chrome

Quick VoiceOver Test (macOS)

Press Cmd + F5 to enable VoiceOver
Use Ctrl + Option + Arrow keys to navigate
Listen for meaningful announcements
Press Cmd + F5 again to disable

Resources

Learn more about web accessibility: