@lugom.io/hefesto 0.2.0 → 0.3.0

package/skills/hefesto-design/references/ux-rules.md

@@ -0,0 +1,349 @@
+# Regras UX — 50 Essenciais por Prioridade
+
+---
+
+## Prioridade CRÍTICA (sempre aplicar)
+
+### Acessibilidade
+
+**UX-01 — Contraste de Cores**
+Todo texto deve ter contraste mínimo WCAG AA: 4.5:1 para texto normal (< 18px), 3:1 para texto grande (≥ 18px bold ou ≥ 24px regular). Testar com ferramentas como Contrast Checker ou DevTools.
+- Padrão: usar tokens semânticos que garantem contraste em ambos os temas
+- Evitar: texto cinza claro sobre branco, placeholder como conteúdo, cores vibrantes sobre vibrantes
+- Por quê: ~8% dos homens têm algum grau de daltonismo. Baixo contraste afeta todos em telas com brilho baixo ou ao sol
+- Ref: WCAG 2.2 — 1.4.3 Contrast (Minimum)
+
+**UX-02 — Focus States Visíveis**
+Todo elemento interativo deve ter um indicador de focus visível durante navegação por teclado. Focus ring de 2-4px, cor de alto contraste, offset de 2px.
+- Padrão: `outline: 2px solid var(--border-focus); outline-offset: 2px` em `:focus-visible`
+- Evitar: `outline: none` sem substituto, focus ring apenas com mudança de cor de fundo
+- Por quê: usuários de teclado ficam completamente perdidos sem indicador de focus
+- Ref: WCAG 2.2 — 2.4.7 Focus Visible
+
+**UX-03 — Texto Alternativo**
+Toda imagem significativa precisa de `alt` descritivo. Imagens decorativas recebem `alt=""` (string vazia, não ausente).
+- Padrão: descrever a informação que a imagem transmite, não a imagem em si. "Gráfico mostrando crescimento de 40% em vendas" > "Gráfico de barras"
+- Evitar: `alt="imagem"`, `alt="foto"`, alt ausente, alt repetindo o caption
+- Por quê: screen readers leem alt. Sem alt, leem o filename — "DSC_0234.jpg"
+- Ref: WCAG 2.2 — 1.1.1 Non-text Content
+
+**UX-04 — ARIA Labels**
+Elementos interativos sem texto visível (icon buttons, links de ícone) precisam de `aria-label` ou `aria-labelledby`.
+- Padrão: `<button aria-label="Fechar modal">` para botões com apenas ícone
+- Evitar: aria-label redundante com texto visível, aria-label genérico ("botão", "link")
+- Por quê: sem label, screen readers anunciam "botão" sem contexto
+- Ref: WCAG 2.2 — 4.1.2 Name, Role, Value
+
+**UX-05 — Navegação por Teclado**
+Todo fluxo deve ser completável apenas com teclado: Tab (avançar), Shift+Tab (voltar), Enter/Space (ativar), Escape (cancelar/fechar), Arrow keys (navegar dentro de grupos).
+- Padrão: testar todo fluxo crítico com Tab sem usar mouse
+- Evitar: elementos focáveis fora da ordem visual (tabindex > 0), conteúdo acessível apenas via hover
+- Por quê: além de a11y, power users preferem teclado — é mais rápido
+- Ref: WCAG 2.2 — 2.1.1 Keyboard
+
+**UX-06 — Labels de Formulário**
+Todo input deve ter um `<label>` visível e conectado via `for`/`id`. Placeholder NÃO é label.
+- Padrão: label acima do input, sempre visível, fonte medium weight
+- Evitar: placeholder como label (desaparece ao digitar), label apenas via aria (invisível)
+- Por quê: placeholder desaparece, criando carga cognitiva. Labels visíveis são scannáveis
+- Ref: WCAG 2.2 — 1.3.1 Info and Relationships
+
+**UX-07 — Skip Links**
+Primeira coisa focável na página deve ser um link "Pular para conteúdo" que leva ao `#main-content`. Visível apenas em focus.
+- Padrão: `position: absolute; left: -9999px` quando não focado, visível em `:focus`
+- Evitar: ausência total de skip links, skip link que não funciona
+- Por quê: sem skip link, usuários de teclado navegam por toda a nav a cada página
+- Ref: WCAG 2.2 — 2.4.1 Bypass Blocks
+
+**UX-08 — Hierarquia de Headings**
+Uma e apenas uma `<h1>` por página. Headings em ordem sequencial sem pular níveis (h1 → h2 → h3, nunca h1 → h3).
+- Padrão: h1 = título da página, h2 = seções, h3 = subseções
+- Evitar: usar heading por tamanho visual, pular de h2 para h4, múltiplos h1
+- Por quê: screen readers navegam por headings. Hierarquia quebrada = navegação confusa
+- Ref: WCAG 2.2 — 1.3.1 Info and Relationships
+
+**UX-09 — Cor Não é Único Indicador**
+Nunca usar cor como única forma de comunicar informação. Sempre combinar com ícone, texto, padrão ou posição.
+- Padrão: erro = vermelho + ícone ⚠ + texto. Sucesso = verde + ícone ✓ + texto
+- Evitar: campo com erro apenas com borda vermelha, status apenas por cor de badge
+- Por quê: daltonismo afeta percepção de vermelho-verde — a dupla mais usada para erro/sucesso
+- Ref: WCAG 2.2 — 1.4.1 Use of Color
+
+**UX-10 — Redução de Movimento**
+Respeitar `prefers-reduced-motion: reduce`. Desabilitar animações decorativas, manter apenas transições essenciais (feedback de ação).
+- Padrão: `@media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; } }`
+- Evitar: ignorar a media query, parallax sem fallback, auto-play vídeo
+- Por quê: animações podem causar náusea, tontura ou crises em pessoas com vestibular disorders
+- Ref: WCAG 2.2 — 2.3.3 Animation from Interactions
+
+### Touch e Interação
+
+**UX-11 — Tamanho de Área de Toque**
+Mínimo 44×44px para touch targets (botões, links, checkboxes). Ideal: 48×48px.
+- Padrão: `min-height: 44px; min-width: 44px` para todo elemento clicável
+- Evitar: ícones de 16px como botão sem padding, links inline muito curtos
+- Por quê: dedos têm ~10mm de área de contato. Alvos pequenos = erros frequentes = frustração
+- Ref: WCAG 2.2 — 2.5.8 Target Size (Minimum)
+
+**UX-12 — Espaçamento entre Touch Targets**
+Mínimo 8px de espaço entre elementos clicáveis adjacentes. Ideal: 12px.
+- Padrão: gap ou margin entre botões adjacentes ≥ 8px
+- Evitar: botões grudados, lista de ações sem espaçamento
+- Por quê: sem espaço, o usuário toca no alvo errado e executa ação indesejada
+- Ref: Material Design Touch guidelines
+
+**UX-13 — Hover vs Tap**
+Nunca esconder funcionalidade essencial atrás de hover. Mobile não tem hover. Se hover revela algo, deve haver alternativa tap/click.
+- Padrão: informação em hover → exibir em tap/long-press ou sempre visível em mobile
+- Evitar: tooltips como única fonte de informação, menus que aparecem apenas em hover
+- Por quê: ~60% do tráfego web é mobile. Hover-only = inacessível para maioria
+- Ref: Apple HIG — Touch interactions
+
+**UX-14 — Botões de Loading**
+Ao clicar em botão de ação, desabilitar imediatamente e mostrar spinner. Prevenir double-submit.
+- Padrão: `disabled + spinner` durante request. Restaurar em success/error. Manter largura do botão
+- Evitar: nenhum feedback visual, permitir múltiplos clicks, mudar tamanho do botão
+- Por quê: sem feedback, usuário clica de novo → ação duplicada (compra dupla, post duplo)
+- Ref: UX best practice universal
+
+**UX-15 — Feedback de Erro**
+Erros devem ser específicos, posicionados próximos ao campo, e sugerir correção. Nunca apenas "Erro" ou alert genérico.
+- Padrão: mensagem vermelha abaixo do campo, com ícone, descrevendo como corrigir
+- Evitar: alert() JavaScript, erro genérico no topo da página sem scroll, apenas mudar cor
+- Por quê: mensagens genéricas não ajudam. Proximidade ao campo reduz tempo de correção
+- Ref: Nielsen Norman Group — Error Messages
+
+**UX-16 — Cursor Pointer**
+Todo elemento clicável deve ter `cursor: pointer`. Todo elemento desabilitado: `cursor: not-allowed`.
+- Padrão: aplicar via CSS em botões, links, cards clicáveis, toggles
+- Evitar: div clicável sem cursor pointer, cursor pointer em texto não-clicável
+- Por quê: cursor é affordance — comunica "isto é clicável" instantaneamente
+- Ref: UX convention
+
+**UX-17 — Conflitos de Gestos**
+Evitar gestos custom que conflitam com gestos nativos do sistema (swipe back, pull to refresh, pinch zoom).
+- Padrão: testar gestos custom em iOS Safari e Android Chrome. Usar `touch-action` quando necessário
+- Evitar: horizontal swipe que conflita com back gesture, pull-down custom que conflita com refresh
+- Por quê: gesto nativo ganha. Usuário ativa o comportamento do sistema em vez da ação custom
+- Ref: Apple HIG, Material Design gestures
+
+**UX-18 — Feedback de Press**
+Elementos clicáveis devem ter feedback visual imediato ao toque (< 50ms). Scale down sutil, mudança de cor, ou ripple.
+- Padrão: `:active { transform: scale(0.98) }` ou mudança de background-color
+- Evitar: nenhum feedback visual entre tap e resultado, delay > 100ms
+- Por quê: feedback imediato confirma que o sistema recebeu o input. Sem ele, usuário acha que não funcionou
+- Ref: Material Design — State layers
+
+---
+
+## Prioridade ALTA
+
+### Layout e Responsivo
+
+**UX-19 — Viewport Meta**
+`<meta name="viewport" content="width=device-width, initial-scale=1">` obrigatório. Nunca `maximum-scale=1` ou `user-scalable=no`.
+- Por quê: bloquear zoom é violação de acessibilidade — usuários com baixa visão precisam zoom
+- Ref: WCAG 2.2 — 1.4.4 Resize Text
+
+**UX-20 — Mobile First**
+CSS começa com layout mobile, expande com `min-width` media queries. Não o contrário.
+- Padrão: estilos base = mobile → `@media (min-width: 768px)` → `@media (min-width: 1024px)`
+- Evitar: desktop-first com `max-width` queries, layout que "encolhe" em vez de "expandir"
+- Por quê: mais fácil adicionar complexidade do que remover. Mobile tem mais restrições
+
+**UX-21 — Breakpoints Consistentes**
+Usar set fixo de breakpoints em todo o projeto: 640px (sm), 768px (md), 1024px (lg), 1280px (xl), 1536px (2xl).
+- Evitar: breakpoints arbitrários diferentes por componente, muitos breakpoints
+- Por quê: breakpoints inconsistentes criam estados onde componentes diferentes respondem em momentos diferentes
+
+**UX-22 — Tamanho Mínimo de Fonte**
+Corpo de texto: mínimo 16px em mobile. Nunca abaixo de 12px para qualquer texto legível.
+- Padrão: `font-size: 1rem` (16px) para body. Labels e captions: 14px mínimo
+- Evitar: 10px, 11px, fontes que parecem menores que o tamanho real (condensadas)
+- Por quê: iOS faz zoom automático em inputs < 16px. Texto pequeno = ilegível em mobile
+- Ref: Apple HIG typography
+
+**UX-23 — Largura de Linha**
+Texto corrido: 45-75 caracteres por linha (ideal: 65). Usar `max-width: 65ch` em containers de texto.
+- Evitar: texto de margem a margem em telas largas, linhas > 90 caracteres
+- Por quê: linhas muito longas fazem o olho perder a próxima linha. Muito curtas quebram ritmo
+- Ref: The Elements of Typographic Style — Robert Bringhurst
+
+**UX-24 — Sem Scroll Horizontal**
+Nunca em layout principal. Se necessário em componente específico (tabela, carrossel), indicar visualmente que há conteúdo.
+- Padrão: `overflow-x: hidden` no body. Tabelas: `overflow-x: auto` no container
+- Evitar: conteúdo que vaza horizontalmente, layout que assume largura mínima
+- Por quê: scroll horizontal é inesperado e esconde conteúdo sem indicação
+
+**UX-25 — Escala de Espaçamento**
+Usar escala consistente baseada em múltiplos: 4, 8, 12, 16, 24, 32, 48, 64, 96px. Nunca valores arbitrários.
+- Padrão: 8px base grid. Componentes internos: 8/12/16. Entre componentes: 16/24/32. Seções: 48/64/96
+- Evitar: padding 13px, margin 37px, valores que não seguem a escala
+- Por quê: escala consistente cria ritmo visual. Valores arbitrários criam ruído sutil
+
+**UX-26 — Largura Máxima de Container**
+Conteúdo principal limitado a 1200-1440px. Nunca edge-to-edge em desktops largos.
+- Padrão: `max-width: 1200px; margin: 0 auto; padding: 0 24px`
+- Evitar: conteúdo que estica até 2560px, texto edge-to-edge em ultra-wide
+- Por quê: linhas de texto ficam ilegíveis. Layout perde coesão em telas > 1440px
+
+### Navegação
+
+**UX-27 — Limite de Itens em Bottom Nav**
+Bottom navigation: máximo 5 itens. 3-4 é ideal.
+- Padrão: 4 itens (Home, Search, [Core Action], Profile) + ícone + label
+- Evitar: 6+ itens, labels truncados, ícones ambíguos sem label
+- Por quê: > 5 itens força ícones minúsculos e labels ilegíveis. Hamburger não é item de bottom nav
+- Ref: Material Design — Bottom navigation
+
+**UX-28 — Comportamento de Back**
+Botão/gesto back deve sempre funcionar de forma previsível. Modais fecham. Subpáginas voltam. Nunca prender o usuário.
+- Padrão: usar history API corretamente, modais com pushState para back fechar modal
+- Evitar: back que sai do app, back que perde dados do formulário sem aviso
+- Por quê: back é o gesto mais usado. Comportamento inesperado = sensação de app "bugado"
+
+**UX-29 — Deep Linking**
+Toda visualização deve ter URL própria e compartilhável. Estado relevante na URL (filtros, tabs, modais).
+- Padrão: `/products?category=shoes&sort=price` em vez de estado apenas em memória
+- Evitar: SPA onde toda navegação usa a mesma URL, estado perdido ao refresh
+- Por quê: URLs são a interface do web. Compartilhar, favoritar, voltar — tudo depende de URL
+
+**UX-30 — Estado Ativo na Navegação**
+Item atual na navegação deve ter indicador visual claro. Nunca deixar o usuário sem saber onde está.
+- Padrão: underline, fundo diferente, cor diferente + font-weight, `aria-current="page"`
+- Evitar: nenhum indicador, apenas mudança sutil de cor
+- Por quê: sem indicador, usuário precisa ler o conteúdo para saber onde está
+
+**UX-31 — Escape de Modal**
+Tecla Escape sempre fecha modal/drawer/popup. Click no overlay fecha (exceto com dados não salvos).
+- Padrão: event listener para Escape, click handler no overlay, botão X visível
+- Evitar: modal sem forma de fechar, Escape não funcionar, overlay que não fecha
+- Por quê: usuários esperam Escape como "saída de emergência" universal
+- Ref: WCAG 2.2 — 3.2.5 Change on Request
+
+---
+
+## Prioridade MÉDIA
+
+### Animação
+
+**UX-32 — Duração de Animações**
+Micro-interações: 100-200ms. Transições de layout: 200-300ms. Animações de entrada: 200-400ms. Nunca > 500ms para ações do usuário.
+- Padrão: hover 150ms, modal open 250ms, page transition 300ms
+- Evitar: animações de 1s+ para feedback, delay antes de animação, animação que trava interação
+- Por quê: > 300ms sente-se lento. < 100ms é imperceptível
+- Ref: Material Design — Motion duration
+
+**UX-33 — Performance de Transform**
+Animar apenas `transform` e `opacity`. Nunca animar `width`, `height`, `top`, `left`, `margin`, `padding`.
+- Padrão: usar `transform: translateX/Y/scale` para movimento/tamanho, `opacity` para fade
+- Evitar: `transition: all`, animar layout properties, animação que causa repaint
+- Por quê: transform/opacity rodam na GPU (compositor). Layout properties causam reflow = jank
+- Ref: Google Web Fundamentals — Rendering Performance
+
+**UX-34 — Loading States**
+Conteúdo que demora > 300ms para carregar deve mostrar skeleton screens ou spinner. Spinner para ações, skeleton para conteúdo.
+- Padrão: skeleton com formato do conteúdo final, pulse animation sutil
+- Evitar: tela branca, spinner onde skeleton funcionaria, skeleton que não representa o conteúdo
+- Por quê: percepção de velocidade importa mais que velocidade real. Skeleton parece mais rápido
+
+**UX-35 — Easing Natural**
+Usar easing curves naturais, nunca `linear` para UI (exceto spinners). Entrada: ease-out. Saída: ease-in. Ambos: ease-in-out.
+- Padrão: `cubic-bezier(0.4, 0, 0.2, 1)` (standard), `cubic-bezier(0, 0, 0.2, 1)` (decelerate)
+- Evitar: `linear` para transições de UI, bounce excessivo, ease-in para entradas
+- Por quê: movimento linear parece mecânico e antinatural. Easing imita física real
+
+**UX-36 — Significado do Movimento**
+Animação deve comunicar relação espacial ou mudança de estado. Nunca animação decorativa que não informa nada.
+- Padrão: slide de onde veio, fade para mudança de conteúdo, scale para ênfase
+- Evitar: animação por animação, elementos que "dançam" sem propósito, entrada de página elaborada
+- Por quê: animação significativa melhora compreensão. Decorativa adiciona latência sem valor
+
+**UX-37 — Saída Mais Rápida que Entrada**
+Animações de saída devem ser 30-50% mais rápidas que de entrada. Entrada: 250ms. Saída: 150ms.
+- Padrão: modal entra em 250ms, sai em 150ms. Toast entra em 200ms, sai em 100ms
+- Evitar: mesma duração para entrada e saída, saída mais lenta que entrada
+- Por quê: ao sair, o usuário já decidiu. Manter na tela atrasa o próximo passo
+
+### Forms e Feedback
+
+**UX-38 — Labels Sempre Visíveis**
+Labels de input devem estar acima do campo e sempre visíveis. Mesmo após preenchimento. Floating labels são aceitáveis se implementadas corretamente.
+- Padrão: label persistente acima, font-size 14px, font-weight medium
+- Evitar: label que desaparece, placeholder como label, label ao lado (em mobile fica estreito)
+- Por quê: formulário preenchido precisa ser revisável. Sem label, usuário não sabe o que preencheu
+
+**UX-39 — Posição de Erro**
+Mensagem de erro diretamente abaixo do campo que a causou, não em banner no topo.
+- Padrão: error message 12-14px, cor `--status-error`, ícone ⚠, abaixo do input
+- Evitar: todos os erros em alert no topo, erro em toast que desaparece, erro sem indicar qual campo
+- Por quê: erro no topo = scroll + encontrar o campo. Erro abaixo do campo = correção imediata
+
+**UX-40 — Feedback de Submit**
+Formulário enviado com sucesso deve dar feedback claro: toast, redirect, ou mudança de estado visível.
+- Padrão: toast "Salvo com sucesso" por 3-5s, ou redirect para página de confirmação
+- Evitar: nenhum feedback, apenas limpar o formulário, feedback que desaparece em < 2s
+- Por quê: sem confirmação, usuário não tem certeza se enviou. Reenvia por precaução
+
+**UX-41 — Estados Vazios**
+Tela sem dados deve ter: ilustração/ícone + texto explicativo + CTA primário para criar/adicionar.
+- Padrão: ícone contextual + "Nenhum [item] ainda" + botão "Criar primeiro [item]"
+- Evitar: tela em branco, apenas "Sem resultados", tabela vazia com headers
+- Por quê: vazio é oportunidade de onboarding. Primeiro uso é primeiro impressão
+
+**UX-42 — Confirmação de Ações Destrutivas**
+Ações irreversíveis (deletar, cancelar conta) precisam de confirmação explícita: modal com texto claro + botão primário sendo cancelar.
+- Padrão: modal com "Tem certeza? Esta ação não pode ser desfeita." + botão outline "Excluir" + botão primário "Cancelar"
+- Evitar: deletar direto sem confirmação, confirmação genérica "Tem certeza?", botão destrutivo como primário
+- Por quê: cliques acidentais acontecem. Ação irreversível sem confirmação = perda de dados
+
+**UX-43 — Validação Inline**
+Validar campos conforme preenchimento (on blur), não apenas no submit. Mostrar ✓ em campos válidos complexos (senha, email).
+- Padrão: validar on blur, mostrar erro on blur se inválido, limpar erro on focus + change
+- Evitar: validar on change (erro antes de terminar de digitar), validar apenas no submit
+- Por quê: feedback imediato reduz erros. Validação apenas no submit frustra em formulários longos
+
+### Tipografia e Cor
+
+**UX-44 — Line Height**
+Corpo de texto: line-height 1.5-1.7. Headlines: 1.1-1.3. Nunca usar `line-height: 1` em texto de múltiplas linhas.
+- Padrão: body `line-height: 1.5`, h1/h2 `line-height: 1.2`, captions `line-height: 1.4`
+- Evitar: line-height 1 em parágrafos, line-height > 2 (parece double-space)
+- Por quê: line-height inadequada prejudica legibilidade significativamente
+
+**UX-45 — Pareamento de Fontes**
+Máximo 2 famílias tipográficas. Uma para display/headlines, outra para corpo. Contraste entre elas (serif + sans, por exemplo).
+- Padrão: Serifa display + sans corpo (Playfair + Inter). Ou sans bold + sans regular da mesma família
+- Evitar: 3+ famílias, duas serifas similares, fontes que competem visualmente
+- Por quê: cada fonte adicional é 100-300KB de download e complexidade visual
+
+**UX-46 — Cor Semântica**
+Cores devem comunicar significado consistente em toda a aplicação. Vermelho = erro/perigo. Verde = sucesso. Amarelo = atenção. Azul = info/ação.
+- Padrão: definir palette semântica e usar consistentemente via tokens
+- Evitar: vermelho decorativo onde não é erro, verde em botões não relacionados a sucesso
+- Por quê: cor semântica inconsistente destrói padrões aprendidos pelo usuário
+
+**UX-47 — Dark Mode de Cores**
+Em dark mode: dessaturar cores 10-20%, clarear tons, testar contraste separadamente. Não é inversão.
+- Padrão: blue-600 (light) → blue-400 (dark), red-600 → red-400, green-600 → green-400
+- Evitar: mesma cor em ambos os temas, inverter automaticamente, cores saturadas em fundo escuro
+- Por quê: cores saturadas em fundo escuro vibram visualmente e causam fadiga
+
+**UX-48 — Hierarquia por Peso**
+Criar hierarquia tipográfica com peso (regular/medium/semibold/bold), não apenas tamanho. Tamanho para nível, peso para ênfase.
+- Padrão: body regular, labels medium, headings semibold/bold, emphasis dentro do texto medium
+- Evitar: tudo bold, hierarquia apenas por tamanho, thin/100 weight (ilegível em telas)
+- Por quê: peso cria distinção sutil sem mudar tamanho. Mais refinado e escalável
+
+**UX-49 — Alinhamento de Texto**
+Texto longo: sempre alinhado à esquerda (LTR). Nunca justificado na web. Centralizado apenas para headlines e CTAs curtos.
+- Padrão: `text-align: left` para body, `text-align: center` apenas para hero titles e CTA sections
+- Evitar: `text-align: justify` (cria rios de espaço), centralizar parágrafos, alinhar à direita sem motivo
+- Por quê: olho busca o início da próxima linha na esquerda. Justificado cria espaçamento imprevisível
+
+**UX-50 — Contraste em Inputs**
+Campos de formulário devem ser visualmente distinguíveis do fundo. Borda OU fundo diferente — nunca invisível.
+- Padrão: input com borda 1px `--border-default` ou fundo `--surface-secondary`
+- Evitar: input sem borda e sem fundo diferente (Material floating label sem underline), borderless em dark mode
+- Por quê: usuário precisa identificar onde digitar. Input invisível causa hesitação
+- Ref: Nielsen Norman Group — Text Fields