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