In-page nav guidance update #1995

mitchmoccia · 2023-02-03T02:18:59Z

This guidance update supports PR 5124 which changes the main content section requirement for in-page nav from the main element to any element with the class .usa-in-page-nav__main.
uswds/uswds#5124

https://federalist-ead78f8d-8948-417c-a957-c21ec5617a57.sites.pages.cloud.gov/preview/uswds/uswds-site/mm-in-page-nav-guidance/components/in-page-navigation/

A changelog entry has been made as well. Thanks for your review!

amyleadem

@mitchmoccia
Thanks for your work here. I added some suggestions in the comments for your review. Some are small single word fixes, others are slightly larger structural recommendations. There might be reasoning for the existing structure that I am not aware of -- if so, feel free to take or leave my recommendations. I also understand if some of these items are creeping out of scope. If you have any questions, please don't hesitate to reach out.

_components/in-page-navigation/guidance/accessibility.md

amyleadem · 2023-02-03T23:00:12Z

_components/in-page-navigation/guidance/accessibility.md

@@ -1,5 +1,5 @@
 - **Allow keyboard navigation.** Users should be able to navigate between nav items by using the `Tab` key. They should also be able to activate a link when pressing `Enter` on their keyboard. Users should be able to activate hover and focus states with both a mouse and a keyboard.

- **Enable tab order so  keyboard users access the in-page navigation before the main content section.** When a user tabs through a page that contains the in-page navigation component, they should find the in-page navigation before the `main` content. Since the in-page nav will most commonly exist to the right of the content (and follows the `main` element in the markup) this may seem like a tab-order error, but tabbing through the entire page before getting to in-page navigation links is not logical, creates confusion, and diminishes the user experience.
+- **Enable tab order so keyboard users access the in-page navigation before the main content section.** When a user tabs through a page that contains the in-page navigation component, they should find the in-page navigation links before the main content. The in-page nav will most commonly exist to the right of the content, yet in the markup, precede the `.usa-in-page-nav__main` element. This may seem like a tab-order error, but this prevents tabbing through the entire page before getting to the in-page navigation links, which is not logical, creates confusion, and diminishes the user experience.


The phrase "Enable tab order" felt confusing to me. I made a few suggestions in an effort to add clarity and shorten the text a bit. Take what you will!

Suggested change

- **Enable tab order so keyboard users access the in-page navigation before the main content section.** When a user tabs through a page that contains the in-page navigation component, they should find the in-page navigation links before the main content. The in-page nav will most commonly exist to the right of the content, yet in the markup, precede the `.usa-in-page-nav__main` element. This may seem like a tab-order error, but this prevents tabbing through the entire page before getting to the in-page navigation links, which is not logical, creates confusion, and diminishes the user experience.

- **Consider tab order.** Structure your markup so that keyboard users can access the in-page navigation _before_ the main content section. The in-page navigation will most commonly exist to the right of the content, but should come before the `.usa-in-page-nav__main` element in the markup. This may seem like a tab order error, but it allows keyboard users to find navigation items sooner, which is more logical and minimizes confusion.

Made the requested changes on accessibility and clarified tab order.

amyleadem · 2023-02-06T16:22:04Z

_components/in-page-navigation/guidance/implementation.md

 - **Root margin.** The root margin property (`data-root-margin`) is a string that allows you to define the observable area. This set of values grows or shrinks the observable area from each side of the root element's bounding box before computing intersections. It can accept values similar to the CSS margin property, and can be percentages. By default, the in-page navigation component is set to `0px 0px 0px 0px`. 
- **Threshold.** The threshold property (`data-threshold`) determines how much of the observable section must be present in the observed area before the nav's item is set to current. The default is `1`, which means 100% of the observables must be in the observed section. You can set `data-threshold` to any integer between 0 and 1.
+
+{:.usa-content-list }
+- **Threshold.** The threshold property (`data-threshold`) determines how much of the observable section must be present in the observed area before the nav's item is set to current. The default is `1`, which means 100% of the observables must be in the observed section. You can set `data-threshold` to any decimal value between 0 and 1. For example, `threshold: .5` would require that 50% of the observable section is visible in the observed section before the navigation item is set to `current`.


Is it possible to condense this property-related content (e.g. the summaries for threshold and root margin) into their related descriptions in the properties table? It feels a little confusing to me that similar/overlapping information about these properties is found in two separate areas on the page.

amyleadem · 2023-02-06T16:25:20Z

_components/in-page-navigation/guidance/implementation.md

 Implementing the in-page navigation component requires a few additions and adjustments to your page's markup.

 {:.usa-content-list }
- A wrapper `div` with the class `usa-in-page-nav-container` must surround the `main` element of your page.
- A new sibling `aside` with the class `usa-in-page-nav` must precede the `main` element.
+- A wrapper `div` with the class `.usa-in-page-nav` must surround the `aside` element with the class `.usa-in-page-nav__container` and be followed by a sibling element (e.g. `div`) with the class `.usa-in-page-nav__main`.

 The following is an example of the minimum markup your page would need to inplement the in-page navigation component:

 ```
-<div class="usa-in-page-nav-container">
-  <aside class="usa-in-page-nav"></aside>
-  <main id="main-content" class="main-content">
+<div class="usa-in-page-nav">
+  <aside class="usa-in-page-nav__container"></aside>
+  <div class="usa-in-page-nav__main">
     [ Page content ]
-  </main>
+  </div>
 </div>
 ```


There is a formatting issue that caused the content in this section to visually extend beyond the width of usa-content-list content. Additionally, there are a couple opportunities to standardize content structure. I added a suggestion for lines 2-16 below that:

Adds a bolded summary for the section

Combines related content into one list item

Fixes formatting issues.

- **Structure your markup.** Implementing the in-page navigation component requires a few additions and adjustments to your page's markup. A wrapper `div` with the class `usa-in-page-nav-container` must surround the `main` element of your page. A new sibling `aside` with the class `usa-in-page-nav` must precede the `main` element. The following is an example of the minimum markup your page would need to implement the in-page navigation component: ```html <div class="usa-in-page-nav"> <aside class="usa-in-page-nav__container"></aside> <div class="usa-in-page-nav__main"> [ Page content ] </div> </div> ```

amyleadem · 2023-02-06T16:31:55Z

_components/in-page-navigation/guidance/implementation.md


 {:.usa-content-list }


This file should need only one declaration of {:.usa-content-list }. It should be safe to remove this and the other declarations below. As long as there is no unnecessary space between the list items, it should be format correctly.

Suggested change

{:.usa-content-list }

amyleadem · 2023-02-06T16:45:38Z

_data/changelogs/component-in-page-navigation.yml

@@ -2,6 +2,17 @@ title: In-page navigation
 type: component
 changelogURL:
 items:


Would you add a changelog item that explains the changes made to the uswds-site repo in this PR? It might feel a bit redundant but I like the consistency of letting users have quick access to more context about the documentation updates if desired.

amyleadem · 2023-02-06T16:48:29Z

_data/changelogs/component-in-page-navigation.yml

@@ -2,6 +2,17 @@ title: In-page navigation
 type: component
 changelogURL:
 items:
+  - date: 2023-02-03
+    summary: Component updated to allow for any element to be used as the main content section.


Need a small structure shift. Changelog entries should begin with an active verb and provide the name of the component for added clarity.

Suggested change

summary: Component updated to allow for any element to be used as the main content section.

summary: Updated in-page navigation to allow for any element to be used as the main content section.

amyleadem · 2023-02-06T17:01:02Z

_components/in-page-navigation/guidance/usability.md

@@ -1,6 +1,6 @@
 - **Make it stand out.** Site visitors should be able to quickly and easily distinguish in-page navigation from other landmarks on the page. Include borders and well-defined link active states to clearly convey the utility and purpose of the section. Define a consistent width for the in-page navigation component that is sufficiently wide and does not change based on text length.

- **Use language that matches section headings.** The text of the links displayed within the in-page navigation `aside` should match the heading text of the target sections. Our component scans the page for `h2` and `h3` elements within the `main` element, automatically creates the in-page navigation block, and dynamically inserts the text to match the section headings.
+- **Use language that matches section headings.** The text of the links displayed within the in-page navigation `aside` should match the heading text of the target sections. Our component scans the page for `h2` and `h3` elements within the element that contains the class `.usa-in-page-nav__main`, automatically creates the in-page navigation block, and dynamically inserts the text to match the section headings.


Opportunity to be slightly more direct

Suggested change

- **Use language that matches section headings.** The text of the links displayed within the in-page navigation `aside` should match the heading text of the target sections. Our component scans the page for `h2` and `h3` elements within the element that contains the class `.usa-in-page-nav__main`, automatically creates the in-page navigation block, and dynamically inserts the text to match the section headings.

- **Use language that matches section headings.** The text of the links displayed within the in-page navigation `aside` should match the heading text of the target sections. Our component scans the page for `h2` and `h3` elements within the `.usa-in-page-nav__main` element, automatically creates the in-page navigation block, and dynamically inserts the text to match the section headings.

amyleadem · 2023-02-06T17:04:04Z

_data/changelogs/component-in-page-navigation.yml

+    affectsStyles: true
+    githubRepo: uswds
+    githubPr: 5124
+    versionUswds: 3.3.0


Note: Before merge, the version and date will need to be updated for this changelog item

amyleadem · 2023-02-06T17:06:15Z

_components/in-page-navigation/guidance/usability.md

@@ -1,6 +1,6 @@
 - **Make it stand out.** Site visitors should be able to quickly and easily distinguish in-page navigation from other landmarks on the page. Include borders and well-defined link active states to clearly convey the utility and purpose of the section. Define a consistent width for the in-page navigation component that is sufficiently wide and does not change based on text length.

- **Use language that matches section headings.** The text of the links displayed within the in-page navigation `aside` should match the heading text of the target sections. Our component scans the page for `h2` and `h3` elements within the `main` element, automatically creates the in-page navigation block, and dynamically inserts the text to match the section headings.
+- **Use language that matches section headings.** The text of the links displayed within the in-page navigation `aside` should match the heading text of the target sections. Our component scans the page for `h2` and `h3` elements within the element that contains the class `.usa-in-page-nav__main`, automatically creates the in-page navigation block, and dynamically inserts the text to match the section headings.

 - **Don't include the page `h1` in the nav.** Each page should have a single `h1` to describe its contents. It would be redundant to include this heading level in the in-page navigation.


Change "nav" to "navigation".

Suggested change

- **Don't include the page `h1` in the nav.** Each page should have a single `h1` to describe its contents. It would be redundant to include this heading level in the in-page navigation.

- **Don't include the page `h1` in the navigation.** Each page should have a single `h1` to describe its contents. It would be redundant to include this heading level in the in-page navigation.

Spell out navigation (was "nav" in several places). Clarify tab order.

mejiaj · 2023-08-07T16:41:59Z

@amyleadem is this PR still relevant or should we close and move to a new PR?

mitchmoccia added 4 commits January 18, 2023 21:54

Remove package-lock

a5a3bb4

Pull main and resolve conflicts

cb8d3fc

Merge branch 'main' of https://github.com/uswds/uswds-site

4a93762

Update in-page nav guidance to support PR 5124

e370a2c

mitchmoccia requested review from jonadecker, mejiaj, thisisdano, maomeara63 and amyleadem February 3, 2023 02:18

mitchmoccia mentioned this pull request Feb 3, 2023

USWDS input mask version 2 uswds/uswds#5104

Closed

jonadecker added 2 commits February 3, 2023 12:14

Minor wordsmithing

9508cc1

Change integers to decimal values in implementation guide for Threshold

0f2a7c9

amyleadem self-assigned this Feb 3, 2023

Set width of properties table to full width in in-page nav guidance

bdeb20f

amyleadem suggested changes Feb 6, 2023

View reviewed changes

amyleadem removed their assignment Feb 6, 2023

Responding to comments

e0bbdba

Spell out navigation (was "nav" in several places). Clarify tab order.

thisisdano added this to the uswds 3.5.0 milestone Mar 7, 2023

amyleadem mentioned this pull request Apr 10, 2023

USWDS - Input mask: Version 2 uswds/uswds#5227

Open

22 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

In-page nav guidance update #1995

In-page nav guidance update #1995

Uh oh!

mitchmoccia commented Feb 3, 2023 •

edited

Loading

Uh oh!

amyleadem left a comment •

edited

Loading

Uh oh!

Uh oh!

amyleadem Feb 3, 2023

Uh oh!

jonadecker Feb 6, 2023

Uh oh!

amyleadem Feb 6, 2023

Uh oh!

amyleadem Feb 6, 2023

Uh oh!

amyleadem Feb 6, 2023

Uh oh!

amyleadem Feb 6, 2023

Uh oh!

amyleadem Feb 6, 2023

Uh oh!

amyleadem Feb 6, 2023

Uh oh!

amyleadem Feb 6, 2023

Uh oh!

amyleadem Feb 6, 2023

Uh oh!

mejiaj commented Aug 7, 2023

Uh oh!

Uh oh!

	summary: Component updated to allow for any element to be used as the main content section.
	summary: Updated in-page navigation to allow for any element to be used as the main content section.

	- Don't include the page `h1` in the nav. Each page should have a single `h1` to describe its contents. It would be redundant to include this heading level in the in-page navigation.
	- Don't include the page `h1` in the navigation. Each page should have a single `h1` to describe its contents. It would be redundant to include this heading level in the in-page navigation.

In-page nav guidance update #1995

Are you sure you want to change the base?

In-page nav guidance update #1995

Uh oh!

Conversation

mitchmoccia commented Feb 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

amyleadem left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mejiaj commented Aug 7, 2023

Uh oh!

Uh oh!

mitchmoccia commented Feb 3, 2023 •

edited

Loading

amyleadem left a comment •

edited

Loading