Summary

Added mobile sidenav to the Documentation page template. Sidenavs will now always follow logical HTML order on mobile and desktop views. Both navs use utility classes to change display settings based on viewport width.

Breaking change

⚠️ This is potentially breaking change.

Workaround

Include a duplicate sidenav after main content. Visibility is toggled using utility classes to avoid accessibility issues related to tab order and users of assistive technologies.

Recommended workaround

<div class="grid-container">
  <div class="grid-row grid-gap">
-   <div class="usa-layout-docs__sidenav">
+   <!-- One of two sidenav's only shown in desktop breakpoints. --> 
+   <div class="usa-layout-docs__sidenav display-none desktop:display-block desktop:grid-col-3">
      {{ SIDENAV_MARKUP }}
    </div>
-   <main class="usa-layout-docs__main desktop:grid-col-9 usa-prose usa-layout-docs" id="main-content">
+   <main class="desktop:grid-col-9 usa-prose usa-layout-docs" id="main-content">
      {{ MAIN_CONTENT }}
    </main>
  </div>
+ <!-- New duplicate section only shown on mobile. -->
+  <div class="usa-layout-docs__sidenav desktop:display-none">
+    {{ SIDENAV_MARKUP }}
+  </div>
</div>

Changed HTML

This solution effectively duplicates the nav HTML and displays only the correctly placed in-page nav.

While this doesn’t affect the in-page nav component, we do offer this page as a template and the component code is changed as a result of this PR. // Need to verify this causes a change

Removed template classes:

• usa-layout-docs__main: This is the class that had the styles that reordered element.
• usa-layout-docs: This selector unused in current styles.

Related issue

Closes #4594

Related pull requests

Alternate approach as discussed in #5681
Changelog → (Taken from #5681)

Preview link

Problem statement

In mobile, tab order doesn't match visual order in the documentation page example.

Solution

Create a second, mobile only in-page nav. Use utility classes to dictate which is displayed.

Testing and review

Visit Documentation page →

In desktop widths

1. Tab through navigation
2. Confirm tab order is correct
3. Confirm screen readers read nav before main content
4. Confirm second nav is hidden and not tabbed to or read by screen readers

In mobile widths

1. Confirm nav is still at the bottom of the page
2. Confirm tab order is correct
3. Confirm screen readers read main content before nav
4. Confirm original nav is hidden and not tabbed to or read by screen readers

Testing checklist

• No visual regressions
• Hidden navs are not targetted by tabbing
• Hidden navs are not read by screen readers
• Screen readers read content in visual order
• Tab order follows matches expectation.