SeConectai_Vendas/Etapas/V2/12-frontend-design-system.md

# Etapa 12 — Sistema de Design e Componentes Base

## Contexto do projeto

Continuação do frontend do **SeConectai Vendas**. A Etapa 11 entregou o
projeto Next.js configurado com Tailwind, tokens de design e estrutura
de pastas. Nenhum componente de UI reutilizável existe ainda.

Referência obrigatória: seção 6 (tokens) e seção 7 (lista de
componentes) do `10-frontend-schema-arquitetura.md`.

## Objetivo desta etapa

Construir a biblioteca de componentes base (`components/ui/`) que será
usada por **todas** as telas de negócio das próximas etapas. Tudo aqui
deve já nascer responsivo e acessível — as telas de negócio só vão
compor esses componentes, não reimplementar comportamento responsivo
caso a caso.

## Tarefas

1. **Base a partir do shadcn/ui**
   - Instalar e configurar shadcn/ui, mas customizar cada componente
     usado para consumir os tokens do projeto (não deixar cores/spacing
     hardcoded vindos do template padrão).
   - Justificar no código (comentário curto) qualquer componente que
     fugir do padrão shadcn por necessidade específica do projeto.

2. **Componentes a construir** (todos em `components/ui/`, cada um com
   suas variantes documentadas via comentário ou arquivo `.stories`
   opcional):

   - **Button**: variantes `primary` (usa `--color-primary`),
     `secondary`, `destructive`, `ghost`; tamanhos `sm`/`md`/`lg`; estado
     `loading` (spinner substituindo o label, sem mudar a largura do
     botão); estado `disabled`.
   - **Input / Textarea**: com label, texto de ajuda, estado de erro
     (borda + mensagem), prefixo/sufixo opcional (ex: "R$" para campos
     de valor).
   - **Select**: nativo estilizado ou baseado em Radix (via shadcn),
     com busca para listas longas (ex: seleção de cliente/produto).
   - **DatePicker**: seleção de data única e, quando necessário, período
     (usado nos filtros de dashboard/listagens).
   - **FormField**: wrapper que padroniza label + input + mensagem de
     erro + texto de ajuda — todo formulário do sistema deve usar esse
     wrapper, nunca montar label/erro manualmente.
   - **Table**: **componente central desta etapa**. Recebe colunas e
     dados de forma genérica (tipado com generics em TypeScript).
     Abaixo do breakpoint `md`, renderiza automaticamente como lista de
     **Cards empilhados** (cada linha vira um card com pares
     rótulo:valor, permitindo destacar 1–2 campos principais e colapsar
     o resto). Suporta: ordenação por coluna, estado de loading
     (skeleton), estado vazio (usa o `EmptyState`), paginação integrada.
   - **Modal / Sheet**: um único componente que se comporta como modal
     centralizado no desktop e como tela cheia (ou bottom sheet, definir
     e justificar qual) no mobile, controlado pelo mesmo breakpoint `md`.
   - **Toast**: sistema de notificação temporária (sucesso, erro, aviso,
     info), empilhável, com auto-dismiss configurável.
   - **Badge / StatusPill**: variantes semânticas mapeadas para os
     status de negócio já existentes no backend (`pendente`, `pago`,
     `atrasado`, `cancelado`, `ativo`, `inadimplente`, `suspenso`,
     `trial`, `confirmada`, `concluida`, `orcamento`) — cada status com
     cor e label em português já resolvidos aqui, para não repetir esse
     mapeamento em cada tela.
   - **Card**: contêiner base usado em dashboards e nas listas
     responsivas da Table.
   - **Pagination**: controles de página, compatível com os parâmetros
     de paginação da API do backend.
   - **EmptyState**: ilustração/texto + ação sugerida, usado em toda
     listagem vazia (ex: "Nenhum cliente cadastrado ainda" + botão
     "Cadastrar cliente").
   - **Skeleton**: blocos de carregamento reutilizáveis (linha de texto,
     card, linha de tabela).
   - **Tabs**: navegação em abas (usado, por exemplo, no detalhe de
     venda: Itens / Parcelas / Histórico).

3. **Acessibilidade (obrigatório, não opcional)**
   - Todos os componentes interativos com foco de teclado visível
     (`outline` customizado com a cor de foco do design system, não o
     padrão do navegador nem `outline: none` sem substituto).
   - Componentes baseados em Radix/shadcn já trazem boa parte da
     semântica ARIA — não remover isso ao customizar.
   - Respeitar `prefers-reduced-motion` em qualquer transição/animação.
   - Touch targets mínimos de 44x44px nos componentes interativos.

4. **Página de showcase**
   - Criar uma rota de desenvolvimento (ex: `/dev/componentes`, não
     exposta em produção) que renderiza todos os componentes acima com
     suas variantes, para revisão visual rápida em qualquer breakpoint
     sem precisar montar uma tela de negócio primeiro.

## Critérios de aceite

- [ ] Todos os componentes listados existem, tipados em TypeScript, com
      as variantes descritas
- [ ] `Table` alterna corretamente entre tabela (≥768px) e cards
      empilhados (<768px) na página de showcase
- [ ] `Modal/Sheet` alterna corretamente entre modal centralizado
      (desktop) e tela cheia/bottom sheet (mobile)
- [ ] `StatusPill` cobre todos os status de negócio listados, com cor e
      label em português
- [ ] Navegação por teclado (Tab) percorre todos os componentes
      interativos da página de showcase com foco visível
- [ ] Nenhum componente quebra ou tem overflow horizontal em 375px
- [ ] Página de showcase acessível apenas em ambiente de desenvolvimento