upgrade-de-experiencia-em-interfaces

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:

1. Gerar o relatorio consultivo com diagnostico por camada (analise rigorosa, como ja faz hoje)
2. Listar os arquivos do projeto que serao modificados para implementar cada recomendacao
3. Aplicar as mudancas usando Edit/Write nos arquivos listados
4. Validar visualmente o resultado (ver bloco abaixo)
5. 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