> ## Documentation Index
> Fetch the complete documentation index at: https://clementineds.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Button Component: Variants, States, and Token Contract

> The Clementine DS Button — AI-Ready, 4 variants, 3 sizes, 6 interaction states, 15 component tokens, full ARIA coverage. Backed by Mantine.

Button is the only AI-Ready component in Clementine DS. All five spec gates pass. The component ships 15 component-tier tokens, 6 interaction states, and 4 variants across 3 sizes. It wraps Mantine's `Button` and extends `MantineButtonProps` with an explicit `onClick` typing — always a native `<button>` element, never a `<div>`.

> [!NOTE]
>
> **Status: AI-Ready** — `aria_correct`, `structure_correct`, `states_complete`, `tokens_valid`, and `no_invented_styles` all pass. Token contract is closed at 15 component-tier tokens. Spec last verified `2026-06-08`.

## When to use

* Form actions: submit, cancel, reset
* Page-level actions: Create, Save, Publish
* Destructive actions: Delete, Revoke — always paired with a confirm step or undo
* Modal footer actions

## When not to use

* **Navigation to another page.** Use a link (`<a>` or your router's `<Link>`).
* **Toggling a single setting.** Use Switch.
* **A clickable icon with no label.** Use IconButton (not yet specced — add `aria-label` as a stopgap).

## Anatomy

Button is composed of five semantic parts. Only `root` and `label` are always present.

| Part | Element | Purpose |
| - | - | - |
| `root` | `<button>` | The native button element. Owns interactive state, focus ring, padding, and sizing. |
| `icon-leading` | `<span>` | Optional leading icon to the left of the label. Replaced by the spinner in the loading state. |
| `label` | `<span>` | The visible text content of the button. |
| `icon-trailing` | `<span>` | Optional trailing icon to the right of the label. |
| `spinner` | `<span>` | Loading-state indicator. Replaces `icon-leading` when `loading` is `true`. |

In the loading state the HTML structure becomes:

```html theme={null}
<button class="ds-button" aria-busy="true" data-intent="primary" data-size="md">
  <span class="ds-button__spinner">…</span>
  <span class="ds-button__label">Saving…</span>
</button>
```

## Variants

| Variant | Intent | When to use |
| - | - | - |
| `filled` (primary) | Default | Main action in a visual region. Use one per region. |
| `filled` (destructive) | Destructive | Irreversible actions (delete, revoke). Always pair with confirm or undo. |
| `outline` | Secondary | Sits alongside a filled primary. Lower visual weight. |
| `subtle` | Tertiary | Toolbar actions, dense UI. Lowest visual weight. |

## Sizes

| Size | Height | When to use |
| - | - | - |
| `sm` | 32px | Toolbar, dense table rows |
| `md` | 40px | Default — form actions, page-level actions |
| `lg` | 48px | Marketing CTAs, mobile primary actions |

Pass `size` as a prop: `<Button size="sm">`. The default is `md`.

## Interaction states

| State | Visual change | Token(s) | Notes |
| - | - | - | - |
| `default` | Base fill | `button.bg.default` | |
| `hover` | One step darker | `button.bg.hover` | Pointer cursor |
| `focus` | 2px orange ring, 2px offset | `button.border.focus` | `:focus-visible` only — never `:focus` |
| `active` | One step darker again | `button.bg.active` | Mouse-down state |
| `disabled` | 50% opacity, no pointer events | `button.bg.disabled`, `button.fg.disabled` | Set `aria-disabled="true"` alongside native `disabled` |
| `loading` | Spinner replaces leading icon | base tokens unchanged | Set `aria-busy="true"`. Click handler is suppressed. |

## Usage

```tsx theme={null}
import { Button } from '@clementine-ds/ui';

// Default filled primary
<Button variant="filled" color="blue" onClick={handleSubmit}>
  Save changes
</Button>

// Destructive
<Button variant="filled" color="red" aria-label="Delete user">
  Delete user
</Button>

// Loading
<Button loading aria-busy="true">
  Saving...
</Button>

// Outline secondary
<Button variant="outline" onClick={handleCancel}>
  Cancel
</Button>

// Small toolbar action
<Button variant="subtle" size="sm" onClick={handleEdit}>
  Edit
</Button>
```

**Content guidelines:** Use action verbs, one to three words, sentence case.

* ✅ Save changes, Revoke session, Delete user, Add member
* ❌ Click here, OK, Yes, Save (when a more specific label is possible)

For destructive actions, name the consequence: "Delete project" not "Delete", "Revoke 3 sessions" not "Confirm".

## Accessibility

| Concern | Requirement |
| - | - |
| Keyboard | Enter and Space activate the button. Tab moves focus to it. |
| Focus ring | Orange ring (`button.border.focus` → `focus.ring` → `#ff8040`) on `:focus-visible` only. |
| Screen reader | Native `<button>` is announced as "button" by default. Add `aria-label` when the button is icon-only or the visible label lacks enough context. |
| Hit area | Minimum 44 × 44 px in compliance with WCAG 2.5.5. |
| Loading | Set `aria-busy="true"` while the spinner is visible. The click handler must be suppressed — do not let the user trigger duplicate actions. |
| Disabled | Set both `aria-disabled="true"` and the native `disabled` attribute together. Never communicate the disabled state with color alone — opacity must change too. |

## Token contract

15 component-tier tokens. Tokens follow the 3-tier cascade: component → semantic → primitive. Never reference a primitive directly in component code, and never hardcode a hex value.

| Token | Resolves through | Light value |
| - | - | - |
| `button.bg.default` | `action.primary` | `#2563eb` |
| `button.bg.hover` | `action.primary-hover` | `#1d4ed8` |
| `button.bg.active` | `action.primary-active` | `#1e40af` |
| `button.bg.disabled` | `surface.subtle` | `#f3f3f0` |
| `button.bg-destructive.default` | `action.destructive` | `#dc2626` |
| `button.bg-destructive.hover` | `action.destructive-hover` | `#b91c1c` |
| `button.bg-outline.default` | `surface.elevated` | `#ffffff` |
| `button.bg-outline.hover` | `surface.subtle` | `#f3f3f0` |
| `button.fg.on-filled` | `text.on-action` | `#ffffff` |
| `button.fg.on-outline` | `text.primary` | `#1a1a18` |
| `button.fg.disabled` | `text.tertiary` | `#a3a39e` |
| `button.border.default` | `border.strong` | `#d4d4cf` |
| `button.border.hover` | `action.primary` | `#2563eb` |
| `button.border.focus` | `focus.ring` | `#ff8040` |
| `button.radius` | `radius.md` | `8px` |

Dark mode is handled automatically — the same token names resolve to different primitive values in dark mode. You don't need to add any theme-switching logic to your components.

## TypeScript usage

Button exports `ButtonProps` alongside the component so you can type your own wrappers:

```tsx theme={null}
import { Button, type ButtonProps } from '@clementine-ds/ui';

interface SaveButtonProps extends ButtonProps {
  isSaving: boolean;
}

function SaveButton({ isSaving, ...props }: SaveButtonProps) {
  return (
    <Button loading={isSaving} aria-busy={isSaving} {...props}>
      {isSaving ? 'Saving…' : 'Save changes'}
    </Button>
  );
}
```

> [!TIP]
>
> Dark mode is handled automatically. Clementine's token cascade resolves the same token names to different primitive values in dark mode — you don't need to add any theme-switching logic to your components.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.