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).

ADR 003 - Color contrast

• Date raised: March 11, 2026
• Decision date: September 24, 2026

Context

The color contrast of va-button-segmented was raised as a possible violation of . The current governance team and the current 508 office reviewed the component and did not find it to be in violation of this criterion.

WCAG 1.4.11 guidance on boundaries states that a visual boundary indicating a control’s hit area is not required when the control has visible content, such as text, that helps users identify its presence. Guidance on buttons similarly notes that a button with a distinguishing indicator, such as position, text style, or context, does not need a contrasting visual indicator to show that it is a button.

This guidance had previously been interpreted more strictly than the criterion requires. This article, “”, was referenced as context for how this criterion is often over-applied in similar cases.

Alternatives considered

Attempts were made to darken the grey used in the component to increase contrast. In the end the decision was made to leave --vads-color-base-lighter as the background color without a border. The edges of the component, internally and externally, have a color contrast ratio of 1.31:1.

Decision

va-button-segmented background color will not be changed to address color contrast at this time. The current coloring will remain as is.

Consequences

Positive:

• No visual design change is required for existing implementations of the component.

Negative / watch items:

• Some users may still identify a button more easily when it has an outline that meets contrast requirements, even though one is not required by WCAG 1.4.11.