Decision: Button Action Hierarchy

Status

Accepted

Date

March 3, 2026

Context

The button component ships six variants (default, secondary, destructive, outline, ghost, link), but there was no documented hierarchy mapping action importance to variant choice. Teams were picking variants by visual preference rather than by the action's role in the interface.

The secondary variant — a tonal/muted fill — doesn't map cleanly to a distinct action level. It sits between default (full fill) and outline (border only) in visual weight, but its purpose overlaps with both. In practice, outline better communicates "supporting action" because the reduction from solid fill to border-only creates a clear visual step-down from the primary action.

Decision

Define a four-tier action hierarchy that maps action importance to button variant:

Action LevelVariantWhen to Use
PrimarydefaultThe single most important action in a view. Limit to one per section.
SecondaryoutlineSupporting actions that complement the primary action.
TertiaryghostLow-emphasis, repeated, or supplementary actions (toolbars, table rows, dismiss).
DestructivedestructiveIrreversible or dangerous operations. Always pair with a confirmation step.

The link variant is used for navigation-style actions and sits outside the hierarchy — no special ranking rules apply.

The secondary (tonal fill) variant is deprecated. It remains in the component for backward compatibility, but new usage should choose outline instead.

Alternatives Considered

  1. Keep secondary as the secondary-action style. Rejected because the tonal fill doesn't create enough visual separation from default to clearly communicate a lower action priority.
  2. Fully remove the secondary variant. Rejected to avoid breaking existing implementations. Deprecation allows a gradual migration.

Consequences

  • Existing variant="secondary" usage still renders correctly but should be migrated to variant="outline" over time.
  • The spec and preview pages document the hierarchy so teams and AI agents pick variants by action importance, not aesthetics.
  • Button groups and form footers have a clear pattern: primary on the right, secondary/tertiary on the left.

When to Revisit

  • If a tonal variant is genuinely needed for a distinct purpose (e.g., toolbar active states, toggle groups), consider reintroducing it under a more descriptive name.
  • If the team finds that three levels of non-destructive emphasis (default → outline → ghost) are insufficient, reconsider the hierarchy tiers.