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 make sure 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 input 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 setup in the Visual Design Studio when you're creating a guide.
These features are an important part of creating accessible web content. 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 the guide designer to implement.
- Adopt Partner's Pendo agent settings must be 2.26 or greater
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.
- Add a descriptive Alt Text or ARIA Labels 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
- Auto-Focus 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
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.
Accessing Theme Settings
1) Click Guides > Manage Theme.
2) In either the Typography or Button sections click the pencil icon.
3) The Color Contrast Section will then appear. If your color settings don't meet WGAC AAA standards, you will be notified by a warning modal.
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="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.
Click on 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 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
Click on the edge of the guide step to open 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
Edit Text Or Button Settings
Click on the building block to open 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
- Sub title is an
- Paragraph is a
- 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
Edit Image Settings
Click on 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
Click on 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.
Click on 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.
- 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
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 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 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 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 clicking these elements or tabbing through a page.
Focus ring example provided by Google
HTML Tag - Input
Badges use the
input tag in the HTML. They will likely inherit any properties assigned to
input in your CSS styling. Prior to adding accessibility features, badges used the
Example of the Resource Center Badge inspected with Dev Tools
Autofocus this step traps focus for assistive technology on the guide step until it is dismissed. This setting is configured in Container Settings for each guide step.
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, Alt Text applies to image building blocks, and Title is used for video building blocks.
Example of ARIA label in the DOM
ARIA Label, Alt Text, and Title are added in each individual building block.
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 with keyboard inputs.
- Press the Esc key to dismiss the current active guide
- Use Tab to advance through element in a guide step
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.
- No Role
Accessibility Feature Limitations
Poll building blocks are not accessible
Resource Center modules are not accessible
Text building blocks are all semantically paragraphs
<p>and assistive technologies will treat them as such regardless of Theme style selected (Title, Subtitle, or Paragraph) when styling these building blocks
Buttons with URL Link actions do not notify the user that it is a link