Button

Aliases

cta, action button

Explore the math

Color,Type and Scale,Motion,Proof System

Decision guide

• Choose Button when the interaction should feel deliberate, documented, and reusable across product surfaces.
• If the scenario is more specialized than the current Button contract, prefer a simpler component or build a dedicated workflow on top of the lower-level DK primitives.

Do

• Keep the Button label, value, or status language direct enough to scan quickly.
• Use the documented size and state recipes instead of inventing one-off variants in product code.

Do not

• Do not hide the main purpose of Button behind decorative copy or overloaded surface treatments.
• Do not stretch Button into a workflow it was not designed to handle just because the visuals are close.

Anti-patterns

• Using Button as a generic layout container instead of a purpose-built interaction or content surface.
• Forking the documented recipe in product code instead of extending the shared DK contract.

Migration notes

• Migrate legacy button usage by mapping existing variants and states onto the documented DK props before porting any custom styling.
• Treat the docs examples as the reference contract for accessibility and event behavior during adoption.

interactive container

Carries the main action styling, spacing, and state transitions.

text label

Communicates the action in plain language.

supporting icon slot

Adds emphasis or direction before the label.

supporting icon slot

Adds continuation or disclosure after the label.

loading indicator

Replaces the icon/leading slot during loading states.

Variants

• solid: Highest-emphasis action for the main next step.
• soft: Prominent but calmer secondary emphasis.
• outline: Action with visible affordance and lighter fill.
• ghost: Low-emphasis action for denser surfaces.
• link: Button-like action styled with link energy while preserving a button frame.
• destructive: High-clarity destructive action with stronger risk signaling.

Sizes

• xs / sm: Compact sizes for dense UI and supporting actions.
• md: Default button scale for most product surfaces.
• lg: Higher-emphasis action size for spacious or touch-focused contexts.

States

• rest: Default compiled appearance.
• hover: Color and depth shift that strengthens affordance.
• focus-visible: Visible keyboard focus treatment using the system focus ring.
• pressed: Subtle active-state shift without scale distortion.
• disabled: Visually and semantically non-interactive state.
• loading: Busy state that suppresses activation and surfaces progress.

Semantics

• Renders as a native button by default or as an anchor when `href` or `as="a"` is supplied.
• Preserves disabled semantics for buttons and `aria-disabled` behavior for anchors.

Keyboard

• Supports native button activation with Enter and Space.
• Focus-visible styling appears without relying on hover-only affordance.

Screen readers

• Label text is exposed directly from the visible content or `ariaLabel` in icon-only mode.
• Loading buttons stay in the accessibility tree while suppressing repeated activation.

Caveats

• Icon-only buttons require `ariaLabel` so the action remains understandable to assistive technology.

Checklist

• Verify the visible label or title still produces a clear accessible name.
• Verify focus remains obvious in every supported state and size.
• Verify disabled, selected, and error states do not rely on color alone.

Implementation notes

• Button remains the reference component for the recipe compiler and proof pipeline.
• The slot-var section shows the resolved CSS variable contract the runtime consumes.

Implementation checklist

• Use the public component API first and only drop to lower-level primitives when the component contract genuinely does not fit.
• Keep theme overrides token-driven so proofs and recipes stay meaningful.
• Verify the shipped examples and proof fixtures still represent the real product scenario you are implementing.