@adamosuiteservices/ui 2.11.20 → 2.12.0

package/docs/components/ui/button.md

@@ -1,1137 +1,1156 @@
-# Button Component
-
-## Descripción
-
-Componente fundamental para **acciones e interacciones del usuario**. Ofrece 11 variantes visuales, 6 tamaños, estados automáticos (hover, focus, disabled, loading), iconos auto-dimensionados, y la capacidad de renderizarse como cualquier elemento usando `asChild`. Basado en CVA para variants y Radix UI Slot para composición.
-
-## Características
-
-- ✅ 12 variantes: default, success (2), warning (2), destructive (2), secondary, outline, ghost, ghost-neutral, link
-- ✅ 6 tamaños: sm, default, lg, icon, icon-sm, icon-lg
-- ✅ Iconos auto-dimensionados (16px) con ajuste automático de padding
-- ✅ Estados automáticos: hover, focus-visible, disabled, loading
-- ✅ Prop `asChild` para renderizar como links u otros elementos
-- ✅ Focus ring accesible con detección de teclado
-- ✅ Soporte para aria-invalid con anillos de error
-- ✅ Transiciones suaves en todos los estados
-- ✅ Dark mode completo en todas las variantes
-
-## Importación
-
-```typescript
-import { Button } from "@adamosuiteservices/ui/button";
-```
-
-## Uso Básico
-
-### Botón Simple
-
-```tsx
-<Button>Click me</Button>
-```
-
-### Con Icono
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<Button>
-  <Icon symbol="add" />
-  Add Item
-</Button>;
-```
-
-**Nota**: El icono se auto-dimensiona a 16px y el padding se ajusta automáticamente con `has-[>svg]`.
-
-### Como Link (asChild)
-
-```tsx
-<Button asChild>
-  <a href="/dashboard">Go to Dashboard</a>
-</Button>
-```
-
-**Uso de asChild**: Mantiene el estilo de Button pero renderiza el hijo (`<a>`) en lugar de `<button>`.
-
-## Variantes
-
-### default (Primary)
-
-Botón principal con colores de marca para acciones primarias.
-
-```tsx
-<Button variant="default">Default</Button>
-```
-
-**Estilos**:
-
-- Fondo: `bg-primary`
-- Texto: `text-primary-foreground`
-- Hover: `bg-primary-700`
-- Uso: Acciones primarias, CTAs principales
-
-### success
-
-Botón verde sólido para acciones exitosas o confirmaciones importantes.
-
-```tsx
-<Button variant="success">Success</Button>
-```
-
-**Estilos**:
-
-- Fondo: `bg-success` (verde)
-- Texto: `text-white`
-- Hover: `bg-success-700`
-- Focus ring: `ring-success/20`
-- Dark mode: `bg-success/60`
-- Uso: Guardar, aprobar, confirmar, completar
-
-### success-medium
-
-Versión suave del botón success con fondo claro y texto verde.
-
-```tsx
-<Button variant="success-medium">Success Medium</Button>
-```
-
-**Estilos**:
-
-- Fondo: `bg-success-50` (verde muy claro)
-- Texto: `text-success` (verde)
-- Hover: `bg-success/20`
-- Uso: Acciones exitosas secundarias, estados de éxito menos enfáticos
-
-### warning
-
-Botón naranja/amarillo sólido para acciones que requieren precaución.
-
-```tsx
-<Button variant="warning">Warning</Button>
-```
-
-**Estilos**:
-
-- Fondo: `bg-warning` (naranja/amarillo)
-- Texto: `text-white`
-- Hover: `bg-warning-700`
-- Focus ring: `ring-warning/20`
-- Dark mode: `bg-warning/60`
-- Uso: Acciones de advertencia, confirmaciones con riesgo moderado
-
-### warning-medium
-
-Versión suave del botón warning con fondo claro.
-
-```tsx
-<Button variant="warning-medium">Warning Medium</Button>
-```
-
-**Estilos**:
-
-- Fondo: `bg-warning-50` (naranja/amarillo muy claro)
-- Texto: `text-warning`
-- Hover: `bg-warning/20`
-- Uso: Advertencias secundarias, alertas menos críticas
-
-### destructive
-
-Botón rojo sólido para acciones destructivas o peligrosas.
-
-```tsx
-<Button variant="destructive">Destructive</Button>
-```
-
-**Estilos**:
-
-- Fondo: `bg-destructive` (rojo)
-- Texto: `text-white`
-- Hover: `bg-destructive-700`
-- Focus ring: `ring-destructive/20`
-- Dark mode: `bg-destructive/60`
-- Uso: Eliminar, cancelar suscripción, reset, acciones irreversibles
-
-### destructive-medium
-
-Versión suave del botón destructive con fondo claro.
-
-```tsx
-<Button variant="destructive-medium">Destructive Medium</Button>
-```
-
-**Estilos**:
-
-- Fondo: `bg-destructive-50` (rojo muy claro)
-- Texto: `text-destructive`
-- Hover: `bg-destructive/20`
-- Uso: Acciones destructivas secundarias, advertencias de error
-
-### secondary
-
-Botón secundario para acciones de menor importancia.
-
-```tsx
-<Button variant="secondary">Secondary</Button>
-```
-
-**Estilos**:
-
-- Fondo: `bg-secondary`
-- Texto: `text-secondary-foreground`
-- Hover: `bg-primary-200`
-- Uso: Acciones secundarias, botones de soporte
-
-### outline
-
-Botón con borde y fondo transparente para acciones secundarias.
-
-```tsx
-<Button variant="outline">Outline</Button>
-```
-
-**Estilos**:
-
-- Fondo: `bg-background` con `border`
-- Shadow: `shadow-xs`
-- Hover: `bg-accent`
-- Dark mode: `bg-input/30`, `border-input`
-- Uso: Cancelar, acciones alternativas, botones en grupos
-
-### ghost
-
-Botón mínimo sin borde con color primario que solo aparece en hover.
-
-```tsx
-<Button variant="ghost">Ghost</Button>
-```
-
-**Estilos**:
-
-- Fondo: Transparente
-- Texto: `text-primary`
-- Hover: `bg-primary-50`, `text-primary`
-- Dark mode: `hover:bg-primary-50/20`
-- Uso: Acciones terciarias con énfasis primario, iconos de herramientas, menús
-
-### ghost-neutral
-
-Botón mínimo sin borde con color neutral que solo aparece en hover.
-
-```tsx
-<Button variant="ghost-neutral">Ghost Neutral</Button>
-```
-
-**Estilos**:
-
-- Fondo: Transparente
-- Texto: Color heredado del contexto
-- Hover: `bg-accent`, `text-accent-foreground`
-- Dark mode: `hover:bg-accent/50`
-- Uso: Acciones terciarias neutras, iconos de herramientas sin énfasis, controles de interfaz
-
-### link
-
-Botón que se ve como un link con subrayado en hover.
-
-```tsx
-<Button variant="link">Link</Button>
-```
-
-**Estilos**:
-
-- Color: `text-primary`
-- Hover: `underline`
-- Offset: `underline-offset-4`
-- Uso: Navegación inline, acciones de bajo énfasis
-
-## Tamaños
-
-### sm (Small)
-
-Botón compacto para espacios reducidos.
-
-```tsx
-<Button size="sm">Small</Button>
-```
-
-**Dimensiones**:
-
-- Altura: `h-8` (32px)
-- Padding horizontal: `px-3` (12px)
-- Padding con icono: `px-2.5` (10px) con `has-[>svg]`
-- Gap: `gap-1.5` (6px)
-- Border radius: `rounded-md`
-
-### default
-
-Tamaño estándar para la mayoría de casos.
-
-```tsx
-<Button size="default">Default</Button>
-```
-
-**Dimensiones**:
-
-- Altura: `h-9` (36px)
-- Padding horizontal: `px-4` (16px)
-- Padding con icono: `px-3` (12px) con `has-[>svg]`
-- Gap: `gap-2` (8px)
-- Border radius: `rounded-md`
-
-### lg (Large)
-
-Botón grande para CTAs prominentes.
-
-```tsx
-<Button size="lg">Large</Button>
-```
-
-**Dimensiones**:
-
-- Altura: `h-10` (40px)
-- Padding horizontal: `px-6` (24px)
-- Padding con icono: `px-4` (16px) con `has-[>svg]`
-- Gap: `gap-2` (8px)
-- Border radius: `rounded-md`
-
-### icon (Icon Only - Default)
-
-Botón cuadrado solo para iconos (tamaño medio).
-
-```tsx
-<Button size="icon" aria-label="Settings">
-  <SettingsIcon />
-</Button>
-```
-
-**Dimensiones**:
-
-- Tamaño: `size-9` (36x36px)
-- **Importante**: Siempre incluye `aria-label` para accesibilidad
-
-### icon-sm (Icon Small)
-
-Botón cuadrado pequeño para iconos.
-
-```tsx
-<Button size="icon-sm" aria-label="Edit">
-  <EditIcon />
-</Button>
-```
-
-**Dimensiones**:
-
-- Tamaño: `size-8` (32x32px)
-
-### icon-lg (Icon Large)
-
-Botón cuadrado grande para iconos.
-
-```tsx
-<Button size="icon-lg" aria-label="Search">
-  <SearchIcon />
-</Button>
-```
-
-**Dimensiones**:
-
-- Tamaño: `size-10` (40x40px)
-
-## Estados
-
-### Normal (Default)
-
-Estado por defecto con interacciones completas.
-
-```tsx
-<Button>Normal State</Button>
-```
-
-### Disabled
-
-Desactiva el botón y reduce opacidad.
-
-```tsx
-<Button disabled>Disabled</Button>
-```
-
-**Comportamiento**:
-
-- `opacity-50`: Opacidad al 50%
-- `pointer-events-none`: No acepta clicks ni hover
-- Automático en todos los navegadores
-
-### Loading
-
-Muestra spinner y desactiva interacciones.
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<Button disabled>
-  <Icon symbol="progress_activity" className="animate-spin" />
-  Loading...
-</Button>;
-```
-
-**Patrón recomendado**:
-
-```tsx
-const [isLoading, setIsLoading] = useState(false);
-
-<Button disabled={isLoading} onClick={handleSubmit}>
-  {isLoading && <Icon symbol="progress_activity" className="animate-spin" />}
-  {isLoading ? "Saving..." : "Save Changes"}
-</Button>;
-```
-
-### Hover
-
-Estado automático al pasar el mouse.
-
-- Cada variante tiene su propio color de hover
-- Transición suave con `transition-all`
-- No afecta a botones disabled
-
-### Focus-Visible
-
-Anillo visible solo al navegar con teclado.
-
-```tsx
-<Button>Focus me with Tab key</Button>
-```
-
-**Estilos aplicados**:
-
-- `focus-visible:border-ring`: Borde del color del anillo
-- `focus-visible:ring-ring/50`: Anillo exterior con 50% opacidad
-- `focus-visible:ring-[3px]`: Anillo de 3px
-- Solo visible con teclado (no con mouse)
-
-### Invalid (Error State)
-
-Para formularios con validación.
-
-```tsx
-<Button aria-invalid="true">Invalid Button</Button>
-```
-
-**Estilos aplicados**:
-
-- `aria-invalid:ring-destructive/20`: Anillo rojo claro
-- `aria-invalid:border-destructive`: Borde rojo
-- Dark mode: `ring-destructive/40`
-
-## Patrones Avanzados
-
-### Botón con Icono (Text + Icon)
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-{
-  /* Icono a la izquierda */
-}
-<Button>
-  <Icon symbol="save" />
-  Save Changes
-</Button>;
-
-{
-  /* Icono a la derecha */
-}
-<Button>
-  Download
-  <Icon symbol="download" />
-</Button>;
-
-{
-  /* Múltiples iconos */
-}
-<Button variant="destructive">
-  <Icon symbol="delete" />
-  Delete All
-  <span className="ml-auto text-xs">(5)</span>
-</Button>;
-```
-
-**Nota**: El gap (`gap-2`) se aplica automáticamente entre elementos.
-
-### Botón Redondeado (Pill)
-
-```tsx
-<Button className="rounded-full">
-  <PlusIcon />
-  Add New
-</Button>
-```
-
-### Botón de Ancho Completo
-
-```tsx
-<Button className="w-full">Continue</Button>
-```
-
-### Grupo de Botones
-
-```tsx
-<div className="flex gap-2">
-  <Button variant="outline">Cancel</Button>
-  <Button>Save</Button>
-</div>
-```
-
-### Botón Interactivo con Estado
-
-```tsx
-import { useState } from "react";
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-function LikeButton() {
-  const [liked, setLiked] = useState(false);
-
-  return (
-    <Button
-      variant={liked ? "default" : "outline"}
-      onClick={() => setLiked(!liked)}
-    >
-      <Icon symbol="favorite" className={liked ? "fill-current" : ""} />
-      {liked ? "Liked" : "Like"}
-    </Button>
-  );
-}
-
-function SaveButton() {
-  const [saved, setSaved] = useState(false);
-
-  return (
-    <Button
-      variant={saved ? "secondary" : "outline"}
-      onClick={() => setSaved(!saved)}
-    >
-      <Icon symbol="star" className={saved ? "fill-current" : ""} />
-      {saved ? "Saved" : "Save"}
-    </Button>
-  );
-}
-
-function PlayButton() {
-  const [playing, setPlaying] = useState(false);
-
-  return (
-    <Button variant="outline" onClick={() => setPlaying(!playing)}>
-      {playing ? <Icon symbol="pause" /> : <Icon symbol="play_arrow" />}
-      {playing ? "Pause" : "Play"}
-    </Button>
-  );
-}
-```
-
-### asChild con Link (Next.js)
-
-```tsx
-import Link from "next/link";
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<Button asChild>
-  <Link href="/dashboard">
-    Go to Dashboard
-  </Link>
-</Button>
-
-<Button asChild variant="outline">
-  <a href="https://example.com" target="_blank" rel="noopener noreferrer">
-    <Icon symbol="open_in_new" />
-    External Link
-  </a>
-</Button>
-```
-
-### asChild con React Router
-
-```tsx
-import { Link } from "react-router-dom";
-
-<Button asChild>
-  <Link to="/profile">View Profile</Link>
-</Button>;
-```
-
-### Botón con Badge
-
-```tsx
-import { Badge } from "@adamosuiteservices/ui/badge";
-
-<Button variant="outline" className="relative">
-  Notifications
-  <Badge
-    variant="destructive"
-    className="absolute -top-2 -right-2 h-5 w-5 rounded-full p-0 flex items-center justify-center text-xs"
-  >
-    5
-  </Badge>
-</Button>;
-```
-
-### Botón Dropdown Trigger
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<Button>
-  Options
-  <Icon symbol="keyboard_arrow_down" className="ml-auto -mr-1" />
-</Button>;
-```
-
-## Props
-
-| Prop      | Tipo                                                                                                                                                                                            | Default     | Descripción                                                    |
-| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------- |
-| variant   | `"default" \| "success" \| "success-medium" \| "warning" \| "warning-medium" \| "destructive" \| "destructive-medium" \| "secondary" \| "outline" \| "ghost" \| "ghost-neutral" \| "link"` | `"default"` | Variante visual del botón                                      |
-| size      | `"default" \| "sm" \| "lg" \| "icon" \| "icon-sm" \| "icon-lg"`                                                                                                         | `"default"` | Tamaño del botón                                               |
-| asChild   | `boolean`                                                                                                                                                               | `false`     | Renderiza el hijo en lugar de un `<button>`. Usa Radix UI Slot |
-| disabled  | `boolean`                                                                                                                                                               | `false`     | Desactiva el botón (opacity 50%, pointer-events none)          |
-| className | `string`                                                                                                                                                                | -           | Clases CSS adicionales                                         |
-| children  | `ReactNode`                                                                                                                                                             | -           | Contenido del botón (texto, iconos, etc.)                      |
-| type      | `"button" \| "submit" \| "reset"`                                                                                                                                       | `"button"`  | Tipo de botón HTML                                             |
-| onClick   | `(e: MouseEvent) => void`                                                                                                                                               | -           | Handler de click                                               |
-| ...props  | `ButtonHTMLAttributes`                                                                                                                                                  | -           | Todas las props nativas de `<button>`                          |
-
-**Nota sobre asChild**: Cuando es `true`, el componente usa `Slot` de Radix UI para transferir todas las props y estilos al hijo directo.
-
-## Estilos Base Automáticos
-
-Todos los botones tienen estos estilos aplicados automáticamente:
-
-```css
-inline-flex              /* Display flex inline */
-items-center            /* Alinea verticalmente al centro */
-justify-center          /* Centra horizontalmente */
-gap-2                   /* Espacio de 8px entre hijos (varía por tamaño) */
-whitespace-nowrap       /* No rompe líneas */
-rounded-md              /* Border radius medium */
-text-sm                 /* Tamaño de fuente 14px */
-font-semibold           /* Peso de fuente 600 */
-transition-all          /* Transiciones suaves */
-shrink-0                /* No se encoge en flex/grid */
-outline-none            /* Sin outline por defecto */
-```
-
-### Iconos Auto-dimensionados
-
-```css
-[&_svg]:pointer-events-none              /* Iconos no capturan clicks */
-[&_svg:not([class*=size-])]:size-4       /* SVG sin clase size-* → 16x16px */
-[&_svg]:shrink-0                         /* Iconos no se encogen */
-```
-
-### Padding Dinámico con Iconos
-
-```css
-/* size="default" */
-h-9 px-4                 /* Sin icono: 16px padding horizontal */
-has-[>svg]:px-3          /* Con icono: 12px padding horizontal */
-
-/* size="sm" */
-h-8 px-3
-has-[>svg]:px-2.5
-
-/* size="lg" */
-h-10 px-6
-has-[>svg]:px-4
-```
-
-**Beneficio**: El padding se reduce automáticamente cuando hay iconos para mantener proporciones visuales.
-
-## Casos de Uso Comunes
-
-### Acciones Primarias
-
-Para la acción más importante en la pantalla.
-
-```tsx
-<div className="flex gap-2">
-  <Button>
-    <SaveIcon />
-    Save Changes
-  </Button>
-  <Button>
-    <PlusIcon />
-    Create New
-  </Button>
-  <Button>
-    <DownloadIcon />
-    Export Data
-  </Button>
-</div>
-```
-
-### Acciones Secundarias
-
-Para acciones alternativas o de menor prioridad.
-
-```tsx
-<div className="flex gap-2">
-  <Button variant="outline">
-    <EditIcon />
-    Edit
-  </Button>
-  <Button variant="outline">
-    <CopyIcon />
-    Copy
-  </Button>
-  <Button variant="outline">
-    <ShareIcon />
-    Share
-  </Button>
-</div>
-```
-
-### Acciones Destructivas/Peligrosas
-
-Para acciones que requieren confirmación del usuario.
-
-```tsx
-<div className="flex gap-2">
-  <Button variant="destructive">
-    <TrashIcon />
-    Delete Item
-  </Button>
-  <Button variant="destructive">Reset All Data</Button>
-</div>
-```
-
-### Formularios
-
-Combinación típica en formularios.
-
-```tsx
-<form onSubmit={handleSubmit}>
-  {/* Campos del formulario */}
-
-  <div className="flex gap-2 justify-end mt-4">
-    <Button type="button" variant="outline" onClick={onCancel}>
-      Cancel
-    </Button>
-    <Button type="submit">
-      {isSubmitting ? (
-        <>
-          <Loader2Icon className="animate-spin" />
-          Saving...
-        </>
-      ) : (
-        <>
-          <SaveIcon />
-          Save
-        </>
-      )}
-    </Button>
-  </div>
-</form>
-```
-
-### Dialogs y Modals
-
-Acciones en footer de dialogs.
-
-```tsx
-<DialogFooter>
-  <Button variant="outline" onClick={onClose}>
-    Cancel
-  </Button>
-  <Button onClick={onConfirm}>Confirm</Button>
-</DialogFooter>
-```
-
-### Toolbars
-
-Botones de herramientas con iconos.
-
-```tsx
-{/* Toolbar con ghost para acciones primarias */}
-<div className="flex gap-1 p-2 border rounded-lg">
-  <Button size="icon-sm" variant="ghost" aria-label="Bold">
-    <BoldIcon />
-  </Button>
-  <Button size="icon-sm" variant="ghost" aria-label="Italic">
-    <ItalicIcon />
-  </Button>
-  <Button size="icon-sm" variant="ghost" aria-label="Underline">
-    <UnderlineIcon />
-  </Button>
-  <div className="w-px bg-border mx-1" />
-  <Button size="icon-sm" variant="ghost" aria-label="Align left">
-    <AlignLeftIcon />
-  </Button>
-  <Button size="icon-sm" variant="ghost" aria-label="Align center">
-    <AlignCenterIcon />
-  </Button>
-</div>
-
-{/* Toolbar con ghost-neutral para apariencia más sutil */}
-<div className="flex gap-1 p-2 border rounded-lg">
-  <Button size="icon-sm" variant="ghost-neutral" aria-label="Bold">
-    <BoldIcon />
-  </Button>
-  <Button size="icon-sm" variant="ghost-neutral" aria-label="Italic">
-    <ItalicIcon />
-  </Button>
-  <Button size="icon-sm" variant="ghost-neutral" aria-label="Underline">
-    <UnderlineIcon />
-  </Button>
-</div>
-```
-
-### Call to Action (CTA)
-
-Botón prominente en landing pages.
-
-```tsx
-<Button size="lg" className="text-base px-8">
-  Get Started Free
-  <ArrowRightIcon />
-</Button>
-```
-
-### Navegación
-
-Botones como links de navegación.
-
-```tsx
-import { useNavigate } from "react-router-dom";
-
-function Navigation() {
-  const navigate = useNavigate();
-
-  return (
-    <div className="flex gap-2">
-      <Button variant="ghost" onClick={() => navigate("/home")}>
-        Home
-      </Button>
-      <Button variant="ghost" onClick={() => navigate("/about")}>
-        About
-      </Button>
-      <Button variant="ghost" onClick={() => navigate("/contact")}>
-        Contact
-      </Button>
-    </div>
-  );
-}
-```
-
-### Botones de Paginación
-
-```tsx
-<div className="flex items-center gap-2">
-  <Button size="icon-sm" variant="outline" disabled={currentPage === 1}>
-    <ChevronLeftIcon />
-  </Button>
-  <span className="text-sm">
-    Page {currentPage} of {totalPages}
-  </span>
-  <Button
-    size="icon-sm"
-    variant="outline"
-    disabled={currentPage === totalPages}
-  >
-    <ChevronRightIcon />
-  </Button>
-</div>
-```
-
-## Mejores Prácticas
-
-### Jerarquía Visual
-
-```tsx
-{
-  /* ✅ Correcto - Jerarquía clara */
-}
-<div className="flex gap-2">
-  <Button variant="outline">Cancel</Button>
-  <Button>Save</Button> {/* Acción primaria más prominente */}
-</div>;
-
-{
-  /* ❌ Incorrecto - Todas las acciones con igual énfasis */
-}
-<div className="flex gap-2">
-  <Button>Cancel</Button>
-  <Button>Save</Button>
-</div>;
-```
-
-### Textos Descriptivos
-
-```tsx
-{/* ✅ Correcto - Texto claro */}
-<Button>Save Changes</Button>
-<Button variant="destructive">Delete Account</Button>
-
-{/* ❌ Incorrecto - Texto genérico */}
-<Button>OK</Button>
-<Button>Submit</Button>
-```
-
-### aria-label en Botones de Icono
-
-```tsx
-{
-  /* ✅ Correcto - Accesible */
-}
-<Button size="icon" aria-label="Settings">
-  <SettingsIcon />
-</Button>;
-
-{
-  /* ❌ Incorrecto - No accesible */
-}
-<Button size="icon">
-  <SettingsIcon />
-</Button>;
-```
-
-### Loading State
-
-```tsx
-{
-  /* ✅ Correcto - Estado de carga explícito */
-}
-<Button disabled={isLoading}>
-  {isLoading && <Loader2Icon className="animate-spin" />}
-  {isLoading ? "Saving..." : "Save"}
-</Button>;
-
-{
-  /* ❌ Incorrecto - Solo disabled sin feedback visual */
-}
-<Button disabled={isLoading}>Save</Button>;
-```
-
-### Variantes Semánticas
-
-```tsx
-{/* ✅ Correcto - Variantes apropiadas */}
-<Button variant="success">Approve</Button>
-<Button variant="destructive">Delete</Button>
-<Button variant="warning">Proceed with Caution</Button>
-
-{/* ❌ Incorrecto - Variantes genéricas para acciones críticas */}
-<Button>Delete All Data</Button>  {/* Debería ser destructive */}
-```
-
-### Ghost vs Ghost-Neutral
-
-```tsx
-{/* ✅ Correcto - Ghost para acciones con énfasis primario */}
-<Button variant="ghost">
-  <Icon symbol="add" />
-  Add Item
-</Button>
-
-{/* ✅ Correcto - Ghost-neutral para controles sin énfasis */}
-<Button variant="ghost-neutral" size="icon" aria-label="Settings">
-  <Icon symbol="settings" />
-</Button>
-
-{/* ✅ Correcto - Ghost-neutral en toolbars y paneles */}
-<div className="flex gap-1">
-  <Button variant="ghost-neutral" size="icon-sm" aria-label="Edit">
-    <Icon symbol="edit" />
-  </Button>
-  <Button variant="ghost-neutral" size="icon-sm" aria-label="Delete">
-    <Icon symbol="delete" />
-  </Button>
-</div>
-
-{/* ⚠️ Considerar - Ghost puede ser muy prominente en algunos contextos */}
-<Button variant="ghost">Close</Button>  {/* Mejor usar ghost-neutral */}
-```
-
-### Espaciado Consistente
-
-```tsx
-{
-  /* ✅ Correcto - Gap consistente */
-}
-<div className="flex gap-2">
-  <Button variant="outline">Back</Button>
-  <Button variant="outline">Skip</Button>
-  <Button>Next</Button>
-</div>;
-
-{
-  /* ✅ También correcto - Separar acciones por importancia */
-}
-<div className="flex justify-between">
-  <Button variant="outline">Cancel</Button>
-  <div className="flex gap-2">
-    <Button variant="outline">Save as Draft</Button>
-    <Button>Publish</Button>
-  </div>
-</div>;
-```
-
-## Notas de Implementación
-
-- Basado en CVA (class-variance-authority) para variants system
-- Usa Radix UI Slot para la prop `asChild`
-- Los iconos SVG sin clase `size-*` se auto-dimensionan a 16px
-- Padding horizontal se ajusta automáticamente con `has-[>svg]` selector
-- Focus ring usa `focus-visible` (solo teclado, no mouse)
-- Transiciones en `all` para suavidad en todos los cambios
-- Sistema de slots con `data-slot="button"` para identificación
-- Todos los botones son `inline-flex` para alineación perfecta
-- `shrink-0` evita que botones se encojan en layouts flex
-
-## Accesibilidad
-
-### Navegación por Teclado
-
-- ✅ **Tab**: Navega al botón
-- ✅ **Space/Enter**: Activa el botón
-- ✅ **Escape**: Sale del focus (en algunos contextos)
-
-### Estados Visuales Claros
-
-- ✅ Focus ring visible solo con teclado (`focus-visible`)
-- ✅ Disabled state con opacity reducida
-- ✅ Hover state en todas las variantes
-- ✅ Contraste de colores cumple WCAG AA
-
-### ARIA Best Practices
-
-```tsx
-{/* ✅ Botón de icono con aria-label */}
-<Button size="icon" aria-label="Delete item">
-  <TrashIcon />
-</Button>
-
-{/* ✅ Botón con estado de carga */}
-<Button disabled={isLoading} aria-busy={isLoading}>
-  {isLoading && <Loader2Icon className="animate-spin" />}
-  {isLoading ? "Loading..." : "Submit"}
-</Button>
-
-{/* ✅ Botón con estado pressed (toggle) */}
-<Button
-  variant={isActive ? "default" : "outline"}
-  aria-pressed={isActive}
-  onClick={() => setIsActive(!isActive)}
->
-  {isActive ? "Active" : "Inactive"}
-</Button>
-
-{/* ✅ Botón con descripción expandida */}
-<Button aria-describedby="delete-description">
-  Delete Account
-</Button>
-<p id="delete-description" className="sr-only">
-  This action cannot be undone. All your data will be permanently deleted.
-</p>
-```
-
-### Type en Formularios
-
-```tsx
-{
-  /* ✅ Correcto - type explícito */
-}
-<form onSubmit={handleSubmit}>
-  <Button type="submit">Submit</Button>
-  <Button type="button" onClick={handleCancel}>
-    Cancel
-  </Button>
-  <Button type="reset">Reset Form</Button>
-</form>;
-
-{
-  /* ⚠️ Cuidado - sin type en form, default es submit */
-}
-<form>
-  <Button>Click me</Button> {/* Se comporta como submit */}
-</form>;
-```
-
-### Screen Readers
-
-- ✅ Texto descriptivo en lugar de solo iconos
-- ✅ `aria-label` para botones de solo icono
-- ✅ `aria-busy` durante estados de carga
-- ✅ `aria-invalid` para estados de error
-- ✅ Disabled buttons se anuncian como "disabled" o "dimmed"
-
-## Troubleshooting
-
-### Botón No Se Ve Como Esperado
-
-**Problema**: Los estilos no se aplican correctamente.
-
-**Solución**:
-
-```tsx
-// ❌ Incorrecto - className sobrescribe variantes
-<Button className="bg-destructive">Click</Button>
-
-// ✅ Correcto - Usa variantes predefinidas
-<Button variant="destructive">Click</Button>
-
-// ✅ O combina correctamente
-<Button variant="destructive" className="rounded-full">Click</Button>
-```
-
-### Icono No Se Auto-Dimensiona
-
-**Problema**: El icono es muy grande o muy pequeño.
-
-**Solución**:
-
-```tsx
-// ❌ Incorrecto - clase size-* evita auto-dimensionado
-<Button>
-  <SaveIcon className="size-8" />  {/* Muy grande */}
-  Save
-</Button>
-
-// ✅ Correcto - sin clase size-*
-<Button>
-  <SaveIcon />  {/* Auto-dimensionado a 16px */}
-  Save
-</Button>
-
-// ✅ O especifica tamaño personalizado si es necesario
-<Button>
-  <SaveIcon className="h-5 w-5" />
-  Save
-</Button>
-```
-
-### asChild No Funciona
-
-**Problema**: El hijo no recibe los estilos.
-
-**Solución**:
-
-```tsx
-// ❌ Incorrecto - múltiples hijos
-<Button asChild>
-  <a href="/link">Click</a>
-  <span>Extra</span>
-</Button>
-
-// ✅ Correcto - un solo hijo directo
-<Button asChild>
-  <a href="/link">
-    <LinkIcon />
-    Click Me
-  </a>
-</Button>
-```
-
-## Referencias
-
-- CVA (Class Variance Authority): https://cva.style/docs
-- Radix UI Slot: https://www.radix-ui.com/primitives/docs/utilities/slot
-- shadcn/ui Button: https://ui.shadcn.com/docs/components/button
-- WCAG 2.1 Button Guidelines: https://www.w3.org/WAI/ARIA/apg/patterns/button/
+# Button Component
+
+## Descripción
+
+Componente fundamental para **acciones e interacciones del usuario**. Ofrece 11 variantes visuales, 6 tamaños, estados automáticos (hover, focus, disabled, loading), iconos auto-dimensionados, y la capacidad de renderizarse como cualquier elemento usando `asChild`. Basado en CVA para variants y Radix UI Slot para composición.
+
+## Características
+
+- ✅ 13 variantes: default, success (2), warning (2), destructive (2), secondary, outline, ghost, ghost-neutral, link, link-neutral
+- ✅ 6 tamaños: sm, default, lg, icon, icon-sm, icon-lg
+- ✅ Iconos auto-dimensionados: SVG (20px), Material Symbols (text-2xl)
+- ✅ Estados automáticos: hover, focus-visible, disabled, loading
+- ✅ Prop `asChild` para renderizar como links u otros elementos
+- ✅ Focus ring accesible con detección de teclado
+- ✅ Soporte para aria-invalid con anillos de error
+- ✅ Transiciones suaves en todos los estados
+- ✅ Dark mode completo en todas las variantes
+
+## Importación
+
+```typescript
+import { Button } from "@adamosuiteservices/ui/button";
+```
+
+## Uso Básico
+
+### Botón Simple
+
+```tsx
+<Button>Click me</Button>
+```
+
+### Con Icono
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<Button>
+  <Icon symbol="add" />
+  Add Item
+</Button>;
+```
+
+**Nota**: Los iconos Material Symbols usan `text-2xl` y los SVG se auto-dimensionan a 20px. El padding se ajusta automáticamente con `has-[>svg]`.
+
+### Como Link (asChild)
+
+```tsx
+<Button asChild>
+  <a href="/dashboard">Go to Dashboard</a>
+</Button>
+```
+
+**Uso de asChild**: Mantiene el estilo de Button pero renderiza el hijo (`<a>`) en lugar de `<button>`.
+
+## Variantes
+
+### default (Primary)
+
+Botón principal con colores de marca para acciones primarias.
+
+```tsx
+<Button variant="default">Default</Button>
+```
+
+**Estilos**:
+
+- Fondo: `bg-primary`
+- Texto: `text-primary-foreground`
+- Hover: `bg-primary-700`
+- Uso: Acciones primarias, CTAs principales
+
+### success
+
+Botón verde sólido para acciones exitosas o confirmaciones importantes.
+
+```tsx
+<Button variant="success">Success</Button>
+```
+
+**Estilos**:
+
+- Fondo: `bg-success` (verde)
+- Texto: `text-white`
+- Hover: `bg-success-700`
+- Focus ring: `ring-success/20`
+- Dark mode: `bg-success/60`
+- Uso: Guardar, aprobar, confirmar, completar
+
+### success-medium
+
+Versión suave del botón success con fondo claro y texto verde.
+
+```tsx
+<Button variant="success-medium">Success Medium</Button>
+```
+
+**Estilos**:
+
+- Fondo: `bg-success-50` (verde muy claro)
+- Texto: `text-success` (verde)
+- Hover: `bg-success/20`
+- Uso: Acciones exitosas secundarias, estados de éxito menos enfáticos
+
+### warning
+
+Botón naranja/amarillo sólido para acciones que requieren precaución.
+
+```tsx
+<Button variant="warning">Warning</Button>
+```
+
+**Estilos**:
+
+- Fondo: `bg-warning` (naranja/amarillo)
+- Texto: `text-white`
+- Hover: `bg-warning-700`
+- Focus ring: `ring-warning/20`
+- Dark mode: `bg-warning/60`
+- Uso: Acciones de advertencia, confirmaciones con riesgo moderado
+
+### warning-medium
+
+Versión suave del botón warning con fondo claro.
+
+```tsx
+<Button variant="warning-medium">Warning Medium</Button>
+```
+
+**Estilos**:
+
+- Fondo: `bg-warning-50` (naranja/amarillo muy claro)
+- Texto: `text-warning`
+- Hover: `bg-warning/20`
+- Uso: Advertencias secundarias, alertas menos críticas
+
+### destructive
+
+Botón rojo sólido para acciones destructivas o peligrosas.
+
+```tsx
+<Button variant="destructive">Destructive</Button>
+```
+
+**Estilos**:
+
+- Fondo: `bg-destructive` (rojo)
+- Texto: `text-white`
+- Hover: `bg-destructive-700`
+- Focus ring: `ring-destructive/20`
+- Dark mode: `bg-destructive/60`
+- Uso: Eliminar, cancelar suscripción, reset, acciones irreversibles
+
+### destructive-medium
+
+Versión suave del botón destructive con fondo claro.
+
+```tsx
+<Button variant="destructive-medium">Destructive Medium</Button>
+```
+
+**Estilos**:
+
+- Fondo: `bg-destructive-50` (rojo muy claro)
+- Texto: `text-destructive`
+- Hover: `bg-destructive/20`
+- Uso: Acciones destructivas secundarias, advertencias de error
+
+### secondary
+
+Botón secundario para acciones de menor importancia.
+
+```tsx
+<Button variant="secondary">Secondary</Button>
+```
+
+**Estilos**:
+
+- Fondo: `bg-secondary`
+- Texto: `text-secondary-foreground`
+- Hover: `bg-primary-200`
+- Uso: Acciones secundarias, botones de soporte
+
+### outline
+
+Botón con borde y fondo transparente para acciones secundarias.
+
+```tsx
+<Button variant="outline">Outline</Button>
+```
+
+**Estilos**:
+
+- Fondo: `bg-background` con `border`
+- Shadow: `shadow-xs`
+- Hover: `bg-accent`
+- Dark mode: `bg-input/30`, `border-input`
+- Soporte para `aria-invalid` con borde y anillo rojos
+- Uso: Cancelar, acciones alternativas, botones en grupos
+
+### ghost
+
+Botón mínimo sin borde con color primario que solo aparece en hover.
+
+```tsx
+<Button variant="ghost">Ghost</Button>
+```
+
+**Estilos**:
+
+- Fondo: Transparente
+- Texto: `text-primary`
+- Hover: `bg-primary-50`, `text-primary`
+- Dark mode: `hover:bg-primary-50/20`
+- Uso: Acciones terciarias con énfasis primario, iconos de herramientas, menús
+
+### ghost-neutral
+
+Botón mínimo sin borde con color neutral que solo aparece en hover.
+
+```tsx
+<Button variant="ghost-neutral">Ghost Neutral</Button>
+```
+
+**Estilos**:
+
+- Fondo: Transparente
+- Texto: Color heredado del contexto
+- Hover: `bg-accent`, `text-accent-foreground`
+- Dark mode: `hover:bg-accent/50`
+- Uso: Acciones terciarias neutras, iconos de herramientas sin énfasis, controles de interfaz
+
+### link
+
+Botón que se ve como un link con color primario.
+
+```tsx
+<Button variant="link">Link</Button>
+```
+
+**Estilos**:
+
+- Color: `text-primary`
+- Sin hover underline
+- Uso: Navegación inline con énfasis primario
+
+### link-neutral
+
+Botón que se ve como un link con color neutral.
+
+```tsx
+<Button variant="link-neutral">Link Neutral</Button>
+```
+
+**Estilos**:
+
+- Color: `text-foreground`
+- Sin hover underline
+- Uso: Navegación inline sin énfasis de color, acciones de bajo impacto
+
+## Tamaños
+
+### sm (Small)
+
+Botón compacto para espacios reducidos.
+
+```tsx
+<Button size="sm">Small</Button>
+```
+
+**Dimensiones**:
+
+- Altura: `h-9` (36px)
+- Padding horizontal: `px-3` (12px)
+- Padding con icono: `px-2.5` (10px) con `has-[>svg]`
+- Gap: `gap-2` (8px)
+- Border radius: `rounded-[12px]` (12px)
+
+### default
+
+Tamaño estándar para la mayoría de casos.
+
+```tsx
+<Button size="default">Default</Button>
+```
+
+**Dimensiones**:
+
+- Altura: `h-10` (40px)
+- Padding horizontal: `px-4` (16px)
+- Padding con icono: `px-3.5` (14px) con `has-[>svg]` o `has-[>[data-slot=icon]]`
+- Gap: `gap-2` (8px)
+- Border radius: `rounded-[12px]` (12px)
+
+### lg (Large)
+
+Botón grande para CTAs prominentes.
+
+```tsx
+<Button size="lg">Large</Button>
+```
+
+**Dimensiones**:
+
+- Altura: `h-11` (44px)
+- Padding horizontal: `px-6` (24px)
+- Padding con icono: `px-5` (20px) con `has-[>svg]`
+- Gap: `gap-2` (8px)
+- Border radius: `rounded-[12px]` (12px)
+
+### icon (Icon Only - Default)
+
+Botón cuadrado solo para iconos (tamaño medio).
+
+```tsx
+<Button size="icon" aria-label="Settings">
+  <SettingsIcon />
+</Button>
+```
+
+**Dimensiones**:
+
+- Tamaño: `size-10` (40x40px)
+- **Importante**: Siempre incluye `aria-label` para accesibilidad
+
+### icon-sm (Icon Small)
+
+Botón cuadrado pequeño para iconos.
+
+```tsx
+<Button size="icon-sm" aria-label="Edit">
+  <EditIcon />
+</Button>
+```
+
+**Dimensiones**:
+
+- Tamaño: `size-9` (36x36px)
+
+### icon-lg (Icon Large)
+
+Botón cuadrado grande para iconos.
+
+```tsx
+<Button size="icon-lg" aria-label="Search">
+  <SearchIcon />
+</Button>
+```
+
+**Dimensiones**:
+
+- Tamaño: `size-11` (44x44px)
+
+## Estados
+
+### Normal (Default)
+
+Estado por defecto con interacciones completas.
+
+```tsx
+<Button>Normal State</Button>
+```
+
+### Disabled
+
+Desactiva el botón y reduce opacidad.
+
+```tsx
+<Button disabled>Disabled</Button>
+```
+
+**Comportamiento**:
+
+- `opacity-50`: Opacidad al 50%
+- `pointer-events-none`: No acepta clicks ni hover
+- Automático en todos los navegadores
+
+### Loading
+
+Muestra spinner y desactiva interacciones.
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<Button disabled>
+  <Icon symbol="progress_activity" className="animate-spin" />
+  Loading...
+</Button>;
+```
+
+**Patrón recomendado**:
+
+```tsx
+const [isLoading, setIsLoading] = useState(false);
+
+<Button disabled={isLoading} onClick={handleSubmit}>
+  {isLoading && <Icon symbol="progress_activity" className="animate-spin" />}
+  {isLoading ? "Saving..." : "Save Changes"}
+</Button>;
+```
+
+### Hover
+
+Estado automático al pasar el mouse.
+
+- Cada variante tiene su propio color de hover
+- Transición suave con `transition-all`
+- No afecta a botones disabled
+
+### Focus-Visible
+
+Anillo visible solo al navegar con teclado.
+
+```tsx
+<Button>Focus me with Tab key</Button>
+```
+
+**Estilos aplicados**:
+
+- `focus-visible:border-ring`: Borde del color del anillo
+- `focus-visible:ring-ring/50`: Anillo exterior con 50% opacidad
+- `focus-visible:ring-[3px]`: Anillo de 3px
+- Solo visible con teclado (no con mouse)
+
+### Invalid (Error State)
+
+Para formularios con validación. **Nota**: Solo funciona con la variante `outline` que tiene borde visible.
+
+```tsx
+<Button variant="outline" aria-invalid="true">Invalid Button</Button>
+```
+
+**Estilos aplicados** (solo en variante outline):
+
+- `aria-invalid:ring-destructive/20`: Anillo rojo claro
+- `aria-invalid:border-destructive`: Borde rojo
+- Dark mode: `ring-destructive/40`
+
+## Patrones Avanzados
+
+### Botón con Icono (Text + Icon)
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+{
+  /* Icono a la izquierda */
+}
+<Button>
+  <Icon symbol="save" />
+  Save Changes
+</Button>;
+
+{
+  /* Icono a la derecha */
+}
+<Button>
+  Download
+  <Icon symbol="download" />
+</Button>;
+
+{
+  /* Múltiples iconos */
+}
+<Button variant="destructive">
+  <Icon symbol="delete" />
+  Delete All
+  <span className="ml-auto text-xs">(5)</span>
+</Button>;
+```
+
+**Nota**: El gap (`gap-2`) se aplica automáticamente entre elementos.
+
+### Botón Redondeado (Pill)
+
+```tsx
+<Button className="rounded-full">
+  <PlusIcon />
+  Add New
+</Button>
+```
+
+### Botón de Ancho Completo
+
+```tsx
+<Button className="w-full">Continue</Button>
+```
+
+### Grupo de Botones
+
+```tsx
+<div className="flex gap-2">
+  <Button variant="outline">Cancel</Button>
+  <Button>Save</Button>
+</div>
+```
+
+### Botón Interactivo con Estado
+
+```tsx
+import { useState } from "react";
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+function LikeButton() {
+  const [liked, setLiked] = useState(false);
+
+  return (
+    <Button
+      variant={liked ? "default" : "outline"}
+      onClick={() => setLiked(!liked)}
+    >
+      <Icon symbol="favorite" className={liked ? "fill-current" : ""} />
+      {liked ? "Liked" : "Like"}
+    </Button>
+  );
+}
+
+function SaveButton() {
+  const [saved, setSaved] = useState(false);
+
+  return (
+    <Button
+      variant={saved ? "secondary" : "outline"}
+      onClick={() => setSaved(!saved)}
+    >
+      <Icon symbol="star" className={saved ? "fill-current" : ""} />
+      {saved ? "Saved" : "Save"}
+    </Button>
+  );
+}
+
+function PlayButton() {
+  const [playing, setPlaying] = useState(false);
+
+  return (
+    <Button variant="outline" onClick={() => setPlaying(!playing)}>
+      {playing ? <Icon symbol="pause" /> : <Icon symbol="play_arrow" />}
+      {playing ? "Pause" : "Play"}
+    </Button>
+  );
+}
+```
+
+### asChild con Link (Next.js)
+
+```tsx
+import Link from "next/link";
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<Button asChild>
+  <Link href="/dashboard">
+    Go to Dashboard
+  </Link>
+</Button>
+
+<Button asChild variant="outline">
+  <a href="https://example.com" target="_blank" rel="noopener noreferrer">
+    <Icon symbol="open_in_new" />
+    External Link
+  </a>
+</Button>
+```
+
+### asChild con React Router
+
+```tsx
+import { Link } from "react-router-dom";
+
+<Button asChild>
+  <Link to="/profile">View Profile</Link>
+</Button>;
+```
+
+### Botón con Badge
+
+```tsx
+import { Badge } from "@adamosuiteservices/ui/badge";
+
+<Button variant="outline" className="relative">
+  Notifications
+  <Badge
+    variant="destructive"
+    className="absolute -top-2 -right-2 h-5 w-5 rounded-full p-0 flex items-center justify-center text-xs"
+  >
+    5
+  </Badge>
+</Button>;
+```
+
+### Botón Dropdown Trigger
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<Button>
+  Options
+  <Icon symbol="keyboard_arrow_down" className="ml-auto -mr-1" />
+</Button>;
+```
+
+## Props
+
+| Prop      | Tipo                                                                                                                                                                                            | Default     | Descripción                                                    |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------- |
+| variant   | `"default" \| "success" \| "success-medium" \| "warning" \| "warning-medium" \| "destructive" \| "destructive-medium" \| "secondary" \| "outline" \| "ghost" \| "ghost-neutral" \| "link"` | `"default"` | Variante visual del botón                                      |
+| size      | `"default" \| "sm" \| "lg" \| "icon" \| "icon-sm" \| "icon-lg"`                                                                                                         | `"default"` | Tamaño del botón                                               |
+| asChild   | `boolean`                                                                                                                                                               | `false`     | Renderiza el hijo en lugar de un `<button>`. Usa Radix UI Slot |
+| disabled  | `boolean`                                                                                                                                                               | `false`     | Desactiva el botón (opacity 50%, pointer-events none)          |
+| className | `string`                                                                                                                                                                | -           | Clases CSS adicionales                                         |
+| children  | `ReactNode`                                                                                                                                                             | -           | Contenido del botón (texto, iconos, etc.)                      |
+| type      | `"button" \| "submit" \| "reset"`                                                                                                                                       | `"button"`  | Tipo de botón HTML                                             |
+| onClick   | `(e: MouseEvent) => void`                                                                                                                                               | -           | Handler de click                                               |
+| ...props  | `ButtonHTMLAttributes`                                                                                                                                                  | -           | Todas las props nativas de `<button>`                          |
+
+**Nota sobre asChild**: Cuando es `true`, el componente usa `Slot` de Radix UI para transferir todas las props y estilos al hijo directo.
+
+## Estilos Base Automáticos
+
+Todos los botones tienen estos estilos aplicados automáticamente:
+
+```css
+inline-flex              /* Display flex inline */
+items-center            /* Alinea verticalmente al centro */
+justify-center          /* Centra horizontalmente */
+gap-2                   /* Espacio de 8px entre hijos */
+whitespace-nowrap       /* No rompe líneas */
+rounded-[12px]          /* Border radius 12px */
+text-sm                 /* Tamaño de fuente 14px */
+font-semibold           /* Peso de fuente 600 */
+transition-all          /* Transiciones suaves */
+outline-none            /* Sin outline por defecto */
+```
+
+### Iconos Auto-dimensionados
+
+```css
+[&_svg]:pointer-events-none              /* Iconos no capturan clicks */
+[&_svg:not([class*=size-])]:size-5       /* SVG sin clase size-* → 20x20px */
+[&_svg]:shrink-0                         /* Iconos no se encogen */
+[&>[data-slot=icon]]:text-2xl            /* Material Symbols icons → text-2xl */
+[&>[data-slot=icon]]:shrink-0            /* Material Symbols no se encogen */
+```
+
+### Padding Dinámico con Iconos
+
+```css
+/* size="default" */
+h-10 px-4                /* Sin icono: 16px padding horizontal */
+has-[>svg]:px-3.5        /* Con icono SVG: 14px padding horizontal */
+has-[>[data-slot=icon]]:px-3.5  /* Con Material Symbol: 14px padding */
+
+/* size="sm" */
+h-9 px-3
+has-[>svg]:px-2.5
+has-[>[data-slot=icon]]:px-2.5
+
+/* size="lg" */
+h-11 px-6
+has-[>svg]:px-5
+has-[>[data-slot=icon]]:px-5
+```
+
+**Beneficio**: El padding se reduce automáticamente cuando hay iconos para mantener proporciones visuales.
+
+## Casos de Uso Comunes
+
+### Acciones Primarias
+
+Para la acción más importante en la pantalla.
+
+```tsx
+<div className="flex gap-2">
+  <Button>
+    <SaveIcon />
+    Save Changes
+  </Button>
+  <Button>
+    <PlusIcon />
+    Create New
+  </Button>
+  <Button>
+    <DownloadIcon />
+    Export Data
+  </Button>
+</div>
+```
+
+### Acciones Secundarias
+
+Para acciones alternativas o de menor prioridad.
+
+```tsx
+<div className="flex gap-2">
+  <Button variant="outline">
+    <EditIcon />
+    Edit
+  </Button>
+  <Button variant="outline">
+    <CopyIcon />
+    Copy
+  </Button>
+  <Button variant="outline">
+    <ShareIcon />
+    Share
+  </Button>
+</div>
+```
+
+### Acciones Destructivas/Peligrosas
+
+Para acciones que requieren confirmación del usuario.
+
+```tsx
+<div className="flex gap-2">
+  <Button variant="destructive">
+    <TrashIcon />
+    Delete Item
+  </Button>
+  <Button variant="destructive">Reset All Data</Button>
+</div>
+```
+
+### Formularios
+
+Combinación típica en formularios.
+
+```tsx
+<form onSubmit={handleSubmit}>
+  {/* Campos del formulario */}
+
+  <div className="flex gap-2 justify-end mt-4">
+    <Button type="button" variant="outline" onClick={onCancel}>
+      Cancel
+    </Button>
+    <Button type="submit">
+      {isSubmitting ? (
+        <>
+          <Loader2Icon className="animate-spin" />
+          Saving...
+        </>
+      ) : (
+        <>
+          <SaveIcon />
+          Save
+        </>
+      )}
+    </Button>
+  </div>
+</form>
+```
+
+### Dialogs y Modals
+
+Acciones en footer de dialogs.
+
+```tsx
+<DialogFooter>
+  <Button variant="outline" onClick={onClose}>
+    Cancel
+  </Button>
+  <Button onClick={onConfirm}>Confirm</Button>
+</DialogFooter>
+```
+
+### Toolbars
+
+Botones de herramientas con iconos.
+
+```tsx
+{/* Toolbar con ghost para acciones primarias */}
+<div className="flex gap-1 p-2 border rounded-lg">
+  <Button size="icon-sm" variant="ghost" aria-label="Bold">
+    <BoldIcon />
+  </Button>
+  <Button size="icon-sm" variant="ghost" aria-label="Italic">
+    <ItalicIcon />
+  </Button>
+  <Button size="icon-sm" variant="ghost" aria-label="Underline">
+    <UnderlineIcon />
+  </Button>
+  <div className="w-px bg-border mx-1" />
+  <Button size="icon-sm" variant="ghost" aria-label="Align left">
+    <AlignLeftIcon />
+  </Button>
+  <Button size="icon-sm" variant="ghost" aria-label="Align center">
+    <AlignCenterIcon />
+  </Button>
+</div>
+
+{/* Toolbar con ghost-neutral para apariencia más sutil */}
+<div className="flex gap-1 p-2 border rounded-lg">
+  <Button size="icon-sm" variant="ghost-neutral" aria-label="Bold">
+    <BoldIcon />
+  </Button>
+  <Button size="icon-sm" variant="ghost-neutral" aria-label="Italic">
+    <ItalicIcon />
+  </Button>
+  <Button size="icon-sm" variant="ghost-neutral" aria-label="Underline">
+    <UnderlineIcon />
+  </Button>
+</div>
+```
+
+### Call to Action (CTA)
+
+Botón prominente en landing pages.
+
+```tsx
+<Button size="lg" className="text-base px-8">
+  Get Started Free
+  <ArrowRightIcon />
+</Button>
+```
+
+### Navegación
+
+Botones como links de navegación.
+
+```tsx
+import { useNavigate } from "react-router-dom";
+
+function Navigation() {
+  const navigate = useNavigate();
+
+  return (
+    <div className="flex gap-2">
+      <Button variant="ghost" onClick={() => navigate("/home")}>
+        Home
+      </Button>
+      <Button variant="ghost" onClick={() => navigate("/about")}>
+        About
+      </Button>
+      <Button variant="ghost" onClick={() => navigate("/contact")}>
+        Contact
+      </Button>
+    </div>
+  );
+}
+```
+
+### Botones de Paginación
+
+```tsx
+<div className="flex items-center gap-2">
+  <Button size="icon-sm" variant="outline" disabled={currentPage === 1}>
+    <ChevronLeftIcon />
+  </Button>
+  <span className="text-sm">
+    Page {currentPage} of {totalPages}
+  </span>
+  <Button
+    size="icon-sm"
+    variant="outline"
+    disabled={currentPage === totalPages}
+  >
+    <ChevronRightIcon />
+  </Button>
+</div>
+```
+
+## Mejores Prácticas
+
+### Jerarquía Visual
+
+```tsx
+{
+  /* ✅ Correcto - Jerarquía clara */
+}
+<div className="flex gap-2">
+  <Button variant="outline">Cancel</Button>
+  <Button>Save</Button> {/* Acción primaria más prominente */}
+</div>;
+
+{
+  /* ❌ Incorrecto - Todas las acciones con igual énfasis */
+}
+<div className="flex gap-2">
+  <Button>Cancel</Button>
+  <Button>Save</Button>
+</div>;
+```
+
+### Textos Descriptivos
+
+```tsx
+{/* ✅ Correcto - Texto claro */}
+<Button>Save Changes</Button>
+<Button variant="destructive">Delete Account</Button>
+
+{/* ❌ Incorrecto - Texto genérico */}
+<Button>OK</Button>
+<Button>Submit</Button>
+```
+
+### aria-label en Botones de Icono
+
+```tsx
+{
+  /* ✅ Correcto - Accesible */
+}
+<Button size="icon" aria-label="Settings">
+  <SettingsIcon />
+</Button>;
+
+{
+  /* ❌ Incorrecto - No accesible */
+}
+<Button size="icon">
+  <SettingsIcon />
+</Button>;
+```
+
+### Loading State
+
+```tsx
+{
+  /* ✅ Correcto - Estado de carga explícito */
+}
+<Button disabled={isLoading}>
+  {isLoading && <Loader2Icon className="animate-spin" />}
+  {isLoading ? "Saving..." : "Save"}
+</Button>;
+
+{
+  /* ❌ Incorrecto - Solo disabled sin feedback visual */
+}
+<Button disabled={isLoading}>Save</Button>;
+```
+
+### Variantes Semánticas
+
+```tsx
+{/* ✅ Correcto - Variantes apropiadas */}
+<Button variant="success">Approve</Button>
+<Button variant="destructive">Delete</Button>
+<Button variant="warning">Proceed with Caution</Button>
+
+{/* ❌ Incorrecto - Variantes genéricas para acciones críticas */}
+<Button>Delete All Data</Button>  {/* Debería ser destructive */}
+```
+
+### Ghost vs Ghost-Neutral
+
+```tsx
+{/* ✅ Correcto - Ghost para acciones con énfasis primario */}
+<Button variant="ghost">
+  <Icon symbol="add" />
+  Add Item
+</Button>
+
+{/* ✅ Correcto - Ghost-neutral para controles sin énfasis */}
+<Button variant="ghost-neutral" size="icon" aria-label="Settings">
+  <Icon symbol="settings" />
+</Button>
+
+{/* ✅ Correcto - Ghost-neutral en toolbars y paneles */}
+<div className="flex gap-1">
+  <Button variant="ghost-neutral" size="icon-sm" aria-label="Edit">
+    <Icon symbol="edit" />
+  </Button>
+  <Button variant="ghost-neutral" size="icon-sm" aria-label="Delete">
+    <Icon symbol="delete" />
+  </Button>
+</div>
+
+{/* ⚠️ Considerar - Ghost puede ser muy prominente en algunos contextos */}
+<Button variant="ghost">Close</Button>  {/* Mejor usar ghost-neutral */}
+```
+
+### Espaciado Consistente
+
+```tsx
+{
+  /* ✅ Correcto - Gap consistente */
+}
+<div className="flex gap-2">
+  <Button variant="outline">Back</Button>
+  <Button variant="outline">Skip</Button>
+  <Button>Next</Button>
+</div>;
+
+{
+  /* ✅ También correcto - Separar acciones por importancia */
+}
+<div className="flex justify-between">
+  <Button variant="outline">Cancel</Button>
+  <div className="flex gap-2">
+    <Button variant="outline">Save as Draft</Button>
+    <Button>Publish</Button>
+  </div>
+</div>;
+```
+
+## Notas de Implementación
+
+- Basado en CVA (class-variance-authority) para variants system
+- Usa Radix UI Slot para la prop `asChild`
+- Los iconos SVG sin clase `size-*` se auto-dimensionan a 16px
+- Padding horizontal se ajusta automáticamente con `has-[>svg]` selector
+- Focus ring usa `focus-visible` (solo teclado, no mouse)
+- Transiciones en `all` para suavidad en todos los cambios
+- Sistema de slots con `data-slot="button"` para identificación
+- Todos los botones son `inline-flex` para alineación perfecta
+- Border radius de 12px para apariencia más moderna
+- `aria-invalid` solo disponible en variante `outline` (única con borde visible)
+
+## Accesibilidad
+
+### Navegación por Teclado
+
+- ✅ **Tab**: Navega al botón
+- ✅ **Space/Enter**: Activa el botón
+- ✅ **Escape**: Sale del focus (en algunos contextos)
+
+### Estados Visuales Claros
+
+- ✅ Focus ring visible solo con teclado (`focus-visible`)
+- ✅ Disabled state con opacity reducida
+- ✅ Hover state en todas las variantes
+- ✅ Contraste de colores cumple WCAG AA
+
+### ARIA Best Practices
+
+```tsx
+{/* ✅ Botón de icono con aria-label */}
+<Button size="icon" aria-label="Delete item">
+  <TrashIcon />
+</Button>
+
+{/* ✅ Botón con estado de carga */}
+<Button disabled={isLoading} aria-busy={isLoading}>
+  {isLoading && <Loader2Icon className="animate-spin" />}
+  {isLoading ? "Loading..." : "Submit"}
+</Button>
+
+{/* ✅ Botón con estado pressed (toggle) */}
+<Button
+  variant={isActive ? "default" : "outline"}
+  aria-pressed={isActive}
+  onClick={() => setIsActive(!isActive)}
+>
+  {isActive ? "Active" : "Inactive"}
+</Button>
+
+{/* ✅ Botón con descripción expandida */}
+<Button aria-describedby="delete-description">
+  Delete Account
+</Button>
+<p id="delete-description" className="sr-only">
+  This action cannot be undone. All your data will be permanently deleted.
+</p>
+```
+
+### Type en Formularios
+
+```tsx
+{
+  /* ✅ Correcto - type explícito */
+}
+<form onSubmit={handleSubmit}>
+  <Button type="submit">Submit</Button>
+  <Button type="button" onClick={handleCancel}>
+    Cancel
+  </Button>
+  <Button type="reset">Reset Form</Button>
+</form>;
+
+{
+  /* ⚠️ Cuidado - sin type en form, default es submit */
+}
+<form>
+  <Button>Click me</Button> {/* Se comporta como submit */}
+</form>;
+```
+
+### Screen Readers
+
+- ✅ Texto descriptivo en lugar de solo iconos
+- ✅ `aria-label` para botones de solo icono
+- ✅ `aria-busy` durante estados de carga
+- ✅ `aria-invalid` para estados de error
+- ✅ Disabled buttons se anuncian como "disabled" o "dimmed"
+
+## Troubleshooting
+
+### Botón No Se Ve Como Esperado
+
+**Problema**: Los estilos no se aplican correctamente.
+
+**Solución**:
+
+```tsx
+// ❌ Incorrecto - className sobrescribe variantes
+<Button className="bg-destructive">Click</Button>
+
+// ✅ Correcto - Usa variantes predefinidas
+<Button variant="destructive">Click</Button>
+
+// ✅ O combina correctamente
+<Button variant="destructive" className="rounded-full">Click</Button>
+```
+
+### Icono No Se Auto-Dimensiona
+
+**Problema**: El icono es muy grande o muy pequeño.
+
+**Solución**:
+
+```tsx
+// ❌ Incorrecto - clase size-* evita auto-dimensionado
+<Button>
+  <SaveIcon className="size-8" />  {/* Muy grande */}
+  Save
+</Button>
+
+// ✅ Correcto - sin clase size-*
+<Button>
+  <SaveIcon />  {/* Auto-dimensionado a 16px */}
+  Save
+</Button>
+
+// ✅ O especifica tamaño personalizado si es necesario
+<Button>
+  <SaveIcon className="h-5 w-5" />
+  Save
+</Button>
+```
+
+### asChild No Funciona
+
+**Problema**: El hijo no recibe los estilos.
+
+**Solución**:
+
+```tsx
+// ❌ Incorrecto - múltiples hijos
+<Button asChild>
+  <a href="/link">Click</a>
+  <span>Extra</span>
+</Button>
+
+// ✅ Correcto - un solo hijo directo
+<Button asChild>
+  <a href="/link">
+    <LinkIcon />
+    Click Me
+  </a>
+</Button>
+```
+
+## Referencias
+
+- CVA (Class Variance Authority): https://cva.style/docs
+- Radix UI Slot: https://www.radix-ui.com/primitives/docs/utilities/slot
+- shadcn/ui Button: https://ui.shadcn.com/docs/components/button
+- WCAG 2.1 Button Guidelines: https://www.w3.org/WAI/ARIA/apg/patterns/button/