@adamosuiteservices/ui 1.2.5 → 1.3.5

package/docs/components/ui/badge.md

@@ -0,0 +1,1024 @@
+# Badge Component
+
+## Descripción
+
+Componente compacto para **etiquetar, categorizar y resaltar información**. Ofrece 13 variantes semánticas (incluyendo versiones "medium" suaves), 2 tamaños, iconos auto-dimensionados, soporte para links clickeables, y estilos especiales para números. Ideal para estados, notificaciones, etiquetas de producto, roles de usuario y contadores.
+
+## Características
+
+- ✅ 13 variantes: default (2), waiting (2), secondary, success (2), warning (2), destructive (2), muted, outline
+- ✅ Versiones "medium" con fondos suaves y colores vibrantes
+- ✅ 2 tamaños: default (compact) y lg (large)
+- ✅ Iconos auto-dimensionados (12px default, 16px large)
+- ✅ Prop `asChild` para badges clickeables (links)
+- ✅ Hover automático cuando es link (`[a&]:hover`)
+- ✅ Focus ring accesible con aria-invalid support
+- ✅ Width auto-ajustable (`w-fit`)
+- ✅ Estilos especiales para números circulares
+- ✅ Dark mode completo en todas las variantes
+
+## Importación
+
+```typescript
+import { Badge } from "@adamosuiteservices/ui/badge";
+```
+
+## Uso Básico
+
+### Badge Simple
+
+```tsx
+<Badge>Badge</Badge>
+```
+
+### Con Icono
+
+```tsx
+import { CheckIcon } from "lucide-react";
+
+<Badge>
+  <CheckIcon />
+  Verified
+</Badge>;
+```
+
+**Nota**: Los iconos se auto-dimensionan a 12px (default) o 16px (lg).
+
+### Como Link Clickeable
+
+```tsx
+<Badge asChild>
+  <a href="/profile">View Profile</a>
+</Badge>
+```
+
+**Comportamiento**: El badge se renderiza como `<a>` con estilos de hover automáticos.
+
+## Variantes
+
+### default (Primary)
+
+Badge sólido con colores primarios de la marca.
+
+```tsx
+<Badge variant="default">Default</Badge>
+```
+
+**Estilos**:
+
+- Fondo: `bg-primary`
+- Texto: `text-primary-foreground`
+- Border: Transparente
+- Hover (link): `bg-primary/90`
+- Uso: Badges principales, featured, new, popular
+
+### default-medium
+
+Versión suave con fondo claro y icono en color primario.
+
+```tsx
+<Badge variant="default-medium">Default Medium</Badge>
+```
+
+**Estilos**:
+
+- Fondo: `bg-primary-50` (muy claro)
+- Texto: `text-neutral-600`
+- Icono: `text-primary` (color vibrante)
+- Hover (link): `bg-primary-100`
+- Dark mode: `bg-primary-200`, `text-primary-800`
+- Uso: Estados informativos suaves, categorías
+
+### waiting
+
+Badge para estados pendientes o en espera.
+
+```tsx
+<Badge variant="waiting">Waiting</Badge>
+```
+
+**Estilos**:
+
+- Fondo: `bg-waiting` (color de espera)
+- Texto: `text-waiting-foreground`
+- Hover (link): `bg-waiting/90`
+- Uso: Pendiente, en revisión, en proceso
+
+### waiting-medium
+
+Versión suave del badge waiting.
+
+```tsx
+<Badge variant="waiting-medium">Waiting Medium</Badge>
+```
+
+**Estilos**:
+
+- Fondo: `bg-waiting-50`
+- Texto: `text-neutral-600`
+- Icono: `text-waiting`
+- Dark mode: `bg-waiting-200`, `text-waiting-800`
+- Uso: Estados de espera sutiles
+
+### secondary
+
+Badge con colores secundarios.
+
+```tsx
+<Badge variant="secondary">Secondary</Badge>
+```
+
+**Estilos**:
+
+- Fondo: `bg-secondary`
+- Texto: `text-secondary-foreground`
+- Hover (link): `bg-secondary/90`
+- Uso: Información adicional, etiquetas genéricas
+
+### success
+
+Badge verde sólido para estados exitosos.
+
+```tsx
+<Badge variant="success">Success</Badge>
+```
+
+**Estilos**:
+
+- Fondo: `bg-success` (verde)
+- Texto: `text-white`
+- Hover (link): `bg-success/90`
+- Focus ring: `ring-success/20`
+- Dark mode: `bg-success/60`
+- Uso: Completado, aprobado, activo, disponible
+
+### success-medium
+
+Versión suave del badge success.
+
+```tsx
+<Badge variant="success-medium">Success Medium</Badge>
+```
+
+**Estilos**:
+
+- Fondo: `bg-success-50` (verde muy claro)
+- Texto: `text-neutral-600`
+- Icono: `text-success` (verde vibrante)
+- Hover (link): `bg-success-100`
+- Dark mode: `bg-success-200`, `text-success-800`
+- Uso: Estados positivos sutiles, confirmaciones
+
+### warning
+
+Badge naranja/amarillo sólido para advertencias.
+
+```tsx
+<Badge variant="warning">Warning</Badge>
+```
+
+**Estilos**:
+
+- Fondo: `bg-warning` (naranja/amarillo)
+- Texto: `text-white`
+- Hover (link): `bg-warning/90`
+- Focus ring: `ring-warning/20`
+- Dark mode: `bg-warning/60`
+- Uso: Advertencia, atención requerida, casi lleno
+
+### warning-medium
+
+Versión suave del badge warning.
+
+```tsx
+<Badge variant="warning-medium">Warning Medium</Badge>
+```
+
+**Estilos**:
+
+- Fondo: `bg-warning-50` (naranja muy claro)
+- Texto: `text-neutral-600`
+- Icono: `text-warning`
+- Dark mode: `bg-warning-200`, `text-warning-800`
+- Uso: Advertencias sutiles, precauciones
+
+### destructive
+
+Badge rojo sólido para errores y estados negativos.
+
+```tsx
+<Badge variant="destructive">Destructive</Badge>
+```
+
+**Estilos**:
+
+- Fondo: `bg-destructive` (rojo)
+- Texto: `text-white`
+- Hover (link): `bg-destructive/90`
+- Focus ring: `ring-destructive/20`
+- Dark mode: `bg-destructive/60`
+- Uso: Error, inactivo, cancelado, rechazado
+
+### destructive-medium
+
+Versión suave del badge destructive.
+
+```tsx
+<Badge variant="destructive-medium">Destructive Medium</Badge>
+```
+
+**Estilos**:
+
+- Fondo: `bg-destructive-50` (rojo muy claro)
+- Texto: `text-neutral-600`
+- Icono: `text-destructive` (rojo vibrante)
+- Dark mode: `bg-destructive-200`, `text-destructive-800`
+- Uso: Errores sutiles, estados negativos
+
+### muted
+
+Badge con colores apagados para bajo énfasis.
+
+```tsx
+<Badge variant="muted">Muted</Badge>
+```
+
+**Estilos**:
+
+- Fondo: `bg-muted`
+- Texto: `text-muted-foreground`
+- Hover (link): `bg-muted/90`
+- Dark mode: `bg-muted/60`
+- Uso: Información secundaria, disabled, draft
+
+### outline
+
+Badge con borde y fondo transparente.
+
+```tsx
+<Badge variant="outline">Outline</Badge>
+```
+
+**Estilos**:
+
+- Fondo: Transparente
+- Texto: `text-foreground`
+- Border: Visible
+- Hover (link): `bg-accent`
+- Uso: Tags, categorías, filtros, etiquetas neutrales
+
+## Tamaños
+
+### default (Compact)
+
+Tamaño compacto para uso general.
+
+```tsx
+<Badge>Compact Badge</Badge>
+```
+
+**Dimensiones**:
+
+- Padding horizontal: `px-2` (8px)
+- Padding vertical: `py-0.5` (2px)
+- Texto: `text-xs` (12px)
+- Iconos: `size-3` (12x12px)
+- Gap: `gap-1` (4px)
+
+### lg (Large)
+
+Tamaño grande para mayor visibilidad.
+
+```tsx
+<Badge size="lg">Large Badge</Badge>
+```
+
+**Dimensiones**:
+
+- Padding horizontal: `px-2` (8px)
+- Padding vertical: `py-1` (4px)
+- Texto: `text-sm` (14px)
+- Iconos: `size-4` (16x16px)
+- Gap: `gap-2` (8px)
+
+## Props
+
+| Prop      | Tipo                                                                                                                                                                                                               | Default     | Descripción                                                  |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------ |
+| variant   | `"default" \| "default-medium" \| "waiting" \| "waiting-medium" \| "secondary" \| "success" \| "success-medium" \| "warning" \| "warning-medium" \| "destructive" \| "destructive-medium" \| "muted" \| "outline"` | `"default"` | Variante visual del badge                                    |
+| size      | `"default" \| "lg"`                                                                                                                                                                                                | `"default"` | Tamaño del badge                                             |
+| asChild   | `boolean`                                                                                                                                                                                                          | `false`     | Renderiza el hijo en lugar de un `<span>`. Usa Radix UI Slot |
+| className | `string`                                                                                                                                                                                                           | -           | Clases CSS adicionales                                       |
+| children  | `ReactNode`                                                                                                                                                                                                        | -           | Contenido del badge (texto, iconos, números)                 |
+| ...props  | `HTMLAttributes<HTMLSpanElement>`                                                                                                                                                                                  | -           | Todas las props nativas de `<span>`                          |
+
+**Nota sobre asChild**: Útil para badges clickeables con links `<a>`.
+
+## Estilos Base Automáticos
+
+Todos los badges tienen estos estilos aplicados:
+
+```css
+inline-flex              /* Display flex inline */
+items-center            /* Alinea verticalmente */
+justify-center          /* Centra horizontalmente */
+rounded-md              /* Border radius medium */
+border                  /* Border (transparente en la mayoría) */
+w-fit                   /* Ancho auto-ajustable */
+whitespace-nowrap       /* No rompe líneas */
+shrink-0                /* No se encoge en flex/grid */
+overflow-hidden         /* Oculta overflow */
+transition-[color,box-shadow]  /* Transiciones suaves */
+```
+
+### Iconos Auto-dimensionados
+
+```css
+[&>svg]:size-3               /* SVG → 12x12px (default) */
+[&>svg]:size-4               /* SVG → 16x16px (size="lg") */
+[&>svg]:pointer-events-none  /* Iconos no capturan clicks */
+gap-1                        /* 4px entre elementos (default) */
+gap-2                        /* 8px entre elementos (lg) */
+```
+
+### Hover Automático en Links
+
+```css
+[a&]:hover:bg-primary/90     /* Solo si el badge es un <a> */
+```
+
+**Beneficio**: El hover solo se aplica cuando usas `asChild` con `<a>`.
+
+## Patrones Avanzados
+
+### Badges de Estado
+
+Para indicadores de estado del sistema.
+
+```tsx
+import { CheckIcon, XIcon, AlertCircleIcon, ZapIcon } from "lucide-react";
+
+<div className="flex gap-2">
+  <Badge variant="success">
+    <CheckIcon />
+    Active
+  </Badge>
+  <Badge variant="secondary">
+    <ZapIcon />
+    Pending
+  </Badge>
+  <Badge variant="warning-medium">
+    <AlertCircleIcon />
+    Warning
+  </Badge>
+  <Badge variant="destructive">
+    <XIcon />
+    Inactive
+  </Badge>
+</div>;
+```
+
+### Badges Numéricos (Circulares)
+
+Para notificaciones y contadores.
+
+```tsx
+{/* Small circular badges */}
+<Badge className="h-5 min-w-5 rounded-full px-1 font-mono tabular-nums">
+  8
+</Badge>
+
+<Badge
+  variant="destructive"
+  className="h-5 min-w-5 rounded-full px-1 font-mono tabular-nums"
+>
+  99
+</Badge>
+
+<Badge
+  variant="outline"
+  className="h-5 min-w-5 rounded-full px-1 font-mono tabular-nums"
+>
+  20+
+</Badge>
+
+{/* Larger circular badge */}
+<Badge
+  variant="secondary"
+  className="h-6 min-w-6 rounded-full px-1.5 font-mono tabular-nums"
+>
+  1.2K
+</Badge>
+```
+
+**Clases importantes**:
+
+- `rounded-full`: Circular
+- `min-w-5`: Ancho mínimo para mantener forma circular
+- `font-mono`: Fuente monoespaciada para números
+- `tabular-nums`: Números alineados
+
+### Badges con Notificaciones (Posicionados)
+
+Para iconos con contadores.
+
+```tsx
+import { BellIcon, HeartIcon, GiftIcon } from "lucide-react";
+import { Button } from "@adamosuiteservices/ui/button";
+
+<div className="flex gap-6 items-center">
+  {/* Con contador */}
+  <div className="relative">
+    <Button variant="outline" size="icon">
+      <BellIcon />
+    </Button>
+    <Badge
+      variant="destructive"
+      className="absolute -top-2 -right-2 h-5 min-w-5 rounded-full px-1 font-mono tabular-nums"
+    >
+      3
+    </Badge>
+  </div>
+
+  {/* Con número más grande */}
+  <div className="relative">
+    <Button variant="outline" size="icon">
+      <HeartIcon />
+    </Button>
+    <Badge
+      variant="default"
+      className="absolute -top-2 -right-2 h-5 min-w-5 rounded-full px-1 font-mono tabular-nums"
+    >
+      12
+    </Badge>
+  </div>
+
+  {/* Solo indicador (sin número) */}
+  <div className="relative">
+    <Button variant="outline" size="icon">
+      <GiftIcon />
+    </Button>
+    <Badge
+      variant="secondary"
+      className="absolute -top-2 -right-2 h-4 min-w-4 rounded-full px-0.5 text-xs"
+    >
+      •
+    </Badge>
+  </div>
+</div>;
+```
+
+### Roles de Usuario
+
+Para permisos y niveles.
+
+```tsx
+import { CrownIcon, ShieldIcon, BadgeCheckIcon } from "lucide-react";
+
+<div className="flex gap-2">
+  <Badge variant="default">
+    <CrownIcon />
+    Admin
+  </Badge>
+  <Badge variant="secondary">
+    <ShieldIcon />
+    Moderator
+  </Badge>
+  <Badge variant="default-medium">
+    <BadgeCheckIcon />
+    Verified
+  </Badge>
+  <Badge variant="outline">Member</Badge>
+</div>;
+```
+
+### Badges de Producto (E-commerce)
+
+Para etiquetas promocionales.
+
+```tsx
+import { GiftIcon, StarIcon } from "lucide-react";
+
+<div className="space-y-4">
+  {/* Badges básicos */}
+  <div className="flex gap-2">
+    <Badge variant="destructive">Sale</Badge>
+    <Badge variant="default">New</Badge>
+    <Badge variant="secondary">Bestseller</Badge>
+    <Badge variant="outline">Limited</Badge>
+  </div>
+
+  {/* Badges personalizados */}
+  <div className="flex gap-2">
+    <Badge className="bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-200">
+      Free Shipping
+    </Badge>
+    <Badge className="bg-purple-100 text-purple-800 dark:bg-purple-900 dark:text-purple-200">
+      <StarIcon />
+      Premium
+    </Badge>
+    <Badge className="bg-yellow-100 text-yellow-800 dark:bg-yellow-900 dark:text-yellow-200">
+      <GiftIcon />
+      Bundle Deal
+    </Badge>
+  </div>
+</div>;
+```
+
+### Badges con Avatares
+
+Para menciones y tags de usuario.
+
+```tsx
+import {
+  Avatar,
+  AvatarImage,
+  AvatarFallback,
+} from "@adamosuiteservices/ui/avatar";
+import { BadgeCheckIcon } from "lucide-react";
+
+<div className="flex gap-4 items-center">
+  <div className="flex items-center gap-2">
+    <Avatar className="size-6">
+      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+      <AvatarFallback>CN</AvatarFallback>
+    </Avatar>
+    <Badge variant="secondary">shadcn</Badge>
+  </div>
+
+  <div className="flex items-center gap-2">
+    <Avatar className="size-6">
+      <AvatarFallback>ML</AvatarFallback>
+    </Avatar>
+    <Badge variant="default">
+      <BadgeCheckIcon />
+      maxleiter
+    </Badge>
+  </div>
+</div>;
+```
+
+### Badges de Precio
+
+Para información de precios y promociones.
+
+```tsx
+import { DollarSignIcon, TrendingUpIcon } from "lucide-react";
+
+<div className="flex gap-2">
+  <Badge variant="secondary">
+    <DollarSignIcon />
+    $9.99
+  </Badge>
+  <Badge variant="destructive" className="animate-pulse">
+    50% OFF
+  </Badge>
+  <Badge variant="default">
+    <TrendingUpIcon />
+    Best Value
+  </Badge>
+  <Badge variant="outline">Free Trial</Badge>
+</div>;
+```
+
+### Colores Personalizados
+
+Para casos especiales de branding.
+
+```tsx
+import {
+  BadgeCheckIcon,
+  CheckIcon,
+  StarIcon,
+  TrendingUpIcon,
+} from "lucide-react";
+
+<div className="flex gap-2">
+  <Badge className="bg-blue-500 text-white dark:bg-blue-600">
+    <BadgeCheckIcon />
+    Verified
+  </Badge>
+  <Badge className="bg-green-500 text-white dark:bg-green-600">
+    <CheckIcon />
+    Success
+  </Badge>
+  <Badge className="bg-purple-500 text-white dark:bg-purple-600">
+    <StarIcon />
+    Premium
+  </Badge>
+  <Badge className="bg-orange-500 text-white dark:bg-orange-600">
+    <TrendingUpIcon />
+    Trending
+  </Badge>
+</div>;
+```
+
+### Badges Clickeables
+
+Para navegación y filtros.
+
+```tsx
+{
+  /* Badge como link */
+}
+<Badge asChild>
+  <a href="/category/react">React</a>
+</Badge>;
+
+{
+  /* Badge como botón */
+}
+<Badge asChild>
+  <button onClick={handleClick}>
+    <XIcon />
+    Remove
+  </button>
+</Badge>;
+
+{
+  /* Badge interactivo con estado */
+}
+<Badge asChild variant={isActive ? "default" : "outline"}>
+  <button onClick={() => setIsActive(!isActive)}>
+    {isActive ? "Active" : "Inactive"}
+  </button>
+</Badge>;
+```
+
+## Casos de Uso Comunes
+
+### Indicadores de Estado
+
+```tsx
+// Estados del sistema
+<Badge variant="success">Online</Badge>
+<Badge variant="warning">Maintenance</Badge>
+<Badge variant="destructive">Offline</Badge>
+<Badge variant="muted">Draft</Badge>
+
+// Estados de pedido
+<Badge variant="waiting">Pending</Badge>
+<Badge variant="default">Processing</Badge>
+<Badge variant="success">Completed</Badge>
+<Badge variant="destructive">Cancelled</Badge>
+```
+
+### Tags y Categorías
+
+```tsx
+<div className="flex gap-2 flex-wrap">
+  <Badge variant="outline">React</Badge>
+  <Badge variant="outline">TypeScript</Badge>
+  <Badge variant="outline">Tailwind CSS</Badge>
+  <Badge variant="outline">Next.js</Badge>
+</div>
+```
+
+### Contadores y Notificaciones
+
+```tsx
+<div className="flex items-center gap-2">
+  <span className="text-sm">New messages</span>
+  <Badge variant="destructive" className="h-5 min-w-5 rounded-full px-1">
+    12
+  </Badge>
+</div>
+
+<div className="flex items-center gap-2">
+  <span className="text-sm">Unread</span>
+  <Badge>3</Badge>
+</div>
+```
+
+### Etiquetas de Producto
+
+```tsx
+// En tarjeta de producto
+<div className="relative">
+  <img src={productImage} alt="Product" />
+  <div className="absolute top-2 left-2 flex gap-2">
+    <Badge variant="destructive">-50%</Badge>
+    <Badge variant="default">New</Badge>
+  </div>
+</div>
+```
+
+### Información de Usuario
+
+```tsx
+<div className="flex items-center gap-3">
+  <Avatar className="size-10">
+    <AvatarImage src={userAvatar} />
+    <AvatarFallback>JD</AvatarFallback>
+  </Avatar>
+  <div>
+    <div className="flex items-center gap-2">
+      <span className="font-medium">John Doe</span>
+      <Badge variant="default-medium">
+        <BadgeCheckIcon />
+        Verified
+      </Badge>
+    </div>
+    <div className="flex gap-2 mt-1">
+      <Badge variant="outline" size="sm">
+        Admin
+      </Badge>
+      <Badge variant="outline" size="sm">
+        Pro
+      </Badge>
+    </div>
+  </div>
+</div>
+```
+
+### Lista de Tareas/Items
+
+```tsx
+<ul className="space-y-2">
+  <li className="flex items-center justify-between">
+    <span>Complete project documentation</span>
+    <Badge variant="success">Done</Badge>
+  </li>
+  <li className="flex items-center justify-between">
+    <span>Review pull requests</span>
+    <Badge variant="warning">In Progress</Badge>
+  </li>
+  <li className="flex items-center justify-between">
+    <span>Deploy to production</span>
+    <Badge variant="outline">Todo</Badge>
+  </li>
+</ul>
+```
+
+### Filtros Removibles
+
+```tsx
+import { XIcon } from "lucide-react";
+
+<div className="flex gap-2">
+  <Badge asChild>
+    <button className="cursor-pointer hover:bg-accent/80">
+      Category: Electronics
+      <XIcon className="h-3 w-3 ml-1" />
+    </button>
+  </Badge>
+  <Badge asChild>
+    <button className="cursor-pointer hover:bg-accent/80">
+      Price: $50-$100
+      <XIcon className="h-3 w-3 ml-1" />
+    </button>
+  </Badge>
+</div>;
+```
+
+## Mejores Prácticas
+
+### Selección de Variantes
+
+```tsx
+{/* ✅ Correcto - Variantes semánticas */}
+<Badge variant="success">Approved</Badge>
+<Badge variant="destructive">Rejected</Badge>
+<Badge variant="warning">Pending Review</Badge>
+
+{/* ❌ Incorrecto - Variantes genéricas para estados importantes */}
+<Badge variant="secondary">Approved</Badge>  {/* Debería ser success */}
+<Badge variant="outline">Error</Badge>        {/* Debería ser destructive */}
+```
+
+### Badges Numéricos
+
+```tsx
+{
+  /* ✅ Correcto - Circular con fuente mono */
+}
+<Badge className="h-5 min-w-5 rounded-full px-1 font-mono tabular-nums">
+  99+
+</Badge>;
+
+{
+  /* ❌ Incorrecto - Rectangular para números */
+}
+<Badge>99+</Badge>;
+```
+
+### Tamaño de Texto
+
+```tsx
+{/* ✅ Correcto - Textos cortos */}
+<Badge>New</Badge>
+<Badge>Sale</Badge>
+<Badge variant="success">Active</Badge>
+
+{/* ❌ Incorrecto - Textos muy largos */}
+<Badge>This is a very long badge text that should be avoided</Badge>
+
+{/* ✅ Mejor - Usa Tooltip para textos largos */}
+<Tooltip>
+  <TooltipTrigger>
+    <Badge>Info</Badge>
+  </TooltipTrigger>
+  <TooltipContent>
+    This is the full explanation that was too long for the badge
+  </TooltipContent>
+</Tooltip>
+```
+
+### Accesibilidad en Badges Clickeables
+
+```tsx
+{
+  /* ✅ Correcto - Link semántico */
+}
+<Badge asChild>
+  <a href="/category" aria-label="View React category">
+    React
+  </a>
+</Badge>;
+
+{
+  /* ✅ Correcto - Botón con aria-label */
+}
+<Badge asChild>
+  <button onClick={handleRemove} aria-label="Remove React filter">
+    React
+    <XIcon />
+  </button>
+</Badge>;
+```
+
+### Consistencia Visual
+
+```tsx
+{
+  /* ✅ Correcto - Tamaños consistentes en el mismo contexto */
+}
+<div className="flex gap-2">
+  <Badge variant="outline">React</Badge>
+  <Badge variant="outline">TypeScript</Badge>
+  <Badge variant="outline">Next.js</Badge>
+</div>;
+
+{
+  /* ❌ Incorrecto - Mezcla innecesaria de tamaños */
+}
+<div className="flex gap-2">
+  <Badge size="lg">React</Badge>
+  <Badge>TypeScript</Badge>
+  <Badge size="lg">Next.js</Badge>
+</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 se auto-dimensionan: 12px (default), 16px (lg)
+- Width es `w-fit` para auto-ajustarse al contenido
+- Hover automático solo en badges que son links: `[a&]:hover`
+- Focus ring usa `focus-visible` (solo teclado)
+- `shrink-0` evita que badges se encojan en flex layouts
+- Border es transparente en la mayoría de variantes
+- Transiciones solo en `color` y `box-shadow` para mejor performance
+- Sistema de slots con `data-slot="badge"` para identificación
+
+## Accesibilidad
+
+### Badges No Interactivos
+
+```tsx
+{/* ✅ Correcto - Solo visual, no necesita ARIA */}
+<Badge variant="success">Active</Badge>
+<Badge variant="outline">React</Badge>
+```
+
+### Badges Interactivos
+
+```tsx
+{
+  /* ✅ Correcto - Link con texto descriptivo */
+}
+<Badge asChild>
+  <a href="/category/new">New Items</a>
+</Badge>;
+
+{
+  /* ✅ Correcto - Botón con aria-label */
+}
+<Badge asChild>
+  <button aria-label="Remove tag: JavaScript" onClick={handleRemove}>
+    JavaScript
+    <XIcon />
+  </button>
+</Badge>;
+
+{
+  /* ✅ Correcto - Badge numérico con contexto */
+}
+<span className="flex items-center gap-2">
+  <span id="notification-label">Unread notifications</span>
+  <Badge aria-labelledby="notification-label">5</Badge>
+</span>;
+```
+
+### Contraste de Colores
+
+- ✅ Todas las variantes sólidas (default, success, warning, destructive) tienen contraste AAA
+- ✅ Variantes "medium" tienen contraste AA para texto
+- ✅ Iconos en variantes "medium" usan colores vibrantes para mejor visibilidad
+- ⚠️ Verifica contraste si usas colores personalizados
+
+### Screen Readers
+
+```tsx
+{
+  /* ✅ Badges decorativos - ocultos de screen readers */
+}
+<div className="flex items-center gap-2">
+  <span>New features available</span>
+  <Badge aria-hidden="true">3</Badge>
+</div>;
+
+{
+  /* ✅ Badges con información importante - incluidos */
+}
+<div>
+  <span>Order status: </span>
+  <Badge variant="success">Completed</Badge>
+</div>;
+```
+
+## Troubleshooting
+
+### Badge Demasiado Ancho
+
+**Problema**: El badge es más ancho de lo esperado.
+
+**Solución**:
+
+```tsx
+// ❌ Badge con texto largo
+<Badge>This is a very long badge</Badge>
+
+// ✅ Texto más corto
+<Badge>Long...</Badge>
+
+// ✅ O usa max-width
+<Badge className="max-w-[100px] truncate">
+  This is a very long badge
+</Badge>
+```
+
+### Iconos No Se Alinean
+
+**Problema**: Los iconos no están centrados verticalmente.
+
+**Solución**:
+
+```tsx
+// ❌ Incorrecto - icono con tamaño personalizado
+<Badge>
+  <CheckIcon className="h-5 w-5" />  {/* Muy grande */}
+  Verified
+</Badge>
+
+// ✅ Correcto - sin clase size (auto-dimensionado)
+<Badge>
+  <CheckIcon />  {/* Auto: 12px */}
+  Verified
+</Badge>
+
+// ✅ También correcto - size lg con iconos más grandes
+<Badge size="lg">
+  <CheckIcon />  {/* Auto: 16px */}
+  Verified
+</Badge>
+```
+
+### Badge No Es Clickeable
+
+**Problema**: El badge no responde a clicks.
+
+**Solución**:
+
+```tsx
+// ❌ Incorrecto - badge span no es clickeable
+<Badge onClick={handleClick}>Click me</Badge>
+
+// ✅ Correcto - usa asChild con button
+<Badge asChild>
+  <button onClick={handleClick}>Click me</button>
+</Badge>
+
+// ✅ O usa asChild con link
+<Badge asChild>
+  <a href="/link">Click me</a>
+</Badge>
+```
+
+## Referencias
+
+- CVA (Class Variance Authority): https://cva.style/docs
+- Radix UI Slot: https://www.radix-ui.com/primitives/docs/utilities/slot
+- shadcn/ui Badge: https://ui.shadcn.com/docs/components/badge
+- WCAG Contrast Guidelines: https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html