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

# Buttons

> Variants, sizes, and states

Interactive elements that trigger actions with consistent styling and behavior.

## Button Variants

<AccordionGroup>
  <Accordion title="Default" icon="square">
    Primary action button with high emphasis.

    **Usage:** Primary actions, Form submissions, Call-to-action buttons

    ```html theme={null}
    <button hlmBtn>Default Button</button>
    ```
  </Accordion>

  <Accordion title="Secondary" icon="square">
    Secondary action button with medium emphasis.

    **Usage:** Secondary actions, Alternative options, Supporting actions

    ```html theme={null}
    <button hlmBtn variant="secondary">Secondary</button>
    ```
  </Accordion>

  <Accordion title="Outline" icon="square">
    Outlined button with subtle emphasis.

    **Usage:** Less important actions, Cancel buttons, Tertiary actions

    ```html theme={null}
    <button hlmBtn variant="outline">Outline</button>
    ```
  </Accordion>

  <Accordion title="Ghost" icon="square">
    Minimal button with low visual weight.

    **Usage:** Navigation, Menu items, Subtle interactions

    ```html theme={null}
    <button hlmBtn variant="ghost">Ghost</button>
    ```
  </Accordion>

  <Accordion title="Destructive" icon="triangle-exclamation">
    Destructive action button for dangerous operations.

    **Usage:** Delete actions, Irreversible operations, Warning actions

    ```html theme={null}
    <button hlmBtn variant="destructive">Delete</button>
    ```
  </Accordion>

  <Accordion title="Link" icon="link">
    Link-styled button for text-based actions.

    **Usage:** Inline links, Text navigation, Subtle call-to-actions

    ```html theme={null}
    <button hlmBtn variant="link">Link Button</button>
    ```
  </Accordion>
</AccordionGroup>

## Button Sizes

| Size      | Name        | Description                                | Usage                                               |
| --------- | ----------- | ------------------------------------------ | --------------------------------------------------- |
| `xsm`     | Extra Small | Very compact button for dense interfaces   | Table controls, Inline actions, Compact forms       |
| `sm`      | Small       | Compact button for tight spaces            | Form controls, Table actions, Secondary UI elements |
| `default` | Default     | Standard button size for most use cases    | Primary actions, Forms, General interactions        |
| `lg`      | Large       | Prominent button for important actions     | Hero sections, Key call-to-actions, Landing pages   |
| `icon`    | Icon        | Square button designed for icon-only usage | Icon buttons, Tool toggles, Compact actions         |

## Button States

| State    | Description              | Notes                           |
| -------- | ------------------------ | ------------------------------- |
| Default  | Normal interactive state | Standard appearance             |
| Hover    | Mouse hover state        | Automatic `hover:bg-primary/90` |
| Active   | Pressed/clicked state    | CSS `:active` state             |
| Focus    | Keyboard focus state     | `focus-visible:ring-2`          |
| Disabled | Non-interactive state    | Use `disabled` attribute        |
| Loading  | Processing state         | Show spinner icon               |

## Icon Buttons

### Buttons with Icons

```html theme={null}
<button hlmBtn variant="outline" size="sm">
  <ng-icon hlm name="lucideGitBranch" size="sm" class="mr-2" />
  New Branch
</button>
```

### Icon-Only Buttons

```html theme={null}
<button hlmBtn variant="outline" size="sm" title="Settings">
  <ng-icon hlm name="lucideSettings" size="sm" />
</button>
```

<Warning>Always include proper `aria-labels` or `title` attributes for icon-only buttons for accessibility.</Warning>

## Best Practices

<CardGroup cols={2}>
  <Card title="Do" icon="check">
    * Use primary buttons for the most important action on a page - Limit primary buttons to one per page or section -
      Use consistent button sizes within the same context - Provide clear, action-oriented button labels - Include loading
      states for async operations - Ensure sufficient touch target size (44px minimum) - Ghost buttons automatically adapt
      text color for dark mode - Outline buttons use white borders and text in dark mode
  </Card>

  <Card title="Don't" icon="xmark">
    * Use multiple primary buttons in the same area - Make buttons too small for easy interaction - Use vague labels
      like "Click here" or "Submit" - Place destructive actions next to primary actions - Forget disabled states for
      invalid actions - Use buttons for navigation (use links instead)
  </Card>
</CardGroup>

## Dark Mode Behavior

All button variants automatically adapt to dark mode using CSS custom properties and Tailwind's dark mode utilities.

<Tabs>
  <Tab title="Light Mode">
    * **Primary:** Uses primary color (neutral-900) - **Secondary:** Uses secondary background - **Outline:** Gray
      border with default text - **Ghost:** Transparent background
  </Tab>

  <Tab title="Dark Mode">
    * **Primary:** Uses primary color (neutral-50) - **Secondary:** White text for contrast - **Outline:** White border
      and text - **Ghost:** White text on hover
  </Tab>
</Tabs>

## Implementation

### Template

```html theme={null}
<button hlmBtn variant="default" size="lg" (click)="handleClick()">
  <ng-icon hlm name="lucidePlus" size="sm" class="mr-2" />
  Add Item
</button>
```

### Component

```typescript theme={null}
import { HlmButtonDirective } from '@spartan-ng/ui-button-helm';

handleClick() {
  // Handle button action
}
```