Guide Accessibility Features Overview

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.

Overview

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.

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 theWorld Wide Web Consortium (W3C) website for more information on web accessibility and Web Content Accessibility Guidelines (WCAG).

Requirements

• Reseller Adopt Partner's Pendo agent settings must be 2.126.0 or greater

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 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
• 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.

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.

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.

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 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

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.

Resource Center Accessibility

Keyboard navigation and focus elements are applied automatically when the Resource Center is promoted published. The Home, Guide List, and Onboarding modules support keyboard navigation and screenreader tools. External Website module uses external code and is unable to use accessibility features.

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

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 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

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 img tag.

Example of the Resource Center Badge inspected with Dev Tools

 

Autofocus

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.

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 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.

Available Roles

• No Role
• Article
• Banner
• Complementary
• Contentinfo
• 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

• Resource Center modules use only non-configurable accessibility attributes that are applied automatically

• The External Website Resource Center module is 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