Components
Details - 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
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 - Design updates
- Date raised: October 1, 2025
- Decision date: November 18, 2025
Context
The initial bug request asked that the component more clearly resemble a button, reflecting its intended behavior. During review, we determined that shifting the component to use the <details> element meant it would no longer function as a button—but it still shouldn’t appear as a link. We concluded that it should retain a button-like visual identity to avoid user confusion.
We reviewed several existing button patterns—including Accordions, Primary Buttons, and Secondary Buttons—and determined that the Additional Info component required its own style to distinguish it from both buttons and accordions, as its interaction pattern differs from each.
Height: Although early explorations proposed a 44px height to meet WCAG touch target guidance, reviewing real use cases showed that a 26px height better supports the component’s role in contexts where space and visual hierarchy are important.
Border: A 1px border using the medium gray token was added to reinforce its button-like appearance. This provides the minimum AA-compliant contrast while keeping the component visually subtle and preventing it from competing with higher-priority content.
Icon: The icon was moved to the beginning for accessibility reasons related to high zoom levels. Similar to findings in issues filed with USWDS regarding accordions, right-aligned icons may disappear at high zoom. Left-aligning the icon eliminates this risk.
Decision
The new design improves accessibility and adheres to our guidelines: links should look like links, and buttons should look like buttons.
Consequences
Although we aimed to keep the visual updates minimal, the new design is still more prominent than the previous version. This may introduce challenges in current implementations, as the component may draw more attention than intended. We plan to update guidance to help teams navigate these changes. Some teams may need to transition certain uses of the Additional Info component to different components.
ADR 003 - Sizes
- Date raised: September 12, 2025
- Decision date: November 18, 2025
Context
Creating a solution for the new Additional Info component that reduced emphasis across various use cases proved challenging. One approach was to offer more control over the component’s width. The original component uses a full-width option, which we wanted to preserve, but we also looked to text inputs for inspiration. Like select and text input components, we determined that predefined width options could help teams better match the component to its context.
Decision
The component will support custom width, XL, and 2XL options so that the Additional Info component doesn’t appear excessively wide when not appropriate.
We considered adding a minimum width but decided against it. In many contexts—such as indented layouts—a minimum width could lead to overflow issues.
Consequences
Because this component is used extensively, it’s difficult to predict whether these additional sizing options will introduce new challenges or ultimately provide the right balance of flexibility and visual control.
ADR 004 - Remove border
- Date raised: January 20, 2026
- Decision date: January 20, 2026
Context
The existing additional info component has a prop to hide/show a left border.
Decision
In the redesign we aren’t allowing teams to toggle the border. We’ll need to remove the prop from the code.
ADR 005 - Indenting details text
- Date raised: January 17, 2026
- Decision date: January 21, 2026
Context
The original Additional Info component doesn’t indent content within the details area because the icon has historically been placed on the right side of the summary text. We’re moving the icon to the left side, which has created an alignment issue between the summary text and the details text. The summary text is indented due to the new icon, while the details text is not.
Decision
We decided to indent the details text by 24px so that it aligns with the summary text above. This helps create a clearer visual hierarchy and improves understanding of the relationship between the summary text and the details text.
Consequences
There is already an issue with text becoming too condensed on mobile, and this change will add an extra 24px of empty space to the content, which could cause readability issues—especially if the Additional Info component already contains a large amount of content. In some cases, the Additional Info component may already be indented, and this change could exacerbate spacing issues on mobile. We’ll need to reevaluate this design choice if we encounter use cases where the content requires more space.
ADR 006 - Icon vertical alignment
- Date raised: January 17, 2026
- Decision date: January 21, 2026
Context
The Additional Info icon was originally intended to be vertically centered to align with the Accordion icon. However, after reviewing the design, we determined that this could cause confusion about where the summary text begins. While the Accordion uses a centered icon, it includes visual differences that support this alignment. The Accordion has a gray background that creates visual separation, whereas the Additional Info component will have no divider or visual separation between the summary and the details.
Decision
We’ll vertically align the icon in the summary text to the top of the summary so that it more closely matches how HTML bullets are designed, where bullets align to the top of the text. This helps users quickly identify where the summary text begins.
ADR 007 - 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’ll create a new additional-info component with a clear deprecation plans for teams. We’ll also need to create a new name for it. We’ll 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’ll try to minimize that with clear documentation and communication.
ADR 008 - va-details
- Date raised: February 2, 2026
- Decision date: February 3, 2026
Context
Changing the foundational html of the existing component could cause downstream issues for teams and failing tests. We want to provide a new component to teams with the least amount of friction. And right now it seems the best way to do that is to create a new details component.
Decision
We’ll create a new details component.
Consequences
It could take time for teams to adopt the new component. It’s visually and semantically different from additional info but not in purpose or design. We don’t see a problem with having both styles out there for a while.