Components

Button - Design decisions

Key design decisions for the Button component.

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 - Destructive button

Date raised: February 7, 2024
Decision date: February 9, 2024

Context

In reviewing the buttons between the VADS and our Mobile components, no Destructive Button variant was found within VADS. Research into Design System best practices finds that utilizing a Destructive Button is common in mature Design Systems. A “destructive button” clearly indicates to users that the action it initiates has significant or irreversible consequences, such as deletion, cancellation, or removal of data.

Decision

Don’t rely on color alone, indicate what will happen when used, and provide a level of error prevention.

Color with text

The use of color should use what is currently in the .
- Red is culturally and psychologically associated with caution, danger, and urgency, making it immediately clear that the action carries significant consequences.
- While color alone should not convey critical meaning (as per WCAG 1.4.1, Use of Color), a red button paired with textual labels clearly indicates the button’s destructive nature without relying exclusively on color.
  - Include descriptive text (e.g., “Delete,” “Remove permanently”).
  - Provide confirmation prompts or secondary verifications to further emphasize the action’s irreversible nature.

Design: button on white/light background

Default: vads-color-secondary #d83933 (AA 4.61:1 contrast)
Hover: vads-color-secondary-dark #b50909 (AA 6.98:1 contrast)
Active: vads-color-secondary-darkest #8b0a03 (AAA 9.8:1 contrast)

Design: button on black/dark background

Default: vads-color-secondary #d83933 (AA 4.61:1 contrast)
Hover: vads-color-secondary-light #F2938C (AAA 9.33:1 contrast)
Active: vads-color-secondary-lightest #F8DFE2 (AAA 16.64:1 contrast)

Friction

The Destructive button should be used with friction before completing the action.

Users should always see a to make sure they want to complete the action.
Example shown on VA Design System’s pattern when .
WCAG Criterion: 3.3.4 Error Prevention (Legal, Financial, Data)

Order considerations in a group

In usability and accessibility best practices, the destructive action button (e.g., “Delete”) should typically be second, placed after the neutral action (“Cancel”).

[ Cancel ]   [ Delete ]

Why this order is preferred:

Follows User Expectation: Users commonly expect neutral actions to appear first, with actions having more severe consequences placed later.
Error Prevention: Positioning the neutral action first helps prevent accidental selection of a destructive option due to habit or quick navigation.
Accessibility and Consistency: Aligns with common patterns used in major design systems (e.g., Apple Human Interface Guidelines, Material Design, and Microsoft Fluent UI), providing predictability and reducing user error.
Logical Flow: Users typically read left-to-right (in languages such as English), encountering the safer or neutral action first allows thoughtful consideration before selecting a more severe, destructive action.

How to meet accessibility standards

To ensure a destructive button conforms to accessibility requirements defined by WCAG and Section 508, several considerations are necessary:

1. Clear visual distinction and contrast

WCAG Criterion: 1.4.3 Contrast (AA) or 1.4.6 Contrast (AAA)
The button must have sufficient contrast against its background (minimum 4.5:1 contrast ratio for normal text). Red is commonly used, but verify contrast explicitly, as certain reds might lack sufficient contrast, especially against darker backgrounds.

2. Explicit labeling

WCAG Criterion: 2.4.6 Headings and Labels; 3.3.2 Labels or Instructions
Clearly label buttons explicitly indicating the destructive action (e.g., “Delete account” instead of “Submit” or ambiguous phrases).
Provide accessible labels (ARIA attributes) when necessary.

3. Accessible role and ARIA attributes

WCAG Criterion: 4.1.2 Name, Role, Value
Use semantic HTML (<button> element) rather than generic <div> or <span> elements.
Optionally, utilize ARIA attributes to clarify destructive actions for screen reader users:

<button aria-label="Delete your account permanently">
  Delete Account
</button>

4. Clear warnings and confirmations

WCAG Criterion: 3.3.4 Error Prevention (Legal, Financial, Data)
Provide confirmation dialogs or a two-step verification process, ensuring users deliberately confirm before action execution.

5. Keyboard navigation and focus

WCAG Criterion: 2.1.1 Keyboard, 2.4.7 Focus Visible
Ensure the button is accessible and operable via keyboard-only navigation.
Provide distinct visual focus indicators clearly visible when the button receives keyboard focus.

6. Error handling and reversibility (when applicable)

WCAG Criterion: 3.3.1 Error Identification, 3.3.3 Error Suggestion
When possible, provide an undo capability for critical destructive actions or communicate clearly if actions are irreversible.

Example of accessible destructive button implementation:

<button class="usa-button usa-button--destructive" aria-label="Cancel appointment on 'July 2, 2025'">
  Cancel appointment
</button>

Consequences

A destructive button can be used anytime the action being taken cannot be undone, such as canceling an appointment.

Open Questions

The Mobile component includes a “dark mode” variation. How should VADS handle this, given that VADS does not currently have a comprehensive “dark mode” strategy?
Should we propose creating an issue to discuss renaming the Mobile “Segmented Control” component for better alignment?

ADR 002 - Remove radio as buttons guidance

Date raised: December 17, 2025
Decision date: February 25, 2026

Context

Button Documentation Updates - Radio buttons as buttons guidance updates . Button: Remove ‘button as radio’ section from docs .

The VA design system documentation includes guidance on choosing components for UI patterns. During a recent review of the guidance for button and radio components, the team identified existing documentation that describes using button elements as radio button options. This guidance appears to have been introduced for a special use case that is now archived, and there is uncertainty about whether this exception should remain in the guidance.

Additionally, the mobile team indicated that the use case could be better served by a radio tile pattern instead of button elements acting as radio options.

This led to the need to evaluate whether to retain, update, or remove the guidance on buttons as radio options.

Decision

We will remove the guidance since there is no longer a valid use case. There is not a team using this pattern and it was more of a special use case. If teams do need this in the future, they can reference it here.

Guidance removed from the documentation:

This variation substitutes the large tap target of a button where a radio button would traditionally be used. This serves a similar purpose to the USWDS Tile variation of a Radio button.

Limit to Yes/No. This variation should be limited to Yes/No questions rather than used as a substitute for radio buttons which can more readily handle 3 or more responses.
Reflect selections. The response of the user must change the button from a secondary button to a $vads-color-primary-dark background in order to reflect the state of the user’s response.

Consequences

If teams do decide to use Radio’s as buttons it will be more challenging for teams to revive guidance that has been deprecated.

Edit this page in GitHub (Permissions required)

Last updated: May 15, 2026