UX Playbook
Construa interfaces de usuário que sejam corretas para o negócio, fáceis de usar e consistentes. O Mantine fornece os componentes; este playbook informa quando usar qual, quais estados uma tela precisa e como verificar o resultado. Leia apenas as páginas que sua tarefa precisa.
Precedência
Quando as fontes discordarem, a de maior prioridade vence:
- Requisitos de negócio: a especificação, o ticket ou a instrução do responsável. Nunca altere um silenciosamente.
- Regras próprias do produto:
AGENTS.md/CLAUDE.md, seus documentos de UX e design, seus componentes existentes. - Este playbook.
- Documentação e padrões do Mantine.
Se 2 e 3 discordarem, siga 2. Se você achar que 2 ou 1 está errado, siga-os mesmo assim e levante uma proposta de UX.
Antes do trabalho de UI, procure as regras de UX do produto (pesquise nos docs do repositório por "UX", "UI", "design", "painel"). Se não houver nenhuma, elabore-as com o modelo de brief do produto e proponha o rascunho no plano ou PR, com cada suposição rotulada como [Assunção].
Escolha o nível
| Nível | A mudança | O que você faz |
|---|---|---|
| P | Pequena alteração em uma tela existente: um campo, um botão, uma mensagem, uma coluna | Leia a página do componente que você toca. Execute sua lista de verificação. Tire capturas de tela se o layout mudou. |
| M | Uma nova tela, diálogo ou formulário, ou uma grande alteração em um deles | Escreva uma especificação de UX curta primeiro. Construa-a. Faça a verificação visual. Faça uma autorrevisão com a rubrica. |
| G | Um novo fluxo entre telas, uma nova área de funcionalidade ou uma alteração na navegação | Faça uma nota de pesquisa com 2–3 opções. Construa a opção segura, A. Depois trate cada tela como nível M. |
Detalhes e entregáveis para cada nível: fluxo de trabalho.
Encontre a página
| Você está decidindo... | Leia |
|---|---|
| Estrutura da página, hierarquia, espaçamento, layout responsivo | decisões/layout |
| Botões, primário vs secundário, botões de ícone, menus de ação | decisões/ações |
| Modal vs Drawer vs Popover vs inline, dicas de ferramentas | decisões/sobreposições |
| Navegação do aplicativo, abas, breadcrumbs, steppers, paginação, link vs botão | decisões/navegação |
| Tabelas, listas, cartões, rótulos de status, datas, texto longo | decisões/exibição-de-dados |
| Toasts, alertas, banners, mensagens inline | decisões/feedback |
| Qual entrada para uma escolha: checkbox, switch, radio, controle segmentado, select, combobox, chips | decisões/seleção |
| Formulários, rótulos, validação, campos obrigatórios | padrões/formulários |
| Botões de salvar, salvamento automático, alterações não salvas | padrões/salvamento |
| Nada para mostrar ainda, nenhum resultado | padrões/estados-vazios |
| Aguardando dados ou conclusão de trabalho | padrões/carregamento |
| Opções avançadas, "mostrar mais", detalhes sob demanda | padrões/revelação-progressiva |
| Introdução de uma funcionalidade, primeira execução, dicas | padrões/onboarding-de-funcionalidade |
| Backend offline, sem internet, falha parcial, permissão ausente | padrões/experiências-degradadas |
| Excluir, redefinir, revogar, sobrescrever | fluxos/ações-destrutivas |
| Rótulos, texto de botão, texto de erro, texto de estado vazio | escrita |
| Teclado, foco, rótulos, contraste, ARIA | acessibilidade |
| Consultar API do Mantine, tokens do tema, versões | mantine |
| A razão por trás de uma regra | princípios |
Sempre
- Use os componentes existentes do produto e do Mantine antes de escrever os seus próprios. Use um componente por tarefa.
- Dê a cada visualização de dados seus estados de carregamento, vazio e erro. Dê a cada ação um estado pendente e um resultado.
- Mantenha uma ação principal por visualização. Ações secundárias são mais discretas. Ações raras vão em um menu.
- Uma ação que não está disponível no momento permanece visível e informa o motivo, em texto que o usuário pode alcançar pelo teclado e toque, não apenas em uma dica de ferramenta. Prefira a aparência inativa (
data-disabled) ao atributodisabled, e nunca desabilite um botão de envio: ações. - Confirme ou permita desfazer qualquer coisa que destrua dados. Nunca perca a entrada do usuário em um erro.
- Toda entrada tem um rótulo visível. O significado nunca é transmitido apenas pela cor. Tudo é acessível pelo teclado.
- Verifique o resultado na largura de telefone e na largura de desktop, no modo claro e escuro: verificação visual.
- Exemplos aqui usam strings literais em inglês. Use a i18n do produto.
Quando você acha que poderia ser melhor
Você pode, e deve, propor fluxos e componentes melhores. A regra é construir o padrão seguro, anexar a proposta:
- Construa o que a especificação pede, usando os padrões aqui.
- Adicione sua ideia como uma proposta de UX no plano ou PR, no formato fixo.
- Pare e pergunte antes de construir apenas quando a especificação perderia dados, exporia um segredo, bloquearia um usuário que depende de teclado ou leitor de tela, ou se contradiz.
Relatório
Encerre cada tarefa de UI com uma seção de Notas de UX no PR ou relatório:
## Notas de UX
- Nível: M — nova aba "Mods"
- Estados: carregando ✓ vazio ✓ erro ✓ desabilitado-com-motivo ✓
- Capturas de tela: 1280 claro/escuro, 390 claro/escuro (anexadas)
- Rubrica: todas passam; n/a: destrutivo (nenhum)
- Assunções: [Assunção] a lista de mods é curta (< 50), então sem paginação
- Propostas de UX: 1 (veja abaixo)