---
name: ui-nova-escolher-componente
description: Escolher o componente certo da ui-nova (vueui-nova-kit) antes de criar UI, evitando duplicar o que já existe. Use quando for adicionar qualquer elemento visual num projeto com ui-nova, quando houver dúvida entre componentes parecidos (Alert vs Banner vs Toast, Select vs RadioGroup vs SegmentedControl, Dialog vs Sheet vs Drawer) ou quando alguém propuser criar um componente novo.
---

# Escolher o componente ui-nova certo (reuso obrigatório)

> `references/inventario.md` é **gerado** por `scripts/gen-skill-refs.mjs`.

## Procedimento

1. Descreva a necessidade em uma frase: *"mostrar 3–5 opções exclusivas sempre visíveis"*.
2. Abra a categoria certa em `references/inventario.md` (primitives, form, navigation, data,
   feedback, containment, layout, motion).
3. Aplique a árvore de decisão abaixo.
4. Só proponha componente novo se **nenhum** item servir **e** a composição de existentes não
   resolver. Nesse caso, escreva a justificativa (o que falta e em qual componente) e pare para
   pedir aprovação.

## Árvore de decisão (pares que mais confundem)

| Necessidade | Use | Não use |
|---|---|---|
| 2–5 opções exclusivas, sempre visíveis, troca imediata | `VSegmentedControl` | `VRadioGroup` |
| Opções exclusivas num formulário (com rótulo/descrição) | `VRadioGroup` | `VSelect` se forem ≤ 5 |
| Muitas opções ou lista longa | `VSelect` | `VRadioGroup` |
| Liga/desliga com efeito imediato | `VSwitch` | `VCheckbox` |
| Aceite / item marcado que só vale ao enviar | `VCheckbox` | `VSwitch` |
| Mensagem contextual dentro do conteúdo | `VAlert` | `VToast` |
| Mensagem de página inteira, persistente | `VBanner` | `VAlert` |
| Confirmação efêmera de ação concluída | `VToast` (via host) | `VAlert` |
| Decisão que bloqueia o fluxo | `VDialog` (`variant="confirmation"`) | `VSheet` |
| Painel lateral de detalhes/edição | `VSheet` / `VDrawer` | `VDialog` |
| Métrica com variação | `VStatCard` | `VCard` + texto |
| Ranking/proporção simples | `VBarList` | `VBarChart` |
| Pares rótulo → valor | `VDescriptionList` | tabela de 2 colunas |
| Estado vazio | `VEmptyState` | texto solto |
| Carregando com layout conhecido | `VSkeleton` | `VSpinner` |
| Ação primária / secundária | `VButton` (`variant`) | `<button>` estilizado |
| Chip clicável / token removível | `VTag` | `VBadge` |
| Rótulo de status não clicável | `VBadge` / `VStatusMark` | `VTag` |

> A tabela acima é curada. As descrições e variantes na referência são geradas do código e mandam
> em caso de conflito.

## Sinais de alerta (pare e reavalie)

- Você está escrevendo `<div class="card">`, `<button class="btn">`, `<input>` cru ou CSS de cor.
- Você vai "embrulhar" um `V*` só para mudar margem, cor ou tamanho.
- Você criou um componente com nome parecido a um `V*` existente.

## Arquivos

- `references/inventario.md`: **gerado**. Todos os componentes por categoria, com a descrição de uma
  linha e as variantes.
- Para props detalhadas: `../ui-nova-vue/references/components.md`.
