Fluxo de Escolha de Componentes

Um checklist aninhado para escolher o componente certo quando vários parecem "próximos o suficiente". Use isso antes de recorrer a shadcn/ui, MUI, Headless UI, React Native Paper ou Tamagui - o primitivo errado trava fricção que nenhum estilo pode corrigir depois.

Este guia trata React web e React Native / web mobile como cidadãos de primeira classe. Onde eles divergem, a recomendação chama isso explicitamente.

Etapa 1 - Enquadre a decisão antes de navegar por bibliotecas de componentes

• O que o usuário está realmente fazendo? (selecionando, navegando, revelando, confirmando, inserindo, monitorando)
• Quantas opções / estados / etapas estão envolvidas? (1, 2, 3–5, 6–15, 16+, ilimitado)
• A escolha é mutuamente exclusiva ou multi-seleção?
• O resultado é reversível ou destrutivo? (destrutivo exige mais fricção)
• Qual é a superfície principal - desktop, web mobile, iOS nativo, Android nativo, ou todos os quatro?
• Qual é a modalidade de entrada? (mouse, toque, apenas teclado, leitor de tela, voz, caneta)
• O componente está no caminho crítico (checkout, cadastro) ou é ambiente (configurações, filtros)?
• As opções são conhecidas no momento da compilação, buscadas uma vez, ou transmitidas/paginadas?
• O usuário precisa comparar opções lado a lado, ou escanear sequencialmente?

Se você não conseguir responder a essas perguntas em uma frase cada, pare e esclareça com o solicitante. As decisões de componentes abaixo são consequência desse enquadramento.

Etapa 2 - Escolha a família

Combine a intenção do usuário com uma família, e depois aprofunde-se no componente específico na Etapa 3.

• Seleção - usuário escolhe 1+ de um conjunto conhecido → Etapa 3A
• Estado binário - usuário alterna ligar/desligar → Etapa 3B
• Revelação - usuário revela/esconde conteúdo no local → Etapa 3C
• Overlay / transitório - conteúdo flutua acima da página → Etapa 3D
• Navegação - usuário se move entre visualizações → Etapa 3E
• Conteúdo sequencial - usuário pagina através de uma série → Etapa 3F
• Entrada numérica / de intervalo → Etapa 3G
• Notificação / status → Etapa 3H

Etapa 3A - Seleção: rádio, checkbox, select, combobox, segmentado, chips

A família mais ambígua. Decida por contagem, exclusividade e espaço de tela.

Seleção única (mutuamente exclusiva)

• 2 opções que cabem em uma linha? → Controle segmentado / Grupo de Alternância (amigável para mobile, instantâneo, sem estado oculto). Web: ToggleGroup. Nativo: controle segmentado / SegmentedButtons (Paper).
• 2–5 opções, todas importantes para ver de uma vez? → Grupo de rádio. Melhor para formulários onde a própria escolha é informativa (velocidade de envio, nível do plano).
• 6–15 opções? → Select / Dropdown. Em mobile, prefira o <select> nativo na web e o seletor nativo (Picker / ActionSheetIOS / BottomSheet) no React Native - eles obtêm a UI de roda/sheet do nível do SO gratuitamente.
• 16+ opções ou buscadas dinamicamente? → Combobox / Autocompletar com digitação para filtrar. Necessário quando a rolagem se torna dolorosa.
• Opções hierárquicas ou agrupadas (país → estado)? → Select em cascata ou Combobox com seções agrupadas, não rádios aninhados.
• Opções visuais (cores, avatares, templates)? → Cartões de rádio ou grupo de chips, não um dropdown de texto.

Armadilha mobile: um dropdown personalizado que funcionou lindamente no desktop geralmente parece quebrado em um telefone (alvo de toque pequeno, sem rolagem de momentum, sem haptics). Prefira seletores nativos em superfícies de toque, a menos que você tenha um motivo forte.

Multi-seleção

• 2–7 opções, todas visíveis? → Grupo de checkboxes.
• 8+ opções ou filtráveis? → Combobox de multi-seleção com chips para valores selecionados.
• Estilo de tag / categoria com entrada de texto livre? → Entrada de tag / entrada de chip.
• Mutuamente exclusivo dentro de categorias (facetas de filtro)? → Painel de filtro facetado (grupos de checkboxes dentro de acordions ou popovers).

Etapa 3B - Estado binário: switch, checkbox, botão de alternância

Estes três não são intercambiáveis. Escolha por quando a mudança entra em vigor e que tipo de valor representa.

• Configuração que entra em vigor imediatamente, sem necessidade de submissão? → Switch (ex: "Modo escuro", "Notificações"). Em nativo, use o Switch da plataforma - iOS e Android o renderizam de forma diferente e os usuários esperam isso.
• Uma das muitas opções em um formulário, aplicada na submissão? → Checkbox (ex: "Eu concordo com os termos", "Inscrever-se na newsletter").
• Uma ação que muda o estado da visualização, como negrito/itálico em um editor? → Botão de alternância (botão de ícone com aria-pressed).
• Uma ação verdadeiramente transitória que faz algo agora e não é um estado? → Botão, não uma alternância.

Acessibilidade: switches precisam de role="switch" (web) e o accessibilityRole correto (switch, nativo). Uma checkbox estilizada como um switch falha com leitores de tela.

Etapa 3C - Revelação: acordeão vs colapsível vs abas vs detalhes

Todos os quatro escondem conteúdo até ser solicitado. Diferem em quantos painéis podem estar abertos e se os itens são pares.

• Muitos itens pares independentes, qualquer número pode estar aberto ao mesmo tempo (FAQ)? → Acordeão (modo multi-abertura).
• Muitos itens pares, apenas um aberto por vez (especificações / envio / avaliações)? → Acordeão (modo de abertura única) ou Abas - escolha Abas se os painéis forem aproximadamente iguais em importância e comprimento, Acordeão se forem prosa longa.
• Uma única região de mostrar/esconder - "Mostrar mais", configurações avançadas? → Colapsível (uma revelação, sem grupo).
• Expansão inline minúscula, com sensação nativa, sem necessidade de estado JS? → <details> / <summary> na web. Nativo do navegador, a11y gratuito, SEO gratuito, descoberta Ctrl+F gratuita.
• Contexto mobile, painéis são de largura total e o conteúdo é pesado? → Acordeão (Abas ficam apertadas abaixo de ~360px).
• Contexto mobile, o conteúdo é curto e a comparação lado a lado ajuda? → Abas com rolagem horizontal para overflow.

Anti-padrão: abas com 7+ itens em mobile. Ou mude para um seletor / segmentado rolável, ou repense a IA.

Etapa 3D - Overlays: modal vs drawer vs popover vs tooltip vs toast

Escolha por roubo de foco, dismissibilidade e tamanho do conteúdo.

• Bloqueia a tarefa inteira até ser tratada, pode ter um formulário? → Modal / Diálogo. Prende o foco, retorna o foco ao fechar.
• Painel lateral de conteúdo relacionado, página abaixo permanece significativa? → Drawer / Sheet. Em mobile, prefira bottom sheet (alcançável pelo polegar); em desktop, side drawer.
• Menu contextual pequeno ou informação ancorada a um gatilho? → Popover.
• Linha única, apenas hover, rótulo suplementar? → Tooltip. ⚠️ Tooltips não existem em dispositivos de toque - nunca coloque informações críticas lá. Usuários de mobile sentirão falta disso.
• Confirmar uma ação destrutiva? → Diálogo de alerta (um modal mais restrito com confirmação/cancelamento explícito).
• Feedback por tempo limitado após uma ação ("Salvo")? → Toast / Snackbar. Não coloque ações necessárias em um toast - ele se auto-descarta.
• Status persistente na página que o usuário deve reconhecer? → Alerta / Banner (permanece até ser dispensado ou corrigido).

Regra geral mobile: se você usaria um popover ou tooltip no desktop, use um bottom sheet no mobile. Overlays ancorados se comportam mal quando o teclado abre.

Etapa 3E - Navegação: abas vs sidebar vs segmentado vs breadcrumb vs bottom nav

• 2–5 visualizações pares dentro de uma página? → Abas.
• 5–15 destinos em todo o aplicativo, primeiro desktop? → Navegação lateral (sidebar).
• 3–5 destinos de nível superior em mobile? → Barra de abas inferior (padrão nativo no iOS/Android; na web mobile, navegação fixa inferior).
• Mostrando profundidade / localização em uma hierarquia? → Breadcrumb.
• 2–4 modos de visualização (lista / grade / mapa)? → Controle segmentado no cabeçalho, não abas.
• Muitos destinos com overflow? → Sidebar com seções colapsáveis (web) ou drawer acionado por hambúrguer (mobile).

Etapa 3F - Conteúdo sequencial / paginado: carrossel, paginação, scroll infinito, stepper

Carrossel horizontal vs vertical

• Itens que o usuário está navegando (produtos, fotos, recomendações)? → Carrossel horizontal (pares com swipe de polegar no mobile, arrasto de mouse no desktop).
• Itens que o usuário está consumindo sequencialmente (stories, reels, feed)? → Carrossel vertical / paginador vertical (modelo TikTok / Stories). Certo quando cada item é tela cheia e imersivo.
• Ambos os eixos parecem plausíveis (uma galeria)? → Horizontal, exceto em telas de TV / paisagem grandes onde vertical é lido como uma lista e horizontal como destacado.
• Mais de ~10 itens? → Não use carrossel - mude para um rail rolável (sem avanço automático, sem pontos de paginação), uma grade, ou paginação.
• Carrossel principal / promocional? → Considere fortemente não construir um. Carrosséis principais com avanço automático têm quedas de engajamento bem documentadas; um herói estático ou dois cards empilhados geralmente superam.

Paginação vs scroll infinito vs carregar mais

• Usuário precisa de link profundo e previsibilidade do botão voltar (resultados de busca)? → Paginação.
• Feed mobile onde o engajamento importa mais que a navegação? → Scroll infinito, mas com um rodapé que ainda é alcançável (use um botão "Carregar mais" no final do primeiro lote prático, ou exponha um rodapé em um drawer).
• Usuário precisa saber quanto resta? → Botão carregar mais com uma contagem, não infinito.
• Formulário / assistente multi-etapas? → Stepper, com um indicador de progresso visível.

Etapa 3G - Entrada numérica e de intervalo: slider, stepper, input, segmentado

• Valor impreciso onde a sensação importa (volume, brilho)? → Slider.
• Valor preciso que o usuário conhece (idade, quantidade)? → Entrada numérica com inputMode="numeric" no mobile.
• Pequeno intervalo de inteiros, ações ±1 parecem naturais (quantidade do carrinho)? → Stepper / NumberInput com botões ±. Alvos de toque amigáveis são essenciais aqui (mínimo de 44pt).
• Intervalo com dois pontos finais (preço mínimo – preço máximo)? → Slider de intervalo.
• 3–5 baldes discretos? → Controle segmentado ("P / M / G / GG"), não um slider.
• Data ou hora? → Seletor nativo no mobile (<input type="date"> web, DatePickerIOS / DatePickerAndroid / seletor de data da comunidade no RN). Calendários personalizados só são corretos quando o intervalo, multi-seleção ou regras de negócios o exigem.

Etapa 3H - Notificação / status: toast, alert, banner, badge, skeleton

• Ação acabou de ser concluída, sem necessidade de reconhecimento? → Toast (3–5s).
• Mensagem persistente do sistema ("Você está offline")? → Banner no topo.
• Problema inline de formulário/campo? → Alerta inline abaixo do campo.
• Erro ou aviso no nível da página? → Componente de alerta no topo da área de conteúdo.
• Indicador numérico ou booleano em outro elemento ("3 não lidos")? → Badge.
• Carregando conteúdo que o usuário está prestes a ver? → Skeleton correspondendo ao layout final (não um spinner) para ganhos de performance percebida.
• Trabalho de fundo indeterminado? → Spinner / indicador de progresso.

Etapa 4 - Verificações transversais antes de confirmar

Execute esta lista contra o componente que você escolheu.

• Alvos de toque ≥ 44pt (iOS) / 48dp (Android)? Especialmente para steppers, switches, botões de fechar.
• Navegável por teclado? A ordem de tabulação faz sentido, Enter/Espaço ativam, Escape fecha overlays.
• Leitor de tela anuncia mudanças de estado? aria-expanded, aria-pressed, aria-selected, role="switch", aria-live para toasts.
• Funciona sem JS / em redes lentas? <select>, <details>, <form> nativos degradam graciosamente; substitutos personalizados geralmente não o fazem.
• Respeita prefers-reduced-motion? Carrosséis, acordeões, sheets devem pular ou encurtar a animação.
• Seguro para direita-para-esquerda? Carrosséis, breadcrumbs, sliders precisam de direção ciente de RTL.
• Usuários de mobile apenas com teclado (teclados Bluetooth no iPad)? Mesmas regras de foco que o desktop.
• Tokens de modo escuro aplicados? Não apenas a superfície - bordas, anéis de foco, estados desativados.
• O componente escala para o conteúdo realista mais longo? Strings traduzidas podem ser 30–60% mais longas.
• O componente tem um estado vazio sensato? Selects vazios, listas vazias, sem resultados.

Etapa 5 - Paridade Web ↔ Mobile: mapa rápido

Mesma intenção, primitivo diferente. Escolha o nativo da plataforma ao enviar React Native, e o equivalente web mais próximo ao enviar web.

Etapa 6 - Padrões quando você está preso

Se você passou pelo checklist e duas opções ainda parecem igualmente válidas, use estes padrões - eles são a escolha de menor risco na maioria das vezes:

• Seleção de tamanho desconhecido → Combobox.
• Alternância em uma tela de configurações → Switch.
• Alternância em um formulário enviado posteriormente → Checkbox.
• Um de três modos de visualização → Controle segmentado.
• Confirmar uma ação destrutiva → Diálogo de alerta com o botão destrutivo estilizado em vermelho e rotulado com o verbo ("Excluir conta"), não "OK".
• Overlay mobile → Bottom sheet.
• Dropdown de seleção única mobile → Seletor nativo.
• Lista de 50+ itens → Lista virtualizada (react-window web, FlatList / FlashList nativo), nunca um .map() simples.

Referências cruzadas

• Accordion, Tabs - decisões de revelação na Etapa 3C
• Radio Group, Checkbox, Select, Dropdown, Toggle Group - Etapa 3A
• Switch - Etapa 3B
• Modal, Popover, Tooltip, Toast, Alert - Etapa 3D
• Sidebar, Breadcrumb, Pagination - Etapa 3E e 3F
• Slider - Etapa 3G
• Badge, Skeleton - Etapa 3H