# StatCard

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

Cartão de número em destaque — um valor grande em vermelho e o rótulo embaixo —, para mostrar a escala da instituição em grade.

- Função: Conteúdo
- Também chamado de: número, estatística, indicador, métrica
- Mora em: `app/components/molecules/StatCard.tsx`
- Página: [https://phorte-design-system.vercel.app/styleguide/peca/StatCard](https://phorte-design-system.vercel.app/styleguide/peca/StatCard)
- Ficha no Storybook: [components-complex-statcard](https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-complex-statcard--docs)
- Prévia ao vivo, sozinha: [https://phorte-design-system.vercel.app/previa/StatCard/0](https://phorte-design-system.vercel.app/previa/StatCard/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 { StatCard } from '@/app/components/molecules/StatCard';

<StatCard value={…} label={…}>…</StatCard>
```

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

## Uso

### Variantes na ficha

1. [Padrão](https://phorte-design-system.vercel.app/previa/StatCard/0)
2. [Em Grade](https://phorte-design-system.vercel.app/previa/StatCard/1)
3. [Rótulo longo](https://phorte-design-system.vercel.app/previa/StatCard/2)
4. [Em grupo](https://phorte-design-system.vercel.app/previa/StatCard/3)
5. [Contagem ao rolar](https://phorte-design-system.vercel.app/previa/StatCard/4)
6. [Número grande](https://phorte-design-system.vercel.app/previa/StatCard/5)

Em grade de três ou quatro, para números que provam algo: anos de história, alunos formados, cursos.

### Quando não usar

Para uma faixa de números em campanha, use o MetricsBanner. Para um conteúdo com título e texto, o Card.

### Faça

- Escreva o `value` como ele deve aparecer ("+250.000", "98%", "4,5"): a contagem lê o número de dentro do texto e termina nele, com o mesmo prefixo, sufixo, milhar e casas (E126).
- Desligue a contagem (`animar={false}`) quando o número muda em tempo real.
- Escreva o valor já formatado, com a unidade ("+30", "250 mil").
- Rótulo curto que diga o que o número conta.
- Em grade, ponha os cartões num `StatGroup` (E72): vira uma lista de definições, e cada número fica ligado ao que mede.

### Evite

- Número sem fonte ou sem data, que envelhece sem ninguém notar.
- Usar como link: o cartão não é clicável.

### Anatomia

1. **Cartão** — Um Card com o espaço no `CardContent` (E72), texto centrado. No `StatGroup`, o cartão é o par da `<dl>` e leva o espaço.
2. **Valor** — `font-black`, vermelho de interface, com o tamanho pelo comprimento (E126): até 6 caracteres, 30/36/48px (celular, tablet, computador); até 9, um degrau abaixo; mais, dois. A largura do valor final fica reservada enquanto conta.
3. **Rótulo** — `text-sm`, `--muted-foreground`.
4. **Grupo** — `StatGroup`: `<dl>` em grade (duas colunas, quatro a partir de 1024px); no cartão, `dt` o rótulo e `dd` o número, com o número em cima pela ordem visual (`flex-col-reverse`).

### Estados

| Estado | O que muda |
| --- | --- |
| Padrão | Borda do Card. |
| Hover | Nada (E68): o hover de borda saiu, porque o cartão não é clicável. |

### Comportamento

| Situação | O que acontece |
| --- | --- |
| O cartão entra na tela | O número sobe de zero até o valor em 1,6s (tempo fixo, `DURACAO_DA_CONTAGEM`), desacelerando no fim, e termina no texto exato — testado na ficha (E126). |
| Movimento reduzido | Não conta: o número aparece pronto. |
| Já à vista ao carregar | Fica pronto: a contagem é para quem rola até o cartão, e o número cheio não cai para zero — testado na ficha. |
| Dentro de uma caixa que rola | Conta quando a caixa rola até ele (E158): "à vista" é o que o navegador mostra de fato, descontado o corte da caixa, e não a altura da janela. Veja a ficha "Contagem ao rolar" — role a caixa. Testado na ficha. |
| Número longo em cartão estreito | O tamanho desce um ou dois degraus pelo comprimento do texto e, como último recurso, o número quebra dentro do cartão — testado na ficha. |
| Rótulo longo | Quebra linha, centrado. |

### Relacionados

- [MetricsBanner](https://phorte-design-system.vercel.app/styleguide/md/MetricsBanner.md) — Faixa de números de campanha.
- [Card](https://phorte-design-system.vercel.app/styleguide/md/Card.md) — A superfície que ele usa.

## Especificação

### Propriedades

| Prop | Tipo | Padrão | Obrigatória | Descrição |
| --- | --- | --- | --- | --- |
| `value` | `string` | — | sim |  |
| `label` | `string` | — | sim |  |
| `animar` | `boolean` | `true` | não | O número sobe de zero até o valor quando o cartão entra na tela (E126). Padrão ligado; com movimento reduzido no sistema, não anima. Desligue quando o número muda em tempo real. |

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

### Tokens de cor

| Token | Valor | Usado como |
| --- | --- | --- |
| `--muted-foreground` | #595959 | `text-muted-foreground` |
| `--primary` | #D42B2B | `text-primary` |

## Acessibilidade

### Leitor de tela

- Solto, valor e rótulo são dois parágrafos, lidos em sequência ("+30", "anos de história").
- No `StatGroup`, uma lista de definições: o leitor anuncia quantos itens há e lê o rótulo com o número ("anos de história: +30") — conferido no teste da ficha.
- Quem ouve recebe só o valor final, em texto oculto; a contagem e a reserva de largura são `aria-hidden` (E126).

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

- `251416b` 2026-10-01 — E159: Testimonials — o vídeo toca dentro do cartão, YouTube e Vimeo
- Histórico completo no GitHub: https://github.com/srbunnie/Pos-Phorte-Design-System/commits/main/app/components/molecules/StatCard.tsx