Accordion - 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 - Separate ‘expand all’ and ‘collapse all’ buttons

• Date raised: September 15, 2025
• Decision date: September 15, 2025

Context

Originally, the accordion ‘expand all’ and ‘collapse all’ buttons were a single toggle option. They were separated into two buttons that are visible all the time. You can read more about the change in this PR:

Decision

Separate the single toggle into two always-visible buttons: one for expanding all and one for collapsing all.

Consequences

The new pattern introduces a potential null button state where clicking a button doesn’t create an action. Here is a review of different government design systems and how they handle the ‘expand all’ and ‘collapse all’ buttons:

ADR 002 - Button design

• Date raised: September 15, 2025
• Decision date: October 22, 2025

Context

As part of updating the accordion component to display both “Expand all” and “Collapse all” actions simultaneously, we reviewed the design and visual treatment of these buttons.

Currently, the buttons resemble links but these elements perform actions on the page. They should be visually represented as buttons, not links. This change will improve clarity and accessibility by reinforcing their interactive nature.

Within our current design system, we identified two possible options for the accordion control buttons:

1. Secondary button - The outlined button style aligns with the system’s hierarchy but may visually compete with more prominent actions elsewhere on the page.
2. Icon button - The icon button, used as a tertiary action in specific contexts, may be a better fit. This would treat the “Expand all / Collapse all” actions as tertiary interactions.

Implementing this approach would require designing a new variation of the tertiary icon button. A proposed design can be reviewed in this .

Decision

• Component choice: We decided to move forward with the Icon button component since the accordion expand all or collapse all actions are considered tertiary in ranking.
• Button placement: We will keep the buttons right-aligned to maintain consistency with the icon below.
• Icon: We will use the same plus and minus icons that the accordions use for continued consistency.

Consequences

Either option will give the buttons more presence on the page and the accordions are used often throughout VA.gov. This change will have an impact on other teams’ designs and the prominence of the buttons.

ADR 003 - Button width

• Date raised: October 22, 2025
• Decision date: October 29, 2025

Context

When replacing the current Accordion buttons with the Icon Buttons it was discovered that they would overflow off the page at small screen sizes. There are a few options to fix this issue:

1. Stack the buttons on small screen sizes
2. Reduce the width of the accordion buttons

Decision

Reduce the width of the Icon Button component. We will reduce the button padding on the left and right from 20px to 8px. Normally, all of our buttons have 20px padding on the left and right. For this special use case we will reduce the padding for the Icon Button to 8px so that the two buttons will be visible at a 288px screen size.

Consequences

Reducing the width of the buttons creates more opportunities for users to accidentally press the wrong button. Even though the buttons will still be above the minimum 40x40px touch target WCAG requirements, having a larger button target area is ideal. It would be good to monitor the analytics for the Accordion button toggles to see if there is a change in interaction.

ADR 004 - Add state announcement

• Decision date: May 4, 2026

Context

The va-accordion component includes Expand all and Collapse all buttons that allow users to toggle every accordion panel at once. When a sighted user clicks either button, the visual change (panels opening or closing) provides immediate feedback. However, screen reader users received no programmatic announcement of the resulting state change, leaving them uncertain whether the action succeeded.

This is an accessibility gap: WCAG 2.1 Success Criterion 4.1.3 (Status Messages) requires that status or state changes not receiving focus be conveyed to assistive technologies so users are not left without feedback.

Decision

We will add an aria-live region (polite) to the va-accordion component that announces the resulting state after the Expand all or Collapse all button is activated. When the user clicks Expand all, the live region will announce “All sections expanded.” When the user clicks Collapse all, it will announce “All sections collapsed.” The live region will be visually hidden but present in the DOM so that screen readers pick up the message without disrupting the visual layout.

Implementation is tracked in .

Consequences

Positive

• Screen reader users now receive clear, immediate feedback when accordion state changes globally, improving parity between sighted and non-sighted experiences.
• Brings the component into compliance with WCAG 2.1 SC 4.1.3 (Status Messages).
• No visual change; the announcement is delivered through an aria-live region and does not affect the existing layout or sighted-user experience.
• Consumers of va-accordion across VA.gov benefit automatically without any changes to their own code.

Negative / Risks

• Overly chatty announcements could be disruptive if a user rapidly toggles state. Mitigated by using aria-live="polite", which waits for the user to be idle before announcing.