# Avatar

> Componentes / Conteúdo · Estado: **Em andamento** — Implementado e utilizável, mas ainda sem a validação completa de acessibilidade.

Foto redonda de uma pessoa, em quatro tamanhos. Quando a foto falta ou não carrega — inclusive se falhou antes de o React chegar —, mostra as iniciais do nome (primeira e última palavra) e passa a ser uma imagem nomeada.

- Função: Conteúdo
- Também chamado de: foto de perfil, avatar, retrato, iniciais
- Mora em: `app/components/atoms/Avatar.tsx`
- Página: [https://phorte-design-system.vercel.app/styleguide/peca/Avatar](https://phorte-design-system.vercel.app/styleguide/peca/Avatar)
- Ficha no Storybook: [components-base-avatar](https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-base-avatar--docs)
- Prévia ao vivo, sozinha: [https://phorte-design-system.vercel.app/previa/Avatar/0](https://phorte-design-system.vercel.app/previa/Avatar/0)
- Todas as peças: [https://phorte-design-system.vercel.app/llms.txt](https://phorte-design-system.vercel.app/llms.txt)

## Como usar no código

```tsx
import { Avatar } from '@/app/components/atoms/Avatar';

<Avatar>…</Avatar>
```

## Uso

### Variantes na ficha

1. [Padrão](https://phorte-design-system.vercel.app/previa/Avatar/0)
2. [Com Foto](https://phorte-design-system.vercel.app/previa/Avatar/1)
3. [Tamanhos](https://phorte-design-system.vercel.app/previa/Avatar/2)
4. [Foto indisponível](https://phorte-design-system.vercel.app/previa/Avatar/3)
5. [Iniciais Longas](https://phorte-design-system.vercel.app/previa/Avatar/4)
6. [Decorativo](https://phorte-design-system.vercel.app/previa/Avatar/5)
7. [Com presença](https://phorte-design-system.vercel.app/previa/Avatar/6)

Ao lado do nome de uma pessoa — palestrante, professor, autor de depoimento.

### Quando não usar

Para várias pessoas sobrepostas, com "+N", use o AvatarGroup. Para um ícone num fundo redondo, o IconBox.

### Faça

- Passe o `name`: ele dá as iniciais e, sem foto, o nome acessível.
- Use `decorativo` quando o nome já está escrito ao lado — a foto fica com `alt=""`.
- Escolha o tamanho pela densidade: `sm` em listas, `xl` em destaque.
- Passe `presenca` (`disponivel` ou `ausente`) só onde ela muda o que a pessoa faz: o tutor no chat, quem está na turma ao vivo (E116).

### Evite

- Um `<img>` solto no lugar do Avatar: perde o tratamento de imagem quebrada.
- Nome acessível duplicado: foto nomeada ao lado do nome escrito faz o leitor dizer o nome duas vezes.

### Nota de uso

**Quando não usar (E64):** numa lista sem espaço, ou quando o nome escrito basta — a foto sozinha não identifica ninguém. As iniciais são duas letras (primeira e última palavra do nome). O `alt` é o nome da pessoa, sem "foto de": o leitor já diz que é imagem. Tem tratamento de imagem quebrada. É o átomo que o `EventSpeaker` passou a usar em vez de um `<img>` solto — se você estiver desenhando uma peça com foto de pessoa, comece por aqui. Passe o `name`: ele dá as iniciais (primeira e última palavra) e, sem foto, o nome acessível do avatar. Quando o nome já está escrito ao lado, use `decorativo` — a foto fica com `alt=""` e o leitor não repete o nome. `fallback` só sobrescreve as iniciais.

### Anatomia

1. **Círculo** — Borda de 2px `--surface`, fundo `--muted`, recorte redondo.
2. **Foto** — Cobre o círculo (`object-cover`).
3. **Iniciais** — Sem foto: duas letras em seminegrito, `--muted-foreground`, decorativas.
4. **Presença** — Com `presenca`: o ponto no canto de baixo, fora do recorte redondo, com anel de 2px `--card` — cheio `--success` (disponível) ou vazado com borda `--muted-foreground` (ausente); 10, 12, 14 ou 16px conforme o tamanho.

### Estados

| Estado | O que muda |
| --- | --- |
| Com foto | A imagem, com `alt` do `alt` ou do `name` (vazio se `decorativo`). |
| Sem foto ou foto quebrada | As iniciais; o círculo vira `role="img"` com o nome acessível. |
| Decorativo | Sem nome acessível em nenhum dos dois casos. |
| Tamanho | `sm` 32px, `md` 40px (padrão), `lg` 48px, `xl` 64px. |
| Disponível | Ponto cheio verde, e o nome ganha "(disponível)". |
| Ausente | Anel vazado cinza — a forma muda, não só a cor —, e o nome ganha "(ausente)". |

### Comportamento

| Situação | O que acontece |
| --- | --- |
| A imagem falha ao carregar | Troca pelas iniciais — e troca de novo se o `src` mudar para um endereço que funcione. |
| A imagem falhou antes da hidratação | Na montagem, confere se ela já veio quebrada (`complete` com largura 0) e troca. |
| `fallback` com espaço | É tratado como nome: vira as iniciais dele; sem espaço, usa as duas primeiras letras. |
| Com `presenca` | O avatar ganha um invólucro com o ponto (o `style` vai para ele, o `className` fica no círculo); sem a prop, nada muda — testado na ficha. |

### Relacionados

- [AvatarGroup](https://phorte-design-system.vercel.app/styleguide/md/AvatarGroup.md) — Várias pessoas sobrepostas.
- [EventSpeaker](https://phorte-design-system.vercel.app/styleguide/md/EventSpeaker.md) — Palestrante com foto, que usa o Avatar.

## Especificação

### Propriedades

| Prop | Tipo | Padrão | Obrigatória | Descrição |
| --- | --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | não | Variante do `cva`. |
| `src` | `string` | — | não |  |
| `name` | `string` | — | não | Nome da pessoa. Dá as iniciais e, sem foto, o nome acessível do avatar. |
| `alt` | `string` | — | não | Texto alternativo da foto. Sem ele, vale o `name`. |
| `fallback` | `string` | — | não | Sobrescreve as iniciais tiradas do `name`. |
| `decorativo` | `boolean` | `false` | não | O nome já está escrito ao lado (lista de palestrantes, autor do post): a foto vira decoração, com `alt=""`. Sem isto, o leitor dizia "Ana Souza, Ana Souza" em cada item. |
| `presenca` | `'disponivel' \| 'ausente'` | — | não | Presença (E116): `disponivel` ou `ausente` — o tutor no chat, a pessoa na turma ao vivo. Mostra o ponto no canto e diz o estado a quem ouve. Sem a prop, nada muda. |

Aceita também: `React.HTMLAttributes<HTMLDivElement>`.

### Medidas

| Parte | Valor | Classe |
| --- | --- | --- |
| `sm` | 32px | `w-8 h-8` |
| `md` | 40px | `w-10 h-10` |
| `lg` | 48px | `w-12 h-12` |
| `xl` | 64px | `w-16 h-16` |

### Tokens de cor

| Token | Valor | Usado como |
| --- | --- | --- |
| `--card` | #FFFFFF | `bg-card`, `border-card`, `ring-card` |
| `--muted-foreground` | #595959 | `border-muted-foreground`, `text-muted-foreground` |
| `--muted` | #F4F6F9 | `bg-muted` |
| `--success` | #2E844A | `bg-success` |

## Acessibilidade

### Leitor de tela

- Com foto, o nome vai no `alt`; sem foto, no `aria-label` do círculo com `role="img"`. As iniciais são `aria-hidden`: o leitor diz o nome, não "M S".
- A presença entra no nome ("Helena Martins (disponível)"); o ponto é `aria-hidden`. No avatar `decorativo`, que não tem nome, ela vai em texto oculto.

### O que sustenta o estado

Usa os padrões: estatico. Falta ouvir com leitor de tela: estatico.

## Status e recursos

| Tipo | Recurso | Status |
| --- | --- | --- |
| Código | `app/components/atoms/Avatar.tsx` | Disponível |
| Ficha | https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-base-avatar--docs | Disponível |
| Teste de acessibilidade | axe em `npm run test` | No gate de todo commit |
| Leitor de tela | Passada da E33 | Falta ouvir |
| Design | Figma | Desativado até a Fase 2 |

### Histórico

- `60d6190` 2026-09-29 — E116: presença no Avatar e "Adicionar" no AvatarGroup
- `b226180` 2026-09-29 — E115: LinkDeNavegacao — o link da barra sai de dentro da Navbar
- Histórico completo no GitHub: https://github.com/srbunnie/Pos-Phorte-Design-System/commits/main/app/components/atoms/Avatar.tsx