Skip to main content

Accessibility checklist for application building

Considering accessibility from the beginning of a project can lead you to build a more inclusive, user-friendly experience for all of your users. Some of these considerations include:

  • Design guidelines
  • Navigation guidelines
  • Page structure guidelines
  • Image guidelines

Design guidelines


  1. Use labels. Add labels to all fields, controls, cards, and images, but use only one method of labelling the fields. 
    • You can use helper text for more information. Helper text is announced to screen readers too. 
    • Ensure that you place labels above the field that they name.
  2. Alert context changes. Ensure that the UI alerts users of dynamic changes both visually and through Live ARIA means, when the changes impact the context of the page.
    • If your version of Pega Platform™ does not provide context changes out of the box, add them through the WAI ARIA role.
  3. Write meaningful error messages. Provide meaningful error messages for server-side error validation.
    • For example, write "The password must contain at least 8 characters,"  rather than just "Invalid."
  4. Use link controls for links. Links should take the user to a new page, whereas buttons initiate an action. Mixing links and buttons in can cause confusion.
  5. Use helper text. When you provide helper text, be explicit. Avoid referencing the color, shape, or visual location of a UI component.
    • For example, write "Click the Submit button," rather than "Click the blue button."
  6. Use simple language. Avoid technical language and jargon in labels, placeholders, and helper text.

Do Not

  1. Use inline styles. Avoid using inline styles, which might override custom settings that help users understand a page better.
  2. Use timed events. Avoid timed events, which require complex configuration to comply with accessibility guidelines.
  3. Use hover.  Avoid using events with access only through hover and right click.
  4. Use disabled mode. Use visibility conditions to control the appearance of the form. Do not use controls in disabled mode.
  5. Use placeholder text. Avoid using placeholder text for input fields. Do not substitute labels with placeholders!
  6. Use link controls as buttons.

Navigation guidelines


  1. Test your keyboard navigation. Check whether users can navigate your design using only the keyboard.
  2. Validate focus indicator. Ensure that all interactive controls have a focus indicator. 
    • Tip: You can customize your focus indicator to make sure that it stands out more by using :focus in CSS. For more information, see the CSS/Selectors/pseudo-classes/:focus topic on the W3C Wiki.
  3. Include pagination. Ensure that you add add paging to tables, for easier keyboard navigation.
  4. Use optimized tables. Always use optimized tables for the best keyboard navigation. Standard tables are no longer supported for accessibility reasons.
  5. Name links explicitly. Ensure that you write meaningful, descriptive text for links, that ideally is unique from other links on the page. For example, write "Main page" instead of "Click here".
  6. Ensure keyboard equity. For each on-click event, ensure that you configure a keyboard alternative.
  7. Focus consideration. WCAG allows for initial focus to be set on first interaction on a page, and most Pega applications that use UI Kit and Theme Cosmos follow this rule. However in Pega Platform version 8.8, you can configure your app to change initial focus to the on-process header flow during a case flow, and to the h1 heading level in all other cases. For more information, see the article entitled Setting initial focus to assignment title on the Pega Documentation site.

Do Not

  1. Use custom key commands. Key commands can conflict with screen readers.
  2. Rely on dialog boxes. Avoid using dialog boxes or modal dialog boxes for complex workflows that require searching and search results, tables with lots of data and interactions, and complex forms with lookups and dynamic content. This complexity generally introduces issues for users who are dependent on the keyboard alone, especially screen reader users.  This can also introduce challenges for users with low vision who require magnification and focus on small areas of the screen.
  3. Use Repeating dynamic layouts (RDLs) to display a grid or table. RDLs are best used to display repeated data that does not easily use a grid design. Implement Tab key navigation to simplify navigation for keyboard users.

Page structure guidelines


  1. Use heading levels.  Define headings by using markup rather than formatting within dynamic layouts.
  2. Ensure that you use at least one level 1 heading. Always configure a level one heading on the main content page, then use heading levels in descending order
  3. Structure page linearly. Organize your content in the UI and in the document object model in a linear way, to accommodate screen readers.
    • Tip: If your UI includes a large conditional section, consider making the transition explicit by putting the conditional content in multiple assignment steps.
  4. Use responsive layouts. Layouts and forms that have fixed window sizes can cause problems for users who need to resize their screens.

Do Not

  1. Force orientation. Never force landscape or portrait mode in mobile apps. 
  2. Use multiple main sections. On any page, there should only be one main section. This creates optimal navigation routes for screen readers.
  3. Use tables for layout. Do not use tables to define areas on your page. Use tables only to present collected data. 
    • Tip: Screen reader users navigate tables in a specific way. Once you add interactive elements, such as drop-down lists, checkboxes, and radio buttons, it becomes difficult to navigate and understand the context of the page and task.

Image guidelines


  1. Use icons selectively. Use caution when you introduce multiple icons. Ensure that the icons are properly labeled and can receive focus from the keyboard. If possible, try not to use icons within table cells.
  2. Use alternative text. Add meaningful alternative text and avoid reusing the same descriptive text for different resources.

Do Not

  1. Wrap text in images. This is a compliance violation.
  2. Add alternative text to decorative elements. Unnecessary text adds needless verbosity to screen readers.

This Topic is available in the following Module:

If you are having problems with your training, please review the Pega Academy Support FAQs.

Did you find this content helpful?

100% found this content useful

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega Academy has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

Close Deprecation Notice