This section covers development accessibility. Developers should also be familiar with accessibility fundamentals, content, and design.

While our elements themselves were developed and tested with accessibility in mind, components can still be rendered inaccessible in how they are used. The HTML slotted within a component could be inaccessible, or CSS variables and part selectors could be used in a way that renders the component inaccessible. Therefore, you should always consider how your particular use of a component may impact its accessibility.

Icons and SVGs

Meaningful icons

Icons must adhere to the same accessibility rules as other images. When icons are used for interactivity (e.g., as buttons or links), they are considered meaningful, unless they are either accompanied by sufficient text within that interactive element, or the interactive element itself is already labeled (e.g., via aria-label). Visit our Content section for more information on image accessibility.

Avoiding icon fonts

Icon fonts are a nifty visual hack that you shouldn’t use.

To make icon fonts accessible, you often have to re-hack what’s already a hack. So best just to avoid them altogether.

SVG accessibility

Describing SVGs

As with any other image, SVGs that are loaded into your page via an <img> tag should include alt attributes. This attribute should be descriptive for meaningful SVGs and null for decorative SVGs. In addition, we recommend adding a role="img" attribute to the <img> element for SVGs:

Inline <svg> elements (i.e., SVGs that are coded directly into the page source) cannot use the alt attribute. You must use some other means to describe or hide these images. Instead of an alt attribute, an <svg> element comprising a simple image can include the role="img" attribute and contain a descriptive <title> element as its first child, like in the following example:

More complex <svg> elements may require additional descriptive information. One way of including this information is via the <desc> element:

Hiding SVGs

You can hide inline <svg> elements with an aria-hidden="true" attribute.

Carie Fisher explores several patterns (including the above) for embedding accessible SVGs in her 2021 Smashing Magazine article.

Web standards and semantics

The W3C establishes standards for the web. Browsers work according to these standards. And assistive technologies, like screen readers, are designed to work with this standard as well. When everything follows the same standard, it’s easy to be accessible. It’s what we do outside of the standards that has potential to make the web inaccessible.

Semantic HTML, using the standard HTML tags based on their meaning, is how we can communicate our intent to both the browser and assistive tech. For example, <a> and <h1> indicate meaning while <div> and <span> do not. For interactive components that aren’t covered by semantic HTML, refer to the Accessible Rich Internet Applications (ARIA) W3C specification. ARIA also allows us to specify certain regions of a page as landmarks that screen reader users can skip to.

To help ensure your work is accessible:

  • Start by using semantic HTML as it was intended. For example, use <a> for links and <button> for buttons, as they are already built to work the way they should work.
  • Markup order, visual order, and focus order should match. Ensure that the assistive tech read order and keyboard focus order follow what is presented visually.
  • When there is no standard HTML for a UI component, use ARIA. For example, there is no semantic HTML for a tabs component, so you’ll need to include some ARIA roles, states and properties to supply additional meaning to assistive technology.
  • Use ARIA landmarks, but in a limited number. Think of landmarks as shortcuts on a page, if there are too many of them, they cease to be shortcuts.

Accessible patterns

The best approach for making a component accessible is to refer to an existing HTML element or an established pattern. You can find examples of existing patterns via the following resources:

WAI ARIA authoring practices guide

The WAI ARIA Authoring Practices Guide (APG) includes patterns and practices for making components accessible. Contributors should refer to the pattern that best matches the component they are building when considering the following:

  • Keyboard navigation.
  • WAI-ARIA roles, states and properties.

Deque University Code Library

Accessibility solutions provider Deque Solutions offers training via its educational arm, Deque University. Deque University's Code Library is a beta project that includes the Cauldron Pattern Library and ARIA examples. Contributors may also refer to examples in this code library. Each example includes all applicable HTML, CSS and JavaScript.

Inclusive Components

Heydon Pickering describes his Inclusive Components as "a blog trying to be a pattern library, with a focus on inclusive design." Each post covers a specific type of component—like a card or a data table—and provides a step-by-step explanation of how to make it more accessible. A more comprehensive list of components can be found in the Inclusive Components book.


The following World Wide Web Consortium (W3C) Web Content Accessibility Guidelines (WCAG) 2.1 A and AA apply to developing interactive elements:


For more on keyboard navigation, see the WAI ARIA Authoring Practices Guide's (APG) Developing a Keyboard Interface.

Hiding elements

The following World Wide Web Consortium (W3C) Web Content Accessibility Guidelines (WCAG) 2.1 A and AA apply to dyanmic content:


For more on dynamic content, see the Mozilla Developer Network's (MDN) ARIA live regions.

Disabled elements

For disabled composite components, such as fieldsets, radio groups, menus, and listboxes, WAI-ARIA recommends] that elements of these components remain focusable.

Users should still be able to read options within the composite group even if they cannot activate or trigger them. For example, a disabled dropdown menu should allow users to toggle it open via keyboard and focus on options even when activating the options is disabled.

Keyboard navigation and focus events

When handling focus consider the following:

  • The focus indicator should be visible.
  • Some element must be in focus at all times.
  • Focus is consistent and predictable.

For more information see the WAI-ARIA APG's Fundamental Keyboard Navigation Conventions and Discernible and Predictable Keyboard Focus.

Focus order and roving tabindex

Between components, the default method of navigating via keyboard is with the Tab to move to the next focusable component and Shift+Tab to move to the previous focusable component. Complex components can have multiple focusable items, so rather than force keyboard users to tab through every focusable item within each component, a roving tabindex should be used to allow keyboard users to Tab/Shift+Tab into the complex component, arrow keys to navigate within the component, and Tab/Shift+Tab back out of the complex component. (See the WAI-ARIA APG's Managing Focus Within Components Using a Roving tabindex)

Our complex components, like accordion, secondary navigation, subnavigation, tabs, and tile, use this roving tabindex method via a reactive controller. (Refer to Contributors: Accessibility controllers)

Keyboard traps

If the focus cannot be moved away from a focusable element by keyboard alone, a keyboard user can be "trapped" on the element, unable to focus on and interact with other focusable elements. See the following on avoiding keyboard traps:

Error Handling

The following World Wide Web Consortium (W3C) Web Content Accessibility Guidelines (WCAG) 2.1 A and AA apply to error handling:

Scaling and rotation

Accounting for text scaling and spacing

Your pages should permit users without assistive tech to scale text to at least 200% of its original size in the browser (e.g., via command-plus or control-plus on desktop, and pinch to zoom on touchscreens). Scaled text must all still be functional and visible after such scaling. That means no overlapping, clipping, or unexpected separation of content. (1.4.4: Resize Text)

To give users more control over scaling, font sizes specified in CSS should be set via relative measurements (e.g., em, rem, etc.) rather than absolute sizes (e.g., px, pt, etc.). This applies not only to body copy, but also to form element text. (1.4.4: Resize Text)

Content and functionality must also be maintained if users override the following text styles: line-height (up to 1.5× the font size), paragraph spacing (up to 2× the font size), letter spacing (up to .12× the font size), and word spacing (up to .16× the font size). (1.4.12: Text Spacing)

Screen rotation

Mobile users must be permitted to reorient their screen at will between landscape/portrait, without any messages requesting that they select a particular orientation. (1.3.4: Orientation)

© 2021-2024 Red Hat, Inc. Deploys by Netlify