.agent/skills/auditar-ux-heuristicas/SKILL.md

name	description	scope
auditar-ux-heuristicas	Auditoria de UX baseada em heurísticas de Nielsen e verificação de estados de UI.	local

Skill: Auditar UX por Heurísticas

Objetivo

Avaliar UX de tela ou fluxo antes de propor mudanças.

Etapas

1. Heurísticas de Nielsen

#	Heurística	Pergunta
1	Visibilidade do status	Sistema informa o que acontece?
2	Compatibilidade	Mensagens usam linguagem do domínio?
3	Controle e liberdade	Pode desfazer, voltar, cancelar?
4	Consistência	Mesmos conceitos, mesma aparência?
5	Prevenção de erros	Campos obrigatórios claros? Confirmação em ações destrutivas?
6	Reconhecimento > Lembrança	Labels descritivos?
7	Flexibilidade	Ações frequentes acessíveis?
8	Estética minimalista	Info desnecessária?
9	Recuperação de erros	Mensagens orientam correção?
10	Ajuda	Ajuda contextual disponível?

2. Estados de Interface

Para cada componente: □ Loading □ Vazio □ Sucesso □ Erro □ Desabilitado

2.5. Auditoria de Fluxo Funcional e Jornada (ux-fluxo-funcional)

Para a aplicação como um todo e entre telas conectadas:

• Navegação Visível e Ordenada: A barra principal exibe os módulos na ordem lógica da tarefa (Cadastros Base → Modelos → Planejamento/Entidade → Execução → Monitoramento) sem esconder tudo apenas em menu hambúrguer?
• Pré-requisitos Guiados: Telas dependentes de cadastros prévios exibem aviso claro e botão direto (to="...") para o passo anterior quando vazias?
• Revelação Progressiva (Sem Aperto Visual): Telas com tabelas largas, cronogramas ou 3+ abas utilizam 12 colunas (com seletor de contexto no topo) em vez de split-screen 4+8 espremido?
• Zero Jargão Técnico: Rótulos técnicos de banco/código ((info), JSONB, CRUD, Instanciar, enums crus) foram traduzidos para linguagem humana do domínio?
• Contraste de Tema Vuetify: O token secondary em tema claro (dark: false) usa tom escuro (#3E4436 ou #4A6500) garantindo legibilidade em variant="tonal" e variant="outlined"?
• Ergonomia de Quadros: Quadros Kanban dispostos horizontalmente lado a lado (overflow-x-auto) sem empilhar colunas vazias de 420px verticalmente?

2.6. Auditoria de Despoluição Visual e Hierarquia (Refactoring UI)

Verificar conformidade com rules/refactoring-ui-hierarquia-despoluicao:

• Pirâmide de Ações (1 Primária por Vista): Existe apenas 1 botão sólido (color="primary" variant="flat") por contexto, com secundárias em outlined/tonal e destrutivas discretas (variant="text" ou em v-menu, reservando vermelho sólido apenas para o modal de confirmação)?
• Zero Card-ception e Menos Bordas: Os componentes evitam v-card com borda dentro de v-card e excesso de <v-divider>, separando grupos por contraste de superfície (#FFFFFF sobre #F2F3EE) ou espaçamento (24px–32px)?
• Rótulos como Último Recurso: Dados autoexplicativos (CNPJ, e-mail, datas, status) ou frases combinadas evitam pilhas repetitivas de Rótulo: Valor com mesmo peso visual?
• Tabelas Enxutas (Colunas Combinadas): Tabelas evitam 8+ colunas estreitas agrupando dados relacionados na mesma célula em 2 linhas (Título escuro 600 + subtítulo neutro 12px) e alinham números à direita com tabular-nums?
• Lei da Proximidade e Largura Ideal: O espaço externo entre grupos/campos (16px–32px) é maior que o espaço interno (4px–8px), e formulários simples respeitam max-width: 640px–800px?
• Estados Vazios Despoluídos: Quando não há registros criados na base, filtros secundários e paginação são ocultados em favor apenas do Empty State orientador com CTA?

2.7. Auditoria Quantitativa de Ergonomia, Telas, Modais e Painéis (agent-browser + Material Design 3)

Toda auditoria de UX deve verificar se a tela, modais e painéis seguem os limites espaciais e a Matriz de Superfícies do Material Design 3:

• Orçamento de Viewport (>= 70% Área Livre): Em 1366x768 ou 1440x900, o canvas principal de trabalho (lista, árvore, tabela, Gantt, Kanban) ocupa pelo menos 70% da janela sem ser esmagado por múltiplos painéis laterais abertos ao mesmo tempo?
• Teto de 2 Faixas no Cabeçalho Operacional: A área de trabalho possui no máximo 2 faixas horizontais de cabeçalho/filtros acima do conteúdo, mantendo formulários de criação rápida (+ Nova tarefa) recolhidos sob demanda?
• Exclusão Mútua de Painéis Laterais (Auto-Collapse): Ao abrir uma gaveta inspetora de detalhes (360px–420px) ou entrar no Cronograma Gantt, o menu lateral de navegação recolhe automaticamente?
• Teto de 3 Indicadores por Linha em Repouso: Linhas de árvore/lista e cards exibem no máximo 3 sinais visuais além do título (sem "Natal de Badges" de 5–7 pílulas coloridas por linha), revelando ações secundárias (+ Sub, Editar) em :hover / :focus-within?
• Inspetor em Acordeão e Sem Card de Resumo Redundante: O painel de detalhes inicia apenas com Identificação/Prazo e Entrega abertos, agrupando Pré-requisitos, Recursos e Responsáveis em seções colapsáveis (Acordeão) com resumo no título?
• Matriz de Superfícies e Chunking M3: Formulários longos estão agrupados em seções de até 4–6 campos? Modais básicos (v-dialog, 400px–560px) são usados apenas para confirmações ou 3–4 campos rápidos (usando Side Sheet para 5–8 campos/inspeção e v-snackbar para avisos passivos)?
• Regiões Fixas (Pinned Header & Footer): Em modais e painéis laterais, o cabeçalho (com botão fechar X nos painéis) e o rodapé de ações permanecem sempre fixos caso o conteúdo central precise rolar?

2.8. Auditoria de UX Writing e Microcopy (Material Design 3)

Verificar conformidade com rules/mensagens-usuario e https://m3.material.io/foundations/writing/best-practices:

• Capitalização de Frase (Sentence case): Títulos de telas/modais/painéis, cabeçalhos, labels, abas, menus e botões usam apenas a 1ª letra da 1ª palavra e siglas em maiúscula (ex.: "Nova solicitação" e não "Nova Solicitação")?
• Começar pelo Objetivo (Begin with the objective): Frases de instrução iniciam pelo objetivo antes da ação ("Para concluir a solicitação, anexe o comprovante")?
• Anatomia M3 de Diálogos e Botões Específicos: Modais de confirmação têm título com pergunta direta ("Excluir etapa?"), explicam a consequência de forma neutra sem repetir o título e usam o verbo exato no botão ([Cancelar] / [Excluir etapa]), sem botões ambíguos [Sim], [Não] ou [OK]?
• Pontuação Enxuta de Escaneabilidade: Rótulos, botões, títulos, tooltips de 1 frase, toasts de 1 frase e itens de lista curtos omitem ponto final (.), e nenhum label ou título termina com dois-pontos (:)?
• Tempo Presente, Voz Ativa, Algarismos e Zero Abreviações Truncadas: Textos usam voz ativa no presente, números em algarismos (3, 10 MB), zero pontos de exclamação (!) em erros/alertas e zero abreviações truncadas (Qtd., Obs., Cad., End., Máx.)?

# Detectar excesso de divisores e possíveis cards aninhados
rg "<v-divider" --include='*.vue' <modulo>-front/src/ -c | sort -t: -k2 -rn | head -10
# Detectar botões destrutivos vermelhos sólidos fora de modais de confirmação
rg 'color="error"|<v-btn[^>]*error' --include='*.vue' <modulo>-front/src/ -n
# Detectar botões genéricos ambíguos (Sim, Não, OK), labels com dois-pontos e abreviações truncadas (M3 UX Writing)
rg '>(Sim|Não|OK|Confirmar)</v-btn>|label="[^"]*(:|\bQtd\.|\bObs\.|\bCad\.|\bEnd\.|\bMáx\.)' --include='*.vue' <modulo>-front/src/ -n

3. Acessibilidade Básica e Textual (M3)

• alt conciso (até 125 caracteres) sem iniciar por "Imagem de..." (alt="" para imagens decorativas).
• Textos truncados (text-truncate / ellipsis) oferecem tooltip ou expansão acessível.

rg "<img" --include='*.vue' <modulo>-front/src/ -n | grep -v "alt="
rg "<v-btn\|<button" --include='*.vue' <modulo>-front/src/ -n | grep -v "aria-label\|title"

4. Relatório

# Auditoria UX — [tela/fluxo]

## Achados por Heurística
| # | Heurística | Status | Problema | Recomendação |
|---|-----------|--------|----------|--------------|

## Estados de Interface
| Componente | Loading | Vazio | Erro | Sucesso |
|------------|---------|-------|------|---------|

## Fluxo Funcional, Superfícies e UX Writing (M3)
| Pilar / Critério | Status | Problema Identificado | Correção Proposta |
|------------------|--------|-----------------------|-------------------|

## Plano de Melhoria
1. ...

Referências

• Material Design 3 — Writing Best Practices: https://m3.material.io/foundations/writing/best-practices
• Material Design 3 — Layout, Dialogs & Side Sheets: https://m3.material.io/foundations/layout/understanding-layout/panes, https://m3.material.io/components/dialogs/guidelines, https://m3.material.io/components/side-sheets/guidelines
• Rule: global/rules/refactoring-ui-hierarquia-despoluicao
• Livro Refactoring UI (Paiol): https://adm.paiol.idz.one/estaticos/Refactoring-UI-Steve-Schoger-Adam-Wathan.pdf
• Skill: skills/ux-fluxo-funcional/SKILL.md
• Skill: skills/ux/SKILL.md
• Rule: global/rules/diagnostico-antes-correcao
• Rule: global/rules/mensagens-usuario
• Rule: global/rules/feedback-visivel