Complete screening questions - 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 000 - Origin of screening pattern

• Date raised: December 2, 2022
• Decision date: December 5, 2022

Context

This ADR documents the origin of the “Help users to check eligibility” / “Complete screening questions” pattern that was introduced to the design system in December 2022 (Git history references and Issue #702). The original work added a pattern to help users evaluate whether to continue with a form by checking their eligibility early in the flow.

Decision

Accept the creation of a dedicated screening pattern that provides guidance, examples, and a summary page to communicate likely eligibility. This formalizes the earlier change made to the repository to capture the pattern’s intent and maintenance expectations.

Rationale

• Issue #702 requested a pattern for checking eligibility and included examples and initial guidance.
• The pattern solves a practical problem: reducing wasted effort on lengthy application flows by letting applicants identify potential ineligibility early.
• The repository commit history shows the pattern was added and merged in early December 2022.

Consequences

• The pattern became a formal part of the VADS documentation, requiring ongoing maintenance and accessibility enforcement.
• Future updates to the pattern should reference this ADR when making breaking changes to the screening flow or examples.

Related

• Issue:

Decision

Record the problem as an ADR to preserve historical context and ensure future decisions reference the original issues and motivations.

Rationale

Issue #5025 captures UX, accessibility, and maintainability concerns that motivated later pattern changes. Recording this problem as an ADR ensures the team remembers why stricter rules (plain-language labels, programmatic text, content-first rule) were introduced.

Consequences

• Future pattern updates should reference this ADR when adding or reverting behavior that affects eligibility messaging, examples, or accessibility.

ADR 001 - Rename to Complete screening questions & content-first approach

• Date raised: May 18, 2026
• Decision date: May 27, 2026

Context

Issue #2487 recommended clarifying the purpose of the screening/eligibility pattern by renaming it and prioritizing a content-first approach over automatically creating screening subflows for simple eligibility checks. The change aligns the pattern title and guidance with observed content patterns in consumer flows and reduces unnecessary screening flows that increase maintenance and accessibility risk.

Decision

Rename the pattern to “Complete screening questions” and update guidance to prioritize content-first solutions:

• Use the pattern Introduction (content-first) for short eligibility lists (up to 3 simple checks) rather than creating a separate screening subflow.
• Reserve dedicated screening subflows for complex eligibility that research shows requires interactive checks, progressive disclosure, or conditional logic.
• Update examples and frontmatter to reflect the new name and guidance.

Rationale

• Many teams created screening subflows where a short content-first list would have been sufficient, increasing cognitive load and maintenance.
• Content-first reduces context switching, is easier to author and test, and is more accessible when presented as concise headings and list items with clear Yes/No labels.
• Renaming the pattern clarifies intent for content authors and implementers and aligns naming with the guidance change.

Consequences

• Authors should evaluate whether an eligibility check needs a subflow; default to content-first for simple lists.
• Documentation and examples were updated to reflect the new name and guidance; some existing implementations may need migration notes.
• Improves maintainability and accessibility but may require minor edits in consumer projects to adopt the new naming and guidance.

Related

• Issue:
• Supporting changes: PR:

ADR 002 - Card-based results, introduction eligibility, and prefill behavior

• Date raised: May 18, 2026
• Decision date: May 27, 2026

Context

Issue #6084 proposed a visual and interaction update for screening summary pages: present eligibility outcomes as discrete summary cards with status tags. The proposal also recommended moving short eligibility lists (three or fewer checks) into the Introduction page rather than a separate screening subflow and reusing screening answers to prefill fields on the main form when appropriate.

Decision

Adopt the following pattern-level design decisions:

• Present screening outcomes as summary cards that make each result scannable and self-contained.
  • Cards should include a clear plain-language headline and brief explanatory copy.
  • Each card should display a status tag (success/info/warning/error) to indicate the outcome.
• Move eligibility requirements to the Introduction page (content-first) when there are three or fewer simple requirements. Do not create a separate screening subflow for these short lists.
• When screening answers are reused to prefill main form fields:
  • Prefill only non-sensitive values, such as selections or non-PII text. Sensitive values (for example, SSN or full date of birth) must not be prefilled and must require explicit re-entry or confirmation.
  • Show a clear notification near the prefilled field explaining the source (“Prefilled from your screening answers”) and allow the user to edit the value before continuing.
  • Ensure prefill behavior respects privacy and can be reversed by the user during the session.

Rationale

• Summary cards with status tags improve scannability and reduce reliance on icon-only signals that can fail accessibility checks.
• Moving short eligibility lists into the Introduction reduces flow fragmentation and lowers users’ cognitive load. This follows the content-first guidance in ADR 001.
• Prefilling reduces duplicate entry and speeds completion, but it must be implemented with clear affordances so users understand and can correct prefilled values.

Consequences

• Documentation should describe the card-based summary pattern and the expected status-tag conventions.
• Implementations must provide prefill-notification UI and follow sensitivity rules for which fields may be prefilled.
• Some existing screening subflows may be simplified; migration notes and developer guidance should be provided.

Related

• Issue:
• PR: