Padrões de interface¶
Regras que valem para todas as telas. Divergir delas exige decisão registrada, não preferência.
Cadastro e edição usam cortina lateral¶
Toda tela de cadastro e edição usa cortina lateral (KPDrawer), ancorada à direita. Não modal centralizado.
A cortina é empilhável, para permitir criar uma entidade relacionada sem perder o que já foi digitado. Telas legadas em modal migram sob demanda, não de uma vez.
Os tokens visuais continuam os mesmos: labels de 10px em caixa alta, inputs com 10px por 14px e raio de 10px, foco em #af8b61, overlay rgba(25,23,21,0.55). Muda o contêiner, não o vocabulário. Ver AD-009.
Leitura é exceção
Ler um documento é leitura em tela cheia, e usa modal centralizado. A cortina é para cadastro e edição.
Aviso, confirmação e notificação¶
Nunca usar alert() nem confirm() nativos
Todo feedback visual passa pelo KP Notify System: KPToast para aviso, KPPush para notificação e useKPAlert para confirmação. Toast desenhado em handoff é recriado com KPToast, nunca com componente próprio. Ver AD-004.
Ícones¶
Existe um sistema de ícones oficial, com um componente Icon e nomes canônicos. Ícone solto, SVG colado na tela ou biblioteca nova quebram o sistema.
Estado de tela de listagem vive na URL¶
Filtro, busca e cortina aberta ficam em searchParams, não em contexto global. Assim a tela é compartilhável por link e o botão de voltar funciona. Ver AD-006.
Taxonomia nunca é lista fixa no frontend¶
Etapa, origem, faixa de faturamento e motivo vêm do banco por endpoint de metadados. Lista escrita no componente fica desatualizada em silêncio. Ver AD-003.
Estado vazio explica o que fazer¶
Todo estado vazio diz qual é o próximo passo, não apenas "sem resultados".
Erro diz qual erro foi¶
Uma frase única para 403, 404, 500 e queda de rede esconde o defeito. O caso do anexo de WhatsApp ficou semanas sem diagnóstico por isso: a mesma frase cobria quatro causas diferentes. Cada causa tem a sua.
Convenções desta documentação¶
| Convenção | Regra |
|---|---|
| Um assunto por arquivo | Sempre registrado no nav do mkdocs.yml |
| Títulos em frase | "Fila de atendimento", não caixa alta |
| Decisão tomada | Admonition !!! note "Decisão" com a data |
| Decisão em aberto | Admonition !!! question |
| Regra que quebra algo | Admonition !!! danger |
| Imagem e diagrama | Em docs/assets/<modulo>/, por caminho relativo |
| Nome de tabela e coluna | Entre acentos graves, e conferido contra o banco |
Não documente o que você não verificou
Esta documentação substituiu material que afirmava coisas falsas sobre o produto, como integração com a API da Meta e um módulo de Tracking implementado. Afirmação sobre o sistema vem de leitura do código ou do banco, não de handoff nem de memória.