Additional Info - 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 - Structural updates

• Date raised: January 7, 2025
• Decision date: August 21, 2025

Context

A bug was filed requesting updates to the Additional Info design to improve accessibility and better reflect its button-like behavior. The current design resembles a link, which is misleading.

During investigation, we found that the Additional Info component could be further improved by restructuring it to use the native <summary> and <details> HTML elements. More information on these elements can be found at . While these tags previously raised accessibility concerns, those issues have since been resolved. Using them would provide a more accessible structure and eliminate the need for JavaScript, resulting in a simpler, more robust component.

An experimental issue was created to explore this further: Experimental Design Update Additional Info & Expandable Alert

Decision

Transitioning this component from a JavaScript-based implementation to a native HTML approach provides clear benefits:

• Improved accessibility
• No JavaScript required

Consequences

Changing the component’s structure and markup comes with risks. Because this component is used widely across VA.gov, these updates may introduce unexpected impacts in existing implementations.

ADR 002 - New component

• Date raised: February 2, 2026

Context

Changing the foundational html of the existing component could cause downstream issues for teams and failing tests. We want to provide the updated component to teams with the least amount of friction. And right now it seems the best way to do that is to allow teams to opt-in to the new component with a clear deprecation path.

Decision

We will create a new additional-info component with a clear deprecation plan for teams. We will also need to create a new name for it. We will also be able to more easily update existing prop names within the component.

Consequences

We asked a lot of teams in the v3 migration path to do a lot of migrating of components and are still dealing with some lingering imposters because of it. We may be causing more frustration, but we will try to minimize that with clear documentation and communication.