# UX e Design System

## Objetivo

A interface deve atender escritório e operação. O usuário precisa saber sempre em qual grupo, empresa, estabelecimento e depósito está trabalhando.

## Estrutura visual

- topo com marca, contexto atual, busca, notificações e usuário;
- menu lateral por módulos habilitados e permissões;
- breadcrumb sem sublinhado;
- título, descrição curta e ações principais;
- conteúdo com largura adequada a ERP;
- painel lateral ou modal para ações breves;
- página dedicada para processos complexos.

O seletor de contexto deve impedir troca silenciosa com formulário sujo e exibir claramente quando a visão for consolidada.

## Design tokens

Definir em CSS variables:

- cores de marca;
- fundo, superfície e borda;
- texto primário/secundário;
- sucesso, atenção, erro e informação;
- espaçamento em escala;
- raio, sombras, altura de controles;
- tipografia e densidade.

Tabelas usam zebra clara, bordas discretas e hover, seguindo a preferência visual já adotada pela N4STi. Status nunca depende somente de cor: incluir texto/ícone.

## Componentes mínimos

- botões e grupos de ações;
- campos, máscaras e autocomplete;
- busca assíncrona;
- seletor de empresa/estabelecimento;
- tabela com filtros, ordenação e paginação server-side;
- badge de status;
- timeline/histórico;
- modal de confirmação;
- drawer de detalhes;
- alertas/toasts;
- upload de imagens;
- leitura de código de barras;
- painel de erros de integração;
- impressão e reimpressão;
- empty state e skeleton/loading.

## Formulários

- labels sempre visíveis;
- obrigatoriedade indicada;
- validação ao sair do campo e no submit;
- erro junto ao campo e resumo no topo;
- preservar valores após erro;
- máscara não altera valor canônico;
- atalhos somente documentados;
- salvar rascunho em documentos extensos;
- alertar saída com alterações.

## Listagens

- filtros persistentes por usuário;
- colunas configuráveis futuramente;
- ações em menu, evitando excesso de botões;
- seleção em massa com confirmação de escopo;
- exportação assíncrona quando grande;
- totalizadores informam universo filtrado;
- paginação não carrega milhares de linhas no cliente.

## Fluxos por leitor

- foco automático no campo de leitura;
- aceitar scanners HID terminados por Enter;
- feedback visual e sonoro configurável;
- sucesso verde curto; erro vermelho persistente com motivo;
- impedir leitura duplicada acidental em janela configurada;
- permitir digitação manual apenas com permissão quando necessário;
- tela com botões grandes e alto contraste;
- registrar operador, estação e horário.

## Status compostos

Pedido deve mostrar separadamente:

- Comercial: rascunho/confirmado/cancelado.
- Estoque: não reservado/parcial/reservado.
- Expedição: aguardando/separando/conferido/despachado.
- Financeiro: pendente/parcial/pago/vencido.
- Fiscal: não emitido/processando/autorizado/rejeitado/cancelado.
- Marketplace: sincronizado/pendente/erro.

## Padrões de confirmação

- ações reversíveis simples: confirmação comum;
- ações financeiras/fiscais: resumo de efeitos e motivo;
- ação irreversível: digitação de confirmação ou segundo fator conforme risco;
- nunca usar apenas “Tem certeza?”; dizer o que será afetado.

## Acessibilidade

- navegação por teclado;
- foco visível;
- semântica e labels;
- contraste AA;
- mensagens anunciáveis;
- ícones com texto acessível;
- modal prende/restaura foco;
- zoom de 200% sem perda dos fluxos principais.

## Responsividade

Desktop é prioridade operacional. Tablet deve suportar estoque/expedição. Celular deve permitir consultas, aprovações e ações simples; telas industriais extensas podem usar experiência dedicada sem tentar comprimir toda tabela.

## Teste UX por funcionalidade

Antes de aceitar uma tela, verificar:

1. Usuário sabe onde está?
2. Sabe qual empresa e depósito serão afetados?
3. A ação principal é evidente?
4. Erros explicam correção?
5. É possível concluir apenas com teclado/leitor quando aplicável?
6. Duplo clique repete a operação?
7. Voltar/recarregar causa duplicidade?
8. Status pós-ação é visível?
9. Há caminho para histórico e origem?