Guide accessibility

Last updated: July 31, 2024 10:38

DISCLAIMER: This document isn't intended to demonstrate or indicate compliance with WCAG 2.1 AA Accessibility standards or other similar standards. Pendo's guide accessibility features are designed to allow you to build accessible guides, but Pendo doesn't guarantee that content meets any accessibility standards. Any suggestions provided by Pendo are simply recommendations based on the current set of features.

This article is relevant for the Visual Design Studio. Web content accessibility is necessary to ensure that all users have fair and equal access to the internet. Pendo guides are an important way for users to get information about your app and communicate with you. Guide accessibility features are used by screen readers and other tools to help users with disabilities find and interact with your Pendo guides.

Some features are applied automatically and are available in all guides. Focus and HTML attributes for badges and keyboard navigation are available for all guides. Other features need to be activated or configured during guide creation. Auto-focus, ARIA labels, Alt Text, Title, and ARIA roles can be set up in the Visual Design Studio when creating a guide.

These features are an important part of creating accessible web content, but there are additional requirements in accessibility guidelines that aren't addressed by functionality in Visual Design Studio. Factors like color contrast, captions for embedded video or audio, clickable element size, and others are up to you to implement.

Tip: Web content accessibility is a complicated topic with many considerations beyond just the structure and presentation of a guide. Companies often hire specialists or consultants to manage all of the different factors required to provide an accessible experience. Audits and evaluations might be involved if you are required to meet certain accessibility standards and guidelines. Refer to the World Wide Web Consortium (W3C) website for more information on web accessibility and Web Content Accessibility Guidelines (WCAG).

Requirements

Agent 2.126.0 or greater
Admin, Guide Creator, or Content Editor user roles
Visual Design Studio
Pendo Web

For the best experience using new accessibility features, we recommend configuring your agent settings to automatically update to the latest version to receive updates as soon as they are available. To configure the agent version:

Go to Subscription Settings and select your app in the Applications tab.
Go to Agent Settings.
In Staging Environment or Production Environment, select Settings.
Select the required agent version and then select Save.

Recommendations

Guide activation

Badge-activated guides are more accessible than automatic or target element guides because they give the user the option to trigger them or not.

Always set the badge position to “inline right” or “inline left”. This limits where you can place the badge in your UI, but ensures that the badge can be tabbed to in a logical order with keyboard navigation and not loaded at the end of the DOM.

Guide creation

Add a descriptive Alt Text or ARIA Label where possible. These are read by assistive technologies.
ARIA role depends on the type of guide and how assistive technologies should recognize the guide.
You’ll likely use the ARIA roles Dialog, Banner, or Complementary for Pendo guides.
Autofocus must always be selected for the best guide experience. If the underlying application is also trying to grab focus (e.g. on a modal), there might be a conflict.
Confirm the color contrast ratio of guide elements meets WCAG AA standard in the guide theme.

Configure guide accessibility

Accessibility features are configured in the container and building block settings of a guide in Visual Design Studio. If an element has accessibility settings available, they are in the Accessibility tab in the Edit modal.

The Color Contrast Checker is available when creating or editing a theme in Theme Settings in the Visual Design Studio.

Configurable attributes

Color contrast. Background and font color of elements that contain text.
alt (Image Alt Text). Image building block.
aria-label. Container, close button, button, badge, text building blocks.
aria-modal. Container when backdrop is enabled.
role. Container for each guide step.
title. Video building block.
Autofocus this step. Container for each guide step.

Non-configurable attributes (applied automatically)

h2, h3, p (semantic headers). Title, subtitle, and paragraph text blocks are automatically assigned to the appropriate header or paragraph element.
aria-labelledby. Creates a relationship between two elements, used by open text, yes/no, multi choice, number scale, and NPS polls.
aria-describedby. Create a relationship between two elements, used by number scale polls and NPS surveys to connect the first and last numbers in the scale with their text descriptions.
aria-expanded. Applied automatically to badges for guides and the resource center.
role. role="group" applied automatically to Yes/No buttons and multi choice radio buttons in poll building blocks.

Theme color contrast checker

Theme settings provides a contrast checker for all elements that contain text. This helps you to verify that the color choices applied to your guides comply with WCAG AA 4.5:1 or WCAG AAA 7:1 contrast ratio requirements.

Select an element in Theme Settings. The style settings for that element are displayed on the right side of the page. The contrast checker is at the bottom of the style settings. It updates in real-time as you change the colors of backgrounds and fonts. The WCAG tags flag red if your selections do not have adequate contrast and green if the contrast ratio requirement is met.

Edit container accessibility settings

Select the edge of the guide step to open the container settings. Each guide step has unique settings to control the appearance and behavior of that step. If you're creating multi-step accessible guides, the Accessibility tab must be configured for each guide step.

Container accessibility settings

ARIA Label - Accessible Name. Set the ARIA label for the entire guide container.
Role. Select the ARIA role from a dropdown menu of available roles (no role, article, banner, complementary, contentinfo, dialog, form, main, navigation, presentation, and region).
Autofocus this step. Traps assistive technology focus on the guide.
ARIA Label - Close Button. Set ARIA labels for the default close button, which can also be toggled in container settings.
ARIA Modal. Set to aria-modal="true" when the Backdrop is enabled, indicating the background content underneath the modal is not available for interaction.

Edit text or button settings

Select the building block to open the building block settings. The ARIA Label can be configured for Text and Button building blocks.

Semantic HTML for Text Building Blocks

Text building blocks automatically assign semantic headers in the HTML according to the selected theme style in text building block settings.

Title is an h2 element.
Sub title is an h3 element.
Paragraph is a p element.
Custom retains the semantic header for the last assigned style (e.g. a text block with the paragraph style changed to custom style will stay a p element).

Edit image settings

Select the Image building block to open the settings. Image Alt Text can be configured for image building blocks. Alt text is the preferred method for adding accessible text to images. ARIA labels generally aren't used with images.

Edit video settings

Select the Video building block to open the settings. The Title can be configured for video building blocks. Title is the preferred method for adding accessible text to videos.

Edit poll settings

The various poll building blocks have a combination of configurable and non-configurable settings to make them accessible.

Select the poll response fields to open Poll settings. Text and button elements in the poll have ARIA label fields.

ARIA-describedby, ARIA-labelledby, and group roles are applied automatically to connect poll responses with their respective question text.

Configure Resource Center accessibility

Accessibility settings are configured in the Visual Design Studio after selecting Manage in my App from the Resource Center page. ARIA labels are available for elements on the Home View and badge. Keyboard navigation and focus elements are applied automatically when the Resource Center is promoted to staging and published. The Home, Guide List, and Onboarding modules support keyboard navigation and screenreader tools. Sandbox and Integration modules use external code and are unable to use accessibility features.

Configurable Attributes

Color contrast. Background and font color of elements that contain text.
aria-label. Container, close button, back button, badge.

Non-Configurable Attributes (applied automatically)

aria-expanded. Applied automatically to badges for guides and the Resource Center.
aria-hidden. Used to hide the progress circle in the Resource Center's Onboarding module from assistive technology as they are only decorative.
aria-modal. aria-modal="false" applied automatically to the Resource Center.
role. role="dialog" applied automatically to the Resource Center, role="group" applied automatically to the guide list module.
aria-labelledby. Applied automatically to the Guide List module.

Edit Home View styling

Select the Styling tab in the Edit Home View modal and open the Accessibility menu. Configure ARIA labels for the close button, dialog header, and back button.

Edit Badge styling

Badge settings are available in the activation settings for the Resource Center in the Visual Design Studio. Configure the ARIA label for the Resource Center badge. The badge uses accessible HTML elements and focus states automatically when it's promoted and published.

The badge must be turned on in Activation Settings to use these accessibility features.

Image scaling

WCAG guidelines state that content should be "presented without loss of information or functionality, and without requiring scrolling in two dimensions." Guide containers scale image building blocks automatically to meet this requirement. If a user zooms in on a guide, the image automatically scales proportionally with the width of the container and the image doesn't get cut off or add horizontal scrollbars.

Best practice for full-width images

Pendo guide containers have 40-pixel padding around the outside edge by default to space out guide content and make guide design easier. Images with fill set to 100% stay within to the 40-pixel padding default. Negative margins can be used to spread the image out to the full width of the container. Image scaling automatically adjusts the image so that it matches the container width if the user zooms in or out.

Full-width margin settings

All values are negative numbers

Left margin -40px
Right margin -40px
If you've changed the guide container padding settings, match your negative margin to the container padding values

Note: If you're using custom padding and margins to creatively adjust image building blocks into positions that aren't supported by out-of-the-box building block placement, image scaling might distort the presentation and placement of these images. Check your guides at different zoom levels to see if your custom settings interfere with automatic image scaling.

Focus

Focus states help users with disabilities use apps without requiring a mouse or touchpad. A focus state can appear as a ring around an element, depending on CSS styling. Chrome versions 83+ allow you to style focus elements in your app. You might notice browsers adding a focus state, like an outline around the element, when selecting these elements or tabbing through a page.

The image below is a Focus ring example provided by Google.

HTML Tag - Button

Badges use the button tag in the HTML. Prior to adding accessibility features, badges used the img or input tag. Guide and Resource Center badges both use the button tag.
The image below shows an example of guide badge HTML.

Autofocus

Autofocus this step. Traps focus for assistive technology on the guide step until it's dismissed. This setting is configured in the container settings for each guide step.

Tip: Autofocus this step can be enabled for each guide step in a multi-step guide to continuously trap assistive device focus on the guide content throughout your walkthrough. Without autofocus, the guide content might get lost at the bottom of the DOM hierarchy, requiring users to tab through the entire page before focusing on the guide content.

ARIA Label, Alt Text, and Title

ARIA Labels, Alt Text, and Title are used to identify elements that aren't described in the UI in an accessible way. Accessibility tools use these properties in different ways. For example, a screen reader might read the ARIA label out loud to the user. ARIA Label refers to text and button building blocks and Resource Center elements, Alt Text applies to image building blocks, and Title is used for video building blocks.

ARIA Label, Alt Text, and Title are added in each individual building block.

ARIA labels are available for the Resource Center Home View and badge. You can add {UNSEEN_COUNT} to represent the notification number shown in the Resource Center badge.

For additional information, refer to the W3C definitions for ARIA Labels and Alt Text for images.

Keyboard navigation

Users with disabilities or users with some devices might not be able to use a cursor or touch screen to interact with the page. Keyboard navigation is an important input for content accessibility. Users can navigate guide content and most of the Resource Center with keyboard inputs. Sandbox and Integrations modules can't be used with keyboard navigation.

Press the Esc key to dismiss the current active guide.
Use Tab to advance through an element in a guide step.
Use Space and Enter to interact with elements in the guide.

Tip: The auto-focus setting traps focus in the guide step, which makes it easier to use with a keyboard. Guide content is likely to be at the bottom of the DOM below all content on the page. A user might have to tab through all elements on the page to interact with the guide if focus isn't trapped on the guide automatically.

Guide ARIA roles

ARIA roles are used to identify elements for assistive technologies to provide the appropriate help to the user. Roles are defined in the ARIA Roles Model and have specific purposes. For example, there are different roles for widgets, which identify interactive elements, and document structure, which organizes content on the page and generally isn't interactive.

A role is set for each individual guide step.

Available roles

No Role
Article
Banner
Complementary
Content info
Dialog
Form
Main
Navigation
Presentation
Region

Tip: W3C recommends that roles aren't changed by user behavior or over time after content has been published to users. Platforms and assistive devices generally don't have APIs that allow for progressive updating of roles. The first role seen by assistive technology is generally cached and won't update. If you need to change the ARIA role of a published guide, clone the guide, change the role, publish the updated guide, and disable the previous version. Cloning the guide generates new IDs and the new guide content is cached by assistive devices.

Accessibility feature limitations

Sandbox and Integrations Resource Center modules aren't accessible.
Buttons with URL Link actions don't notify the user that it's a link, but an ARIA label can be used to add descriptive text.