Accessibility

Overview

Accessibility (A11y) means enabling as many people as possible to use websites. To accomplish this, we must write our components so that they adhere to the Web Content Accessibility Guidelines (WCAG) and understand Accessible Rich Internet Applications (ARIA) terms. It is important to know that a "role" is the main descriptor of a "widget" (component), a discrete user interface "object" with which the user can interact. Widgets range from standalone simple objects that have one value or operation (e.g., checkbox and link), to complex composite objects that contain many managed sub-objects (e.g., trees and grids). An object in an accessibility API may represent one or more DOM objects.

When writing ARIA, it is important to know a role is a promise and to test for those promises. Start with ⭐ accessibility essentials for developers and other roles. Understand the tools and techniques to navigate the web and how everyone has individual needs and preferences. ARIA helps bridge the gap between the DOM and accessibility tree. MDN A11y tutorials for more in-depth content.

Accessibility Principles

Accessible products must consider WCAG's broadly grouped four principles. The ⭐ fundamental principle acronym POUR covers: Perceivable information and UI, Operable UI and navigation, Understandable information and UI, and Robust content and reliable interpretation. Testing tools pass/fail on WCAG 2 requirements (success criteria) and techniques that align with POUR.

Roles

Understand the universal ⭐ Design Patterns and Widgets that Core React implements (Alphabetical list of WAI-ARIA roles). Read more on practices, like providing accessible names and descriptions.

Categories of roles that define widgets and page structure:

  • Widget Roles
    • Standalone Widgets. UI widgets that can standalone or as part of larger, composite widgets. The main navigation key (generally the TAB key) will move to the next widget.
    • Composite Widget. Act as containers that manage other, contained widgets. When themselves or a descendant has focus, the user may navigate through the container by pressing additional keys, such as the arrow keys.
  • Document Structure Roles. Structures that organize content in a page.
  • Landmark Roles. Regions intended as navigational landmark in a page.
  • Live Region Roles. Live regions are perceivable regions of a web page that are typically updated as a result of an external event when user focus may be elsewhere.
  • Window Roles. The following roles act as windows within the browser or application.

States and Properties

A "role" defines specific properties an object can have (attributes on HTML elements). The terms "states" and "properties" refer to similar features. Many states and properties accept a specific set of tokens as values. The groups are widget, relationship, live region, and drag-and-drop attributes. Review Taxonomy of WAI-ARIA states and properties or the alphabetical list of states and properties (all aria-* attributes).

Core React Patterns

While using Core React, you can expect the following patterns to help write accessible code.

Documentation

Check JSDocs in your editor! Core React uses @a11y for implementation notes. Use TypeScript! We use TypeScript to help enfore rules.

HTML Tags

Core React has component composition in mind, but isn't ideal in all cases. Alternative patterns to primitive tags include:

  • Core React supports semantic HTML tags like H1 and P. These tags also contain browser reset styles.
  • LinkButton for an anchor styled like and acting like a Button.
  • as prop on certain components to change the HTML tag, e.g. Box as="ul" renders <ul> with browser reset styles.

Prop Placement

For components that wrap HTML inputs, the props and ref go to the native input. The exception is className and style, which go to the outermost HTML element.



⭐️ * Most important onboarding resources