# Illustration

Nove desenhos para as telas em que algo não está onde a pessoa esperava: a
página que não existe, a que ela não pode ver, a que caiu, a conexão que foi
embora, a manutenção, e os quatro vazios (lista, busca, caixa de entrada e
gráfico). Um desenho por situação, e não um por tela: o mesmo `NotFound` serve
o 404 do painel e o 404 do portal do cliente. Vivem em
`@rivocode/ui/illustrations`, fora do índice da raiz, para quem não tem tela de
erro desenhada não pagar por elas.

```tsx
import { Button, Result } from '@rivocode/ui'
import { NotFound } from '@rivocode/ui/illustrations'

<Result
  layout="page"
  titleAs="h1"
  illustration={<NotFound size="lg" />}
  meta="Erro 404"
  title="Não achamos esta página"
  description="O endereço pode ter mudado. A busca acha o pedido pelo número ou pelo cliente."
  actions={
    <>
      <Button>Voltar ao início</Button>
      <Button variant="secondary">Buscar</Button>
    </>
  }
/>
```

**O desenho é apoio, e nunca a mensagem.** Ele sai com `aria-hidden` e sem
texto alternativo: quem diz o que houve e o que fazer é o título e a descrição
de quem o recebe, o `Result` ou o `EmptyState`. Por isso nenhum deles tem
número de erro, palavra ou seta desenhada dentro.

## A página de estado é o `Result`

Não existe `ErrorPage` nem `StatusPage`. A página de erro é um título, uma
descrição, uma saída e um desenho, e o `Result` tem os quatro, com o foco no
título ao montar e o `titleAs="h1"` de página. `layout="page"` alinha tudo ao
início numa coluna de leitura, com o título maior e a `illustration` no topo, e
`meta` é a linha discreta acima do título, onde mora o código do erro. O vazio
dentro de uma tela é o `EmptyState`, com a `illustration` dele. Uma terceira peça repetiria as duas com outro nome, e a pessoa
que lê a doc teria de escolher entre três coisas iguais.

## As nove

| Peça | `name` | Quando |
|---|---|---|
| `NotFound` | `not-found` | O endereço não existe, ou o registro foi apagado: o 404 |
| `Forbidden` | `forbidden` | A pessoa entrou, mas o perfil dela não vê esta tela: o 403 |
| `ServerError` | `server-error` | Algo falhou do nosso lado: o 500, a consulta que estourou |
| `Offline` | `offline` | O aparelho perdeu a conexão, ou o servidor não responde |
| `Maintenance` | `maintenance` | O sistema está parado de propósito, com hora para voltar |
| `EmptyList` | `empty-list` | Primeiro uso: nada foi criado ainda |
| `NoResults` | `no-results` | A busca ou o filtro não achou nada |
| `EmptyInbox` | `empty-inbox` | Notificações ou mensagens: tudo lido, nada pendente |
| `NoData` | `no-data` | O gráfico ou o relatório não tem dado no período |

Importe pelo nome quando a situação é fixa na tela. Quando ela chega como dado
(o status de uma resposta, o motivo de um vazio), `Illustration` recebe o
`name`, e `ILLUSTRATION_NAMES` lista os nove, para uma vitrine ou um teste:

```tsx
import { Illustration, type IllustrationName } from '@rivocode/ui/illustrations'

const BY_STATUS: Record<number, IllustrationName> = {
  403: 'forbidden',
  404: 'not-found',
  503: 'maintenance',
}

<Illustration name={BY_STATUS[status] ?? 'server-error'} size="lg" />
```

`Illustration` traz as nove juntas; a peça pelo nome traz o mesmo arquivo hoje,
e é ela que continua leve se o conjunto crescer.

## Medidas

`size` escolhe a largura, e a altura sai da proporção 4:3:

- **`sm`, 96 px**: dentro de um `Card`, de um painel lateral, de um `Popover`.
- **`md`, 160 px** (o padrão): o vazio de uma lista ou de uma seção.
- **`lg`, 240 px**: só a página inteira, como o 404 e o sem permissão.

Num espaço mais estreito que a medida, o desenho encolhe junto (`max-w-full`), e
não transborda. A regra do espaço apertado é escolher `sm`, e não esticar.

## Cor e tema

Cada forma pinta com um papel da casa, por `var(--rc-*)`: o fundo redondo em
`accent-subtle`, o objeto em `surface-raised` com contorno em `border-strong`, o
toque de cor em `accent`, e os tons de estado onde eles dizem algo (o `danger`
no selo do `ServerError`). Nenhuma cor é literal, então o desenho troca junto
com o tema: no claro e no escuro da casa, e no tema de cliente gerado pelo
`rivocode-ui theme`, sem prop nenhuma.

## Movimento

Na montagem o objeto sobe e aparece (`animate-rise`, em `--rc-duration-slow`).
Logo depois cada desenho conta a sua cena, uma vez só, e para no quadro final.
O fundo fica parado:

| Peça | O que se mexe |
|---|---|
| `NotFound` | O selo "?" balança, como quem não entendeu, e assenta |
| `Forbidden` | O cadeado dá uma sacudida curta: tentaram abrir e não abriu |
| `ServerError` | A luz vermelha do servidor pisca duas vezes, e o selo "!" pulsa |
| `Offline` | As faíscas piscam entre os plugues, e o plugue solto balança no cabo |
| `Maintenance` | As duas engrenagens giram uma contra a outra e engrenam no lugar |
| `EmptyList` | O "+" pulsa, convidando a criar o primeiro |
| `NoResults` | A lupa percorre a lista, linha a linha, e o "×" aparece no fim |
| `EmptyInbox` | O selo aparece e o visto se desenha dentro dele |
| `NoData` | A linha do zero se desenha da esquerda para a direita, e o ponto do fim aparece |

**Toca uma vez e acaba antes de 2,5 s.** Nenhuma cena repete nem fica em
laço: a WCAG 2.2.2 pede pausa para movimento automático que passa de 5
segundos, e aqui não há o que pausar, porque nada fica balançando ao lado do
texto. Cada tempo é múltiplo de `--rc-duration-slow`, e as cenas usam as
classes `animate-illustration-*`, declaradas no tema como as outras
animações da casa.

**Reduzir movimento.** Com a preferência do sistema ligada, o desenho nasce no
quadro final, sem subir e sem cena: a duração vai a zero pelo token e cada
cena leva `motion-reduce:animate-none`. `animated={false}` desliga as duas
coisas numa instância, para a ilustração que aparece de novo a cada troca de
filtro, ou para o retrato de uma vitrine:

```tsx
import { NoResults } from '@rivocode/ui/illustrations'

<NoResults size="sm" animated={false} />
```

## Texto da tela que leva o desenho

- **Diga o que houve sem culpar a pessoa.** "Não achamos esta página", e não
  "Você digitou um endereço errado".
- **Sempre uma saída.** Voltar ao início, buscar, tentar de novo, pedir acesso.
  Tela de erro sem botão é beco.
- **Sem código técnico na cara.** O "404" e o identificador da requisição
  cabem pequenos, no `meta` acima do título, para quem vai abrir chamado; nunca
  no título.

## Quando não usar

- **Erro dentro de uma tela que continua funcionando** é `Alert`. A ilustração
  toma o lugar do conteúdo; o `Alert` mora ao lado dele e deixa trabalhar.
- **Desfecho de uma ação da pessoa** (pagamento recusado, pedido confirmado) é o
  `Result` com `tone`, sem ilustração: o disco com o símbolo diz sucesso ou
  falha numa olhada, e o desenho não diz.
- **Vazio pequeno**, numa coluna de tabela ou num menu, é o `EmptyState` com
  `icon`. Desenho de 96 px numa célula ocupa mais que o dado que faltou.
- **Carregando** é `Skeleton` ou `Spinner`. Ilustração de espera faz a pessoa
  achar que a tela já respondeu.
- **Marca e ilustração editorial** (a página de boas-vindas, o e-mail de
  campanha) não é esta peça: o conjunto é fixo de propósito, para as telas de
  sistema serem reconhecíveis de um produto para o outro.

## No React Native

Traduz em `@rivocode/ui-native/illustrations`, com as mesmas nove peças, o mesmo `name` e as mesmas três medidas (`sm` 96, `md` 160, `lg` 240). A geometria é a mesma do web, dividida em `shared/illustration.ts`: o desenho do celular é o do navegador, traço a traço.

**Desenha com o `react-native-svg`, peer da raiz**, como o `/chart`, e mora em caminho próprio pelo peso: quem não mostra tela de erro desenhada não carrega os nove desenhos. A cor de cada forma vem do papel em `useRivo().colors`, o mesmo que a classe pinta, então o tema de cliente chega sem prop nenhuma.

```tsx
import { NotFound } from "@rivocode/ui-native/illustrations";

<Result
  illustration={<NotFound size="lg" />}
  title="Não achamos esta tela"
  actions={<Button onPress={goHome}>Voltar ao início</Button>}
/>
```

O desenho fica escondido do leitor de tela. O objeto sobe e aparece ao montar, em `slow`, e depois toca a mesma cena do web, uma vez, no `react-native-reanimated` que o pacote já usa: os tempos e os quadros vêm de `ILLUSTRATION_MOTIONS`, a mesma tabela que o CSS do web segue. Com "reduzir movimento", ou `animated={false}`, nasce no quadro final. Sem `className` por parte: são formas de um desenho só, e o `className` veste a caixa de fora.

## Importação

```tsx
import { Illustration } from '@rivocode/ui/illustrations'
```

## Exemplos

### Página não encontrada

```tsx
import { Button, Card, EmptyState, Result } from '@rivocode/ui'
import {
  EmptyList,
  Forbidden,
  ILLUSTRATION_NAMES,
  Illustration,
  NoData,
  NotFound,
  Offline,
} from '@rivocode/ui/illustrations'

export function PageNotFound() {
  return (
    <Result
      layout="page"
      focusOnMount={false}
      illustration={<NotFound size="lg" />}
      meta="Erro 404"
      title="Não achamos esta página"
      description="O endereço pode ter mudado. A busca acha o pedido pelo número ou pelo cliente."
      actions={
        <>
          <Button>Voltar ao início</Button>
          <Button variant="secondary">Buscar</Button>
        </>
      }
    />
  )
}
```

### Sem permissão

```tsx
import { Button, Card, EmptyState, Result } from '@rivocode/ui'
import {
  EmptyList,
  Forbidden,
  ILLUSTRATION_NAMES,
  Illustration,
  NoData,
  NotFound,
  Offline,
} from '@rivocode/ui/illustrations'

export function NoPermission() {
  return (
    <Result
      layout="page"
      focusOnMount={false}
      illustration={<Forbidden size="lg" />}
      title="Esta área é do financeiro"
      description="Seu perfil não vê as contas a pagar. Quem administra a empresa pode liberar o acesso."
      actions={
        <>
          <Button>Pedir acesso</Button>
          <Button variant="secondary">Voltar</Button>
        </>
      }
    />
  )
}
```

### Sem conexão

```tsx
import { Button, Card, EmptyState, Result } from '@rivocode/ui'
import {
  EmptyList,
  Forbidden,
  ILLUSTRATION_NAMES,
  Illustration,
  NoData,
  NotFound,
  Offline,
} from '@rivocode/ui/illustrations'

export function OfflinePage() {
  return (
    <Result
      layout="page"
      focusOnMount={false}
      illustration={<Offline size="lg" />}
      title="Sem conexão"
      description="Os pedidos aparecem assim que a internet voltar. Nada do que você preencheu se perdeu."
      actions={<Button variant="secondary">Tentar de novo</Button>}
    />
  )
}
```

### As três medidas

```tsx
import { Button, Card, EmptyState, Result } from '@rivocode/ui'
import {
  EmptyList,
  Forbidden,
  ILLUSTRATION_NAMES,
  Illustration,
  NoData,
  NotFound,
  Offline,
} from '@rivocode/ui/illustrations'

export function Sizes() {
  return (
    <div className="flex flex-wrap items-end gap-6">
      <EmptyList size="sm" />
      <EmptyList size="md" />
      <EmptyList size="lg" />
    </div>
  )
}
```

### As nove

```tsx
import { Button, Card, EmptyState, Result } from '@rivocode/ui'
import {
  EmptyList,
  Forbidden,
  ILLUSTRATION_NAMES,
  Illustration,
  NoData,
  NotFound,
  Offline,
} from '@rivocode/ui/illustrations'

export function Family() {
  return (
    <div className="grid w-full grid-cols-2 gap-4 sm:grid-cols-3">
      {ILLUSTRATION_NAMES.map((name) => (
        <Card key={name} className="flex flex-col items-center gap-2 p-4">
          <Illustration name={name} size="sm" />
          <code className="text-xs text-fg-muted">{name}</code>
        </Card>
      ))}
    </div>
  )
}
```

### Gráfico sem dado

```tsx
import { Button, Card, EmptyState, Result } from '@rivocode/ui'
import {
  EmptyList,
  Forbidden,
  ILLUSTRATION_NAMES,
  Illustration,
  NoData,
  NotFound,
  Offline,
} from '@rivocode/ui/illustrations'

export function EmptyChart() {
  return (
    <Card className="w-full max-w-md">
      <EmptyState
        illustration={<NoData size="sm" />}
        title="Nenhuma venda em março"
        description="Escolha outro período para ver o faturamento."
      />
    </Card>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `name` | `IllustrationName` | sim |  | - | Qual das nove situacoes: `not-found`, `forbidden`, `server-error`, `offline`, `maintenance`, `empty-list`, `no-results`, `empty-inbox` ou `no-data`. |
| `animated` | `boolean` |  | `true` | - | O objeto sobe e aparece na montagem, em `--rc-duration-slow`, e depois conta a cena uma vez so - o selo balanca, o cadeado sacode, a engrenagem gira - e para no quadro final antes de 2,5 s. |
| `size` | `IllustrationSize` |  | `"md"` | - | A largura do desenho: `sm` 96px, para cartao e painel lateral; `md` 160px, o padrao, para o vazio de uma lista ou de uma secao; `lg` 240px, so para a pagina inteira, como o 404. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [Alert](/componentes/alert.md)
- [Bacalhau](/componentes/bacalhau.md)
- [Badge](/componentes/badge.md)
- [Banner](/componentes/banner.md)
- [CookieConsent](/componentes/cookie-consent.md)
- [EmptyState](/componentes/empty-state.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
