adeyanjufuhad/astrolabe

Regras concisas para construir UIs acessíveis, rápidas e agradáveis. Use MUST/SHOULD/NEVER para orientar decisões.

Interações

Teclado

• MUST: Suporte completo a teclado conforme WAI-ARIA APG
• MUST: Anéis de foco visíveis e desobstruídos (:focus-visible; agrupar com :focus-within); elementos sticky/fixed nunca cobrem o foco
• MUST: Gerenciar foco (capturar, mover, retornar) conforme padrões APG
• NEVER: outline: none sem substituição visível do foco

Alvos & Input

• MUST: Alvo de toque ≥24px (móvel ≥44px); se visual <24px, expandir área de toque
• MUST: <input> móvel com font-size ≥16px para evitar zoom no iOS
• NEVER: Desabilitar zoom do navegador (user-scalable=no, maximum-scale=1)
• MUST: touch-action: manipulation para evitar zoom ao toque duplo
• SHOULD: Definir -webkit-tap-highlight-color para combinar com o design

Formulários

• MUST: Inputs seguros para hidratação (sem perda de foco/valor)
• NEVER: Bloquear colagem em <input>/<textarea>
• MUST: Botões de carregamento mostram spinner e mantêm o rótulo original
• MUST: Enter envia o input focado; em <textarea>, ⌘/Ctrl+Enter envia
• MUST: Manter envio habilitado até o início da requisição; então desabilitar com spinner
• MUST: Aceitar texto livre, validar depois—não bloquear digitação
• MUST: Permitir envio de formulário incompleto para exibir validação
• MUST: Erros na linha próximos aos campos; ao enviar, focar no primeiro erro
• MUST: autocomplete + name significativo; type e inputmode corretos
• SHOULD: Desabilitar verificação ortográfica para emails/códigos/nomes de usuário
• SHOULD: Placeholders terminam com … e mostram exemplo de padrão
• MUST: Avisar sobre alterações não salvas antes da navegação
• MUST: Compatível com gerenciadores de senha e 2FA; permitir colagem de códigos
• MUST: Truncar valores para lidar com espaços à direita da expansão de texto
• MUST: Sem zonas mortas em checkboxes/radios; label+controle compartilham um alvo de toque

Estado & Navegação

• MUST: URL reflete estado (deep-link para filtros/abas/paginação/painéis expandidos)
• MUST: Voltar/Avançar restaura posição de rolagem
• MUST: Links usam <a>/<Link> para navegação (suportar Cmd/Ctrl/clique-do-meio)
• NEVER: Usar <div onClick> para navegação

Feedback

• SHOULD: UI otimista; reconciliar na resposta; em falha reverter ou oferecer Desfazer
• MUST: Confirmar ações destrutivas ou fornecer janela de Desfazer
• MUST: Usar aria-live educado para toasts/validação inline
• SHOULD: Reticências (…) para opções que abrem acompanhamentos ("Renomear…") e estados de carregamento ("Carregando…")

Toque & Arrasto

• MUST: Alvos generosos, affordances claras; evitar interações complicadas
• MUST: Atrasar primeiro tooltip; subsequentes instantâneos
• MUST: overscroll-behavior: contain em modais/gavetas
• SHOULD: Ao suprimir o efeito elástico de rolagem da página, definir overscroll-behavior: none no <html> dentro de @media (pointer: fine); manter padrões de rolagem da página para apontadores grossos para puxar-para-atualizar. Testar dispositivos híbridos de toque: pointer descreve o input primário, e none também desabilita encadeamento de rolagem e navegação nativa por deslize
• MUST: Durante arrasto, desabilitar seleção de texto e definir inert nos elementos arrastados
• MUST: Gestos de arrastar/deslizar/pinça/caminho têm alternativa de toque/clique e teclado, a menos que essenciais
• MUST: Se parece clicável, deve ser clicável

Autofoco

• SHOULD: Autofoco em desktop com único input primário; raramente em móvel

Animação

• MUST: Honrar prefers-reduced-motion (fornecer variante reduzida ou desabilitar)
• SHOULD: Preferir CSS > Web Animations API > bibliotecas JS
• MUST: Animar apenas propriedades amigáveis ao compositor (transform, opacity)
• NEVER: Animar propriedades de layout (top, left, width, height)
• NEVER: transition: all—listar propriedades explicitamente
• SHOULD: Animar apenas para esclarecer causa/efeito ou adicionar deleite intencional
• SHOULD: Escolher easing para corresponder à mudança (tamanho/distância/acionador)
• MUST: Animações interrompíveis e orientadas a input; reprodução automática apenas para loops mudos e não essenciais
• MUST: Movimento em reprodução automática >5s junto com outro conteúdo tem controles de pausa, parar ou ocultar
• MUST: transform-origin correto (movimento começa onde "fisicamente" deveria)
• MUST: Transformações SVG no wrapper <g> com transform-box: fill-box

Layout

• SHOULD: Alinhamento óptico; ajustar ±1px quando a percepção supera a geometria
• MUST: Alinhamento deliberado à grade/linha de base/bordas—sem posicionamento acidental
• SHOULD: Equilibrar ícone/texto (peso/tamanho/espaçamento/cor)
• MUST: Verificar móvel, laptop, ultra-wide (simular ultra-wide com zoom de 50%)
• MUST: Respeitar áreas seguras (env(safe-area-inset-*))
• MUST: Evitar barras de rolagem indesejadas; corrigir estouros
• SHOULD: Flex/grid em vez de medição JS para layout

Conteúdo & Acessibilidade

• SHOULD: Ajuda inline primeiro; tooltips como último recurso
• MUST: Skeletons espelham conteúdo final para evitar mudança de layout
• MUST: <title> corresponde ao contexto atual
• MUST: Sem becos sem saída; sempre oferecer próximo passo/recuperação
• MUST: Projetar estados vazio/esparso/denso/erro
• SHOULD: Aspas curvas (“ ”); evitar viúvas/órfãos (text-wrap: balance)
• MUST: font-variant-numeric: tabular-nums para comparações numéricas
• MUST: Pistas de status redundantes (não apenas cor); ícones têm rótulos de texto
• MUST: Nomes acessíveis existem mesmo quando visuais omitem rótulos
• MUST: Usar caractere … (não ...)
• MUST: scroll-margin-top em cabeçalhos; link "Pular para o conteúdo"; <h1>–<h6> hierárquicos
• MUST: Resiliente a conteúdo gerado pelo usuário (curto/médio/muito longo)
• MUST: Datas/horas/números cientes de localidade (Intl.DateTimeFormat, Intl.NumberFormat)
• SHOULD: translate="no" em nomes de marca, tokens de código e identificadores para evitar tradução automática distorcida
• MUST: aria-label preciso; elementos decorativos aria-hidden
• MUST: Botões apenas com ícone têm aria-label descritivo
• MUST: Preferir semântica nativa (button, a, label, table) antes de ARIA
• MUST: Mídia tem legendas/transcrições/descrições conforme aplicável; controles operáveis por teclado; mídia decorativa oculta da tecnologia assistiva
• MUST: Espaços inseparáveis: 10 MB, ⌘ K, nomes de marca

Manipulação de Conteúdo

• MUST: Contêineres de texto lidam com conteúdo longo (truncate, line-clamp-*, break-words)
• MUST: Filhos de Flex precisam de min-w-0 para permitir truncamento
• MUST: Lidar com estados vazios—sem UI quebrada para strings/arrays vazios

Desempenho

• SHOULD: Testar Modo de Baixo Consumo no iOS e Safari macOS
• MUST: Medir de forma confiável (desabilitar extensões que distorcem runtime)
• MUST: Rastrear e minimizar re-renderizações (React DevTools/React Scan)
• MUST: Perfilar com limitação de CPU/rede
• MUST: Agrupar leituras/escritas de layout; evitar reflows/repaints
• MUST: Mutações (POST/PATCH/DELETE) com alvo <500ms
• SHOULD: Preferir inputs não controlados; inputs controlados baratos a cada tecla
• MUST: Virtualizar listas grandes (>50 itens)
• MUST: Pré-carregar imagens acima da dobra; carregamento lento do resto
• MUST: Prevenir CLS (dimensões explícitas de imagem)
• SHOULD: <link rel="preconnect"> para domínios CDN
• SHOULD: Fontes críticas: <link rel="preload" as="font"> com font-display: swap
• SHOULD: <video autoplay muted loop playsinline> em vez de GIF animado; fornecer alternativa estática/de movimento reduzido
• SHOULD: Loops curtos não essenciais incluem fonte H.264 MP4 do Safari em <picture>, condição de mídia prefers-reduced-motion e fallback estático

Modo Escuro & Temas

• MUST: color-scheme: dark no <html> para temas escuros
• SHOULD: <meta name="theme-color"> combina com fundo da página
• MUST: <select> nativo: background-color e color explícitos (correção Windows)

Hidratação

• MUST: Inputs com value precisam de onChange (ou usar defaultValue)
• SHOULD: Proteger renderização de data/hora contra incompatibilidade de hidratação

Design

• SHOULD: Sombras em camadas (ambiente + direta)
• SHOULD: Bordas nítidas via bordas semitransparentes + sombras
• SHOULD: Raios aninhados: filho ≤ pai; concêntricos
• SHOULD: Consistência de matiz: tingir bordas/sombras/texto em direção ao matiz do fundo
• MUST: Gráficos acessíveis (paletas amigáveis ao daltonismo)
• MUST: Atender contraste—preferir APCA sobre WCAG 2
• MUST: Aumentar contraste em :hover/:active/:focus
• SHOULD: Combinar UI do navegador ao fundo
• SHOULD: Evitar bandeamento de gradiente escuro (usar imagens de fundo quando necessário)