Update prefilled information - Design decisions

What is an ADR?

We use the ADR (Architecture Decision Record) to structure design decision documentation. Each ADR covers three things: the context that prompted the decision, the decision itself, and its consequences — including trade-offs and any open questions.

ADR 001 - Success alert messages

• Date raised: December 15, 2025
• Decision date: December 17, 2025

Context

Success alerts were originally rendered inside the contact info card. Designs called for moving them to appear above the section cards so they were more visible to users after completing an edit.

Decision

Move success alerts outside of the card and render them above the contact information section cards.

Consequences

In standard (non-minimal) header layouts, the alertsBlock appears before the page header. In minimal header layouts, it appears after the <h1>. Alerts are suppressed when the user has submitted and validation errors are present. Each success alert is context-aware: it shows “We’ve made these changes to this form and your profile” when a VA Profile save was detected (hasProfileUpdate), or “We’ve made these changes to only this form” when the change was form-only.

ADR 002 - Optional vs. required label

• Date raised: December 15, 2025
• Decision date: April 7, 2026

Context

Cards within the prefill pattern previously indicated when a section was optional. To align with broader design patterns across VA.gov, the labeling convention was revisited.

Decision

Show “Required” next to required questions and remove “Optional” labels from optional questions.

ADR 003 - Option to update only mailing address

• Date raised: December 15, 2025

Context

Give users the option to select whether they want to update their mailing address for the current form only, or for both the form and their VA profile. A key use case is temporary addresses — for example, when reordering medical supplies, a user may want mail sent to a temporary address without overwriting their permanent profile address.

Decision

The radio button option to choose where changes are saved is added to the mailing address only. Non-address fields (email, phone) display an informational alert on their edit page stating “Any changes you make will also be reflected on your profile.” The mailing address edit page suppresses this alert, since address changes do not automatically sync to VA Profile. A context-aware success alert on the confirmation page distinguishes between “We’ve made these changes to this form and your profile” and “We’ve made these changes to only this form,” based on whether a VA Profile save was detected during the edit session. The goal is to keep the VA Master Person Index current with updated contact information.

Consequences

• Users cannot opt out of saving only their email or phone to a specific form — only mailing address has the form-only option.
• Open question: Should this option be extended to any other editable prefill sections in the future?

ADR 004 - Routing behavior

• Date raised: January 15, 2026

Context

The API calls within the prefill pages require that a user follow the happy path (clicking Continue buttons to proceed through the form). If a user enters the URL of a form page directly, or navigates to a form page and refreshes, data from the save-in-progress endpoint is lost.

Decision

Introduce logic that reroutes the user to the /intro page if they navigate directly to a form URL or refresh a form page, enforcing the happy path.