Skip to content
This repository is currently being migrated. It's locked while the migration is in progress.

Commit 6fd8b9b

Browse files
committed
Clarify route and page
1 parent ef6ff58 commit 6fd8b9b

2 files changed

Lines changed: 11 additions & 7 deletions

File tree

src/_accessibility/focus-management.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,9 @@ On most static pages, you won’t need to move focus because browsers handle tha
5858
#### When a new page loads
5959

6060
* **Don't move focus when a static page loads.** Browsers automatically set focus at the top, which works well for most users.
61-
* **For single-page applications, set focus to the first unique heading when a new page (route change) loads.** If the new content does not have a unique heading, choose the element that gives users the most context. In single-page applications, a new page is defined by a route change, even though the browser does not reload the document. 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).
61+
* **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).
62+
63+
**Note for developers:** In single-page applications (SPAs), a new page loading is technically called a "route change," even though the browser doesn't reload the entire document.
6264

6365
#### When page content is added or removed
6466

@@ -73,7 +75,7 @@ On most static pages, you won’t need to move focus because browsers handle tha
7375
#### When opening and closing a modal
7476

7577
* **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.
76-
* **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.
78+
* **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.
7779
* **When the modal closes, restore focus to the button that opened it.** This helps users continue their workflow without losing their place.
7880

7981
#### When inside a multi-page form

src/_templates/forms/accessibility-guidelines.md

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -54,16 +54,18 @@ Every form interaction should be straightforward, regardless of how a Veteran ac
5454

5555
## Managing focus in form flows
5656

57-
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.
57+
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.
58+
59+
**Note for developers:** In technical terms, moving to a new page in an SPA is called a "route change."
5860

5961
{% include a11y/focus-management-benefits-risks.md %}
6062

61-
### Where to move focus when a new form page (route) loads
63+
### Where to move focus when a new page loads
6264

63-
When a new page (or route) 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:
65+
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:
6466

65-
- **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 route should have a heading that is unique to that view.
66-
- **If the page does not 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 route.
67+
- **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.
68+
- **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.
6769
- **When users navigate back to a form page**, treat it like a fresh page load and move focus to the top unique heading.
6870

6971
### Where to move focus in other scenarios

0 commit comments

Comments
 (0)