Guide accessibility

Last Updated: September 27, 2023 09:20

DISCLAIMER: This document is not 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 does not guarantee that content will meet any accessibility standard. Any suggestions provided by Pendo are simply recommendations based on the current set of features.

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 disabled users find and interact with your Pendo guides.

Some features are applied automatically and are available on 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 the 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 may 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

Note: 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. Configuration for your agent version is in Subscription Settings > App Details > Agent Settings > Manage Staging or Production Settings.

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.

You should always set the badge position to “inline right” or “inline left”. This limits where you can place the badge in your UI, but it ensures that the badge can be tabbed to in 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 will be 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 should always be checked for the best guide experience
If the underlying application is also trying to grab focus (e.g. on a modal), there may 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 the Visual Design Studio. If an element has accessibility settings available they will be 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 verify that the color choices applied to your guides will 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 building block settings. The ARIA Label can be configured for Text and Button building blocks.

Semenatic 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 Image building block 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 Video building block 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 will use accessible HTML elements and focus states automatically when it is promoted and published.

The badge must be toggled 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 does not get cut off or add horizontonal 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 will automatically adjust the image so 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 have 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 may 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 disabled users 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 may notice browsers adding a focus state, like an outline around the element, when selecting these elements or tabbing through a page.

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.

Example of the Guide Badge HTML

Autofocus

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

Tip: Autofocus this step should 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 may 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 may 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

Disabled users or users with some devices may 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 are not able to use keyboard navigation.

Press the Esc key to dismiss the current active guide
Use Tab to advance through 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 will likely be at the bottom of the DOM below all content on the page. A user may 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 role

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.

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 are not 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 will not 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 will be cached by assistive devices.

Accessibility feature limitations

Sandbox and Integrations Resource Center modules are not accessible
Buttons with URL Link actions do not notify the user that it is a link, but an ARIA label can be used to add descriptive text