Manual accessibility testing

Runbook for manual keyboard and screen reader testing of Rizzo components: prerequisites, step-by-step checks, and results log.

Overview

This runbook guides manual keyboard and screen reader testing of Rizzo CSS components. Use it before a release or when adding or changing interactive components. Run automated tests first, then work through the priorities below. Each row links to the component doc page so you can open it and test the live demo.

Full prose and component matrix: Accessibility and docs/ACCESSIBILITY.md (repo).

Before you start

  • Automated tests — Run pnpm test:a11y and fix any failures. Manual testing does not replace axe, keyboard, and ARIA specs.
  • Build and preview — Use pnpm build && pnpm preview (or your deployed docs URL). Test against the same build you will ship.
  • Browser and AT — Use a recent Chrome, Firefox, or Safari. For screen reader: NVDA (Windows), VoiceOver (macOS: Cmd+F5), or JAWS (Windows). Disable mouse for keyboard-only passes.
  • Theme — Optional: lock theme (e.g. data-theme="github-dark-classic") so contrast and focus rings are consistent while testing.

Priority 1 — High interaction (test first)

Test these components with keyboard-only, then with a screen reader (NVDA, VoiceOver, or JAWS).

Component What to test Doc page
Modal Focus moves into modal when opened; focus trapped inside (Tab/Shift+Tab); Escape closes and focus returns to trigger; ARIA: role=dialog, aria-modal, aria-labelledby; screen reader announces purpose. Modal
Dropdown Trigger opens menu; arrow keys move; Enter/Space activates and closes; Escape closes and returns focus; nested submenus if any; ARIA: aria-expanded, role=menu/menuitem; screen reader announces menu and items. Dropdown
Theme Switcher Same as Dropdown; selected theme announced; ARIA: expanded, selected, menuitemradio. Theme Switcher
Font Switcher Same as Dropdown (in Settings or standalone); arrow keys, Enter to select pair; Escape closes; preview and label announced. Font Switcher
Tabs Tab reaches tab list; arrows change tab; Enter/Space activates; panel updates and is announced; ARIA: tablist, tab, tabpanel, aria-selected, aria-controls. Tabs
Search (Cmd+K) Open with keyboard; focus in input; Escape closes and returns focus; results keyboard navigable and announced. Search
Settings Open/close with trigger; focus trap when open; Escape closes; theme, font size, font pair, sound effects, and other toggles keyboard operable and announced. Settings
Accordion Headers focusable; Enter/Space toggles; ARIA: aria-expanded, aria-controls; screen reader announces expanded/collapsed. Accordion

Priority 2 — Forms and feedback

Component What to test Doc page
Forms All inputs reachable by Tab; labels associated (for/id or aria-label); error/required announced; ARIA: aria-required, aria-invalid, aria-describedby. Forms
Tooltip Trigger focus shows tooltip; keyboard user can read it; no focus trap. Tooltip
Toast New toasts announced (live region); dismiss focusable and keyboard operable. Toast
CopyToClipboard Button has accessible name; success feedback announced. Copy to Clipboard

Priority 3 — Navigation and layout

Component What to test Doc page
Navbar Skip link or main content first; nav links and mobile menu keyboard accessible; mobile menu open/close and focus trap. Navbar
Docs Sidebar Nav landmark; group labels and links focusable in order; current page indicated (e.g. aria-current or visible active state); collapse/expand if present. Docs Sidebar
Footer Landmark (role="contentinfo" or semantic footer); links focusable with clear names; no interactive traps. Footer
Pagination, Breadcrumb, Buttons, Badge, Card, Table Links/buttons focusable with clear names; table headers associated if sortable. Components overview
Sound Effects When used standalone: checkbox focusable, label "Play sound on click" and help text announced; state change announced. (When in Settings, covered by Settings.) Sound Effects

Tools

  • Keyboard-only — No mouse. Tab, Shift+Tab, Enter, Space, arrows, Escape. Confirm all actions possible and no focus traps (except intentional in modal/search/settings).
  • Screen reader — NVDA (Windows), VoiceOver (macOS: Cmd+F5), or JAWS. Check announcements (labels, state changes, live regions).
  • 200% zoom — Test at 200% browser zoom (or 200% text scaling). Content should reflow without horizontal scrolling.
  • Increased font size — Use the Settings font-size slider or OS font-size settings.
  • Color blindness / vision — Browser DevTools (e.g. Chrome Rendering → Emulate vision deficiencies) to check information is not conveyed by color alone.
  • axe DevTools — Browser extension for one-off page scans.
  • Lighthouse — Chrome DevTools → Lighthouse → Accessibility for periodic checks.

Step-by-step example: Modal

Use this pattern for other Priority 1 components. Open Modal and follow in order.

  1. Tab to the trigger button (“Open modal”). Activate with Enter or Space.
  2. Confirm focus moves into the dialog (first focusable element or the dialog container).
  3. Tab and Shift+Tab repeatedly — focus must stay inside the modal (no focus on page behind).
  4. Press Escape — modal closes and focus returns to the trigger button.
  5. Re-open the modal. With a screen reader, confirm the dialog is announced (e.g. “dialog” and title/aria-labelledby). Navigate and confirm focus and labels are announced correctly.

Results log

Copy the table below (or use a spreadsheet) to log results. Record Pass, Fail, or N/A and add notes for failures or follow-ups.

Component Keyboard Screen reader Notes
Modal——
Dropdown——
Theme Switcher——
Font Switcher——
Tabs——
Search——
Settings——
Accordion——

Screen reader quick reference

  • NVDA (Windows) — Tab / Shift+Tab: focus; Down/Up: read next/previous line; Insert+Down: read all; Insert+F7: elements list (headings, landmarks, links).
  • VoiceOver (macOS) — VO+Right/Left: move; VO+Shift+Down: enter group; VO+Shift+Up: leave group; VO+A: read all; VO+U: rotor (headings, links, landmarks).
  • JAWS (Windows) — Tab / Shift+Tab: focus; Down/Up: read; Insert+Down: read next; Insert+F7: links list; Insert+F6: headings list.

Suggested order

  1. Keyboard-only pass on Priority 1 (Modal, Dropdown, Theme Switcher, Font Switcher, Settings, Tabs, Search, Accordion). Fix focus and traps.
  2. Screen reader pass on the same. Fix labels and announcements.
  3. axe DevTools on those pages. Fix reported issues.
  4. Repeat for Priority 2 and 3; update Best practices if you find new patterns.