Skip to main content

Accessible page structure and layout

Page layout is critical when you are beginning to design an inclusive experience for your users. Not everyone navigates the page in the same way. Some people are more visual, so they respond better to images, pictures and icons. Other people prefer to read text to understand what they need to do.   

We often use visual cues to orient people to the content of a page, such as bold, italics, font, alignment, boxes or separators, and color. These are wonderful options as they allow a user to quickly skim the page to identify the important primary content, as well as secondary information.   

When designing in Pega, for accessibility reasons we need to keep in mind alternate methods of making those distinctions. Regions, headings, bypass blocks, and searching are just some of the tools that you can use to create such distinctions in your application. These tools allow users who rely on assistive technologies, such as screen readers, to navigate your page in the same way as you designed it. 

In this topic, we will explore:

  • Regions
  • Headings
  • Bypass blocks


Pages within Pega applications are generally divided into different regions. Regions, also known as landmarks, can be dedicated to navigation, your main content area, and for Search tools, among others. People can visually view your page and decide which region to focus on, depending on the task at hand. 

The figure below  shows an example of regions on an application page.

Government platform with highlights on Main, Search and Navigation landmark regions
A Pega application with annotated default regions.


Regions are useful for users to have because they create a consistent experience across your application - consistency is critical for users with disabilities. Consistency allows them to know where to quickly find the information they need to proceed in their task. Wouldn’t it be annoying if the Search box for an application was located in different places on different pages? Most well-designed applications maintain the search box in the same place across pages. 

When these regions are marked in the semantic code using HTML or ARIA (Accessible Rich Internet Application) regions, a screen reader user can utilize special keyboard combinations or other tools in their assistive technology to quickly locate the different regions. For example, in the JAWS screen reader users can navigate directly to regions by pressing the R key on their keyboard. In this way, just like a sighted user, they can quickly jump to the regions of the page needed to complete their task. 

Out of the box, Pega identifies the following ARIA regions: Navigation, Main, and Search. However, you can configure a region on any new section that you create. 

The configurable ARIA regions in Pega Platform (in the order that they are displayed on a page) include: 

  • Banner  
  • Navigation (menu) 
  • Search  
  • Main (where your critical content begins) 
  • Form
  • Complementary 
  • ContentInfo 

Best practices:

  1. Make sure that you identify the major areas of your page. At a minimum, ensure that you have a Navigation region, a Search region, and most importantly, a Main region. (Again, these regions are provided out of the box, but you can configure them as necessary.)
  2. There should only be one Main section on any page. The Main section is where you want users to focus when first coming to the page. It identifies the main purpose of the page. 
  3. Use other regions as necessary, to complement the page.

Configuring a region: 

Regions can only be configured on Dynamic layouts. To add a region during runtime:

  1. Open the Dynamic layout properties window.
  2. Expand the Accessibility section.
  3. In the Role Type list, select Landmark.
  4. In the Value field, select an appropriate Role value. For example, Complementary.
  5. In the Descriptors section, in the Label field, add some text that will read aloud when a screen reader lands on the landmark.


dynamic layout property panel with accessibility section highlighted
The Dynamic layout properties window




Headings provide a way for users to quickly scan a page for relevant content, so that they can find and go directly to the content they are interested in.   

For visual users, headings are often implemented with a specific design, such as use of bold, color, italics, and font size. However, a non-visual user or users with other visual impairments rely instead on heading levels. Heading levels are set in the semantic code, for example, using <h1> to indicate the highest heading in the hierarchy of the page. The heading levels then cascade down the page in ascending order: <h2>, <h3>, <h4>, etc.

Screen reader applications can read the headings, so the user can use a keyboard command to 'jump' directly to the content of interest. When designing your pages, if you find that you are adding visual cues such as larger fonts or Boldface, consider adding heading levels as well.  

The following example shows a hierarchy of heading levels:

  • <h1> Main heading </h1>
    • <h2> Sub heading </h2>
      • <h3>Sub sub heading </h3>
    • <h2>Sub heading </h2>

By default, Pega applications have a main heading (h1) on all Theme Cosmos application pages, and several sub headings (h2). Any additional heading levels require user configuration.

Best practices:

  1. Use only one level 1 heading. This is usually the title of the page.  
  2. The remaining heading levels should cascade down the page logically in ascending order (<h2>, <h3>, <h4>, <h5>). The lower the number, the more importance that header has.  
  3. Headings are used to control page hierarchy and break the content into understandable sections that provide context. For example, a level 2 heading should not be a child of a level 3 heading.   
  4. Skipping heading levels is bad practice, as the user can become disoriented.   
  5. Think of an application or web page like a draft of a written document, with sections and sub-sections. Every content element is part of a hierarchy.
  6. Think carefully about how you organize your page. Too many levels and sections can be overwhelming for a user, visually or when using a screen reader.   

The following figure shows the semantic heading levels assigned to those headings that have visual distinction, as seen through use of an accessibility bookmarklet.   

Case view page highlighting heading levels within page.
An example of heading levels within a page design.


Configuring headings: 

Headings can only be added to Dynamic layouts.

  1. Open the Properties for a Dynamic layout.
  2. Select the Display header and title checkbox. 
  3. Choose whether you want to reference the header element as text, a property, or something else, and then set the correct heading level based on the hierarchy of the page. 

For more information, see Configuring semantic headings

Note:   Do not use a label with formatted text to 'fake' the appearance of a heading. This setting only changes the visible appearance of the label but does not use the correct HTML semantic markup to indicate a heading level for screen reader users.



Bypass Blocks

Bypass blocks allow a keyboard user to move past a set of elements on a page that are repetitive across multiple pages.  The most common form of a bypass block is the use of Skip To links.  Skip To links are highly recommended because they serve as the first tab stop on a given page and provide quick navigation to the critical information for keyboard-only  and screen reader users. This means that the user does not have to click through all of the navigation elements that are often found at the top or left side of every page. They can jump directly to the content of interest.  

By default, Pega applications use Skip To links to Main, Search, and Navigation regions.

Skip to main link that is the first tab on the page
Skip To links are displayed when the user hits the Tab key for the first time on the page.


Best practices:

  1. Use no more than 5 Skip To links; 3 is the recommended maximum.
  2. The links should be visible to all users who tab through a page by using their keyboard. 
  3. Links should display the first time a user presses the Tab key on a page.
  4. Links should have a visible focus and be navigable using the Tab key.

Configuring Skip To links: 

Pega Platform includes a default pySkipLinksToTarget section and adds it automatically to your application. The section includes Skip To links to the Main region, the Search bar, and the Navigation pane, and you do not need to additionally configure it. However, you can create custom Skip To links as needed. For more information, see Creating custom skip links 


All products and versions


Additional Resources:

Perspectives videos by the W3C (World wide web consortium):

Related W3C Web Content Accessibility Guidelines:

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?

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