Accessibility

Accessibility is a major concern of the Prime UI libraries and PrimeReact is no exception. PrimeTek teams have initiated a significant process to review and enhance the accessibility features of the components. This guide documents the foundation of the general guidelines that PrimeReact will follow and each component documentation will have a separate Accessibility section that states the keyboard support, screen reader compatibility, the implementation details along with tips to achieve WCAG compliancy. This work has been completed for PrimeVue as the reference implementation and currently being ported to PrimeReact to be finalized in Q2 2023.

Introduction#

Visual Impairments

Blindness, low-level vision or color blindness are the common types of visual impairments. Screen magnifiers and the color blind mode are usually built-in features of the browsers whereas for people who rely on screen readers, page developers are required to make sure content is readable by the readers. Popular readers are NVDA, JAWS and ChromeVox.

Hearing Impairments

Deafness or hearing loss refers to the inability to hear sounds totally or partially. People with hearing impairments use assistive devices however it may not be enough when interacting with a web page. Common implementation is providing textual alternatives, transcripts and captions for content with audio.

Mobility Impairments

People with mobility impairments have disabilities related to movement due to loss of a limb, paralysis or other varying reasons. Assistive technologies like a head pointer is a device to interact with a screen whereas keyboard or a trackpad remain as solutions for people who are not able to utilize a mouse.

Cognitive Impairments

Cognitive impairments have a wider range that includes people with learning disabilities, depression and dyslexia. A well designed content also leads to better user experience for people without disabilities so designing for cognitive impairments result in better design for any user.

WCAG#

Form Controls#

<button onClick={e => console.log(e)}>Click</button>
 

On the other hand, a fancy css based button using a div has no keyboard or screen reader support.

<div className="fancy-button" onClick={e => console.log(e)}>Click</div>
 

tabIndex is required to make a div element accessible in addition to use a keydown to bring the keyboard support back. To avoid the overload and implementing functionality that is already provided by the browser, native form controls should be preferred.

<div className="fancy-button" onClick={e => console.log(e)} onKeyDown={e => e.code === 'Space' && console.log(e) } tabIndex="0">Click</div>
 

Form components must be related to another element that describes what the form element is used for. This is usually achieved with the label element.

<label htmlFor="myinput">Username:</label>
<input id="myinput" type="text" name="username" />
 

Semantic HTML#

<div className="header">
    <div className="header-text">Header</div>
</div>

<div className="nav"></div>

<div className="main">
    <div className="content">
    </div>

    <div className="sidebar">
    </div>
</div>

<div className="footer">
</div>
 

Same layout can be achieved using the semantic elements with screen reader support built-in.

<header>
    <h1>Header</h1>
</header>

<nav></nav>

<main>
    <article></article>

    <aside></aside>
</main>

<footer>
</footer>
 

WAI ARIA#

<input type="checkbox" value="Prime" name="ui" checked>
 

A fancy checkbox with css animations might look more appealing but accessibility might be lacking. Checkbox below may display a checked font icon with animations however it is not tabbable, cannot be checked with space key and cannot be read by a reader.

<div className="fancy-checkbox">
    {checked && <i className="checked-icon"></i>}
</div>
 

One alternative is using ARIA roles for readers and use javascript for keyboard support. Notice the usage of aria-labelledby as a replacement of the label tag with htmlFor.

<span id="chk-label">Remember Me</span>
<div className="fancy-checkbox" role="checkbox" aria-checked="false" tabindex="0" aria-labelledby="chk-label"
    onClick="() => toggle()" onKeyDown="(e) => e.keyCode === 32 && toggle()">
    {checked && <i className="checked-icon"></i>}
</div>
 

However the best practice is combining semantic HTML for accessibility while keeping the design for UX. This approach involves hiding a native checkbox for accessibility and using javascript events to update its state. Notice the usage of p-sr-onlythat hides the elements from the user but not from the screen reader.

<label for="chkbox">Remember Me</label>
<div className="fancy-checkbox" onClick="() => toggle()">
    <input className="p-sr-only" type="checkbox" id="chkbox" onFocus="() => updateParentVisuals()" onBlur="() => updateParentVisuals()"
        onKeyDown="(e) => e.keyCode === 32 && updateParentVisuals()">
    {checked && <i className="checked-icon"></i>}
</div>
 

A working sample is the PrimeReact checkbox that is tabbable, keyboard accessible and is compliant with a screen reader. Instead of ARIA roles it relies on a hidden native checkbox.

Colors#

Good Contrast

Color contrast between the background and the foreground content should be sufficient enough to ensure readability. Example below displays two cases with good and bad samples.

Vibration

Color vibration is leads to an illusion of motion due to choosing colors that have low visibility against each other. Color combinations need to be picked with caution to avoid vibration.

Dark Mode

Highly saturated colors should be avoided when used within a dark design scheme as they cause eye strain. Instead desaturated colors should be preferred.