# Button Components

> **Props y API:** Disponibles vía MCP tool `widgets-get-component-props`. Este archivo documenta solo convenciones, gotchas y patrones específicos del proyecto.

---

## ⚠️ CRITICAL: color vs variant

DButton uses TWO props for styling:
- `color` - Sets the button color (primary, secondary, success, danger, etc.)
- `variant` - Sets the button style (`'outline'` | `'link'`). Default is solid (no variant).

```tsx
// ✅ CORRECT
<DButton text="Save" color="primary" />              // Solid primary
<DButton text="Cancel" color="secondary" variant="outline" />  // Outline secondary
<DButton text="View" color="info" variant="link" />  // Link style

// ❌ WRONG
<DButton text="Save" variant="primary" />     // variant is for style, not color
<DButton text="Cancel" theme="secondary" />   // No theme prop
```

### Color + Variant Combinations

| Combination | Appearance | Use Case |
|-------------|------------|----------|
| `color="primary"` | Solid blue | Primary actions (submit, save) |
| `color="primary" variant="outline"` | Blue border, white bg | Secondary primary actions |
| `color="secondary"` | Solid gray | Neutral actions |
| `color="secondary" variant="outline"` | Gray border | Cancel, back |
| `color="success"` | Solid green | Confirm, complete |
| `color="danger"` | Solid red | Delete, remove |
| `color="danger" variant="outline"` | Red border | Warning actions |
| `variant="link"` | Link style (any color) | Navigation, tertiary actions |

---

## ⚠️ size="sm" + Icons = SVG Rendering Bug

Using `size="sm"` on buttons with `iconStart` or `iconEnd` causes SVG rendering errors:
```
Error: <svg> attribute width: Expected length, "var(--bs-fs-small...)".
```

```tsx
// ❌ WRONG - Will cause SVG errors
<DButton size="sm" iconStart="ArrowUp" text="Upload" />

// ✅ CORRECT - Use default size
<DButton iconStart="ArrowUp" text="Upload" />

// ✅ ALTERNATIVE - Use DButtonIcon for icon-only small buttons
<DButtonIcon icon="ArrowUp" ariaLabel="Upload" />
```

---

## ⚠️ Icon-Only DButton: text="" Required

If using DButton with icon but no visible text, you MUST provide empty `text=""` to avoid rendering an empty `<span>`.

```tsx
// ❌ WRONG - Creates empty span in HTML
<DButton iconStart="MoreVertical" ariaLabel="More options" />

// ✅ CORRECT - No empty span
<DButton iconStart="MoreVertical" text="" ariaLabel="More options" />

// ✅ PREFERRED - Use DButtonIcon instead
<DButtonIcon icon="MoreVertical" ariaLabel="More options" variant="link" />
```

**DButtonIcon:** Always provide `ariaLabel` for accessibility.

---

## Removed Props (v1→v2 Migration)

**`pill` prop removed in v2.0.** Remove from all DButton instances. Use custom `className` with `border-radius` if pill style is critical.

---

## ⚠️ Common Mistakes

```tsx
// ❌ Using variant for color
<DButton text="Save" variant="primary" />

// ❌ Using theme prop
<DButton text="Save" theme="primary" />

// ❌ Bootstrap bi- prefix (will show "?")
<DButton text="Add" iconStart="bi-plus-circle" />

// ❌ Neither text nor children
<DButton color="primary" onClick={handleClick} />

// ✅ CORRECT
<DButton text="Save" color="primary" />
<DButton text="Add" iconStart="CirclePlus" />
// children render for rich markup and override `text` (prefer `text` for plain labels)
<DButton color="primary"><strong>Bold text</strong></DButton>
```

---

## Button Groups Pattern

```tsx
// Form actions
<div className="d-flex gap-2">
  <DButton text="Cancel" color="secondary" variant="outline" onClick={handleCancel} />
  <DButton text="Save" color="primary" onClick={handleSave} loading={isSubmitting} />
</div>

// Destructive action
<div className="d-flex gap-2">
  <DButton text="Cancel" color="secondary" variant="outline" onClick={onClose} />
  <DButton text="Delete" color="danger" onClick={handleDelete} />
</div>
```