As a user, I expect that the order of content in tab navigation and accessibility tree matches the visual presentation, so that I'm not disoriented by focus shifting unpredictably while navigating content (via Tab, for example).

As a developer, I expect that when I place content in markup after .usa-nav__primary, it will be shown visually after the navigation content.

An example of this is in the primary navigation mobile styling:

You can verify this by tabbing through the mobile navigation menu in the component demo, where you will find that:

• Display order: Close button, search field, search button, menu links
• Tab order: Close button, menu links, search field, search button

Interestingly, this problem does not affect the USWDS main website, since .usa-primary__nav is rendered within a (non-flex) .usa-nav__inner container.

Related guidance:

• C27: Making the DOM order match the visual order

  • The objective of this technique is to ensure that the order of content in the source code is the same as the visual presentation of the content. [...] Each order may be meaningful in itself but may cause confusion for assistive technology users.

• G59: Placing the interactive elements in an order that follows sequences and relationships within the content
  

  • When the order of the HTML source matches the visual order of the Web page, tabbing through the content follows the visual layout of the content. When the source order does not match the visual order, the tab order through the content must reflect the logical relationships in the content that are displayed visually.

Related resources:

• https://developer.mozilla.org/en-US/docs/Web/CSS/order#Accessibility_concerns
• https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout/Ordering_Flex_Items#The_order_property_and_accessibility
• https://tink.uk/flexbox-the-keyboard-navigation-disconnect/
• https://adrianroselli.com/2015/10/html-source-order-vs-css-display-order.html
• https://www.youtube.com/watch?v=8MAvH6vYbDo
• https://alastairc.uk/2017/06/the-responsive-order-conflict/

Possible improvements:

• Update guidance to recommend two copies of the search form or menu items for mobile and desktop, where respectively the search field is shown prior to menu items (mobile) and after menu items (desktop).
• Dynamically update DOM in JavaScript to reorder search field, optionally in combination with MediaQueryList#addListener to update after viewport size changes.