| name | upgrade-de-experiencia-em-interfaces |
| description | Upgrade rigoroso de experiencia em interfaces. Aplica 7 camadas de conhecimento profundo: percepcao humana (Gestalt, Fitts, Hick), sistemas de design (tokens, escalas, cores semanticas), micro-interacoes (6 estados, feedback em ate 100ms), fluxos visuais (estados de tela, progressive disclosure), performance percebida (skeleton, optimistic UI), acessibilidade (contraste 4.5:1, touch 44px, teclado), psicologia de conversao (hierarquia de CTA, fricao, prova social). Ativar quando: construir componente/pagina, corrigir design visual, auditar UI, melhorar conversao, aplicar design system, criar interface production-grade, upgrade de experiencia, upgrade de interface. |
Upgrade de Experiencia Em Interfaces
Opere como um arquiteto senior de experiencia visual com 20+ anos de pratica.
Toda decisao visual tem uma RAZAO funcional. Se nao tem razao, remova.
O teste final e sempre o comportamento do usuario — bonito mas confuso e falha.
Regra de Ortografia em Interface
Em textos visiveis de interface em portugues, SEMPRE usar diacriticos corretos (acentos e cedilhas): "ouça" (nao "ouca"), "você" (nao "voce"), "ação" (nao "acao"), "não" (nao "nao"), "configuração" (nao "configuracao").
So evitar diacriticos em identificadores tecnicos: nomes de variaveis, chaves de objeto JS, data-attributes HTML, classes CSS, nomes de arquivo, slugs, IDs. Exemplo: data-preset="padrao" (tecnico, sem acento) mas Padrão original (texto visivel, com acento).
Regra mental: texto que o humano le tem acento, identificador que o computador le nao tem.
Router de Ativacao
Identifique o tipo de pedido ANTES de agir:
O que esta sendo pedido?
├── Corrigir elemento especifico
│ → Foco: Camada 1 (hierarquia) + Camada 6 (acessibilidade) + Camada 3 (estados)
│ → Ler: references/percepcao-e-acessibilidade.md
│
├── Construir componente ou pagina nova
│ → Aplicar TODAS as 7 camadas
│ → Comecar por Camada 2 (sistema) depois Camada 1 (hierarquia)
│ → Ler: TODOS os references/
│
├── Auditar UI existente
│ → Avaliar contra as 7 camadas, gerar relatorio com score por camada
│ → Ler: TODOS os references/
│
├── Melhorar conversao ou engajamento
│ → Foco: Camada 7 (conversao) + Camada 1 (hierarquia) + Camada 3 (feedback)
│ → Ler: references/fluxos-e-conversao.md
│
└── Mapear fluxo completo com todos os estados
→ DELEGAR para skill fluxo-ux-completo (ela cobre mapeamento profundo)
→ Aplicar Camada 4 apenas para tratamento VISUAL dos estados mapeados
Camada 1: Percepcao Humana
Controlar a ORDEM em que o olho percorre a tela. O olho segue: tamanho > cor/contraste > posicao > espacamento.
Hierarquia visual — checklist obrigatorio:
- Definir exatamente 3 niveis de destaque por viewport: primario (acao principal), secundario (informacao de suporte), terciario (metadados)
- Elemento primario deve ser 2x a 3x maior ou mais contrastante que o secundario
- Nunca dar peso visual igual a acao primaria e secundaria — diferenciar por tamanho, cor ou peso de fonte
- Um unico ponto focal por viewport. Se dois elementos competem, o usuario paralisa
Gestalt — regras operacionais:
- Agrupar elementos relacionados com espacamento menor (8px). Separar grupos com espacamento maior (24px+)
- Nunca usar espacamento igual entre elementos relacionados e nao-relacionados
- Elementos que fazem a mesma coisa devem parecer iguais (cor, tamanho, formato)
- Usar bordas ou fundos sutis para reforcar agrupamento quando espacamento sozinho nao basta
Carga cognitiva:
- Maximo 4 grupos de informacao por viewport (Lei de Miller adaptada)
- Maximo 5-7 itens de navegacao principal
- Se uma tela tem mais de 4 grupos, usar progressive disclosure (Camada 4)
Fitts e Hick:
- Botoes de acao principal: minimo 44x44px, idealmente 48x48px
- Quanto mais importante a acao, maior e mais proximo do polegar (mobile) ou do centro visual (desktop)
- Reduzir opcoes visiveis ao minimo necessario. Cada opcao adicional aumenta tempo de decisao logaritmicamente
Para regras detalhadas com exemplos CSS: references/percepcao-e-acessibilidade.md
Camada 2: Sistema de Design
Todo projeto deve ter um sistema, mesmo que minimo. Consistencia supera perfeicao individual.
Escala tipografica — escolher UMA ratio e derivar todos os tamanhos:
| Ratio | Nome | Uso recomendado |
|---|
| 1.200 | Minor Third | UI compacta, dashboards, apps densos |
| 1.250 | Major Third | Uso geral, SaaS, portais |
| 1.333 | Perfect Fourth | Marketing, landing pages |
| 1.500 | Perfect Fifth | Editorial, blogs, storytelling |
Base: 16px. Derivar: base * ratio^n. Resultado com ratio 1.250: 10, 12, 16, 20, 25, 31, 39px.
Usar no MAXIMO 5-6 tamanhos distintos. Se usar mais, o design perde ritmo.
Escala de espacamento — usar multiplos de 4:
4 · 8 · 12 · 16 · 24 · 32 · 48 · 64 · 96
| Espaco | Quando usar |
|---|
| 4px | Espaço interno minimo (padding de badges, gap entre icone e texto) |
| 8px | Espaco entre elementos dentro de um grupo |
| 12px | Padding interno de botoes e inputs |
| 16px | Espaco padrao entre elementos relacionados |
| 24px | Espaco entre grupos dentro de uma secao |
| 32px | Espaco entre secoes |
| 48-64px | Espaco entre blocos maiores da pagina |
| 96px | Respiro entre secoes hero |
Cores com intencao semantica:
- Nomear por FUNCAO, nunca por aparencia:
--cor-acao-primaria (nao --azul-500)
- Toda paleta precisa: primaria (acao), secundaria (suporte), sucesso, aviso, perigo, info, superficie, texto
- ANTES de escolher qualquer cor, verificar contraste com Camada 6
Tokens:
- Valores visuais sao variaveis nomeadas por funcao
- Mudar um token muda TODO o sistema — e esse o ponto
- Nivel 1 (primitivos):
--azul-500: #3b82f6. Nivel 2 (semanticos): --cor-acao-primaria: var(--azul-500)
- A UI referencia APENAS tokens semanticos, nunca primitivos
Para sistema completo com exemplos: references/design-tokens-e-sistemas.md
Camada 3: Micro-interacoes e Feedback
Silencio visual e a pior experiencia. Toda acao do usuario DEVE ter resposta.
6 estados obrigatorios para todo elemento interativo:
| Estado | Visual | Tempo de resposta |
|---|
| Padrao (default) | Aparencia base | — |
| Hover | Mudanca sutil (sombra, brilho, cor 10% mais clara/escura) | Instantaneo |
| Foco (focus) | Outline visivel de 2-3px, cor contrastante. NUNCA outline: none sem substituto | Instantaneo |
| Pressionado (active) | Escala 0.95-0.98, cor mais escura, ou sombra interna | < 50ms |
| Desabilitado | Opacidade 0.4-0.5, cursor not-allowed, sem hover/focus | — |
| Carregando | Spinner ou skeleton no lugar do conteudo, botao desabilitado | Iniciar em < 100ms |
Easing curves — tabela de decisao:
| Tipo de movimento | Curve | CSS |
|---|
| Elemento aparecendo | ease-out | cubic-bezier(0, 0, 0.2, 1) |
| Elemento saindo | ease-in | cubic-bezier(0.4, 0, 1, 1) |
| Elemento mudando de lugar | ease-in-out | cubic-bezier(0.4, 0, 0.2, 1) |
| Feedback de acao (click) | ease-out rapido | cubic-bezier(0, 0, 0.2, 1) em 100-150ms |
| NUNCA | linear | — (parece robotico, exceto progress bars) |
Duracoes:
- Micro-feedback (hover, click): 100-150ms
- Transicoes pequenas (abrir dropdown, mostrar tooltip): 200-250ms
- Transicoes medias (abrir modal, expandir secao): 250-350ms
- Transicoes grandes (mudanca de pagina, painel lateral): 300-400ms
- NUNCA mais que 500ms — parece lento
Para estados com CSS e padroes completos: references/interacoes-e-performance.md
Camada 4: Fluxo Visual
REGRA: Para mapeamento COMPLETO de fluxos (todos os caminhos, decisoes, edge cases), delegar para a skill fluxo-ux-completo. Esta camada cobre apenas o TRATAMENTO VISUAL dos estados.
Tratamento visual de estados de tela:
| Estado | O que mostrar | O que NUNCA fazer |
|---|
| Vazio (primeiro uso) | Ilustracao + texto guia + CTA claro ("Adicione seu primeiro item") | Tela em branco, "Nenhum resultado" sem acao |
| Carregando | Skeleton que espelha o layout final (mesmas posicoes e tamanhos) | Spinner generico centralizado, tela branca |
| Com dados | Layout completo, hierarquia visual clara | Mostrar tudo de uma vez sem hierarquia |
| Erro | Icone + mensagem humana + acao de recuperacao ("Tentar novamente") | "Error 500", mensagens tecnicas, tela vermelha |
| Sem permissao | Explicar POR QUE nao tem acesso + como conseguir | "403 Forbidden", tela vazia |
| Offline | Indicar estado + mostrar dados em cache se existirem | Fingir que esta online, travar |
Progressive disclosure:
- Mostrar apenas o essencial. Detalhes avancados ficam em "Ver mais", accordions ou abas
- Formularios longos: dividir em etapas com indicador de progresso
- Configuracoes: separar "basico" (visivel) de "avancado" (colapsado)
Para padroes completos: references/fluxos-e-conversao.md
Camada 5: Performance Percebida
Velocidade e design. 53% dos usuarios abandonam se demora mais de 3 segundos.
Skeleton screens:
- O skeleton DEVE espelhar o layout real (mesma quantidade de linhas, mesma posicao de imagens)
- Usar pulsacao sutil (opacity 0.4 → 0.7 em loop) — indica "carregando", nao "quebrado"
- Mostrar skeleton em < 100ms apos o clique/navegacao
- Nunca usar skeleton + spinner juntos — redundante
Optimistic UI:
- Acoes frequentes e reversiveis (curtir, favoritar, marcar como lido): aplicar IMEDIATAMENTE e sincronizar depois
- Acoes irreversiveis (deletar, pagar, enviar): confirmar primeiro, depois executar
- Se otimistic UI falhar: reverter silenciosamente + mostrar toast "Nao foi possivel salvar. Tente novamente."
Above the fold:
- Conteudo visivel sem rolar deve carregar em < 1 segundo
- Imagens abaixo da dobra: usar
loading="lazy"
- Fontes: usar
font-display: swap para texto visivel imediatamente
Prevencao de layout shift (CLS):
- SEMPRE definir
width e height ou aspect-ratio em imagens e videos
- Reservar espaco para conteudo dinamico (ads, embeds) antes do carregamento
- Fontes web: reservar espaco com
size-adjust no @font-face
Para tecnicas completas: references/interacoes-e-performance.md
Camada 6: Acessibilidade
Acessibilidade nao e checklist de compliance — e qualidade de engenharia.
Contraste — regras numericas:
- Texto normal (< 18px): minimo 4.5:1 contra o fundo
- Texto grande (>= 18px bold ou >= 24px regular): minimo 3:1
- Elementos interativos (bordas de input, icones funcionais): minimo 3:1
- Texto decorativo ou logotipos: sem requisito
- NUNCA usar cinza-claro em fundo branco para texto funcional
Navegacao por teclado:
- Todo elemento interativo acessivel via Tab
- Ordem de Tab segue a ordem visual (esquerda→direita, cima→baixo)
- Focus visivel em TODOS os elementos interativos (outline de 2-3px)
- Escape fecha modais e dropdowns
- Enter ou Space ativa botoes e links
- Setas navegam dentro de grupos (abas, menus, radio buttons)
Touch targets (mobile):
- Area tocavel minima: 44x44px (Apple HIG) ou 48x48dp (Material Design)
- Espaco entre targets: minimo 8px
- Botoes de acao principal: idealmente 56px de altura em mobile
Movimento:
- Respeitar
prefers-reduced-motion: desativar animacoes, transicoes e auto-play
- NUNCA usar animacoes piscantes (> 3 flashes por segundo — risco de convulsao)
- Oferecer controle de pausa para carrosseis e videos em auto-play
Para WCAG quick-reference e ARIA: references/percepcao-e-acessibilidade.md
Camada 7: Psicologia de Conversao
Design que FUNCIONA mede resultados, nao elogios.
Hierarquia de CTAs — regra do viewport unico:
- Maximo 1 CTA primario por viewport (botao grande, cor de acao, texto de acao)
- CTAs secundarios visualmente subordinados (outlined, menor, cor neutra)
- O CTA primario deve ser o elemento de maior destaque visual na tela
- Texto do CTA: verbo + beneficio ("Comecar gratis", "Salvar meu progresso"), nunca "Clique aqui" ou "Submit"
Prova social — posicionamento:
- Depoimentos e avaliacoes: colocar DEPOIS da proposta de valor e ANTES do CTA
- Numeros ("10.000+ usuarios"): perto do topo da pagina, visivel sem rolar
- Logos de clientes: imediatamente abaixo do hero
- Funcao: reduzir incerteza no momento exato em que ela aparece
Reducao de friccao:
- Cada campo de formulario a mais reduz conversao em 10-15%
- Formulario de cadastro ideal: 3-4 campos no maximo (nome, email, senha, confirmar)
- Checkout: mostrar progresso (Passo 1 de 3), permitir edicao sem voltar ao inicio
- Autocompletar, mascaras de input, e validacao inline (nao apenas no submit)
Ancoragem visual:
- Mostrar preco original riscado ao lado do preco atual — cria percepcao de ganho
- Em tabelas de preco: destacar visualmente o plano recomendado (borda, badge "Mais popular", tamanho maior)
- Mostrar economia em valor absoluto E percentual ("Economize R$120/ano — 40% OFF")
Para padroes completos: references/fluxos-e-conversao.md
Interacao Entre Camadas
As camadas nao sao independentes. Regras de cruzamento:
- Ao escolher cores (Camada 2) → verificar contraste (Camada 6)
- Ao adicionar transicoes (Camada 3) → respeitar prefers-reduced-motion (Camada 6)
- Ao definir hierarquia visual (Camada 1) → alinhar com hierarquia de conversao (Camada 7)
- Ao criar estados de tela (Camada 4) → aplicar skeleton e optimistic UI (Camada 5)
- Ao dimensionar botoes (Camada 1) → respeitar touch targets (Camada 6) e Fitts (Camada 1)
- Ao dividir conteudo em secoes (Camada 1) → respeitar max 4 grupos/viewport (Camada 1) e progressive disclosure (Camada 4)
Antipadroes — Erros Comuns do Claude em Frontend
| Antipadrao | Por que e errado | Fazer em vez disso |
|---|
| Cinza-claro (#9ca3af) em fundo branco para texto | Falha contraste 4.5:1 | Usar #6b7280 ou mais escuro |
outline: none sem substituto de focus | Quebra navegacao por teclado | Usar outline: 2px solid var(--cor-foco) ou box-shadow |
| Mesmo peso visual para botao primario e secundario | Usuario nao sabe qual clicar | Primario: preenchido + cor forte. Secundario: outlined ou ghost |
| Spinner generico centralizado como loading | Nao informa o que esta carregando | Skeleton screen que espelha o layout real |
| Formulario com 8+ campos na mesma tela | Cada campo = -10-15% conversao | Dividir em etapas ou esconder campos avancados |
| Animacoes em linear easing | Parece robotico e artificial | Usar ease-out para entrada, ease-in para saida |
| Espacamento arbitrario (17px, 23px, 41px) | Quebra ritmo visual, parece "estranho" | Usar escala de 4: 8, 12, 16, 24, 32, 48, 64 |
| Todos os textos no mesmo tamanho | Zero hierarquia, usuario nao sabe por onde comecar | Escala tipografica com ratio: 3 niveis claros de destaque |
| Cor so por estetica, sem funcao semantica | Confunde o usuario sobre significado | Cada cor comunica algo: acao, sucesso, perigo, info |
| Tela de erro com "Error 500" ou msg tecnica | Usuario sente que o app quebrou | Msg humana + icone + acao de recuperacao |
| Hover effects em mobile | Mobile nao tem hover, effect nunca aparece | Usar apenas active/pressed states em mobile |
| Layout shift quando imagens carregam | Conteudo pula, usuario perde o lugar | Definir width/height ou aspect-ratio antes do carregamento |
Protocolo de Execucao Visual — Obrigatorio
Esta skill atua em INTERFACES. Relatorio sem mudanca visual e trabalho pela metade. O modo consultor (analise rigorosa por camada) e a base — mas todo diagnostico precisa virar mudanca no codigo E ser comprovado visualmente antes de encerrar a tarefa.
Sequencia obrigatoria apos qualquer analise:
- Gerar o relatorio consultivo com diagnostico por camada (analise rigorosa, como ja faz hoje)
- Listar os arquivos do projeto que serao modificados para implementar cada recomendacao
- Aplicar as mudancas usando Edit/Write nos arquivos listados
- Validar visualmente o resultado (ver bloco abaixo)
- So declarar a tarefa concluida quando o visual refletir o relatorio
Como validar visualmente
A IA escolhe o metodo conforme a ferramenta em que esta rodando:
Cenario A — IA tem capacidade nativa de ler imagens/screenshots (Claude.ai, Claude Code, Codex, Cursor, ou qualquer interface com vision/multimodal):
- Tirar print da pagina ou componente apos as mudancas (via ferramenta interna, screenshot do SO, ou pedir ao usuario)
- Ler o print e comparar item-a-item com o relatorio gerado
- Confirmar que cada recomendacao virou mudanca visual real na tela
Cenario B — IA NAO tem capacidade nativa de leitura visual (ambientes texto-only ou sem multimodal):
- Usar Playwright para abrir a interface, navegar ate o componente e capturar screenshot
- Antes de usar, verificar se Playwright esta instalado:
- Node: checar
package.json por @playwright/test ou playwright
- Python: checar
requirements.txt/pyproject.toml por playwright
- Se NAO estiver instalado, instalar antes de continuar:
- Node:
npm install -D @playwright/test && npx playwright install chromium
- Python:
pip install playwright && playwright install chromium
- Rodar script curto que: abre a URL local, espera o componente carregar, captura screenshot em
./.skill-screenshots/
- A IA entao envia o screenshot para um modelo com vision (se disponivel) ou pede ao usuario para revisar o arquivo gerado
Regra de ouro: O ciclo so fecha quando existe COMPROVACAO VISUAL — print analisado pela IA ou usuario confirmou olhando a tela. Nunca encerrar a tarefa apenas com "as mudancas foram aplicadas no codigo" — em interface, codigo aplicado sem confirmacao visual e codigo nao verificado.
Quando algo nao bate:
Se o print mostra que o visual NAO reflete o relatorio (CSS sobrescrito, build nao rodou, seletor errado, cache do browser), voltar ao passo 2 e identificar o motivo real antes de retentar. Nao reescrever o relatorio para se ajustar ao que apareceu — o relatorio e o alvo, o visual e a entrega.
Indice de Referencias
Consultar para conhecimento profundo. Ler apenas o arquivo indicado pelo Router de Ativacao.
| Arquivo | Conteudo | Quando consultar |
|---|
references/percepcao-e-acessibilidade.md | Gestalt com exemplos CSS, WCAG quick-ref, ARIA, focus management, contraste | Corrigir elemento, auditar, acessibilidade |
references/design-tokens-e-sistemas.md | Escala tipografica calculada, spacing detalhado, sistema de cores completo, tokens | Construir novo, criar design system |
references/interacoes-e-performance.md | 6 estados com CSS, easing cheat sheet, skeleton patterns, optimistic UI, anti-CLS | Construir novo, melhorar performance, micro-interacoes |
references/fluxos-e-conversao.md | Estados de tela visuais, progressive disclosure, CTAs, prova social, fricao | Melhorar conversao, fluxos visuais |
