Skip to content
This repository is currently being migrated. It's locked while the migration is in progress.
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions src/_accessibility/focus-management.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down
10 changes: 6 additions & 4 deletions src/_templates/forms/accessibility-guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading