# Core/Button - Design

Primary interactive element displaying text and supporting leading and trailing icons.

## Usage

Use a Button when someone needs to submit a form, confirm an action, or move a workflow forward, and the action warrants a dedicated, labeled control.

Use at most one primary (`variant="primary"`) button per view or modal for the main outcome. Pair it with a secondary (`variant="secondary"`) button for cancel or alternate paths. Use `appearance="danger"` with primary or secondary for destructive or irreversible actions.

## Properties

### Variant

| Variant     | Usage                                                                 |
| ----------- | --------------------------------------------------------------------- |
| `primary`   | Highest visual weight. Use once per view for the main action.         |
| `secondary` | Pairs with a primary button for cancel or alternative paths.          |
| `tertiary`  | Lowest visual weight. Use for supplementary or de-emphasized actions. |

### Label

Labels should use a verb + noun structure to describe what the button will do when pressed.

### Icon

Buttons have two icon slots; a leading and a trailing icon. Use the leading icons to visually reinforce their meaning and draw attention.

Trailing icons are used for disclosure and additional behavior indications.

### Size

Buttons come is three different sizes. Medium is the default and preferred size for most situations.

Small size is used when a button is inline with another element, such as a table or popover.

### Appearance

| Appearance | Default | Usage                                                       |
| ---------- | ------- | ----------------------------------------------------------- |
| `default`  | ✓       | Standard interactive actions.                               |
| `neutral`  |         | Lower-prominence secondary actions within a filled surface. |
| `danger`   |         | Destructive or irreversible actions (delete, revoke).       |

### Size

| Size | Default | Usage                                               |
| ---- | ------- | --------------------------------------------------- |
| `sm` |         | Compact toolbars, table row actions, dense layouts. |
| `md` | ✓       | Standard form actions, modal footers.               |
| `lg` |         | Call-to-action in empty states, hero sections.      |
| `xl` |         | Marketing or onboarding hero sections.              |

## Content

* Use verb-first labels: "Save changes", "Add item", "Delete record".
* Title case for all button labels.
* Keep labels to 1-3 words when possible. Never exceed 5 words.
* Use "Add" not "New" (e.g., "Add source", not "New source").
* Avoid vague labels like "OK" or "Submit" — be specific about the action.

## Behavior

* Activated with mouse click, Enter key, or Space key.
* Pending state (`pending` prop): replaces the leading icon or prepends a spinner while an async action is in progress; preserve button width to avoid layout shift.
* Disabled state: buttons with `disabled` prop are non-interactive and non-focusable; use `aria-disabled` if the button should remain focusable (e.g., with a tooltip explaining why it's disabled).

## Best Practices

Do:

* Do use a single `variant="primary"` button per view.
* Do pair primary with secondary for confirm/cancel patterns.
* Do use `appearance="danger"` for destructive actions.
* Do use verb-first, title-case labels.

Don't:

* Don't use a Button for navigation to another page — use [Link](?path=/docs/core-link--design) or [Anchor](?path=/docs/core-anchor--design).
* Don't use a Button for text-only inline navigation — use [Link](?path=/docs/core-link--design).
* Don't use a Button for icon-only actions — use [IconButton](?path=/docs/core-iconbutton--design).
* Don't use two primary buttons side by side.
* Don't truncate button labels.
* Don't disable a button without explaining why (use `aria-disabled` with a tooltip).

## Accessibility

* Always provide a visible text label; if the design requires a short label, add `aria-label` for context.
* For icon-only use cases, use [IconButton](?path=/docs/core-iconbutton--design) instead (which enforces an accessible label).
* Tab / Shift+Tab to focus. Enter or Space to activate.
* The pending state must be communicated to assistive technology (e.g., `aria-label="Saving..."` when `pending` is true).

## Related components

* [IconButton](?path=/docs/core-iconbutton--design) — For icon-only actions.
* [Link](?path=/docs/core-link--design) — For inline text navigation.
* [Modal](?path=/docs/core-modal--design) — Buttons typically appear in modal footers for confirm/cancel patterns.