# Esqueleto

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

O lugar de um conteúdo que ainda está chegando: a forma do cartão, da linha de texto, da foto, para a página não pular quando o conteúdo entra. Cada forma é decorativa; o EsqueletoGrupo em volta diz "Carregando" uma vez.

- Função: Estado e aviso
- Também chamado de: skeleton, esqueleto, placeholder de carregamento, carregando, shimmer
- Mora em: `app/components/atoms/Esqueleto.tsx`
- Página: [https://phorte-design-system.vercel.app/styleguide/peca/Esqueleto](https://phorte-design-system.vercel.app/styleguide/peca/Esqueleto)
- Ficha no Storybook: [components-base-esqueleto](https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-base-esqueleto--docs)
- Prévia ao vivo, sozinha: [https://phorte-design-system.vercel.app/previa/Esqueleto/0](https://phorte-design-system.vercel.app/previa/Esqueleto/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 { Esqueleto } from '@/app/components/atoms/Esqueleto';

<Esqueleto>…</Esqueleto>
```

## Uso

### Variantes na ficha

1. [Padrão](https://phorte-design-system.vercel.app/previa/Esqueleto/0)
2. [Cartão](https://phorte-design-system.vercel.app/previa/Esqueleto/1)
3. [Sem animação](https://phorte-design-system.vercel.app/previa/Esqueleto/2)
4. [Na troca](https://phorte-design-system.vercel.app/previa/Esqueleto/3)

Quando o conteúdo leva mais de um instante para chegar e já se sabe a forma dele: a lista de cursos, o cartão da turma, o perfil de um docente.

### Quando não usar

Para uma ação que a pessoa disparou (enviar, salvar): o Button com carregamento. Para uma tarefa com progresso conhecido: o Progress. Quando não se sabe a forma do que vem: o Progress indeterminado.

### Faça

- Para os cartões que vêm de API, use os esqueletos prontos (E157): `CourseCardEsqueleto`, `BlogCardEsqueleto`, `EventCardEsqueleto` e `TurmaCardEsqueleto`, que têm a forma exata do cartão.
- Envolva os esqueletos de um bloco num `EsqueletoGrupo` com um `rotulo` que diga o quê ("Carregando cursos").
- Imite a forma do conteúdo: miniatura, título e duas linhas para um cartão; avatar e linha para uma pessoa.
- Troque o grupo inteiro pelo conteúdo quando ele chegar: o anúncio sai junto.
- Em lista muito longa, `animado={false}`: dezenas de formas pulsando cansam.

### Evite

- Dar esqueleto a peça que aparece na hora — botão, campo, aviso, modal, menu, rodapé: ela já está pronta, e o esqueleto só atrasaria a leitura. Esqueleto é para conteúdo que chega depois e tem forma previsível (revisão 4).
- Um "Carregando" por forma: o leitor de tela repetiria a mesma palavra a cada linha.
- Esqueleto que fica na tela para sempre: se a carga falhar, troque pelo Alert.
- Forma muito diferente do conteúdo: o salto que ele evitaria volta.

### Anatomia

1. **Forma** — Um bloco em `--border`: texto (14px), título (24px, 60% da largura), avatar (40px, redondo), miniatura (16:9) e botão (44px de altura, raio do controle).
2. **Pulso** — A opacidade vai de 1 a 0,5 e volta, em 1,6s — sem deslocamento. Parado com movimento reduzido.
3. **Grupo** — Uma região `status` com o `rotulo` só para o leitor de tela.

### Estados

| Estado | O que muda |
| --- | --- |
| Pulsando | O padrão, com movimento liberado. |
| Parado | Com `animado={false}` ou com movimento reduzido no sistema. |

### Comportamento

| Situação | O que acontece |
| --- | --- |
| O conteúdo chega | Quem chama troca o grupo pelo conteúdo; o `status` some junto — testado na ficha. |
| Movimento reduzido | A animação é `none`: a forma fica parada, e o "Carregando" do grupo continua. |

### Relacionados

- [Progress](https://phorte-design-system.vercel.app/styleguide/md/Progress.md) — Progresso conhecido, ou carregamento sem forma.
- [EstadoVazio](https://phorte-design-system.vercel.app/styleguide/md/EstadoVazio.md) — Quando carregou e não veio nada.
- [Button](https://phorte-design-system.vercel.app/styleguide/md/Button.md) — O carregamento de uma ação que a pessoa disparou.

## Especificação

### Propriedades

| Prop | Tipo | Padrão | Obrigatória | Descrição |
| --- | --- | --- | --- | --- |
| `forma` | `'texto' \| 'titulo' \| 'avatar' \| 'miniatura' \| 'botao'` | `'texto'` | não | Variante do `cva`. |
| `animado` | `boolean` | `true` | não | O pulso só existe com movimento liberado (ver `.esqueleto-pulsando` em globals.css). |

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

### Tokens de cor

| Token | Valor | Usado como |
| --- | --- | --- |
| `--border` | #E5E5E5 | `bg-border` |

## Acessibilidade

### Leitor de tela

- As formas são `aria-hidden`: não há o que ler nelas.
- O `EsqueletoGrupo` é `role="status"` e diz o `rotulo` uma vez.
- O pulso é indicador de carregamento (exceção nomeada na trava de pausa do audit, WCAG 2.2.2): some quando o conteúdo chega, e para com movimento reduzido.

### O que sustenta o estado

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

## Status e recursos

| Tipo | Recurso | Status |
| --- | --- | --- |
| Código | `app/components/atoms/Esqueleto.tsx` | Disponível |
| Ficha | https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-base-esqueleto--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

- `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/Esqueleto.tsx