Accessibility - Checklist before filing an issue
Accessibility - Checklist before filing an issue
| Accessibility - Checklist before filing an issue | |
|---|---|
| New URL | https://docs.pega.com/bundle/platform-88/page/platform/user-experience/checklist-accessibility.html |
| This article has been moved over to our Pega Community here in order to align with our larger content strategy. Please update any bookmarks or links that you may have to this location. | |
Encountering accessibility issues in the application
Thoroughly testing an application for accessibility and usability is a necessary step in ensuring that all users share an equal experience when using your application. Testing routines can involve a number of technologies, such as manual screen reader testing, keyboard functionality, automated markup inspection, and much more. Prior to submitting an incident with Pega Support, it’s important to check and confirm some preliminary information to both get a better understanding of the components involved and confirm the issue may be a bug in the product.
Take this example - some users have reported that tab focus moves to numerous non-actionable items in their end-user portals, making standard navigation by keyboard lengthier and more complex for keyboard/screen reader users. Through investigation, engineers find that the PegaWAI ruleset is still enabled in the application, causing the unnecessary focus on normally un-focusable items. Since Pega Infinity (8.x), the PegaWAI ruleset is no longer recommended for accessibility features as components are being further improved in their design to have accessible markup out-of-the-box.
Points to confirm
Supported software
Pega maintains a list of supported operating systems, browsers, and assistive technologies corresponding to different versions of the platform. If you come across an issue on specific versions of these technologies, it’s good to refer to this page to confirm if the combination you are using is supported.
If an assistive technology is involved with the issue you are experiencing, it is a good idea to test with different versions of said software, if possible. This may help identify if the issue lies with the third-party technology rather than Pega Platform. It is generally recommended to use the most up-to-date version of assistive technology when using your application.
Component optimization
As mentioned, Pega puts continuous effort into improving controls and components for accessibility. When optimizing for the best accessible experience for users, some configuration options function better than others. For example, Repeating Dynamic Layouts have a checkbox to allow for standard keyboard navigation in Platform versions 8.6 and later, allowing for tab navigation between items in the list.
A list of recommended configurations for optimizing accessibility can be found in the best practices for configuring UI components.
Not every component offered in Pega navigates the same way. Based on WAI standards, different keystrokes are required for navigation based on the elements a user works with. For Pega controls in Theme-Cosmos or in Cosmos React, check if the navigation of the component aligns with the supported keyboard navigation for components.
Reflow and Resolution
Proper reflow in end-user portals is another matter of compliance important for an accessible web application, but often misunderstood when testing. According to W3C criteria on reflow, reflow dimensions are defined as 400% browser zoom at 1280x1024px, or 320x256px. Just zooming the browser into 400% won’t cover the requirements if the screen dimensions aren’t correct. Modifying your screen dimensions is possible either through your browser’s developer tools panel, or through your display settings on your computer.
DOM Components
In some instances, the issue may involve the misuse or lack of one or more attributes in the markup that are necessary for a component to work properly with assistive technologies. In these situations, it’s good to check the W3C guideline standards on how we can expect certain technologies to interact with certain elements. With the browser’s developer tools capabilities, you can also test the manipulation of HTML to see how results differ with certain assistive technologies based on what attributes are contributing.
The Accessibility Tree is a great tool available in Google Chrome's developer tools panel that shows allows for in-depth analysis of individual DOM elements and the information they share with assistive technologies.
It is worth noting that in Pega Infinity, many automated testing tools, such as aXe, that run against web pages built on Pega Platform may come across several instances of non-unique id attribute values on HTML elements. These attributes however exist on non-interatice, non-actionable DOM elements such as div or span. Keyboard users or individuals using assistive technologies will never directly interact with such elements when navigating through pages. Actionable components such as text inputs, radio buttons, checkboxes, etc. all have their own unique ids given to them. The values of these non-unique ids are internally used in Pega code for necessary functionalities in the product.
Filing an Accessibility Issue
Even after consulting with others and checking off potential causes of the issue, the issue may still be unresolved. The next step would be to open a support ticket in the Pega Support Portal. Follow the below guidelines for creating a support ticket to ensure the necessary content exists for engineers to provide an efficient solution.
Attachment Artifacts
In many cases, textual descriptions of an issue do not provide sufficient context for engineers to understand and work to resolve an issue. Providing supplementary information in the form of attachments can help parties involved understand the problem better.
- Screenshots of the scenario and, if applicable, output of the assistive technology being used can be extremely useful in painting a clear picture of the issue scenario.
- Screenshots of the markup of the component(s) involved can help engineers identify any attributes or elements that could be contributing to the issue.
- For more complex scenarios or issues, recording a short walkthrough video helps highlight the steps to reproduce the issue and the components involved.
Issue Details
It's important to provide a clear and exhaustive description of the issue seen in the application to ensure that engineers have all the necessary information to begin reproducing and debugging the issue.
- Avoid using application-specific keywords and terminology when describing processes and components of the application. This applies to both the ticket title and description.
- For example, instead of "Questionnaire items in the Onboarding feedback screen do not receive keyboard focus", say "Radio buttons on a particular page do not receive keyboard focus"
- Specify the browser(s) where the issue is seen.
- Provide the name and version of any assistive technologies used in conjunction with the issue behavior such as JAWS 2021 or Dragon 15, if applicable.
- Provide the name of the section rule(s) and controls involved where the issue is occurring, and specify if these are OOTB or custom. This is key for engineers reproducing the issue locally and identifying the root cause.
Results
An issue you come across in the application could very well be a product bug that needs to be fixed by the product developers. Nonetheless, following the steps in this guide will help to narrow down the root cause of the issue and facilitate a timelier resolution of the issue, whether it be through configuration or a change to be made in the product. Be sure to consider what artifacts to gather when submitting an incident to ensure engineers have the information and tools they need to promptly resolve the issue you are facing.