Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Best practices for accessibility

Updated on December 13, 2022
Applicable to Cosmos React and Theme Cosmos applications

Accessible design helps users with disabilities access the full range of application features. By following best practices for accessibility, you ensure that your application meets the industry standards for all types of users.

General guidelines

Design guidelines

  • Avoid inline styles, which might override custom settings that help users understand a page better.
  • Add labels to all fields, controls, cards, and images, but use only one method to label a field. Place labels above the fields that they describe.
  • Ensure that the UI alerts users of dynamic changes visually and through Live ARIA.
  • Provide meaningful error messages.
    Tip: Write The password must contain at least 8 characters rather than This entry is invalid.
  • Avoid timed events, which require complex configuration to comply with accessibility guidelines.
  • Avoid hover and right-click events.
  • Do not use link controls as buttons.
  • Use visibility conditions to control the appearance of the form. Do not use controls in disabled mode.
  • When you provide helper text, avoid referencing the color, shape, or visual location of a UI component.
    Tip: Write Click the Submit button rather than Click the blue button.
  • Apply placeholder text for input fields but do not substitute labels with placeholders.
  • Avoid technical language and jargon in labels, placeholders, and helper text.

Navigation guidelines

  • Check if users can navigate your design with keyboard only.
  • Avoid key commands. Key commands can conflict with screen readers.
  • Add paging to tables.
  • Give links meaningful text.
    Tip: Write Main page instead of Click here.
  • For each onclick event, configure a keyboard alternative.

Screen organization guidelines

  • Use headers and titles on layouts. Define headings through markup rather than formatting. Always configure a level one heading and use header levels correctly.
  • Limit the use of modal dialog boxes and overlays.
  • Do not force landscape or portrait mode in mobile apps.
  • Organize content on the UI and in the document object model linearly 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.
  • Use responsive layouts. Layouts and forms that have fixed window sizes might cause problems for users who need to resize their screens.
  • Do not use more than one main section on a page.
  • Do not use tables to define areas on your page. Use tables only to present collected data.

Image guidelines

  • Use caution when you introduce multiple icons. Ensure that the icons are labeled properly and can receive focus from the keyboard.
  • Do not wrap text in images.
  • Add meaningful alternative text and avoid reusing the same descriptive text for different resources.
  • Avoid adding alternative text to unimportant or decorative elements. Unnecessary text crowds the feedback from assistive technology such as screen readers.

Color use guidelines

  • Do not use color as the only indicator of a change of state. For example, if an error causes the field to display a red border, but does not produce any other indicators, the field is not accessible.
  • Use a 4.5:1 contrast ratio for text against the background color.
  • For meaningful icons, such as warning icon, use a 3:1 contrast ratio against the background color.
  • For form fields, use a 3:1 contrast ratio against the background color and the border.
  • Best practices for configuring UI components

    Pega Platform UI components have different levels of out-of-the-box accessibility. By learning about best practices for configuring accessible behavior of UI elements such as controls and layouts, you can improve the user experience for customers who rely on assistive technologies.

  • Best practices for using helper text

    While labels organize content and identify a control or a field, helper text is useful when users might need additional instructions to complete a task. Pega Platform provides several out-of-the-box options for adding text to your application with varying degrees of accessibility.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

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

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us