Button - Segmented - 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 - Segmented button design

• Date raised: May 7, 2025
• Decision date: May 7, 2025

Context

As part of our initiative to align VADS components with our existing Mobile Design System counterparts, we reviewed the Segmented Control component that the VA Mobile DS team has successfully implemented.

VADS currently lacks a component providing this specific functionality. We also considered the USWDS segmented button group, which shares visual similarities.

Decision

Based on our review and the successful implementation of the Mobile component in production:

• We will largely adopt the visual design and functionality of the existing Mobile Segmented Control component.
• The VADS visual design will be modified to allow the component to resize responsively, whereas the current mobile design is fixed at 320px.
• We will not be incorporating additional semantic color variations, such as those found in USWDS, at this time.
• The component will be addressed as “Button - Segmented” within guidance and Figma.
• The web component will be named va-button-segmented.

Consequences

• There is a potential risk that product teams may require alternate view configurations not included in the initial implementation.
• The current visual design of the Mobile component does not fully align with current VADS primary button styling, which may require additional design.
• The difference in component names (“Segmented Control” in Mobile vs. “Segmented Button” in VADS) is an inconsistency that should be addressed.

ADR 002 - Accessibility

• Decision date: June 10, 2025

Context

Because of WCAG 2.2 and Section 508 criteria, the Segmented Button component for VADS has a different semantic structure than the Mobile Segmented Control component.

HTML structure

The containing structure is a <ul> element. Each <button> element is within a <li> element.

<ul>
    <li><button>Label</button></li>
    <li><button>Label</button></li>
    <li><button>Label</button></li>
</ul>

UL grouping

The <ul> element groups the buttons and acts similarly to a <div> with role="group".

• The <ul> element acts like a fieldset holding radio buttons.
• The <ul> element tells assistive tech: “This is a group of related options.”
• Since there is no visible heading or label that explains what the group of buttons does, the <ul> element provides meaningful context for the group as a whole.

The <button> elements include the type="button" attribute which:

• Prevents form submission: without this attribute, buttons default to type="submit", which would submit any parent form when clicked.
• Provides semantic clarity: it explicitly declares this element as an interactive button that performs an action.
• Supports accessibility compliance: screen readers and assistive technologies rely on this to understand the element’s purpose and behavior.

<ul aria-label="View selection">
    <li><button type="button">Label</button></li>
    <li><button type="button">Label</button></li>
    <li><button type="button">Label</button></li>
</ul>

Use of aria-pressed

The aria-pressed attribute indicates the current selected state and is used with roles of group.

• aria-pressed="true" = button is currently active/selected
• aria-pressed="false" = button is not active/selected

aria-pressed is for toggle buttons (like view switchers), which is different from aria-checked, which is for radio buttons or checkboxes.

Decision

The Segmented Button component uses a <ul> containing <li> elements, each with a <button type="button"> and aria-pressed to communicate the selected state.

Consequences

The use of role="group" attribute may cause users to assume the segmented button selection (return and space keys) would behave similarly to toggle buttons (e.g., Play/Pause or Hide/Show).