Button-v3

Button‑v3 is an interactive control that triggers an action when activated.

When to use

• Use for primary, secondary, or status‑related actions that submit data, open dialogs, or invoke commands.
• Choose the Style variant that matches the intent of the action (e.g., Primary for main actions, Error for destructive actions).
• Use the size variant that fits the layout density and touch target requirements.

When not to use

• Don’t use for navigation; use a link component instead.
• Don’t use when the action is optional or non‑essential; consider a Checkbox or Toggle for toggling states.
• Don’t rely solely on color to convey meaning; pair Style with clear text or an accessible label.

Anatomy / variants

Variant	Description	When to use
size	Controls the button’s dimensions.	Use Large for prominent calls‑to‑action, Medium for standard UI, and Small for dense layouts.
variant	Visual style of the button.	Filled for strong emphasis, Outline for secondary actions, Ghost for minimal emphasis, Icon when the button contains only an icon.
style	Semantic color intent.	Primary for main actions, Neutral for non‑critical actions, Error for destructive actions, Success for confirmation, Warning for caution, Info for informational actions.
state	Interaction state of the button.	Default for idle, Disabled when the action is unavailable, Loading while processing, _Focused/_Hover/_Pressed for visual feedback during interaction.
leadingIcon	Shows an icon before the label.	Enable when an icon helps clarify the action.
trailingIcon	Shows an icon after the label.	Enable for actions where a trailing indicator is appropriate (e.g., forward navigation).

Props / API

Prop	Type	Default	Description
leadingIcon	boolean	true	Renders an icon at the start of the button label.
trailingIcon	boolean	true	Renders an icon at the end of the button label.
size	variant	Large	Sets the button’s size; options are Large, Medium, Small.
variant	variant	Filled	Determines the visual style; options are Filled, Outline, Ghost, Icon.
style	variant	Primary	Applies semantic color intent; options are Primary, Neutral, Error, Success, Warning, Info.
state	variant	Default	Indicates the interaction state; options are Default, Disabled, Loading, _Focused, _Hover, _Pressed.

Accessibility

• Buttons are focusable with the keyboard and activate on Enter or Space.
• Provide a clear text label or an aria-label when the button contains only an icon.
• In the Loading state, set aria-busy="true" and optionally include a live region announcement.
• Ensure sufficient color contrast for the chosen style variant according to WCAG AA.
• When state is Disabled, remove the button from the tab order and set aria-disabled="true".

Changelog

• 2026-06-29 — Initial doc generated from Figma.