Deepcrawl is now Lumar. Read more.
DeepcrawlはLumarになりました。 詳細はこちら

Complementary landmark not top level (A11y Best Practice Violation)

How to fix the web accessibility issue of “complementary” accessibility landmarks not being top-level — Lumar Web Accessibility Wiki

Semantics - Lumar Accessibility Thumbnail
NULL NULL
 

What does this accessibility issue mean?

Ensures the complementary landmark or aside is at top level

Accessibility issue summary: accessibility landmark with “complementary” role is not top-level

On websites, accessibility ‘landmarks’ enable blind or visually impaired visitors using screen readers to jump to various sections of a web page. 

The “complementary” landmark role attribute should only be used to mark complementary page content that supports the main content of the web page.

Landmark roles with a role attribute of “complementary” (<role=”complementary”>) should only be used on top-level landmarks. 

Other landmark roles that should only be used on top-level landmarks include:

  • banner
  • main
  • contentinfo

If accessibility landmark roles are incorrectly defined or incorrectly structured it can cause issues for users of assistive technologies such as screen readers that rely on these landmarks to navigate webpages easily. 

Solution: Ensure the complementary landmark or aside is at the top level.

Issue details
  • Accessibility Best Practice
  • Severity: Moderate
  • Category: Semantics (BP)
  • Rule ID: landmark-complementary-is-top-level

Lumar can help you find & resolve this website accessibility issue — & many others — on your own site. Speak to our team to get started with the platform.

Get a Lumar demo

 

Example HTML violation: Complementary landmark not top level (A11y Best Practice Violation)

 <header role="banner">
   <h1>Website Title</h1>
   <aside role="complementary">
     <ul>
       <li>
         <a href="#">Related Link 1</a>
       </li>
       <li>
         <a href="#">Related Link 2</a>
       </li>
     </ul>
   </aside>
 </header>
 <h2>Main Content</h2> This is the main content of the page.
 <!-- This will fail the AXE landmark-complementary-is-top-level rule -->
 <footer role="contentinfo">Website Footer Information </footer>

Explanation: The above HTML violates the landmark-complementary-is-top-level accessibility rule because it includes a complementary landmark (aside) within the banner landmark (header).

According to accessibility best practices, it is important to have the complementary landmark at the top level, separate from other landmarks.

 

How to fix "Complementary landmark not top level (A11y Best Practice Violation)" issue

 <header role="banner">
   <h1>Website Title</h1>
 </header>
 <aside role="complementary">
   <ul>
     <li>
       <a href="#">Related Link 1</a>
     </li>
     <li>
       <a href="#">Related Link 2</a>
     </li>
   </ul>
 </aside>
 <h2>Main Content</h2> This is the main content of the page. <footer role="contentinfo">Website Footer Information </footer>

Explanation: In this corrected HTML:- The complementary landmark (aside) has been moved outside of the banner landmark (header). This is because, according to the WCAG 2.1 guidelines, landmarks should form a model of the page and should be at the top level, not nested within other landmarks (unless they are nested within a region or application landmark).

In other words, landmarks such as main, complementary, banner, contentinfo should be treated as top-level components of your page's architecture.

  • Content inside the aside has remain the same.
  • Format and structure of your HTML code are still intact. The content of the document stays the same - it's just that the individual parts (landmarks) are arranged better to enhance the user experience, especially for the users who rely at assistive technologies to understand and navigate the page.

Sources:

 
Digital Accessibility + SEO + Website Health

Build better online experiences — explore the full Lumar platform