diff --git a/src/_accessibility/focus-management.md b/src/_accessibility/focus-management.md index 22983f9b8..90efed464 100644 --- a/src/_accessibility/focus-management.md +++ b/src/_accessibility/focus-management.md @@ -58,7 +58,9 @@ On most static pages, you won’t need to move focus because browsers handle tha #### When a new page loads * **Don't move focus when a static page loads.** Browsers automatically set focus at the top, which works well for most users. -* **For single-page applications, set focus to the first unique heading when a new page loads.** If the new content does not have a unique heading, choose the element that gives users the most context. For multi-page forms, follow the specific guidance for [managing focus in form flows]({{ site.baseurl }}/templates/forms/accessibility-guidelines#managing-focus-in-form-flows). +* **For single-page applications, set focus to the first unique heading when a new page loads.** If the new content doesn't have a unique heading, choose the element that gives users the most context. For multi-page forms, follow the specific guidance for [managing focus in form flows]({{ site.baseurl }}/templates/forms/accessibility-guidelines#managing-focus-in-form-flows). + +**Note for developers:** In single-page applications (SPAs), loading a new page is technically called a "route change," even though the browser doesn't reload the entire document. #### When page content is added or removed @@ -73,7 +75,7 @@ On most static pages, you won’t need to move focus because browsers handle tha #### When opening and closing a modal * **When the modal opens, move focus to the first interactive element in the modal, unless it’s a destructive action.** The element can be a button, a form input, or the "close" button. However, if the first interactive element is a destructive action, choose a safer place to focus. -* **Ensure keyboard focus is trapped inside the modal.** While the modal is open, focus should stay inside the modal and should not move to the page elements behind it. +* **Ensure keyboard focus is trapped inside the modal.** While the modal is open, focus should stay inside the modal and shouldn't move to the page elements behind it. * **When the modal closes, restore focus to the button that opened it.** This helps users continue their workflow without losing their place. #### When inside a multi-page form diff --git a/src/_templates/forms/accessibility-guidelines.md b/src/_templates/forms/accessibility-guidelines.md index e35e10ab2..f792c6f1e 100644 --- a/src/_templates/forms/accessibility-guidelines.md +++ b/src/_templates/forms/accessibility-guidelines.md @@ -54,16 +54,18 @@ Every form interaction should be straightforward, regardless of how a Veteran ac ## Managing focus in form flows -Digitized forms on VA.gov are built as single-page applications (SPAs). When users move to a new page in these forms (also called a “route change" in SPAs) the app must manually set focus. This is because, unlike when a static page loads, focus does not reset automatically after an SPA route change. Setting focus helps users stay oriented and take the next step. +Digitized forms on VA.gov are built as single-page applications (SPAs). When users move to a new page in these forms, the app must manually set focus. This is because, unlike traditional websites where each page loads separately, SPAs don't automatically reset focus when displaying a new page. Setting focus helps users stay oriented and take the next step. + +**Note for developers:** In technical terms, moving to a new page in an SPA is called a "route change." {% include a11y/focus-management-benefits-risks.md %} -### Where to move focus when a new form page loads +### Where to move focus when a new page loads When a new page loads in a form application, move focus to an element that gives users context and helps them find the next action. Use these guidelines to choose the best focus location: -- **If the page has a unique page heading**, set focus there. The unique heading is usually an H1 at the top of the page or H3 inside the step content. -- **If the page does not have a unique page heading**, set focus on the step indicator header. This header is usually an H2. +- **If the page has a unique page heading**, set focus there. The unique heading is usually an H1 at the top of the page or an H3 inside the step content. Each page should have a heading that is unique to that view. +- **If the page doesn't have a unique page heading**, set focus on the step indicator header. This header is usually an H2. Avoid relying on this pattern when possible—prefer providing a unique heading for each page. - **When users navigate back to a form page**, treat it like a fresh page load and move focus to the top unique heading. ### Where to move focus in other scenarios