Skip to the content

Documentation

Accessibility

What every component is checked for, and how.

What every component does

  • Keyboard. It is operable to the WAI-ARIA pattern for its kind. Behaviour comes from Radix where a primitive exists; where none does, the pattern is written here.
  • Names and states. Roles, names and states are there for a screen reader. An icon-only control has a name. State is never carried by colour alone: chosen, disabled, failed and current each have a mark or a word too.
  • Focus. It is visible, it moves into what opens, and it returns to what opened it.
  • Right-to-left. Layout uses logical properties, arrow keys follow the reading direction, and icons that point are mirrored.
  • Phone width. It works from 320 pixels wide, and touch targets are at least 40 pixels.
  • Less motion. Only transform and opacity move, and everything stops when the visitor asks for less motion.
  • No fixed words. What a person reads or hears is passed in, or is a prop with an English default, so a product in any language can use it.
  • No dragging required. Anything done by dragging can also be done with buttons or keys.
  • Contrast. Text keeps at least 4.5 to 1 in light and dark, with any highlight colour: the theme chooses the lightness.

How it is checked

Each group of components has a page on this site and a file of checks that drives that page in a real browser. Every group is run four times: at desktop width, at desktop width right-to-left, at 390 pixels with touch, and at 390 pixels right-to-left. Each time the checks press the component's keys one by one and read its roles, names and states, where focus goes on open and on close, and its controlled and uncontrolled use. Around them the runner checks that axe-core finds no WCAG 2.2 A or AA violation, that nothing overflows sideways, and that the page and the console report no errors.

The library's own lint also runs the React rules that a project's lint runs on a copied component, so a component does not fail in the project it lands in.

The pages the checks drive

  • Foundations. Reading direction, announcements for screen readers, type that follows the script.
  • Choices. Chips, tiles, a segmented control, a number stepper.
  • Dates and times. A calendar, date and date-range pickers, offered time slots, a time field.
  • Flows and lists. Steps, a wizard, a sortable list, a combobox, skeletons that hold their size.
  • Panels. A bottom sheet with snap points, a dock beside the page, a frame for a map.
  • Conversation. A thread, messages, streaming text, a status line, a composer.
  • Pictures and uploads. A gallery, a lightbox with zoom, shared-element transitions, a dropzone with progress.
  • Video and sound. A video player, an audio player with a waveform, a scrubber, captions.
  • Records and decisions. A compare table, fact rows with their source, consent, a language switcher, prices, a countdown.
  • Models in 3D. A viewer for one model, glTF or Gaussian splats, with a poster, progress, keys and a still fallback.
  • Comparison and provenance. A then-and-now slider, a legend of certainty classes, a label that says what a picture is.
  • Carousels and media rows. A scroll-snap carousel with autoplay that can be paused, and reorderable rows of uploads.
  • Primitives. An alert dialog, a collapsible, a hover card, a menubar, a navigation menu, a toolbar, a one-time code, a password field, and words for screen readers.
  • Lists of any length. A windowed list and grid for thousands of rows of any height, with their place remembered.
  • Stage for timed scenes. A sequence of timed scenes with a transport and a clock, and frames drawn on request for export.

Add ?dir=rtl to any of them to see it right-to-left.

What the checks do not prove

An automatic scan finds only part of what can go wrong, and a browser driven by a script is not a person using a screen reader. The checks show that the patterns are in place and stay in place. They do not replace testing a finished product with the people who will use it.