USWDS - Pages: Avoid reordering content in Documentation example

[mahoneycm]

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

Current (develop)	Feature branch
Default	Preview
Template (Site)	Feature branch template

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.

[amyleadem]

This is looking good. Added a suggestion to remove duplicate code. The suggestion will likely need to be tweaked and tested, but wanted to give you a starting point to let you know what I'm thinking. Let me know if you have questions!

[mahoneycm]

Update 3/1/24

Loved @amyleadem's suggestion to implement the side-nav via include. Testing didn't show any regression and the component markup output as expected. Tested via install on site.

[amyleadem]

This is looking good! Just a couple small tweaks to the data, detailed in the comments below.

[amyleadem]

Looks good to me!

I tested the following:

• Confirm no visual regressions from develop
• Confirm that the HTML order matches the visual order
• Confirm that the code meets standards

[mejiaj]

Thanks for helping out with this. Small comment for clarity, otherwise LGTM.

[mejiaj]

@mahoneycm I tweaked the summary to avoid any confusion with USA In-page navigation.

[thisisdano]

LGTM. Thank you!