Multiple responses - 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.

Background

The Multiple responses pattern — originally called List and Loop — was created to address a common form problem: how to let users add, edit, and delete an unknown number of similar items within a form flow. Examples include lists of dependents, employers, medical treatments, or service periods, where the number of entries varies by person and can’t be determined in advance.

The pattern was formally launched in May 2024 and by June 2025 was in use across 17 forms in production on VA.gov.

Timeline

• 2022 —
• May 2024 — Pattern launched as “List and Loop”
• 2024–2025 — Guidance added
• 2025 — Pattern renamed from “List and Loop” to “Multiple responses”

Research

ADR 001 - Button or action link as an alternative to yes/no on the introduction page

• Date raised: October 28, 2024
• Decision date: November 12, 2024

Context

The default introduction page for a multiple responses loop uses a yes/no radio button question to ask the user whether they want to add an item. For some forms — particularly those dealing with sensitive topics like traumatic events — a yes/no framing felt clinical or inappropriate. Teams working on VA Form 21-0781 (PTSD personal statement) and the 10-10EZR (emergency contacts and next of kin) requested an alternative entry point that allowed users to enter the loop without having to answer a yes/no question about whether they want to add something.

Decision

An optional configuration allows the introduction page to use a button or action link to enter the loop instead of a yes/no radio question. The yes/no format remains the default. Teams should choose the entry point that fits their content context — yes/no makes the optional nature of the step explicit, while a button or link may be more appropriate when the framing of a yes/no question would feel awkward or insensitive given the subject matter.

Consequences

Positive:

• Teams working with sensitive content can choose an entry point that is appropriate for their context without having to work around the default pattern.
• Increases the range of use cases the pattern can support without requiring a separate implementation.

Negative / watch items:

• The button and link variants make it less visually explicit that a section can be skipped. Teams using this option should ensure users can clearly bypass the section if it is optional.

ADR 002 - Users cannot proceed past the summary page with incomplete items

• Date raised: September 10, 2024
• Decision date: July 11, 2025

Context

If a user partially filled out an item and that item was left in an incomplete or invalid state — displayed as a card with a red error on the summary page — users could still click Continue and move on to the next step of the form. This meant incomplete data could be carried forward silently. The question was whether to block progression and, if so, how to communicate the problem clearly without disrupting the form flow.

Decision

When a user attempts to continue past the summary page while one or more cards are in an invalid or incomplete state, the form blocks progression, scrolls to the first invalid card, and moves focus to the error within that card. An error message reads:

You haven’t completed all of the required fields for at least one [noun singular]. Edit or delete the [noun singular] marked “incomplete” before continuing.

This applies to both yes/no and button/link entry point variations.

Consequences

Positive:

• Prevents incomplete data from being submitted.
• Users receive clear, actionable feedback — they know which item is incomplete and what to do about it.
• Consistent with standard form validation patterns: errors block progression and focus is sent to the problem.

Negative / watch items:

• None identified.

ADR 003 - Focus management rules for add, edit, delete, and cancel operations

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

Context

When users add, edit, delete, or cancel items from the summary or review pages, focus management was inconsistent. Specific problems included: focus moving to the H2 stepper after canceling an item rather than to the correct heading; focus landing on the success alert web component container rather than an interactive element within it, causing screen readers to not reliably announce the alert text; and focus going to the “Add another” button after a deletion rather than a success confirmation.

Decision

Explicit focus rules apply for each user operation on the summary and review pages:

• After completing an edit (save and continue): Focus moves to the close button of the success alert.
• After deleting an item: Focus moves to the close button of the success alert.
• After adding a new item from the review page: Focus moves to the close button of the success alert.
• After canceling adding an item from the review page: Focus moves to the H3 of the accordion section where the user started.
• When a confirmation modal opens (delete or cancel): Focus moves to the modal’s close (“X”) button, the first interactive element in the modal.

Focusing on the close button of the success alert — rather than the alert component itself — ensures screen readers reliably announce the alert text. Focus on a web component’s container is not consistently announced; focus on an interactive element within the component is.

Consequences

Positive:

• Consistent, predictable focus behavior across all item operations.
• Reliable screen reader announcement of success and deletion confirmations.
• Users are never left with focus stranded on an element that doesn’t communicate the result of their action.

Negative / watch items:

• Web components require focusing on an internal interactive element (the alert close button) rather than the component container to ensure consistent announcement across screen readers. This is a pattern-level constraint that all implementations of this pattern must follow.

ADR 004 - “Add another” call-to-action is a secondary action link, not a primary button

• Date raised: November 17, 2025
• Decision date: April 23, 2026

Context

The summary page includes a call-to-action for users to add more items to their list. Originally this was implemented as a primary button. The summary page also contains a primary Continue button. Having two primary actions on a single page violates VADS guidance, which specifies that a page should have only one primary action. Additionally, the “Add another” action navigates the user to a different page — the first question page of the loop — rather than performing an in-page action. A link is semantically more appropriate than a button for an action that changes the user’s location.

Decision

The “Add another [item]” call-to-action on the summary page uses the Action link (secondary) component, not a primary button. This aligns with the VADS rule of one primary action per page and reflects the navigational intent of the action. The previous primary button option has been deprecated.

Consequences

Positive:

• Aligns with VADS guidance that a page should have a single primary action.
• A link accurately communicates to users that they are navigating to a new page, not triggering an in-page action.

Negative / watch items:

• Teams using the deprecated primary button option need to update their implementations when migrating to the current pattern.