@adamosuiteservices/ui 1.2.5 → 1.3.5

package/docs/components/ui/button.md

@@ -0,0 +1,1078 @@
+# 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
+
+- ✅ 11 variantes: default, success (2), warning (2), destructive (2), secondary, outline, ghost, 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 { PlusIcon } from "lucide-react";
+
+<Button>
+  <PlusIcon />
+  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 que solo aparece en hover.
+
+```tsx
+<Button variant="ghost">Ghost</Button>
+```
+
+**Estilos**:
+
+- Fondo: Transparente
+- Hover: `bg-accent`
+- Dark mode: `hover:bg-accent/50`
+- Uso: Acciones terciarias, iconos de herramientas, menús
+
+### 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 { Loader2Icon } from "lucide-react";
+
+<Button disabled>
+  <Loader2Icon className="animate-spin" />
+  Loading...
+</Button>;
+```
+
+**Patrón recomendado**:
+
+```tsx
+const [isLoading, setIsLoading] = useState(false);
+
+<Button disabled={isLoading} onClick={handleSubmit}>
+  {isLoading && <Loader2Icon 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 { SaveIcon, DownloadIcon, TrashIcon } from "lucide-react";
+
+{
+  /* Icono a la izquierda */
+}
+<Button>
+  <SaveIcon />
+  Save Changes
+</Button>;
+
+{
+  /* Icono a la derecha */
+}
+<Button>
+  Download
+  <DownloadIcon />
+</Button>;
+
+{
+  /* Múltiples iconos */
+}
+<Button variant="destructive">
+  <TrashIcon />
+  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 { HeartIcon, StarIcon, PlayIcon, PauseIcon } from "lucide-react";
+
+function LikeButton() {
+  const [liked, setLiked] = useState(false);
+
+  return (
+    <Button
+      variant={liked ? "default" : "outline"}
+      onClick={() => setLiked(!liked)}
+    >
+      <HeartIcon className={liked ? "fill-current" : ""} />
+      {liked ? "Liked" : "Like"}
+    </Button>
+  );
+}
+
+function SaveButton() {
+  const [saved, setSaved] = useState(false);
+
+  return (
+    <Button
+      variant={saved ? "secondary" : "outline"}
+      onClick={() => setSaved(!saved)}
+    >
+      <StarIcon className={saved ? "fill-current" : ""} />
+      {saved ? "Saved" : "Save"}
+    </Button>
+  );
+}
+
+function PlayButton() {
+  const [playing, setPlaying] = useState(false);
+
+  return (
+    <Button variant="outline" onClick={() => setPlaying(!playing)}>
+      {playing ? <PauseIcon /> : <PlayIcon />}
+      {playing ? "Pause" : "Play"}
+    </Button>
+  );
+}
+```
+
+### asChild con Link (Next.js)
+
+```tsx
+import Link from "next/link";
+import { ExternalLinkIcon } from "lucide-react";
+
+<Button asChild>
+  <Link href="/dashboard">
+    Go to Dashboard
+  </Link>
+</Button>
+
+<Button asChild variant="outline">
+  <a href="https://example.com" target="_blank" rel="noopener noreferrer">
+    <ExternalLinkIcon />
+    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 { ChevronDownIcon } from "lucide-react";
+
+<Button>
+  Options
+  <ChevronDownIcon 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" \| "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
+<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>
+```
+
+### 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 */}
+```
+
+### 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-red-500">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/