# Button

> Slug: `button` · Category: Actions

## When to use
- Trigger an in-page action: submit a form, open a modal, save changes, run a transaction.
- Confirm or progress a flow ("Continue", "Add to cart", "Pay now").
- Provide a secondary alternative ("Cancel") next to a primary action.

## When NOT to use
- Navigation between routes or pages — use `LinkStyledAsButton` (anchor with button styling) for visual buttons that navigate.
- Inline text affordances inside paragraphs — use `Link` or `ButtonStyledAsLink`.
- Icon-only affordances (close, more, favorite) — use `IconButton` (it requires `ariaLabel`).
- Two or more "primary" calls-to-action grouped together — keep one primary per section; use `secondary` and `tertiary` for the others.

## Variants & decision tree
- Highest-emphasis action in the section -> `variant="primary"` (one per section).
- Alternative or secondary action -> `variant="secondary"`.
- Lowest-emphasis / inline tertiary action with optional forward chevron -> `variant="tertiary"`. Pass `trailingIcon` to render the trailing chevron decoration (only honored when `variant="tertiary"`).

## States
- `disabled` — uses `aria-disabled` (button stays focusable per Arrow a11y rules); click is suppressed.
- `loading` — sets `data-loading="true"`, suppresses click, and announces "Submitting" via a screen-reader live region. Tertiary variant ignores `loading`.
- `monochrome` — neutral palette via `data-monochrome`.
- Force-state props for design review: `focused`, `hover`, `pressed`. Do not use in production code.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| **`children`** | `ReactNode` | — | Button label content (rendered inside a `<span>`). |
| `variant` | `'primary' \| 'secondary' \| 'tertiary'` | `'primary'` | Visual emphasis. |
| `size` | `'large' \| 'small' \| 'xs'` | `'large'` | Sets `data-size`. |
| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | Native HTML button type. |
| `icon` | `ReactNode` | — | Leading SVG element. Pass an `<svg>`, never a string. |
| `trailingIcon` | `ReactNode` | — | Trailing icon — only renders when `variant="tertiary"`. |
| `disabled` | `boolean` | `false` | Sets `aria-disabled` and blocks click. |
| `loading` | `boolean` | `false` | Loading state with SR announcement. |
| `monochrome` | `boolean` | `false` | Monochrome palette. |
| `inverse` | `boolean` | inherits | Dark-background styling (inherits from `ArrowThemeProvider`). |
| `ariaLabel` | `string` | — | Override accessible name. |
| `describedBy` | `string` | — | `aria-describedby` target id. |

## Usage examples
```tsx
import { Button } from 'arrow-react-bootstrap';

// Primary form submit
<Button type="submit">Continue</Button>

// Pair: primary + secondary
<Button variant="primary">Save</Button>
<Button variant="secondary">Cancel</Button>

// Tertiary with forward chevron
<Button variant="tertiary" trailingIcon={<svg viewBox="0 0 24 24"><path d="M9 6l6 6-6 6"/></svg>}>
  Learn more
</Button>

// Loading state
<Button loading onClick={submit}>Submit</Button>
```

## Composition
- Use inside `ButtonGroup` or `ButtonTray` for stacked / responsive action layouts.
- Place inside `Modal` footer with one primary + one secondary.
- Pair with `Title` and `SectionHeader` to terminate a content section.

## Accessibility
- Renders a real `<button>` with native focus and Enter/Space activation.
- `disabled` and `loading` use `aria-disabled` (focusable) — Arrow's pattern, not native `disabled`.
- For icon-only buttons, switch to `IconButton` so the accessible name is required.
- Provide `ariaLabel` only when the visible label is insufficient.

## Do / Don't
- Do: keep one `variant="primary"` per content section.
- Do: pass real SVG nodes to `icon` / `trailingIcon`.
- Don't: nest buttons or wrap in `<a>`; use `LinkStyledAsButton` for navigation.
- Don't: pass strings to `icon` — must be a `ReactNode` (SVG element).
