@adamosuiteservices/ui 2.9.15 → 2.10.0

package/docs/components/ui/avatar.md

@@ -1,588 +1,587 @@
-# Avatar Component
-
-## Descripción
-
-Componente para mostrar **imágenes de perfil de usuario** con sistema de fallback automático a iniciales o iconos cuando la imagen no está disponible o falla al cargar. Basado en Radix UI Avatar primitives con carga lazy, estado de error manejado, y diseño circular responsive.
-
-## Características
-
-- ✅ Fallback automático si la imagen falla
-- ✅ Carga lazy de imágenes
-- ✅ Soporte para iniciales o iconos como fallback
-- ✅ Tamaños personalizables
-- ✅ Formas: circular (default) o cuadrado/rectangular
-- ✅ Grupos de avatares con solapamiento
-- ✅ Integración con Tooltip
-- ✅ Accesibilidad: alt text y ARIA
-- ✅ Diseño responsive y flexible
-
-## Importación
-
-```typescript
-import {
-  Avatar,
-  AvatarImage,
-  AvatarFallback,
-} from "@adamosuiteservices/ui/avatar";
-```
-
-## Uso Básico
-
-### Avatar con Imagen y Fallback
-
-```tsx
-<Avatar>
-  <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
-  <AvatarFallback>CN</AvatarFallback>
-</Avatar>
-```
-
-**Comportamiento**:
-
-1. Intenta cargar la imagen del `src`
-2. Si falla o no carga, muestra el `AvatarFallback` automáticamente
-3. Radix UI maneja el estado de carga internamente
-
-### Solo Fallback (Sin Imagen)
-
-```tsx
-<Avatar>
-  <AvatarFallback>JD</AvatarFallback>
-</Avatar>
-```
-
-**Uso**: Cuando no hay imagen disponible o solo quieres mostrar iniciales.
-
-### Imagen Rota (Graceful Degradation)
-
-```tsx
-<Avatar>
-  <AvatarImage src="https://broken-link.com/image.jpg" alt="Broken" />
-  <AvatarFallback>BK</AvatarFallback>
-</Avatar>
-```
-
-**Resultado**: Automáticamente muestra "BK" si la imagen no carga.
-
-## Props
-
-### Avatar (Root)
-
-Contenedor principal del avatar.
-
-| Prop      | Tipo                       | Descripción                 |
-| --------- | -------------------------- | --------------------------- |
-| className | `string`                   | Clases CSS adicionales      |
-| ...props  | Props de Radix Avatar.Root | Props nativas del primitivo |
-
-**Estilos por defecto**:
-
-- `size-8`: 2rem (32x32px) - tamaño base
-- `rounded-full`: Forma circular
-- `shrink-0`: No se encoge en flex/grid
-- `overflow-hidden`: Recorta contenido fuera del círculo
-- `relative`: Para posicionamiento interno
-- `flex`: Contenedor flex
-
-**Atributos automáticos**:
-
-- `data-slot="avatar"`: Para identificación interna
-
-### AvatarImage
-
-Imagen del avatar con carga lazy.
-
-| Prop      | Tipo                        | Descripción                                         |
-| --------- | --------------------------- | --------------------------------------------------- |
-| src       | `string`                    | **Requerido**. URL de la imagen                     |
-| alt       | `string`                    | **Requerido**. Texto alternativo para accesibilidad |
-| className | `string`                    | Clases CSS adicionales                              |
-| ...props  | Props de Radix Avatar.Image | Props nativas del primitivo                         |
-
-**Estilos aplicados**:
-
-- `aspect-square`: Mantiene aspecto cuadrado
-- `size-full`: Ocupa todo el contenedor (100% width/height)
-
-**Comportamiento**:
-
-- Carga lazy automática
-- Emite eventos `onLoadingStatusChange`
-- Estados: `idle`, `loading`, `loaded`, `error`
-- Si falla, muestra AvatarFallback automáticamente
-
-**Atributos automáticos**:
-
-- `data-slot="avatar-image"`: Para identificación interna
-
-### AvatarFallback
-
-Contenido mostrado cuando la imagen no carga o no existe.
-
-| Prop      | Tipo                           | Descripción                                            |
-| --------- | ------------------------------ | ------------------------------------------------------ |
-| children  | `ReactNode`                    | **Requerido**. Iniciales, icono, o cualquier contenido |
-| delayMs   | `number`                       | Delay antes de mostrar el fallback (ms)                |
-| className | `string`                       | Clases CSS adicionales                                 |
-| ...props  | Props de Radix Avatar.Fallback | Props nativas del primitivo                            |
-
-**Estilos por defecto**:
-
-- `bg-muted`: Fondo gris claro
-- `rounded-full`: Forma circular (coincide con el contenedor)
-- `size-full`: Ocupa todo el espacio
-- `flex items-center justify-center`: Centra el contenido
-
-**Contenido común**:
-
-- Iniciales (2 letras): "JD", "AB", "CN"
-- Iconos: `<UserIcon />`, `<PersonIcon />`
-- Texto: "+5" (para grupos)
-
-**Atributos automáticos**:
-
-- `data-slot="avatar-fallback"`: Para identificación interna
-
-## Tamaños Personalizados
-
-El tamaño por defecto es `size-8` (32px). Personaliza con className:
-
-### Tamaños Predefinidos
-
-```tsx
-{
-  /* Extra Small - 24px */
-}
-<Avatar className="size-6">
-  <AvatarImage src={url} alt="User" />
-  <AvatarFallback className="text-xs">CN</AvatarFallback>
-</Avatar>;
-
-{
-  /* Small - 32px (default) */
-}
-<Avatar className="size-8">
-  <AvatarImage src={url} alt="User" />
-  <AvatarFallback>ER</AvatarFallback>
-</Avatar>;
-
-{
-  /* Medium - 48px */
-}
-<Avatar className="size-12">
-  <AvatarImage src={url} alt="User" />
-  <AvatarFallback>ML</AvatarFallback>
-</Avatar>;
-
-{
-  /* Large - 64px */
-}
-<Avatar className="size-16">
-  <AvatarImage src={url} alt="User" />
-  <AvatarFallback className="text-lg">VC</AvatarFallback>
-</Avatar>;
-
-{
-  /* Extra Large - 80px */
-}
-<Avatar className="size-20">
-  <AvatarImage src={url} alt="User" />
-  <AvatarFallback className="text-xl">NJ</AvatarFallback>
-</Avatar>;
-```
-
-**Nota**: Ajusta el tamaño del texto del fallback según el tamaño del avatar para mantener proporciones.
-
-### Tamaño Personalizado
-
-```tsx
-<Avatar className="h-24 w-24">
-  <AvatarImage src={url} alt="User" />
-  <AvatarFallback className="text-2xl">AB</AvatarFallback>
-</Avatar>
-```
-
-## Formas Personalizadas
-
-### Avatar Cuadrado
-
-```tsx
-{
-  /* Rounded large */
-}
-<Avatar className="rounded-lg">
-  <AvatarImage src={url} alt="User" />
-  <AvatarFallback>CN</AvatarFallback>
-</Avatar>;
-
-{
-  /* Rounded medium */
-}
-<Avatar className="rounded-md">
-  <AvatarImage src={url} alt="User" />
-  <AvatarFallback>ER</AvatarFallback>
-</Avatar>;
-
-{
-  /* Rounded small */
-}
-<Avatar className="rounded-sm">
-  <AvatarImage src={url} alt="User" />
-  <AvatarFallback>ML</AvatarFallback>
-</Avatar>;
-
-{
-  /* Completamente cuadrado */
-}
-<Avatar className="rounded-none">
-  <AvatarFallback>SQ</AvatarFallback>
-</Avatar>;
-```
-
-**Uso**: Avatares cuadrados son comunes para logos de empresas o aplicaciones.
-
-## Patrones Avanzados
-
-### Grupo de Avatares (Overlapping)
-
-Para mostrar múltiples usuarios con solapamiento:
-
-```tsx
-<div className="flex -space-x-2">
-  <Avatar className="ring-2 ring-background">
-    <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
-    <AvatarFallback>CN</AvatarFallback>
-  </Avatar>
-  <Avatar className="ring-2 ring-background">
-    <AvatarImage src="https://github.com/evilrabbit.png" alt="@evilrabbit" />
-    <AvatarFallback>ER</AvatarFallback>
-  </Avatar>
-  <Avatar className="ring-2 ring-background">
-    <AvatarImage src="https://github.com/maxleiter.png" alt="@maxleiter" />
-    <AvatarFallback>ML</AvatarFallback>
-  </Avatar>
-  <Avatar className="ring-2 ring-background bg-muted">
-    <AvatarFallback>+2</AvatarFallback>
-  </Avatar>
-</div>
-```
-
-**Técnicas**:
-
-- `-space-x-2`: Espacio negativo para solapar
-- `ring-2 ring-background`: Borde blanco para separación visual
-- Último avatar muestra contador "+N" para usuarios adicionales
-
-### Avatar con Tooltip
-
-Para mostrar información adicional al hover:
-
-```tsx
-import {
-  Tooltip,
-  TooltipContent,
-  TooltipProvider,
-  TooltipTrigger,
-} from "@adamosuiteservices/ui/tooltip";
-
-<TooltipProvider>
-  <Tooltip>
-    <TooltipTrigger asChild>
-      <Avatar className="cursor-pointer">
-        <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
-        <AvatarFallback>CN</AvatarFallback>
-      </Avatar>
-    </TooltipTrigger>
-    <TooltipContent>
-      <p>shadcn - UI Engineer</p>
-    </TooltipContent>
-  </Tooltip>
-</TooltipProvider>;
-```
-
-**Nota**: Agrega `cursor-pointer` para indicar interactividad.
-
-### Card de Perfil de Usuario
-
-Avatar como parte de un perfil completo:
-
-```tsx
-import { Badge } from "@adamosuiteservices/ui/badge";
-import { Button } from "@adamosuiteservices/ui/button";
-
-<div className="flex items-center gap-4 p-6 rounded-lg border max-w-md">
-  <Avatar className="size-16">
-    <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
-    <AvatarFallback className="text-lg">CN</AvatarFallback>
-  </Avatar>
-  <div className="flex-1">
-    <h3 className="text-lg font-semibold">Colin Northcott</h3>
-    <p className="text-sm text-muted-foreground">@shadcn • UI Engineer</p>
-    <div className="flex gap-2 mt-2">
-      <Badge variant="secondary">React</Badge>
-      <Badge variant="secondary">TypeScript</Badge>
-    </div>
-  </div>
-  <Button size="sm">Follow</Button>
-</div>;
-```
-
-### Sistema de Comentarios
-
-Avatares en un layout de conversación:
-
-```tsx
-const comments = [
-  {
-    id: 1,
-    author: "John Doe",
-    avatar: "https://github.com/shadcn.png",
-    fallback: "JD",
-    time: "2 hours ago",
-    content:
-      "This looks great! Really excited to see this feature in production.",
-  },
-  // ... más comentarios
-];
-
-<div className="space-y-4 max-w-2xl">
-  {comments.map((comment) => (
-    <div key={comment.id} className="flex gap-3">
-      <Avatar>
-        {comment.avatar && (
-          <AvatarImage src={comment.avatar} alt={comment.author} />
-        )}
-        <AvatarFallback>{comment.fallback}</AvatarFallback>
-      </Avatar>
-      <div className="flex-1 space-y-1">
-        <div className="flex items-center gap-2">
-          <span className="text-sm font-medium">{comment.author}</span>
-          <span className="text-xs text-muted-foreground">{comment.time}</span>
-        </div>
-        <p className="text-sm">{comment.content}</p>
-      </div>
-    </div>
-  ))}
-</div>;
-```
-
-### Avatar con Indicador de Estado
-
-Para mostrar estado online/offline/busy:
-
-```tsx
-<div className="relative inline-block">
-  <Avatar>
-    <AvatarImage src={url} alt="User" />
-    <AvatarFallback>JD</AvatarFallback>
-  </Avatar>
-  {/* Indicador de estado */}
-  <span className="absolute bottom-0 right-0 block h-3 w-3 rounded-full bg-green-500 ring-2 ring-background" />
-</div>
-```
-
-**Variantes de estado**:
-
-- `bg-green-500`: Online
-- `bg-gray-400`: Offline
-- `bg-yellow-500`: Away/Idle
-- `bg-red-500`: Busy/Do Not Disturb
-
-### Avatar con Badge
-
-Para notificaciones o roles:
-
-```tsx
-import { Badge } from "@adamosuiteservices/ui/badge";
-
-<div className="relative inline-block">
-  <Avatar className="size-12">
-    <AvatarImage src={url} alt="User" />
-    <AvatarFallback>AD</AvatarFallback>
-  </Avatar>
-  <Badge
-    variant="destructive"
-    className="absolute -top-1 -right-1 h-5 w-5 rounded-full p-0 flex items-center justify-center text-xs"
-  >
-    5
-  </Badge>
-</div>;
-```
-
-### Avatar con Icono de Fallback
-
-Para usuarios sin nombre o genéricos:
-
-```tsx
-import { UserIcon } from "lucide-react";
-
-<Avatar>
-  <AvatarImage src={url} alt="User" />
-  <AvatarFallback>
-    <UserIcon className="h-4 w-4" />
-  </AvatarFallback>
-</Avatar>;
-```
-
-## Casos de Uso Comunes
-
-### Lista de Miembros del Equipo
-
-```tsx
-const team = [
-  { name: "John Doe", image: url1, initials: "JD" },
-  { name: "Jane Smith", image: url2, initials: "JS" },
-  // ...
-];
-
-<div className="grid grid-cols-3 gap-4">
-  {team.map((member) => (
-    <div key={member.name} className="flex flex-col items-center gap-2">
-      <Avatar className="size-16">
-        <AvatarImage src={member.image} alt={member.name} />
-        <AvatarFallback className="text-lg">{member.initials}</AvatarFallback>
-      </Avatar>
-      <span className="text-sm font-medium">{member.name}</span>
-    </div>
-  ))}
-</div>;
-```
-
-### Chat de Mensajería
-
-```tsx
-<div className="flex items-start gap-3">
-  <Avatar>
-    <AvatarImage src={senderAvatar} alt={senderName} />
-    <AvatarFallback>{senderInitials}</AvatarFallback>
-  </Avatar>
-  <div className="flex-1">
-    <div className="flex items-center gap-2">
-      <span className="font-medium text-sm">{senderName}</span>
-      <span className="text-xs text-muted-foreground">{timestamp}</span>
-    </div>
-    <p className="text-sm mt-1">{messageContent}</p>
-  </div>
-</div>
-```
-
-### Selector de Usuario
-
-```tsx
-<div className="flex items-center gap-3 p-2 rounded-lg hover:bg-muted cursor-pointer">
-  <Avatar className="size-10">
-    <AvatarImage src={userAvatar} alt={userName} />
-    <AvatarFallback>{userInitials}</AvatarFallback>
-  </Avatar>
-  <div className="flex-1">
-    <p className="text-sm font-medium">{userName}</p>
-    <p className="text-xs text-muted-foreground">{userEmail}</p>
-  </div>
-</div>
-```
-
-## Mejores Prácticas
-
-### Generación de Iniciales
-
-```typescript
-function getInitials(name: string): string {
-  return name
-    .split(" ")
-    .map((part) => part[0])
-    .join("")
-    .toUpperCase()
-    .slice(0, 2);
-}
-
-// Uso
-<AvatarFallback>{getInitials("John Doe")}</AvatarFallback>; // "JD"
-```
-
-### Prop alt Descriptiva
-
-```tsx
-// ✅ Correcto - descriptivo
-<AvatarImage src={url} alt="John Doe" />
-<AvatarImage src={url} alt="@johndoe profile picture" />
-
-// ❌ Incorrecto - genérico
-<AvatarImage src={url} alt="avatar" />
-<AvatarImage src={url} alt="user" />
-```
-
-### Consistencia de Tamaños
-
-Mantén tamaños consistentes por contexto:
-
-- **Listas pequeñas**: `size-8` (32px)
-- **Perfiles**: `size-16` (64px)
-- **Headers/Nav**: `size-10` (40px)
-- **Comentarios**: `size-8` o `size-10`
-- **Grupos**: `size-8` o más pequeños
-
-### Colores de Fallback Personalizados
-
-```tsx
-<Avatar>
-  <AvatarImage src={url} alt="User" />
-  <AvatarFallback className="bg-blue-500 text-white">AB</AvatarFallback>
-</Avatar>
-```
-
-**Patrón común**: Asignar colores basados en el nombre del usuario:
-
-```typescript
-function getAvatarColor(name: string): string {
-  const colors = [
-    "bg-red-500",
-    "bg-blue-500",
-    "bg-green-500",
-    "bg-yellow-500",
-    "bg-purple-500",
-  ];
-  const index = name.charCodeAt(0) % colors.length;
-  return colors[index];
-}
-```
-
-## Notas de Implementación
-
-- Basado en Radix UI Avatar primitives
-- Lazy loading de imágenes por defecto
-- Fallback se muestra automáticamente en error de carga
-- `aspect-square` mantiene proporción 1:1
-- `overflow-hidden` con `rounded-full` crea forma circular
-- `shrink-0` evita que el avatar se encoja en layouts flex
-- Sistema de slots con `data-slot` para composición
-- Tamaño por defecto: 32x32px (`size-8`)
-
-## Accesibilidad
-
-- ✅ **SIEMPRE** incluye prop `alt` en `AvatarImage` con texto descriptivo
-- ✅ Radix UI maneja ARIA attributes automáticamente
-- ✅ El fallback es accesible por screen readers
-- ✅ Usa texto real en fallback (no iconos decorativos solos) cuando sea posible
-- ✅ Si el avatar es clickeable, agrégalo dentro de un `<button>` o `<a>` con aria-label
-- ⚠️ No uses solo color para indicar estado (combina con iconos/texto)
-
-### Avatar Clickeable Accesible
-
-```tsx
-<button
-  type="button"
-  aria-label="View John Doe's profile"
-  className="rounded-full focus:outline-none focus:ring-2 focus:ring-offset-2"
->
-  <Avatar>
-    <AvatarImage src={url} alt="John Doe" />
-    <AvatarFallback>JD</AvatarFallback>
-  </Avatar>
-</button>
-```
-
-## Referencias
-
-- Radix UI Avatar: https://www.radix-ui.com/primitives/docs/components/avatar
-- shadcn/ui Avatar: https://ui.shadcn.com/docs/components/avatar
-- WCAG Image Alternative Text: https://www.w3.org/WAI/tutorials/images/
+# Avatar Component
+
+## Descripción
+
+Componente para mostrar **imágenes de perfil de usuario** con sistema de fallback automático a iniciales o iconos cuando la imagen no está disponible o falla al cargar. Basado en Radix UI Avatar primitives con carga lazy, estado de error manejado, y diseño circular responsive.
+
+## Características
+
+- ✅ Fallback automático si la imagen falla
+- ✅ Carga lazy de imágenes
+- ✅ Soporte para iniciales o iconos como fallback
+- ✅ Tamaños personalizables
+- ✅ Formas: circular (default) o cuadrado/rectangular
+- ✅ Grupos de avatares con solapamiento
+- ✅ Integración con Tooltip
+- ✅ Accesibilidad: alt text y ARIA
+- ✅ Diseño responsive y flexible
+
+## Importación
+
+```typescript
+import {
+  Avatar,
+  AvatarImage,
+  AvatarFallback,
+} from "@adamosuiteservices/ui/avatar";
+import { Icon } from "@adamosuiteservices/ui/icon"; // For icon fallbacks
+```
+
+## Uso Básico
+
+### Avatar con Imagen y Fallback
+
+```tsx
+<Avatar>
+  <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+  <AvatarFallback>CN</AvatarFallback>
+</Avatar>
+```
+
+**Comportamiento**:
+
+1. Intenta cargar la imagen del `src`
+2. Si falla o no carga, muestra el `AvatarFallback` automáticamente
+3. Radix UI maneja el estado de carga internamente
+
+### Solo Fallback (Sin Imagen)
+
+```tsx
+<Avatar>
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+```
+
+**Uso**: Cuando no hay imagen disponible o solo quieres mostrar iniciales.
+
+### Imagen Rota (Graceful Degradation)
+
+```tsx
+<Avatar>
+  <AvatarImage src="https://broken-link.com/image.jpg" alt="Broken" />
+  <AvatarFallback>BK</AvatarFallback>
+</Avatar>
+```
+
+**Resultado**: Automáticamente muestra "BK" si la imagen no carga.
+
+## Props
+
+### Avatar (Root)
+
+Contenedor principal del avatar.
+
+| Prop      | Tipo                       | Descripción                 |
+| --------- | -------------------------- | --------------------------- |
+| className | `string`                   | Clases CSS adicionales      |
+| ...props  | Props de Radix Avatar.Root | Props nativas del primitivo |
+
+**Estilos por defecto**:
+
+- `size-8`: 2rem (32x32px) - tamaño base
+- `rounded-full`: Forma circular
+- `shrink-0`: No se encoge en flex/grid
+- `overflow-hidden`: Recorta contenido fuera del círculo
+- `relative`: Para posicionamiento interno
+- `flex`: Contenedor flex
+
+**Atributos automáticos**:
+
+- `data-slot="avatar"`: Para identificación interna
+
+### AvatarImage
+
+Imagen del avatar con carga lazy.
+
+| Prop      | Tipo                        | Descripción                                         |
+| --------- | --------------------------- | --------------------------------------------------- |
+| src       | `string`                    | **Requerido**. URL de la imagen                     |
+| alt       | `string`                    | **Requerido**. Texto alternativo para accesibilidad |
+| className | `string`                    | Clases CSS adicionales                              |
+| ...props  | Props de Radix Avatar.Image | Props nativas del primitivo                         |
+
+**Estilos aplicados**:
+
+- `aspect-square`: Mantiene aspecto cuadrado
+- `size-full`: Ocupa todo el contenedor (100% width/height)
+
+**Comportamiento**:
+
+- Carga lazy automática
+- Emite eventos `onLoadingStatusChange`
+- Estados: `idle`, `loading`, `loaded`, `error`
+- Si falla, muestra AvatarFallback automáticamente
+
+**Atributos automáticos**:
+
+- `data-slot="avatar-image"`: Para identificación interna
+
+### AvatarFallback
+
+Contenido mostrado cuando la imagen no carga o no existe.
+
+| Prop      | Tipo                           | Descripción                                            |
+| --------- | ------------------------------ | ------------------------------------------------------ |
+| children  | `ReactNode`                    | **Requerido**. Iniciales, icono, o cualquier contenido |
+| delayMs   | `number`                       | Delay antes de mostrar el fallback (ms)                |
+| className | `string`                       | Clases CSS adicionales                                 |
+| ...props  | Props de Radix Avatar.Fallback | Props nativas del primitivo                            |
+
+**Estilos por defecto**:
+
+- `bg-muted`: Fondo gris claro
+- `rounded-full`: Forma circular (coincide con el contenedor)
+- `size-full`: Ocupa todo el espacio
+- `flex items-center justify-center`: Centra el contenido
+
+**Contenido común**:
+
+- Iniciales (2 letras): "JD", "AB", "CN"
+- Iconos: `<Icon symbol="person" />`, `<Icon symbol="account_circle" />`
+- Texto: "+5" (para grupos)
+
+**Atributos automáticos**:
+
+- `data-slot="avatar-fallback"`: Para identificación interna
+
+## Tamaños Personalizados
+
+El tamaño por defecto es `size-8` (32px). Personaliza con className:
+
+### Tamaños Predefinidos
+
+```tsx
+{
+  /* Extra Small - 24px */
+}
+<Avatar className="size-6">
+  <AvatarImage src={url} alt="User" />
+  <AvatarFallback className="text-xs">CN</AvatarFallback>
+</Avatar>;
+
+{
+  /* Small - 32px (default) */
+}
+<Avatar className="size-8">
+  <AvatarImage src={url} alt="User" />
+  <AvatarFallback>ER</AvatarFallback>
+</Avatar>;
+
+{
+  /* Medium - 48px */
+}
+<Avatar className="size-12">
+  <AvatarImage src={url} alt="User" />
+  <AvatarFallback>ML</AvatarFallback>
+</Avatar>;
+
+{
+  /* Large - 64px */
+}
+<Avatar className="size-16">
+  <AvatarImage src={url} alt="User" />
+  <AvatarFallback className="text-lg">VC</AvatarFallback>
+</Avatar>;
+
+{
+  /* Extra Large - 80px */
+}
+<Avatar className="size-20">
+  <AvatarImage src={url} alt="User" />
+  <AvatarFallback className="text-xl">NJ</AvatarFallback>
+</Avatar>;
+```
+
+**Nota**: Ajusta el tamaño del texto del fallback según el tamaño del avatar para mantener proporciones.
+
+### Tamaño Personalizado
+
+```tsx
+<Avatar className="h-24 w-24">
+  <AvatarImage src={url} alt="User" />
+  <AvatarFallback className="text-2xl">AB</AvatarFallback>
+</Avatar>
+```
+
+## Formas Personalizadas
+
+### Avatar Cuadrado
+
+```tsx
+{
+  /* Rounded large */
+}
+<Avatar className="rounded-lg">
+  <AvatarImage src={url} alt="User" />
+  <AvatarFallback>CN</AvatarFallback>
+</Avatar>;
+
+{
+  /* Rounded medium */
+}
+<Avatar className="rounded-md">
+  <AvatarImage src={url} alt="User" />
+  <AvatarFallback>ER</AvatarFallback>
+</Avatar>;
+
+{
+  /* Rounded small */
+}
+<Avatar className="rounded-sm">
+  <AvatarImage src={url} alt="User" />
+  <AvatarFallback>ML</AvatarFallback>
+</Avatar>;
+
+{
+  /* Completamente cuadrado */
+}
+<Avatar className="rounded-none">
+  <AvatarFallback>SQ</AvatarFallback>
+</Avatar>;
+```
+
+**Uso**: Avatares cuadrados son comunes para logos de empresas o aplicaciones.
+
+## Patrones Avanzados
+
+### Grupo de Avatares (Overlapping)
+
+Para mostrar múltiples usuarios con solapamiento:
+
+```tsx
+<div className="flex -space-x-2">
+  <Avatar className="ring-2 ring-background">
+    <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+    <AvatarFallback>CN</AvatarFallback>
+  </Avatar>
+  <Avatar className="ring-2 ring-background">
+    <AvatarImage src="https://github.com/evilrabbit.png" alt="@evilrabbit" />
+    <AvatarFallback>ER</AvatarFallback>
+  </Avatar>
+  <Avatar className="ring-2 ring-background">
+    <AvatarImage src="https://github.com/maxleiter.png" alt="@maxleiter" />
+    <AvatarFallback>ML</AvatarFallback>
+  </Avatar>
+  <Avatar className="ring-2 ring-background bg-muted">
+    <AvatarFallback>+2</AvatarFallback>
+  </Avatar>
+</div>
+```
+
+**Técnicas**:
+
+- `-space-x-2`: Espacio negativo para solapar
+- `ring-2 ring-background`: Borde blanco para separación visual
+- Último avatar muestra contador "+N" para usuarios adicionales
+
+### Avatar con Tooltip
+
+Para mostrar información adicional al hover:
+
+```tsx
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@adamosuiteservices/ui/tooltip";
+
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <Avatar className="cursor-pointer">
+        <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+        <AvatarFallback>CN</AvatarFallback>
+      </Avatar>
+    </TooltipTrigger>
+    <TooltipContent>
+      <p>shadcn - UI Engineer</p>
+    </TooltipContent>
+  </Tooltip>
+</TooltipProvider>;
+```
+
+**Nota**: Agrega `cursor-pointer` para indicar interactividad.
+
+### Card de Perfil de Usuario
+
+Avatar como parte de un perfil completo:
+
+```tsx
+import { Badge } from "@adamosuiteservices/ui/badge";
+import { Button } from "@adamosuiteservices/ui/button";
+
+<div className="flex items-center gap-4 p-6 rounded-lg border max-w-md">
+  <Avatar className="size-16">
+    <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+    <AvatarFallback className="text-lg">CN</AvatarFallback>
+  </Avatar>
+  <div className="flex-1">
+    <h3 className="text-lg font-semibold">Colin Northcott</h3>
+    <p className="text-sm text-muted-foreground">@shadcn • UI Engineer</p>
+    <div className="flex gap-2 mt-2">
+      <Badge variant="secondary">React</Badge>
+      <Badge variant="secondary">TypeScript</Badge>
+    </div>
+  </div>
+  <Button size="sm">Follow</Button>
+</div>;
+```
+
+### Sistema de Comentarios
+
+Avatares en un layout de conversación:
+
+```tsx
+const comments = [
+  {
+    id: 1,
+    author: "John Doe",
+    avatar: "https://github.com/shadcn.png",
+    fallback: "JD",
+    time: "2 hours ago",
+    content:
+      "This looks great! Really excited to see this feature in production.",
+  },
+  // ... más comentarios
+];
+
+<div className="space-y-4 max-w-2xl">
+  {comments.map((comment) => (
+    <div key={comment.id} className="flex gap-3">
+      <Avatar>
+        {comment.avatar && (
+          <AvatarImage src={comment.avatar} alt={comment.author} />
+        )}
+        <AvatarFallback>{comment.fallback}</AvatarFallback>
+      </Avatar>
+      <div className="flex-1 space-y-1">
+        <div className="flex items-center gap-2">
+          <span className="text-sm font-medium">{comment.author}</span>
+          <span className="text-xs text-muted-foreground">{comment.time}</span>
+        </div>
+        <p className="text-sm">{comment.content}</p>
+      </div>
+    </div>
+  ))}
+</div>;
+```
+
+### Avatar con Indicador de Estado
+
+Para mostrar estado online/offline/busy:
+
+```tsx
+<div className="relative inline-block">
+  <Avatar>
+    <AvatarImage src={url} alt="User" />
+    <AvatarFallback>JD</AvatarFallback>
+  </Avatar>
+  {/* Indicador de estado */}
+  <span className="absolute bottom-0 right-0 block h-3 w-3 rounded-full bg-green-500 ring-2 ring-background" />
+</div>
+```
+
+**Variantes de estado**:
+
+- `bg-green-500`: Online
+- `bg-gray-400`: Offline
+- `bg-yellow-500`: Away/Idle
+- `bg-red-500`: Busy/Do Not Disturb
+
+### Avatar con Badge
+
+Para notificaciones o roles:
+
+```tsx
+import { Badge } from "@adamosuiteservices/ui/badge";
+
+<div className="relative inline-block">
+  <Avatar className="size-12">
+    <AvatarImage src={url} alt="User" />
+    <AvatarFallback>AD</AvatarFallback>
+  </Avatar>
+  <Badge
+    variant="destructive"
+    className="absolute -top-1 -right-1 h-5 w-5 rounded-full p-0 flex items-center justify-center text-xs"
+  >
+    5
+  </Badge>
+</div>;
+```
+
+### Avatar con Icono de Fallback
+
+Para usuarios sin nombre o genéricos:
+
+```tsx
+<Avatar>
+  <AvatarImage src={url} alt="User" />
+  <AvatarFallback>
+    <Icon symbol="person" />
+  </AvatarFallback>
+</Avatar>
+```
+
+## Casos de Uso Comunes
+
+### Lista de Miembros del Equipo
+
+```tsx
+const team = [
+  { name: "John Doe", image: url1, initials: "JD" },
+  { name: "Jane Smith", image: url2, initials: "JS" },
+  // ...
+];
+
+<div className="grid grid-cols-3 gap-4">
+  {team.map((member) => (
+    <div key={member.name} className="flex flex-col items-center gap-2">
+      <Avatar className="size-16">
+        <AvatarImage src={member.image} alt={member.name} />
+        <AvatarFallback className="text-lg">{member.initials}</AvatarFallback>
+      </Avatar>
+      <span className="text-sm font-medium">{member.name}</span>
+    </div>
+  ))}
+</div>;
+```
+
+### Chat de Mensajería
+
+```tsx
+<div className="flex items-start gap-3">
+  <Avatar>
+    <AvatarImage src={senderAvatar} alt={senderName} />
+    <AvatarFallback>{senderInitials}</AvatarFallback>
+  </Avatar>
+  <div className="flex-1">
+    <div className="flex items-center gap-2">
+      <span className="font-medium text-sm">{senderName}</span>
+      <span className="text-xs text-muted-foreground">{timestamp}</span>
+    </div>
+    <p className="text-sm mt-1">{messageContent}</p>
+  </div>
+</div>
+```
+
+### Selector de Usuario
+
+```tsx
+<div className="flex items-center gap-3 p-2 rounded-lg hover:bg-muted cursor-pointer">
+  <Avatar className="size-10">
+    <AvatarImage src={userAvatar} alt={userName} />
+    <AvatarFallback>{userInitials}</AvatarFallback>
+  </Avatar>
+  <div className="flex-1">
+    <p className="text-sm font-medium">{userName}</p>
+    <p className="text-xs text-muted-foreground">{userEmail}</p>
+  </div>
+</div>
+```
+
+## Mejores Prácticas
+
+### Generación de Iniciales
+
+```typescript
+function getInitials(name: string): string {
+  return name
+    .split(" ")
+    .map((part) => part[0])
+    .join("")
+    .toUpperCase()
+    .slice(0, 2);
+}
+
+// Uso
+<AvatarFallback>{getInitials("John Doe")}</AvatarFallback>; // "JD"
+```
+
+### Prop alt Descriptiva
+
+```tsx
+// ✅ Correcto - descriptivo
+<AvatarImage src={url} alt="John Doe" />
+<AvatarImage src={url} alt="@johndoe profile picture" />
+
+// ❌ Incorrecto - genérico
+<AvatarImage src={url} alt="avatar" />
+<AvatarImage src={url} alt="user" />
+```
+
+### Consistencia de Tamaños
+
+Mantén tamaños consistentes por contexto:
+
+- **Listas pequeñas**: `size-8` (32px)
+- **Perfiles**: `size-16` (64px)
+- **Headers/Nav**: `size-10` (40px)
+- **Comentarios**: `size-8` o `size-10`
+- **Grupos**: `size-8` o más pequeños
+
+### Colores de Fallback Personalizados
+
+```tsx
+<Avatar>
+  <AvatarImage src={url} alt="User" />
+  <AvatarFallback className="bg-blue-500 text-white">AB</AvatarFallback>
+</Avatar>
+```
+
+**Patrón común**: Asignar colores basados en el nombre del usuario:
+
+```typescript
+function getAvatarColor(name: string): string {
+  const colors = [
+    "bg-red-500",
+    "bg-blue-500",
+    "bg-green-500",
+    "bg-yellow-500",
+    "bg-purple-500",
+  ];
+  const index = name.charCodeAt(0) % colors.length;
+  return colors[index];
+}
+```
+
+## Notas de Implementación
+
+- Basado en Radix UI Avatar primitives
+- Lazy loading de imágenes por defecto
+- Fallback se muestra automáticamente en error de carga
+- `aspect-square` mantiene proporción 1:1
+- `overflow-hidden` con `rounded-full` crea forma circular
+- `shrink-0` evita que el avatar se encoja en layouts flex
+- Sistema de slots con `data-slot` para composición
+- Tamaño por defecto: 32x32px (`size-8`)
+
+## Accesibilidad
+
+- ✅ **SIEMPRE** incluye prop `alt` en `AvatarImage` con texto descriptivo
+- ✅ Radix UI maneja ARIA attributes automáticamente
+- ✅ El fallback es accesible por screen readers
+- ✅ Usa texto real en fallback (no iconos decorativos solos) cuando sea posible
+- ✅ Si el avatar es clickeable, agrégalo dentro de un `<button>` o `<a>` con aria-label
+- ⚠️ No uses solo color para indicar estado (combina con iconos/texto)
+
+### Avatar Clickeable Accesible
+
+```tsx
+<button
+  type="button"
+  aria-label="View John Doe's profile"
+  className="rounded-full focus:outline-none focus:ring-2 focus:ring-offset-2"
+>
+  <Avatar>
+    <AvatarImage src={url} alt="John Doe" />
+    <AvatarFallback>JD</AvatarFallback>
+  </Avatar>
+</button>
+```
+
+## Referencias
+
+- Radix UI Avatar: https://www.radix-ui.com/primitives/docs/components/avatar
+- shadcn/ui Avatar: https://ui.shadcn.com/docs/components/avatar
+- WCAG Image Alternative Text: https://www.w3.org/WAI/tutorials/images/