@etus/ui 0.1.0

package/src/components/primitives/Avatar/README.md

@@ -0,0 +1,1174 @@
+# Avatar
+
+## Visão Geral
+
+O **Avatar** e um componente compound do Design System ETUS usado para representar usuarios, entidades ou objetos atraves de imagens ou iniciais. Como elemento atomico, serve de base para composicoes como listas de usuarios, cabecalhos de perfil e indicadores de presenca.
+
+### Casos de Uso
+
+- Representacao visual de usuarios em listas e comentarios
+- Cabecalhos de perfil e menus de conta
+- Indicadores de autoria em cards e posts
+- Grupos de colaboradores (avatar stacks)
+- Placeholders enquanto imagens carregam
+
+### Classificacao
+
+**Categoria:** Atom (Primitivo)
+**Dependencias:** `@radix-ui/react-avatar`
+
+---
+
+## Design Specs
+
+### Estrutura Compound
+
+O Avatar utiliza o padrao compound component com multiplas partes:
+
+| Componente         | Slot                 | Descricao                                           |
+| ------------------ | -------------------- | --------------------------------------------------- |
+| `Avatar`           | `avatar`             | Container raiz, define tamanho e forma              |
+| `AvatarImage`      | `avatar-image`       | Imagem do avatar, carrega assincronamente           |
+| `AvatarFallback`   | `avatar-fallback`    | Conteudo exibido enquanto imagem carrega ou em erro |
+| `AvatarStatus`     | `avatar-status`      | Indicador de presenca (online/offline/busy/away)    |
+| `AvatarBadge`      | `avatar-badge`       | Badge de verificacao (company/verified)             |
+| `AvatarGroup`      | `avatar-group`       | Agrupa multiplos avatares com overlap               |
+| `AvatarLabelGroup` | `avatar-label-group` | Avatar com nome e descricao                         |
+| `AvatarAddButton`  | `avatar-add-button`  | Botao para adicionar usuarios                       |
+
+### Tamanhos (via prop `size`)
+
+O componente suporta tamanhos pre-definidos via prop `size`:
+
+| Tamanho     | Prop             | Dimensao | Uso                       |
+| ----------- | ---------------- | -------- | ------------------------- |
+| Extra Small | `size="xs"`      | 24px     | Listas compactas, badges  |
+| Small       | `size="sm"`      | 32px     | Comentarios               |
+| Default     | `size="default"` | 40px     | **Padrao**, cards, listas |
+| Large       | `size="lg"`      | 48px     | Headers de perfil         |
+| Extra Large | `size="xl"`      | 56px     | Paginas de perfil         |
+| 2X Large    | `size="2xl"`     | 64px     | Hero sections             |
+
+### Formas (via prop `shape`)
+
+| Forma  | Prop             | Uso                  |
+| ------ | ---------------- | -------------------- |
+| Circle | `shape="circle"` | **Padrao**, usuarios |
+| Square | `shape="square"` | Organizacoes, apps   |
+
+### Variantes
+
+| Variante        | Prop             | Descricao                                                        |
+| --------------- | ---------------- | ---------------------------------------------------------------- |
+| Bordered        | `bordered`       | Borda branca (ring-2 ring-background) para grupos                |
+| Interactive     | `interactive`    | Hover scale + focus ring para avatares clicaveis                 |
+| Contrast Border | `contrastBorder` | Borda sutil (0.5-0.75px) para definir bordas em fundos similares |
+
+### Estados
+
+| Estado   | Comportamento  | Implementacao         |
+| -------- | -------------- | --------------------- |
+| Loading  | Exibe Fallback | Automatico via Radix  |
+| Loaded   | Exibe Image    | Transicao suave       |
+| Error    | Exibe Fallback | Automatico via Radix  |
+| Fallback | Iniciais/Icone | Conteudo customizavel |
+
+### Padrão de Tokens com Tailwind v4
+
+O Avatar usa tokens de componente definidos em `@etus/tokens`. Estes tokens são CSS custom properties que devem ser usadas com a sintaxe correta do Tailwind v4.
+
+#### Tokens Disponíveis
+
+| Token                              | Valor            | Uso                         |
+| ---------------------------------- | ---------------- | --------------------------- |
+| `--avatar-size-xs`                 | 24px             | Tamanho extra pequeno       |
+| `--avatar-size-sm`                 | 32px             | Tamanho pequeno             |
+| `--avatar-size-default`            | 40px             | Tamanho padrão              |
+| `--avatar-size-lg`                 | 48px             | Tamanho grande              |
+| `--avatar-size-xl`                 | 56px             | Tamanho extra grande        |
+| `--avatar-size-2xl`                | 64px             | Tamanho 2x grande           |
+| `--avatar-text-xs`                 | 0.75rem          | Fonte para xs               |
+| `--avatar-text-sm`                 | 0.875rem         | Fonte para sm               |
+| `--avatar-text-default`            | 1rem             | Fonte para default          |
+| `--avatar-text-lg`                 | 1.125rem         | Fonte para lg               |
+| `--avatar-text-xl`                 | 1.25rem          | Fonte para xl               |
+| `--avatar-text-2xl`                | 1.5rem           | Fonte para 2xl              |
+| `--avatar-radius-circle`           | 9999px           | Raio circular               |
+| `--avatar-radius-square`           | 0.375rem         | Raio quadrado               |
+| `--avatar-border-contrast`         | rgba(0,0,0,0.08) | Borda de contraste          |
+| `--avatar-fallback-bg-default`     | OKLCH            | Fundo fallback default      |
+| `--avatar-fallback-bg-primary`     | OKLCH            | Fundo fallback primary      |
+| `--avatar-fallback-bg-secondary`   | OKLCH            | Fundo fallback secondary    |
+| `--avatar-fallback-bg-success`     | OKLCH            | Fundo fallback success      |
+| `--avatar-fallback-bg-warning`     | OKLCH            | Fundo fallback warning      |
+| `--avatar-fallback-bg-destructive` | OKLCH            | Fundo fallback destructive  |
+| `--avatar-fallback-text-*`         | OKLCH            | Texto para cada colorScheme |
+
+#### Sintaxe Tailwind v4
+
+```tsx
+// ✅ CORRETO - Dimensões (não precisam de type hint)
+size-[var(--avatar-size-xs)]
+rounded-[var(--avatar-radius-circle)]
+
+// ✅ CORRETO - Font-size (precisa de length:)
+text-[length:var(--avatar-text-sm)]
+
+// ✅ CORRETO - Cores (precisam de color:)
+bg-[color:var(--avatar-fallback-bg-default)]
+text-[color:var(--avatar-fallback-text-default)]
+border-[color:var(--avatar-border-contrast)]
+
+// ❌ INCORRETO - Cores sem type hint
+bg-[var(--avatar-fallback-bg-default)]
+text-[var(--avatar-fallback-text-default)]
+
+// ❌ INCORRETO - Nunca usar hsl() com OKLCH
+bg-[hsl(var(--avatar-fallback-bg-default))]
+```
+
+#### Por que usar `color:` para cores?
+
+No Tailwind CSS v4, quando você usa valores arbitrários com CSS variables:
+
+1. **Dimensões** (`h-`, `w-`, `p-`, `m-`, `rounded-`, `size-`) funcionam sem type hint
+2. **Font-size** (`text-[length:...]`) precisa de `length:` para diferenciar de cor
+3. **Cores** (`bg-`, `text-` para cor, `border-`) precisam de `color:` para que o Tailwind interprete corretamente
+
+Os tokens de cor do Seven usam OKLCH e são valores completos, não precisam de função wrapper.
+
+### Tokens Semânticos (Status e Badge)
+
+Para componentes compostos como AvatarStatus e AvatarBadge, use tokens semânticos:
+
+```css
+/* Status */
+--success           /* Status online (verde) */
+--destructive       /* Status busy (vermelho) */
+--warning           /* Status away (amarelo) */
+--muted             /* Status offline (cinza) */
+
+/* Badge */
+--brius-500         /* Badge company (roxo brand) */
+--sevends-blue-600  /* Badge verified (azul brand) */
+```
+
+> **IMPORTANTE:** Nunca use cores hardcoded como `bg-green-500` ou `bg-blue-500`. Sempre use tokens para garantir consistência com o design system.
+
+### data-slot
+
+```html
+<span data-slot="avatar">
+  <img data-slot="avatar-image" />
+  <span data-slot="avatar-fallback">AB</span>
+</span>
+```
+
+---
+
+## API
+
+### Props - Avatar (Root)
+
+| Prop        | Tipo        | Padrao | Descricao                       |
+| ----------- | ----------- | ------ | ------------------------------- |
+| `className` | `string`    | -      | Classes CSS adicionais          |
+| `children`  | `ReactNode` | -      | AvatarImage e/ou AvatarFallback |
+
+> Herda todas as props de `React.ComponentProps<typeof AvatarPrimitive.Root>`
+
+### Props - AvatarImage
+
+| Prop                    | Tipo                                                           | Padrao | Descricao                                 |
+| ----------------------- | -------------------------------------------------------------- | ------ | ----------------------------------------- |
+| `src`                   | `string`                                                       | -      | URL da imagem                             |
+| `alt`                   | `string`                                                       | -      | Texto alternativo (obrigatorio para a11y) |
+| `className`             | `string`                                                       | -      | Classes CSS adicionais                    |
+| `onLoadingStatusChange` | `(status: 'idle' \| 'loading' \| 'loaded' \| 'error') => void` | -      | Callback de status                        |
+
+> Herda todas as props de `React.ComponentProps<typeof AvatarPrimitive.Image>`
+
+### Props - AvatarFallback
+
+| Prop        | Tipo        | Padrao | Descricao                              |
+| ----------- | ----------- | ------ | -------------------------------------- |
+| `delayMs`   | `number`    | -      | Delay antes de exibir fallback         |
+| `className` | `string`    | -      | Classes CSS adicionais                 |
+| `children`  | `ReactNode` | -      | Conteudo do fallback (iniciais, icone) |
+
+> Herda todas as props de `React.ComponentProps<typeof AvatarPrimitive.Fallback>`
+
+### Callbacks
+
+| Callback                | Componente  | Tipo               | Descricao                         |
+| ----------------------- | ----------- | ------------------ | --------------------------------- |
+| `onLoadingStatusChange` | AvatarImage | `(status) => void` | Notifica mudancas no carregamento |
+
+### TypeScript
+
+```typescript
+import * as AvatarPrimitive from "@radix-ui/react-avatar";
+
+// Props dos componentes
+type AvatarProps = React.ComponentProps<typeof AvatarPrimitive.Root>;
+type AvatarImageProps = React.ComponentProps<typeof AvatarPrimitive.Image>;
+type AvatarFallbackProps = React.ComponentProps<
+  typeof AvatarPrimitive.Fallback
+>;
+
+// Tipo para status de carregamento
+type ImageLoadingStatus = "idle" | "loading" | "loaded" | "error";
+```
+
+### Comparativo com Design Systems de Referencia
+
+#### Matriz de Features (14 Design Systems)
+
+| Feature           | ETUS | Shadcn | Radix | React Aria | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon | Blueprint |
+| ----------------- | :--: | :----: | :---: | :--------: | :----: | :-: | :-----: | :--: | :----: | :------: | :-----: | :----: | :----: | :-------: |
+| **Compound**      |  ✓   |   ✓    |   ✓   |     -      |   -    |  -  |    -    |  -   |   -    |    -     |    -    |   -    |   -    |     -     |
+| **Fallback auto** |  ✓   |   ✓    |   ✓   |     -      |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    -    |   ✓    |   ✓    |     -     |
+| **Sizes prop**    |  ✓   |   -    |   -   |     -      |   ✓    |  -  |    ✓    |  ✓   |   ✓    |    -     |    -    |   ✓    |   ✓    |     -     |
+| **Shape/radius**  |  ✓   |   ~    |   -   |     -      |   -    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    -    |   ✓    |   -    |     -     |
+| **Badge/Status**  |  ✓   |   -    |   -   |     -      |   -    |  -  |    ✓    |  ✓   |   -    |    -     |    -    |   ✓    |   -    |     -     |
+| **AvatarGroup**   |  ✓   |   -    |   -   |     -      |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |    -    |   ✓    |   -    |     -     |
+| **Loading state** |  ✓   |   ✓    |   ✓   |     -      |   -    |  -  |    -    |  ✓   |   ✓    |    -     |    -    |   -    |   ✓    |     -     |
+| **Initials auto** |  ✓   |   -    |   -   |     -      |   ✓    |  -  |    -    |  -   |   ✓    |    -     |    -    |   ✓    |   ✓    |     -     |
+| **Color scheme**  |  -   |   -    |   -   |     -      |   ✓    |  -  |    ✓    |  -   |   ✓    |    -     |    -    |   ✓    |   -    |     -     |
+| **data-slot**     |  ✓   |   ✓    |   -   |     -      |   -    |  -  |    -    |  -   |   ✓    |    -     |    -    |   -    |   -    |     -     |
+| **Bordered**      |  ✓   |   -    |   -   |     -      |   -    |  -  |    -    |  -   |   ✓    |    -     |    -    |   -    |   -    |     -     |
+| **Interactive**   |  ✓   |   -    |   -   |     -      |   -    |  -  |    -    |  -   |   ✓    |    -     |    -    |   -    |   -    |     -     |
+
+**Legenda:** ✓ = Suporte completo | ~ = Via className | - = Nao suportado
+
+#### Comparativo de Props por Design System
+
+| Prop           |   ETUS    | Chakra |    MUI    | Mantine |  AntD   | NextUI | Fluent  |
+| -------------- | :-------: | :----: | :-------: | :-----: | :-----: | :----: | :-----: |
+| `src`          |   Image   |   ✓    |     ✓     |    ✓    |    ✓    |   ✓    | `image` |
+| `alt`          |   Image   |   ✓    |     ✓     |    ✓    |    ✓    |   ✓    |    ✓    |
+| `name`         |     -     |   ✓    |     -     |    -    |    -    |   ✓    |    ✓    |
+| `size`         | className |   ✓    |     -     |    ✓    |    ✓    |   ✓    |    ✓    |
+| `radius`       | className |   -    | `variant` |    ✓    | `shape` |   ✓    | `shape` |
+| `color`        | className |   ✓    |     -     |    ✓    |    -    |   ✓    |    ✓    |
+| `bordered`     | className |   -    |     -     |    -    |    -    |   ✓    |    -    |
+| `fallback`     | children  |   ✓    |     ✓     |    ✓    | `icon`  |   ✓    |    ✓    |
+| `showFallback` |     -     |   -    |     -     |    -    |    -    |   ✓    |    -    |
+| `getInitials`  |     -     |   ✓    |     -     |    -    |    -    |   ✓    |    -    |
+
+#### Abordagens por Categoria
+
+**Headless/Primitivos (maxima flexibilidade):**
+
+- **Radix UI** - Compound component, loading states automaticos, zero estilos
+- **Headless UI** - Nao possui Avatar dedicado
+- **React Aria** - Nao possui Avatar dedicado
+
+**Styled/Opinionated (produtividade):**
+
+- **Chakra UI** - `name` prop gera iniciais, `colorScheme` automatico
+- **MUI** - Variantes `circular`/`rounded`/`square`, integracao com Badge
+- **Mantine** - `radius` e `color` granulares, `Avatar.Group` built-in
+- **Ant Design** - `shape`, `icon`, integracao com Badge e Tooltip
+
+**Hybrid (meio-termo):**
+
+- **Shadcn/ui** - Compound pattern, customizacao via className
+- **NextUI** - Props ergonomicas + Tailwind, `isBordered`, `isZoomed`
+- **ETUS** - Baseado em Shadcn, compound pattern, data-slot
+
+**Enterprise:**
+
+- **Fluent UI** - `presence` indicator, `activeAppearance`, tokens Microsoft
+- **Carbon** - IBM design, skeleton loading, focus states
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo      | Uso                       | Implementacao                  |
+| ------------- | ------------------------- | ------------------------------ |
+| `role="img"`  | Implicito no `<img>`      | Automatico                     |
+| `alt`         | Descricao da imagem       | **Obrigatorio** em AvatarImage |
+| `aria-label`  | Quando sem imagem         | Usar no Avatar root            |
+| `aria-hidden` | Para avatares decorativos | `aria-hidden="true"`           |
+
+### Texto Alternativo (alt)
+
+```tsx
+// ✓ CORRETO: Alt descritivo
+<AvatarImage src={url} alt="Foto de perfil de Maria Silva" />
+
+// ✓ CORRETO: Avatar decorativo
+<Avatar aria-hidden="true">
+  <AvatarImage src={url} alt="" />
+</Avatar>
+
+// ✗ INCORRETO: Alt generico
+<AvatarImage src={url} alt="avatar" />
+<AvatarImage src={url} alt="user" />
+```
+
+### Suporte a Teclado
+
+O Avatar nao e interativo por padrao. Quando usado como botao:
+
+| Tecla   | Acao                                   |
+| ------- | -------------------------------------- |
+| `Tab`   | Move foco para o avatar (se focusable) |
+| `Enter` | Ativa a acao (se botao)                |
+| `Space` | Ativa a acao (se botao)                |
+
+### Focus Management
+
+```tsx
+// Avatar como botao - adicionar focus styles
+<button className="rounded-full focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2">
+  <Avatar>
+    <AvatarImage src={url} alt="Abrir perfil de Maria" />
+    <AvatarFallback>MS</AvatarFallback>
+  </Avatar>
+</button>
+```
+
+### Contraste de Cores
+
+| Elemento      | Foreground           | Background | Ratio Minimo |
+| ------------- | -------------------- | ---------- | ------------ |
+| Fallback text | `--foreground`       | `--muted`  | >= 4.5:1     |
+| Fallback icon | `--muted-foreground` | `--muted`  | >= 3:1       |
+
+### Screen Readers
+
+- Sempre fornecer `alt` descritivo para AvatarImage
+- Usar `aria-label` no container quando necessario contexto adicional
+- Fallback com texto deve ser legivel (iniciais claras)
+- Anunciar status de presenca se implementado
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature             | ETUS | React Aria | Radix | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon |
+| ------------------- | :--: | :--------: | :---: | :----: | :-: | :-----: | :--: | :----: | :----: | :----: |
+| **alt obrigatorio** |  ~   |     -      |   ~   |   ✓    |  ~  |    ~    |  ~   |   ~    |   ✓    |   ✓    |
+| **aria-label**      |  ~   |     -      |   ~   |   ✓    |  ~  |    ~    |  ~   |   ✓    |   ✓    |   ✓    |
+| **role="img"**      |  ✓   |     -      |   ✓   |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |   ✓    |   ✓    |
+| **Focus visible**   |  ~   |     -      |   -   |   ✓    |  ✓  |    ✓    |  -   |   ✓    |   ✓    |   ✓    |
+| **High contrast**   |  -   |     -      |   -   |   -    |  -  |    -    |  -   |   -    |   ✓    |   ✓    |
+
+**Legenda:** ✓ = Built-in | ~ = Manual/Via props | - = Nao aplicavel
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { Avatar, AvatarImage, AvatarFallback } from "@etus/ui";
+
+function Example() {
+  return (
+    <Avatar>
+      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+      <AvatarFallback>CN</AvatarFallback>
+    </Avatar>
+  );
+}
+```
+
+### Tamanhos
+
+```tsx
+// Extra small (24px)
+<Avatar className="size-6">
+  <AvatarImage src={url} alt="Usuario" />
+  <AvatarFallback className="text-xs">AB</AvatarFallback>
+</Avatar>
+
+// Small (32px) - Padrao
+<Avatar>
+  <AvatarImage src={url} alt="Usuario" />
+  <AvatarFallback>AB</AvatarFallback>
+</Avatar>
+
+// Medium (40px)
+<Avatar className="size-10">
+  <AvatarImage src={url} alt="Usuario" />
+  <AvatarFallback>AB</AvatarFallback>
+</Avatar>
+
+// Large (48px)
+<Avatar className="size-12">
+  <AvatarImage src={url} alt="Usuario" />
+  <AvatarFallback className="text-lg">AB</AvatarFallback>
+</Avatar>
+
+// Extra large (64px)
+<Avatar className="size-16">
+  <AvatarImage src={url} alt="Usuario" />
+  <AvatarFallback className="text-xl">AB</AvatarFallback>
+</Avatar>
+```
+
+### Formas
+
+```tsx
+// Circular (padrao)
+<Avatar>
+  <AvatarImage src={url} alt="Usuario" />
+  <AvatarFallback>AB</AvatarFallback>
+</Avatar>
+
+// Quadrado com bordas arredondadas
+<Avatar className="rounded-md">
+  <AvatarImage src={url} alt="Organizacao" />
+  <AvatarFallback className="rounded-md">ORG</AvatarFallback>
+</Avatar>
+
+// Quadrado
+<Avatar className="rounded-none">
+  <AvatarImage src={url} alt="App" />
+  <AvatarFallback className="rounded-none">APP</AvatarFallback>
+</Avatar>
+```
+
+### Fallback com Icone
+
+```tsx
+import { User } from "lucide-react";
+
+<Avatar>
+  <AvatarImage src={url} alt="Usuario" />
+  <AvatarFallback>
+    <User className="size-4" />
+  </AvatarFallback>
+</Avatar>;
+```
+
+### Fallback com Iniciais Customizadas
+
+```tsx
+function getInitials(name: string): string {
+  return name
+    .split(' ')
+    .map(word => word[0])
+    .join('')
+    .toUpperCase()
+    .slice(0, 2)
+}
+
+function UserAvatar({ name, src }: { name: string; src?: string }) {
+  return (
+    <Avatar>
+      <AvatarImage src={src} alt={`Foto de ${name}`} />
+      <AvatarFallback>{getInitials(name)}</AvatarFallback>
+    </Avatar>
+  )
+}
+
+// Uso
+<UserAvatar name="Maria Silva" src={url} />  // Fallback: "MS"
+<UserAvatar name="Joao" />                   // Fallback: "JO"
+```
+
+### Com Borda
+
+```tsx
+<Avatar className="ring-2 ring-primary ring-offset-2 ring-offset-background">
+  <AvatarImage src={url} alt="Usuario" />
+  <AvatarFallback>AB</AvatarFallback>
+</Avatar>
+```
+
+### Avatar Group (Stack)
+
+```tsx
+function AvatarGroup({ users, max = 4 }: { users: User[]; max?: number }) {
+  const visible = users.slice(0, max);
+  const remaining = users.length - max;
+
+  return (
+    <div className="flex -space-x-3">
+      {visible.map((user) => (
+        <Avatar key={user.id} className="ring-2 ring-background">
+          <AvatarImage src={user.avatar} alt={user.name} />
+          <AvatarFallback>{user.initials}</AvatarFallback>
+        </Avatar>
+      ))}
+      {remaining > 0 && (
+        <Avatar className="ring-2 ring-background">
+          <AvatarFallback className="bg-muted text-muted-foreground text-xs">
+            +{remaining}
+          </AvatarFallback>
+        </Avatar>
+      )}
+    </div>
+  );
+}
+```
+
+### Com Status/Presenca
+
+```tsx
+// Usando o componente AvatarStatus (recomendado)
+import { Avatar, AvatarImage, AvatarFallback, AvatarStatus } from "@etus/ui";
+
+<div className="relative">
+  <Avatar>
+    <AvatarImage src={url} alt="Usuario" />
+    <AvatarFallback>AB</AvatarFallback>
+  </Avatar>
+  <AvatarStatus status="online" />
+</div>;
+
+// Ou manualmente com tokens semanticos
+function AvatarWithStatus({
+  src,
+  alt,
+  status,
+}: {
+  src: string;
+  alt: string;
+  status: "online" | "offline" | "busy" | "away";
+}) {
+  // Usar tokens semanticos - NUNCA hardcode cores!
+  const statusColors = {
+    online: "bg-success", // --success token
+    offline: "bg-muted", // --muted token
+    busy: "bg-destructive", // --destructive token
+    away: "bg-warning", // --warning token
+  };
+
+  return (
+    <div className="relative">
+      <Avatar>
+        <AvatarImage src={src} alt={alt} />
+        <AvatarFallback>AB</AvatarFallback>
+      </Avatar>
+      <span
+        className={cn(
+          "absolute bottom-0 right-0 size-3 rounded-full ring-2 ring-background",
+          statusColors[status],
+        )}
+        aria-label={`Status: ${status}`}
+      />
+    </div>
+  );
+}
+```
+
+### Avatar como Botao
+
+```tsx
+import { Button } from "@etus/ui"
+
+// Usando asChild
+<Button variant="ghost" size="icon" className="rounded-full" asChild>
+  <button aria-label="Abrir menu do usuario">
+    <Avatar>
+      <AvatarImage src={url} alt="" />
+      <AvatarFallback>AB</AvatarFallback>
+    </Avatar>
+  </button>
+</Button>
+
+// Ou wrapper simples
+<button
+  className="rounded-full focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+  aria-label="Abrir perfil"
+>
+  <Avatar>
+    <AvatarImage src={url} alt="" />
+    <AvatarFallback>AB</AvatarFallback>
+  </Avatar>
+</button>
+```
+
+### Monitorando Status de Carregamento
+
+```tsx
+function AvatarWithLoadingState({ src, alt }: { src: string; alt: string }) {
+  const [status, setStatus] = React.useState<
+    "idle" | "loading" | "loaded" | "error"
+  >("idle");
+
+  return (
+    <div>
+      <Avatar>
+        <AvatarImage src={src} alt={alt} onLoadingStatusChange={setStatus} />
+        <AvatarFallback delayMs={600}>
+          {status === "loading" ? <Spinner /> : "AB"}
+        </AvatarFallback>
+      </Avatar>
+      {status === "error" && (
+        <span className="text-sm text-destructive">
+          Erro ao carregar imagem
+        </span>
+      )}
+    </div>
+  );
+}
+```
+
+### Responsividade
+
+```tsx
+// Tamanho responsivo
+<Avatar className="size-8 md:size-10 lg:size-12">
+  <AvatarImage src={url} alt="Usuario" />
+  <AvatarFallback className="text-xs md:text-sm lg:text-base">
+    AB
+  </AvatarFallback>
+</Avatar>
+```
+
+### Com Container Queries
+
+```tsx
+<div className="@container">
+  <Avatar className="size-8 @sm:size-10 @md:size-12">
+    <AvatarImage src={url} alt="Usuario" />
+    <AvatarFallback>AB</AvatarFallback>
+  </Avatar>
+</div>
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// Avatar.test.tsx
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Avatar, AvatarImage, AvatarFallback } from "./Avatar";
+
+describe("Avatar", () => {
+  it("renders avatar container", () => {
+    render(
+      <Avatar data-testid="avatar">
+        <AvatarFallback>AB</AvatarFallback>
+      </Avatar>,
+    );
+    expect(screen.getByTestId("avatar")).toBeInTheDocument();
+  });
+
+  it("has data-slot attribute", () => {
+    render(
+      <Avatar data-testid="avatar">
+        <AvatarFallback>AB</AvatarFallback>
+      </Avatar>,
+    );
+    expect(screen.getByTestId("avatar")).toHaveAttribute("data-slot", "avatar");
+  });
+
+  it("applies custom className", () => {
+    render(
+      <Avatar className="size-16" data-testid="avatar">
+        <AvatarFallback>AB</AvatarFallback>
+      </Avatar>,
+    );
+    expect(screen.getByTestId("avatar")).toHaveClass("size-16");
+  });
+
+  it("maintains default classes with custom className", () => {
+    render(
+      <Avatar className="custom-class" data-testid="avatar">
+        <AvatarFallback>AB</AvatarFallback>
+      </Avatar>,
+    );
+    const avatar = screen.getByTestId("avatar");
+    expect(avatar).toHaveClass("rounded-full");
+    expect(avatar).toHaveClass("custom-class");
+  });
+});
+```
+
+### Testes de AvatarImage
+
+```tsx
+describe("AvatarImage", () => {
+  it("renders image with src and alt", () => {
+    render(
+      <Avatar>
+        <AvatarImage src="test.jpg" alt="Test user" />
+        <AvatarFallback>TU</AvatarFallback>
+      </Avatar>,
+    );
+    const img = screen.getByRole("img");
+    expect(img).toHaveAttribute("src", "test.jpg");
+    expect(img).toHaveAttribute("alt", "Test user");
+  });
+
+  it("has data-slot attribute", () => {
+    render(
+      <Avatar>
+        <AvatarImage src="test.jpg" alt="Test" data-testid="avatar-image" />
+        <AvatarFallback>T</AvatarFallback>
+      </Avatar>,
+    );
+    // Note: Radix may not render image immediately
+    const img = screen.queryByTestId("avatar-image");
+    if (img) {
+      expect(img).toHaveAttribute("data-slot", "avatar-image");
+    }
+  });
+});
+```
+
+### Testes de AvatarFallback
+
+```tsx
+describe("AvatarFallback", () => {
+  it("renders fallback content", () => {
+    render(
+      <Avatar>
+        <AvatarFallback>AB</AvatarFallback>
+      </Avatar>,
+    );
+    expect(screen.getByText("AB")).toBeInTheDocument();
+  });
+
+  it("renders icon as fallback", () => {
+    render(
+      <Avatar>
+        <AvatarFallback data-testid="fallback">
+          <svg data-testid="icon" />
+        </AvatarFallback>
+      </Avatar>,
+    );
+    expect(screen.getByTestId("icon")).toBeInTheDocument();
+  });
+
+  it("has data-slot attribute", () => {
+    render(
+      <Avatar>
+        <AvatarFallback data-testid="fallback">AB</AvatarFallback>
+      </Avatar>,
+    );
+    expect(screen.getByTestId("fallback")).toHaveAttribute(
+      "data-slot",
+      "avatar-fallback",
+    );
+  });
+
+  it("applies custom className", () => {
+    render(
+      <Avatar>
+        <AvatarFallback className="bg-primary" data-testid="fallback">
+          AB
+        </AvatarFallback>
+      </Avatar>,
+    );
+    expect(screen.getByTestId("fallback")).toHaveClass("bg-primary");
+  });
+});
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe";
+
+expect.extend(toHaveNoViolations);
+
+describe("Avatar accessibility", () => {
+  it("has no accessibility violations with proper alt", async () => {
+    const { container } = render(
+      <Avatar>
+        <AvatarImage src="test.jpg" alt="Profile photo of John Doe" />
+        <AvatarFallback>JD</AvatarFallback>
+      </Avatar>,
+    );
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+
+  it("decorative avatar has no violations", async () => {
+    const { container } = render(
+      <Avatar aria-hidden="true">
+        <AvatarImage src="test.jpg" alt="" />
+        <AvatarFallback>JD</AvatarFallback>
+      </Avatar>,
+    );
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+
+  it("avatar button has no violations", async () => {
+    const { container } = render(
+      <button aria-label="Open user menu">
+        <Avatar>
+          <AvatarImage src="test.jpg" alt="" />
+          <AvatarFallback>JD</AvatarFallback>
+        </Avatar>
+      </button>,
+    );
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+});
+```
+
+### Testes de Composicao
+
+```tsx
+describe("Avatar composition", () => {
+  it("renders avatar group correctly", () => {
+    render(
+      <div className="flex -space-x-3" data-testid="avatar-group">
+        <Avatar>
+          <AvatarFallback>A1</AvatarFallback>
+        </Avatar>
+        <Avatar>
+          <AvatarFallback>A2</AvatarFallback>
+        </Avatar>
+        <Avatar>
+          <AvatarFallback>+3</AvatarFallback>
+        </Avatar>
+      </div>,
+    );
+    expect(screen.getByText("A1")).toBeInTheDocument();
+    expect(screen.getByText("A2")).toBeInTheDocument();
+    expect(screen.getByText("+3")).toBeInTheDocument();
+  });
+
+  it("renders with status indicator", () => {
+    render(
+      <div className="relative">
+        <Avatar>
+          <AvatarFallback>AB</AvatarFallback>
+        </Avatar>
+        <span
+          data-testid="status"
+          className="bg-green-500"
+          aria-label="Online"
+        />
+      </div>,
+    );
+    expect(screen.getByTestId("status")).toBeInTheDocument();
+    expect(screen.getByLabelText("Online")).toBeInTheDocument();
+  });
+});
+```
+
+### Cenarios Criticos
+
+```tsx
+describe("Avatar edge cases", () => {
+  it("handles missing image gracefully", () => {
+    render(
+      <Avatar>
+        <AvatarImage src="" alt="Missing" />
+        <AvatarFallback>FB</AvatarFallback>
+      </Avatar>,
+    );
+    // Fallback should be visible when image fails
+    expect(screen.getByText("FB")).toBeInTheDocument();
+  });
+
+  it("handles long initials", () => {
+    render(
+      <Avatar>
+        <AvatarFallback>ABCDEF</AvatarFallback>
+      </Avatar>,
+    );
+    expect(screen.getByText("ABCDEF")).toBeInTheDocument();
+  });
+
+  it("handles empty fallback", () => {
+    render(
+      <Avatar data-testid="avatar">
+        <AvatarFallback data-testid="fallback" />
+      </Avatar>,
+    );
+    expect(screen.getByTestId("fallback")).toBeInTheDocument();
+  });
+});
+```
+
+---
+
+## Features Implementadas
+
+Todas as features de alta prioridade foram implementadas:
+
+### ✅ Prop `size`
+
+```tsx
+<Avatar size="lg">...</Avatar>
+// Tamanhos: xs (24px), sm (32px), default (40px), lg (48px), xl (56px), 2xl (64px)
+```
+
+### ✅ Prop `shape`
+
+```tsx
+<Avatar shape="square">...</Avatar>
+// Formas: circle (padrao), square
+```
+
+### ✅ Props `bordered`, `interactive`, `contrastBorder`
+
+```tsx
+<Avatar bordered interactive contrastBorder>
+  ...
+</Avatar>
+```
+
+### ✅ `AvatarStatus`
+
+```tsx
+<Avatar>
+  <AvatarImage src={url} alt="User" />
+  <AvatarFallback>AB</AvatarFallback>
+  <AvatarStatus status="online" size="default" />
+</Avatar>
+// Status: online, offline, busy, away
+```
+
+### ✅ `AvatarBadge`
+
+```tsx
+<Avatar>
+  <AvatarImage src={url} alt="User" />
+  <AvatarFallback>AB</AvatarFallback>
+  <AvatarBadge variant="verified" size="default" />
+</Avatar>
+// Variantes: company (purple), verified (blue)
+```
+
+### ✅ `AvatarGroup`
+
+```tsx
+<AvatarGroup max={4} size="default" bordered>
+  <Avatar>...</Avatar>
+  <Avatar>...</Avatar>
+  <Avatar>...</Avatar>
+  <Avatar>...</Avatar>
+  <Avatar>...</Avatar>
+</AvatarGroup>
+// Renderiza 4 avatares + "+1"
+```
+
+### ✅ `AvatarLabelGroup`
+
+```tsx
+// Uso basico com status
+<AvatarLabelGroup
+  src={url}
+  name="Maria Silva"
+  description="Software Engineer"
+  status="online"
+  size="default"
+/>
+// Gera iniciais automaticamente: "MS"
+
+// Com badge de verificacao (company ou verified)
+<AvatarLabelGroup
+  src={url}
+  name="ETUS Corp"
+  description="Empresa verificada"
+  badge="company"
+  size="default"
+/>
+
+// Modo interativo (hover/focus states, clicavel)
+<AvatarLabelGroup
+  src={url}
+  name="Maria Silva"
+  description="Clique para ver perfil"
+  interactive
+  onClick={(e) => console.log("Avatar clicado!")}
+/>
+```
+
+**Props disponiveis:**
+
+| Prop          | Tipo                                                 | Padrao      | Descricao                                            |
+| ------------- | ---------------------------------------------------- | ----------- | ---------------------------------------------------- |
+| `name`        | `string`                                             | -           | Nome (obrigatorio, usado para iniciais)              |
+| `src`         | `string`                                             | -           | URL da imagem                                        |
+| `alt`         | `string`                                             | -           | Texto alternativo (usa `name` se omitido)            |
+| `description` | `string`                                             | -           | Texto secundario abaixo do nome                      |
+| `size`        | `"xs" \| "sm" \| "default" \| "lg" \| "xl" \| "2xl"` | `"default"` | Tamanho do avatar                                    |
+| `status`      | `"online" \| "offline" \| "busy" \| "away"`          | -           | Indicador de presenca                                |
+| `badge`       | `"company" \| "verified"`                            | -           | Badge de verificacao (nao pode ser usado com status) |
+| `interactive` | `boolean`                                            | `false`     | Habilita hover/focus states                          |
+| `onClick`     | `(e: MouseEvent) => void`                            | -           | Handler de clique (usado com interactive)            |
+| `tooltip`     | `string \| boolean`                                  | -           | Tooltip (true = usa name + description)              |
+
+> **Nota:** `status` e `badge` sao mutuamente exclusivos. Se ambos forem fornecidos, `status` tem prioridade.
+
+### ✅ `AvatarAddButton`
+
+```tsx
+<AvatarGroup>
+  <Avatar>...</Avatar>
+  <AvatarAddButton size="default" onClick={handleAdd} />
+</AvatarGroup>
+```
+
+### ✅ `colorScheme` (AvatarFallback)
+
+Customiza as cores do fallback usando tokens semanticos:
+
+```tsx
+<Avatar>
+  <AvatarImage src={url} alt="User" />
+  <AvatarFallback colorScheme="primary">AB</AvatarFallback>
+</Avatar>
+
+// Todas as opcoes disponiveis
+<AvatarFallback colorScheme="default">AB</AvatarFallback>     // bg-muted (padrao)
+<AvatarFallback colorScheme="primary">AB</AvatarFallback>     // bg-primary
+<AvatarFallback colorScheme="secondary">AB</AvatarFallback>   // bg-secondary
+<AvatarFallback colorScheme="success">AB</AvatarFallback>     // bg-success
+<AvatarFallback colorScheme="warning">AB</AvatarFallback>     // bg-warning
+<AvatarFallback colorScheme="destructive">AB</AvatarFallback> // bg-destructive
+```
+
+### ✅ `tooltip` (Avatar e AvatarLabelGroup)
+
+Adiciona tooltip ao avatar ou label group:
+
+```tsx
+// Avatar com tooltip customizado
+<Avatar tooltip="Maria Silva - Software Engineer">
+  <AvatarImage src={url} alt="Maria" />
+  <AvatarFallback>MS</AvatarFallback>
+</Avatar>
+
+// AvatarLabelGroup com tooltip automatico (usa name + description)
+<AvatarLabelGroup
+  name="Maria Silva"
+  description="Software Engineer"
+  tooltip  // exibe "Maria Silva - Software Engineer"
+/>
+
+// AvatarLabelGroup com tooltip customizado
+<AvatarLabelGroup
+  name="Maria Silva"
+  description="Software Engineer"
+  tooltip="Clique para ver perfil completo"
+/>
+```
+
+### ✅ `AvatarSkeleton` e `AvatarLabelGroupSkeleton`
+
+Skeletons para loading states:
+
+```tsx
+import { AvatarSkeleton, AvatarLabelGroupSkeleton } from "@etus/ui";
+
+// Skeleton simples para Avatar
+{
+  isLoading ? (
+    <AvatarSkeleton size="lg" shape="circle" />
+  ) : (
+    <Avatar size="lg">...</Avatar>
+  );
+}
+
+// Skeleton para AvatarLabelGroup (inclui linhas de texto)
+{
+  isLoading ? (
+    <AvatarLabelGroupSkeleton size="default" />
+  ) : (
+    <AvatarLabelGroup name="Maria Silva" description="Engineer" />
+  );
+}
+
+// Em grupos
+<AvatarGroup>
+  <AvatarSkeleton />
+  <AvatarSkeleton />
+  <AvatarSkeleton />
+</AvatarGroup>;
+```
+
+### ✅ Lazy Loading (Imagens)
+
+Use o atributo nativo `loading="lazy"` para otimizar listas longas:
+
+```tsx
+// Avatar com lazy loading
+<Avatar>
+  <AvatarImage src={url} alt="User" loading="lazy" />
+  <AvatarFallback>AB</AvatarFallback>
+</Avatar>;
+
+// Em listas longas (recomendado)
+{
+  users.map((user) => (
+    <Avatar key={user.id}>
+      <AvatarImage
+        src={user.avatar}
+        alt={user.name}
+        loading="lazy" // carrega apenas quando visivel
+      />
+      <AvatarFallback>{getInitials(user.name)}</AvatarFallback>
+    </Avatar>
+  ));
+}
+```
+
+> **Nota:** `loading="lazy"` e suportado nativamente em browsers modernos (Chrome 77+, Firefox 75+, Safari 15.4+).
+
+## Roadmap / Features Futuras
+
+### Implementado Recentemente
+
+| Feature                        | Versao | Descricao                                             |
+| ------------------------------ | ------ | ----------------------------------------------------- |
+| `colorScheme` prop             | v1.2   | Customizacao de cores do fallback                     |
+| `tooltip` prop                 | v1.2   | Tooltip integrado em Avatar e AvatarLabelGroup        |
+| `AvatarSkeleton`               | v1.2   | Skeleton loading para Avatar                          |
+| `AvatarLabelGroupSkeleton`     | v1.2   | Skeleton loading para AvatarLabelGroup                |
+| Lazy loading docs              | v1.2   | Documentacao de loading="lazy" nativo                 |
+| AvatarLabelGroup `badge` prop  | v1.1   | Suporte a badge company/verified no label group       |
+| AvatarLabelGroup `interactive` | v1.1   | Modo interativo com hover/focus states                |
+| Tokens semanticos              | v1.1   | Migracao para tokens (bg-success, bg-brius-500, etc.) |
+| Contrast border                | v1.0   | Borda sutil para definicao em fundos similares        |
+
+### Pendente
+
+| Feature            | Prioridade | Justificativa                                            |
+| ------------------ | ---------- | -------------------------------------------------------- |
+| Custom badge icons | P2         | Icones personalizados no badge (ja suporta via children) |
+
+**Legenda:** P1 = Alta | P2 = Media | P3 = Baixa
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System  | Documentacao Avatar                                                         | GitHub                                                                        |
+| -------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| **Shadcn/ui**  | [Avatar](https://ui.shadcn.com/docs/components/avatar)                      | [shadcn-ui/ui](https://github.com/shadcn-ui/ui)                               |
+| **Radix UI**   | [Avatar](https://www.radix-ui.com/primitives/docs/components/avatar)        | [radix-ui/primitives](https://github.com/radix-ui/primitives)                 |
+| **Chakra UI**  | [Avatar](https://chakra-ui.com/docs/components/avatar)                      | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui)                 |
+| **MUI**        | [Avatar](https://mui.com/material-ui/react-avatar/)                         | [mui/material-ui](https://github.com/mui/material-ui)                         |
+| **Mantine**    | [Avatar](https://mantine.dev/core/avatar/)                                  | [mantinedev/mantine](https://github.com/mantinedev/mantine)                   |
+| **Ant Design** | [Avatar](https://ant.design/components/avatar)                              | [ant-design/ant-design](https://github.com/ant-design/ant-design)             |
+| **NextUI**     | [Avatar](https://nextui.org/docs/components/avatar)                         | [nextui-org/nextui](https://github.com/nextui-org/nextui)                     |
+| **Fluent UI**  | [Avatar](https://react.fluentui.dev/?path=/docs/components-avatar--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui)                   |
+| **Carbon**     | [Avatar](https://carbondesignsystem.com/components/avatar/usage/)           | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+
+### Especificacoes e Padroes
+
+- [WAI-ARIA - Images](https://www.w3.org/WAI/tutorials/images/)
+- [WCAG 2.1 - Non-text Content](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html)
+- [MDN - img Element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img)
+- [Radix Avatar Primitive](https://www.radix-ui.com/primitives/docs/components/avatar)
+
+### Ferramentas Utilizadas
+
+- [Radix UI Avatar](https://www.radix-ui.com/primitives/docs/components/avatar)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [Lucide Icons](https://lucide.dev/icons/)