Accessibility

Accessibility guidelines, utilities, and best practices

WCAG 2.2 checklist alignment

Rizzo aligns with the Web Accessibility Checklist (WCAG 2.2). Every checklist item (HTML, keyboard, forms, content, links, contrast, headings, images, media, ARIA, testing) is implemented or documented. Full prose and patterns: docs/ACCESSIBILITY.md (in repo). The key areas below are summarized on this page.

Accessibility Features

Rizzo CSS is built with accessibility as a core principle, following WCAG 2.1/2.2 guidelines.

Keyboard Navigation

All interactive components support full keyboard navigation:

  • Tab navigation
  • Arrow keys for menus
  • Enter/Space for activation
  • Escape to close/dismiss

ARIA Attributes

Components include proper ARIA attributes:

  • aria-label - Descriptive labels
  • aria-expanded - Menu/accordion state
  • aria-controls - Element relationships
  • aria-describedby - Additional descriptions
  • role - Semantic roles

Focus Management

  • Visible focus indicators using --accent / --accent-fg color
  • Focus trapping in modals
  • Focus restoration: when you close overlays (Search, Modal, Dropdown), focus returns to the trigger
  • Skip links for main content

Utility Classes

Screen Reader Only

Hide content visually but keep it available to screen readers:

html html 
<span class="sr-only">Screen reader only text</span>

Uses modern clip-path: inset(50%) instead of deprecated clip property.

Focusable Screen Reader Content

Make screen reader content focusable:

html html 
<a href="#content" class="sr-only sr-only-focusable">Skip to content</a>

When focused, the content becomes visible and accessible.

Skip Links

Skip to main content link:

html html 
<a href="#main-content" class="skip-link">Skip to main content</a>

Visually Hidden

Hide content completely:

html html 
<span class="visually-hidden">Hidden content</span>

Focus Styles

All interactive elements have visible focus indicators:

css css 
:focus-visible {
  outline: 2px solid var(--accent-fg);
  outline-offset: 2px;
}

Form Accessibility

Labels

Always use labels with form inputs:

html html 
<label for="email">Email</label>
<input type="email" id="email" name="email" />

Required Fields

html html 
<label for="name" class="required">Name</label>
<input type="text" id="name" name="name" required />

Error States

html html 
<input type="email" aria-invalid="true" aria-describedby="email-error" />
<span id="email-error" class="error-message">Invalid email address</span>

Success States

html html 
<span class="success-message">Form submitted successfully</span>

Responsive Design

  • Mobile-first approach
  • Touch-friendly targets (minimum 44x44px)
  • Responsive typography
  • Flexible layouts

Color Contrast

All themes meet WCAG AA contrast requirements:

  • Normal text: 4.5:1 contrast ratio
  • Large text: 3:1 contrast ratio
  • Interactive elements: 3:1 contrast ratio

Contrast-Aware Text Colors

Rizzo CSS automatically provides proper contrast through semantic text color variables:

  • --accent-text - Automatically white or dark based on accent color lightness
  • --success-text - Contrast-appropriate text for success backgrounds
  • --warning-text - Dark text for light warning backgrounds
  • --error-text - Contrast-appropriate text for error backgrounds
  • --info-text - Contrast-appropriate text for info backgrounds

All buttons and components using colored backgrounds automatically use these contrast-aware variables to ensure accessibility.

Text over images and AAA

When text sits on images or gradients, ensure at least 4.5:1 (normal) or 3:1 (large) contrast. Use the Settings High contrast toggle for enhanced contrast (helps toward AAA 7:1).

Content, links, and images

Apply these when authoring content or adding links/images:

  • Language changes — Use lang on phrases in another language (e.g. lang="fr").
  • Links that open in a new window — Add text like “(opens in new tab)” or an icon with aria-label so users know before activating.
  • Images — Meaningful images need descriptive alt; use alt="" for decorative. Complex images need a description nearby or a link. Avoid images of text; use live text.
  • Media — No autoplay with sound; provide captions/transcripts; ensure custom players have ARIA and keyboard support.

Reduced Motion

Respects user preferences:

css css 
@media (prefers-reduced-motion: reduce) {
  /* Animations disabled */
}

High Contrast Mode

Supports high contrast mode through both media queries and user settings:

Media Query

css css 
@media (prefers-contrast: high) {
  /* Enhanced borders and contrast */
}

User Setting

The Settings component includes a "High contrast" toggle that applies the .high-contrast class to the document root, enabling enhanced contrast across all components.

Reduce Motion

The Settings component also includes a "Reduce motion" toggle that applies the .reduced-motion class, respecting user motion preferences beyond just the prefers-reduced-motion media query.

Best Practices

  1. Always provide labels - Every form input needs a label
  2. Use semantic HTML - Use proper heading hierarchy, landmarks
  3. Test with keyboard - Navigate without a mouse
  4. Test with screen readers - Use NVDA, JAWS, or VoiceOver
  5. Check color contrast - Use tools to verify contrast ratios
  6. Provide alternatives - Alt text for images, captions for videos

Testing

We use axe (WCAG 2/2.1 A & AA) in CI as the primary automated check (pnpm test:a11y). For manual keyboard and screen reader testing, use the Manual testing checklist — it lists each component with what to test and links to the doc pages.

Keyboard Testing

  • Tab through all interactive elements
  • Use arrow keys in menus
  • Test Escape key functionality
  • Verify focus indicators are visible

Screen Reader Testing

  • Test with NVDA (Windows)
  • Test with JAWS (Windows)
  • Test with VoiceOver (macOS/iOS)
  • Verify all content is announced

Zoom and vision

  • 200% zoom — Test at 200% browser zoom; content should reflow without horizontal scroll.
  • Font size — Use the Settings font-size slider or OS settings.
  • Color blindness / blurry vision — Use DevTools (e.g. Emulate vision deficiencies) to ensure info isn’t conveyed by color alone.

Automated and one-off tools

  • axe DevTools
  • WAVE
  • Lighthouse
  • Pa11y

Resources