# IconBox

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

Ícone dentro de um quadrado ou círculo de fundo suave, para ilustrar um item de lista ou de grade — em quatro tamanhos, quatro tratamentos e quatro arredondamentos. Decorativo por padrão; com `label`, uma imagem nomeada.

- Função: Conteúdo
- Também chamado de: ícone com fundo, caixa de ícone, selo de ícone
- Mora em: `app/components/atoms/IconBox.tsx`
- Página: [https://phorte-design-system.vercel.app/styleguide/peca/IconBox](https://phorte-design-system.vercel.app/styleguide/peca/IconBox)
- Ficha no Storybook: [components-base-iconbox](https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-base-iconbox--docs)
- Prévia ao vivo, sozinha: [https://phorte-design-system.vercel.app/previa/IconBox/0](https://phorte-design-system.vercel.app/previa/IconBox/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 { IconBox } from '@/app/components/atoms/IconBox';

<IconBox icon={…}>…</IconBox>
```

O `…` marca as props obrigatórias — ver *Propriedades*.

## Uso

### Variantes na ficha

1. [Padrão](https://phorte-design-system.vercel.app/previa/IconBox/0)
2. [Variantes](https://phorte-design-system.vercel.app/previa/IconBox/1)
3. [Tamanhos](https://phorte-design-system.vercel.app/previa/IconBox/2)
4. [Com Texto Ao Lado](https://phorte-design-system.vercel.app/previa/IconBox/3)
5. [Com rótulo](https://phorte-design-system.vercel.app/previa/IconBox/4)
6. [Interativo](https://phorte-design-system.vercel.app/previa/IconBox/5)

No começo de itens de uma grade de benefícios ou de uma lista de passos, para dar ritmo visual.

### Quando não usar

Para uma pessoa, use o Avatar. Para um botão com ícone, o Button com `aria-label`. Para ícone sozinho no texto, o próprio ícone do `lucide-react`.

### Faça

- Passe o componente do ícone (`icon={Award}`), não o elemento.
- Deixe o texto ao lado dizer o que o ícone ilustra: sem `label`, ele é decorativo.
- Passe `label` quando o ícone for a informação, sem texto ao lado — a modalidade só por ícone (E64).
- Use `interativo` dentro de um cartão ou link com `group`: a caixa acende junto no hover.
- Mantenha o mesmo tamanho e tratamento em todos os itens de uma grade.

### Evite

- Usar o IconBox como botão: não tem foco nem alvo.
- Um ícone que carrega informação sozinho sem `label`: ele fica `aria-hidden`, e a informação some para quem ouve.

### Anatomia

1. **Caixa** — Quadrado de 32 a 80px, arredondado pelo `rounded` (círculo por padrão).
2. **Ícone** — O átomo `Icone` (E66), no degrau da caixa: 16, 24, 32 e 32px — o `xl` usava 40, fora da escala. Traço do degrau (2; 1,75 no 32px), 1,5 no `outline`.

### Estados

| Estado | O que muda |
| --- | --- |
| Primário | `primary` (padrão): fundo `--primary-subtle` (sólido, E64) e ícone vermelho — 4,32:1. |
| Secundário | `secondary`: fundo `--secondary-subtle` e ícone verde — 4,28:1. |
| Interativo | Com `interativo`, o `group-hover` do pai enche a caixa na cor cheia e deixa o ícone claro (E64). |
| Contorno | `outline`: sem fundo, borda `--border`, ícone cinza de traço fino. |
| Fantasma | `ghost`: sem fundo, ícone `--ink`. |

### Comportamento

| Situação | O que acontece |
| --- | --- |
| Qualquer variante | Sem foco. Só reage ao hover com `interativo`, pelo `group` do pai. |

### Relacionados

- [Card](https://phorte-design-system.vercel.app/styleguide/md/Card.md) — A superfície onde o IconBox costuma entrar.
- [Avatar](https://phorte-design-system.vercel.app/styleguide/md/Avatar.md) — Para uma pessoa.

## Especificação

### Propriedades

| Prop | Tipo | Padrão | Obrigatória | Descrição |
| --- | --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | não | Variante do `cva`. |
| `variant` | `'primary' \| 'secondary' \| 'outline' \| 'ghost'` | `'primary'` | não | Variante do `cva`. |
| `rounded` | `'md' \| 'lg' \| 'xl' \| 'full'` | `'full'` | não | Variante do `cva`. |
| `interativo` | `boolean` | `false` | não | Reage ao `group-hover` do pai (E64): o cartão ou link inteiro é o alvo, e a caixa acende junto — enche na cor e o ícone fica claro. |
| `icon` | `LucideIcon` | — | sim |  |
| `label` | `string` | — | não | Quando o ícone **é** a informação, sem texto ao lado (E64) — a modalidade só por ícone, por exemplo. Com ele, a caixa vira `role="img"` com este nome; sem ele, é decoração, como sempre foi. |

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

### Medidas

| Parte | Valor | Classe |
| --- | --- | --- |
| `sm` | 32px, ícone de 16px | `w-8 h-8` |
| `md` | 48px, ícone de 24px | `w-12 h-12` |
| `lg` | 64px, ícone de 32px | `w-16 h-16` |
| `xl` | 80px, ícone de 32px (E66) | `w-20 h-20` |

### Tokens de cor

| Token | Valor | Usado como |
| --- | --- | --- |
| `--primary` | #D42B2B | `bg-primary`, `text-primary` |
| `--secondary` | #0B8434 | `bg-secondary`, `text-secondary` |
| `--border` | #E5E5E5 | `border-border` |
| `--foreground` | #1A1A1A | `text-ink` |
| `--muted-foreground` | #595959 | `text-muted-foreground` |
| `--primary-foreground` | #FFFFFF | `text-primary-foreground` |
| `--primary-subtle` | #FBEAEA | `bg-primary-subtle` |
| `--secondary-foreground` | #FFFFFF | `text-secondary-foreground` |
| `--secondary-subtle` | #EAF4EE | `bg-secondary-subtle` |

## Acessibilidade

### Leitor de tela

- O ícone é `aria-hidden`: sem `label`, a caixa não é lida e o sentido tem de estar no texto ao lado.
- Com `label`, a caixa é `role="img"` com esse nome — conferido no teste da ficha.

### 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/IconBox.tsx` | Disponível |
| Ficha | https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-base-iconbox--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

- `fdd10ff` 2026-09-29 — ESTADO: E109 concluida, roteiro final fechado; proximo o merge na main
- Histórico completo no GitHub: https://github.com/srbunnie/Pos-Phorte-Design-System/commits/main/app/components/atoms/IconBox.tsx