Manual de UI/UX

O que UX faz?

Grandes interfaces vêm de três coisas feitas juntas: um ponto de vista claro (quem, qual tarefa, qual sensação), um sistema consistente (tokens + componentes) e centenas de detalhes corretos (estados, movimento, acessibilidade, texto). Este manual orquestra o arsenal de skills que cobrem cada parte.

Fluxo de trabalho para qualquer tarefa de UI

Escalone: um ajuste de botão precisa dos passos 5–7; um novo aplicativo precisa de todos eles.

1. Brief — Quem é a pessoa, qual é a tarefa (verbo), qual contexto/dispositivo, qual deve ser a sensação (palavras concretas). Deduza a partir do código e da solicitação; faça apenas uma pergunta se uma restrição crítica for desconhecida (plataforma, marca existente, público).
2. Direção — escolha o caráter estético e de interação antes do código. Veja 2–4 referências reais para este tipo de tela (ui-stack-advisor/references/inspiration.md).
3. Sistema — tokens e DESIGN.md (design-system-builder; cores via color-theory). Projeto existente? Leia e siga seu sistema; estenda-o, não o bifurque.
4. Pilha — bibliotecas de componentes/movimento (ui-stack-advisor). Use primitivos acessíveis; não crie manualmente diálogos, menus, comboboxes, seletores de data, toasts.
5. Construção — estrutura e hierarquia primeiro (layout, tipo, espaçamento), depois cor, depois detalhe. Conteúdo real, não lorem ipsum. Todos os estados: carregando, vazio, erro, parcial, sucesso, desabilitado, conteúdo longo.
6. Movimento — apenas onde tem um propósito (feedback, continuidade, mudança de estado); veja as skills de movimento.
7. Verificar olhando — renderize (servidor de desenvolvimento + Playwright/Chrome MCP/simulador), verifique em tamanhos reais (390, 768, 1280+; celular pequeno, tablet), ambos os temas, apenas teclado, zoom 200% / maior Tipo Dinâmico. Corrija o que vê em lotes.
8. Revisão — execute a lista de verificação pré-entrega abaixo ou uma skill de revisão.

Qual skill para quê (roteamento)

Necessidade	Carregar
Direção estética para landing pages, marketing, design visual distinto	frontend-design
UI de produto (dashboards, SaaS, admin, ferramentas) com memória de design persistente	interface-design
Sistema de design, tokens, temas, tokens multiplataforma, DESIGN.md	design-system-builder
Escolher/derivar cores, paletas, cores do modo escuro, contraste, segurança para daltonismo	color-theory (gera) · better-colors (audita)
Tipografia: escala, quebra, recursos de fonte, truncamento	better-typography
Layout: agrupamento, alinhamento, responsivo, espaço para i18n	better-layout
Polimento: raio, sombras, ícones, alinhamento óptico	better-ui
Revisão/correção de acessibilidade (WCAG 2.2)	better-accessibility
Texto de UX, rótulos, erros, estados vazios	better-writing
Revisão classificada de tela inteira em todos os itens acima	better-interface · revisão de branch/PR: interface-review
Escolha de bibliotecas de componentes/animação/widgets	ui-stack-advisor
Filosofia de animação, easing, durações, molas, sensação de componentes	emil-design-eng
Construir uma animação web	animate · vários elementos juntos: choreograph
Revisar / auditar / corrigir animações instáveis	review-animations · improve-animations · animation-performance
Movimento fluido estilo Apple, gestos, materiais (web ou nativo)	apple-design
Web móvel com sensação nativa (PWA, toque, 100vh, áreas seguras)	mobile-native
Design e revisão React Native / Expo	mobile-design · animação: animate-expo · skills de plugin Expo: expo-native-ui, expo-ui, expo-design-system, expo-animation, expo-router
Especificidades do shadcn/ui	shadcn (plugin Vercel)
Galeria de variantes / estado / teste de estresse de componente	variant · state-machine · break (invocado pelo usuário)
Visualização de dados em gráficos e dashboards	dataviz
Figma ↔ código	Skills MCP do Figma (figma-design-to-code, figma-generate-library, …)

Regra de conflito: quando duas skills discordam, o DESIGN.md/sistema existente do projeto vence, depois o brief do usuário, depois a skill mais específica (ex.: animate-expo sobre emil-design-eng em um app Expo). Não empilhe múltiplas skills de direção estética em uma tarefa — escolha uma (frontend-design ou interface-design).

Folha de referência de padrões

Acessibilidade (WCAG 2.2 AA — linha de base legal nos EUA (ADA/508), UE (Lei Europeia de Acessibilidade, em vigor desde junho de 2025) e muitos outros)

• Contraste 4.5:1 texto, 3:1 texto grande e componentes de UI/gráficos significativos
• Tudo operável por teclado; foco visível (2.4.7) não oculto por UI fixa (2.4.11); ordem lógica
• Tamanho do alvo ≥ 24×24 px CSS (2.5.8) — projete para 44×44
• Arrastar tem uma alternativa de ponteiro único (2.5.7)
• Rótulos para cada entrada, erros identificados em texto, nenhuma informação apenas por cor
• Texto redimensiona para 200% / reflui na largura de 320px sem rolagem horizontal (1.4.10)
• Respeite movimento reduzido; sem flash > 3/s; conteúdo em movimento automático > 5s pode ser pausado
• Localização de ajuda consistente (3.2.6), sem reentrada redundante (3.3.7), autenticação acessível — sem testes cognitivos, permitir colar/gerenciadores de senha (3.3.8)
• HTML semântico primeiro; ARIA apenas para preencher lacunas. Nativo: labels/traits de acessibilidade (iOS), contentDescription/semantics (Android/Compose), accessibilityLabel/accessibilityRole (RN)

Plataformas

• iOS (HIG): alvos de 44×44pt, barra de abas para navegação de nível superior (≤5), pilha de navegação com gesto de voltar, sheets com detents, SF Symbols, Tipo Dinâmico, cores semânticas, Liquid Glass para a camada de controle (iOS 26+), hápticos para eventos significativos
• Android (Material 3 / Expressive): alvos de 48×48dp, barra/trilha/gaveta de navegação por classe de largura, gesto de voltar preditivo, borda a borda com insets, cor dinâmica, escala tipográfica M3
• Detalhes e diferenças: references/mobile-standards.md

Desempenho (Core Web Vitals, percentil 75): LCP ≤ 2.5s · INP ≤ 200ms · CLS ≤ 0.1. Responda à entrada em ~100ms; mostre progresso para qualquer coisa > 400ms (limiar de Doherty); skeletons para conteúdo, spinners para ações; UI otimista onde seguro. Móvel: 60/120fps, mantenha a thread JS livre (worklets do Reanimated), listas virtualizadas.

Princípios de UX: 10 heurísticas de Nielsen + Leis da UX (Fitts, Hick, Jakob, Miller/chunking, Tesler, Doherty, pico-fim, estética-usabilidade, Von Restorff, Gestalt). Orientação de padrões para formulários, navegação, pesquisa, tabelas, onboarding, estados vazios/erro/carregamento, notificações, configurações, ações destrutivas: references/ux-principles-and-patterns.md.

Ética: sem padrões obscuros (confirmshaming, cancelamento armadilha, consentimento pré-marcado, urgência falsa, custos ocultos, perseguição). Eles são cada vez mais ilegais (DSA/DMA da UE, regras de clique-para-cancelar da FTC, regras de consentimento do GDPR) e corroem a confiança.

Lista de verificação pré-entrega

• Propósito de cada tela óbvio em 5 segundos; uma ação primária por visualização
• Hierarquia legível ao apertar os olhos (tamanho/peso/contraste, não apenas cor)
• Espaçamento, raio, tipo, cor apenas de tokens; consistente com DESIGN.md
• Estados de carregamento, vazio, erro, parcial, offline e conteúdo longo projetados
• Formulários: rótulos, tipos de entrada/autocomplete corretos, erros inline, entrada preservada no erro, sem bloqueio de colar
• Teclado: ordem de tabulação, foco visível, Escape fecha sobreposições, foco retorna ao gatilho
• Leitor de tela: nomes/funções/estados, regiões ativas para atualizações assíncronas, estrutura de cabeçalhos
• Contraste medido em ambos os temas; nada transmitido apenas por cor
• Responsivo em 320 / 390 / 768 / 1024 / 1440; alvos de toque ≥ 44; sem affordances apenas por hover
• Movimento proposital, ≤ 300ms para UI, interrompível, movimento reduzido respeitado
• Texto: verbos específicos nos botões, erros explicam a correção, terminologia consistente, pronto para i18n (sem strings concatenadas, espaço para +30–40% de texto, propriedades lógicas seguras para RTL)
• Desempenho: imagens dimensionadas/lazy, fontes pré-carregadas/trocadas, sem deslocamento de layout, listas longas virtualizadas
• Olhou para o resultado renderizado (capturas de tela em tamanhos reais), não apenas o código

Auditoria de código web com o conjunto completo de regras (foco, formulários, animação, tipografia, conteúdo, imagens, desempenho, navegação, toque, temas, i18n, hidratação, texto, antipadrões): leia references/web-interface-guidelines.md e relate como arquivo:linha - problema.

Referências

• references/web-interface-guidelines.md — Diretrizes de Interface Web da Vercel (internalizado, MIT) para auditorias de código
• references/ux-principles-and-patterns.md — heurísticas, Leis da UX e melhores práticas de padrões
• references/mobile-standards.md — iOS HIG + fundamentos do Material 3 e diferenças entre plataformas
• references/arsenal.md — toda skill de UI instalada: fonte, licença, para que serve, como atualizar; extras opcionais