s0up4200/mobile-adapt

Mobile Adapt

Objetivo

Adaptar interfaces existentes para funcionar bem em celulares sem remover a funcionalidade principal. Priorize web móvel no padrão iPhone, a menos que o usuário nomeie outro destino.

Destino padrão

Se o usuário não especificar um dispositivo ou navegador, otimize primeiro para:

• iPhone Pro Max em retrato e paisagem
• iOS Safari
• telas sensíveis ao toque compactas com cerca de 375-440 CSS px de largura
• uso com teclado aberto, texto grande, áreas seguras e movimento reduzido

Quando pesquisar

Esta habilidade depende do comportamento atual da plataforma.

• Consulte fontes oficiais quando o usuário pedir orientação mais recente/atual, comportamento específico do iPhone, peculiaridades do Safari/WebKit, comportamento de área segura, comportamento PWA/tela inicial ou citações diretas.
• Prefira Apple Developer, WebKit, W3C/WCAG, MDN, Android Developers e web.dev.
• Use datas absolutas ao citar mudanças recentes de plataforma.

Para as regras e fontes atuais de alto sinal, leia references/mobile-ui-2026.md.

Regras principais

• Mantenha celulares compactos em painel único. Não mude para IA de desktop só porque um celular em paisagem cruza um ponto de interrupção genérico. Um celular girado de lado ainda é segurado com duas mãos à distância do braço — o modelo mental do usuário é "celular", não "tablet". Dividir em um layout de vários painéis cria uma experiência desorientadora onde nada é grande o suficiente para ser usado confortavelmente.

• Use navegação mobile inferior para seções verdadeiramente de nível superior. Mantenha de 3 a 5 destinos primários; mova o excesso para Mais, uma folha ou fluxos secundários. A parte inferior da tela é a zona de descanso natural do polegar — colocar a navegação primária ali significa que as ações mais comuns exigem o menor esforço. Mais de 5 itens encolhem os alvos de toque abaixo do tamanho utilizável e sobrecarregam a varredura.

• Cada alvo interativo deve ter pelo menos 44x44 CSS px em ambas as dimensões. Isso inclui elementos secundários fáceis de ignorar: botões de ação inline (editar, excluir, visualizar), alternâncias de expandir/recolher, chips de filtro, botões de ícone em barras de ferramentas, botões de fechar em folhas e linhas de caixa de seleção/botão de rádio (use <label> como alvo de toque completo, não apenas a entrada). Telas sensíveis ao toque capacitivas registram o centro da área de contato do dedo em aproximadamente 44pt — alvos menores causam frustração por toques errados, especialmente em movimento. Classes Tailwind comuns que ficam aquém: h-8 (32px), h-9 (36px), p-1 em um ícone (~24px), p-1.5 (~28px), p-2 (~32px). Use h-11 (44px), min-h-[44px] ou equivalente como base para cada elemento tocável. Isso está alinhado com as HIG da Apple e excede o mínimo de 24px do WCAG 2.2.

• Não confie em hover, toques em ícones minúsculos ou ações ocultas em linhas. Não há estado de hover no toque — qualquer coisa que exija hover para ser descoberta é invisível. Use controles visíveis, ações de deslizar com dica visual ou uma folha/menu contextual.

• Evite rolagem horizontal da página. O uso do celular com uma mão é rolagem vertical com o polegar. A rolagem horizontal quebra o modelo espacial do usuário e esconde o conteúdo fora da tela sem nenhum affordance visível. Reflua, empilhe, pagine ou role localmente tabelas e gráficos em vez de toda a página.

• Use viewport-fit=cover, env(safe-area-inset-*) e min-height: 100dvh. iPhones modernos têm cantos arredondados, a Ilha Dinâmica e o indicador de início — todos os quais consomem o viewport retangular. Sem o tratamento explícito de área segura, o conteúdo fica cortado atrás do chrome do hardware. dvh leva em conta a barra de ferramentas recolhível do Safari que o vh antigo não considera.

• Mantenha as ações primárias longe das barras do navegador, do indicador de início, dos cantos arredondados e do teclado na tela. Um botão "Enviar" escondido atrás do teclado ou sobrepondo o indicador de início está funcionalmente quebrado — o usuário não consegue vê-lo ou tocá-lo sem acionar um gesto do sistema.

• Prefira um contêiner de rolagem principal para fluxos com muitos formulários ou teclado. Regiões de rolagem aninhadas no iOS Safari criam aprisionamento de rolagem: o polegar do usuário rola o contêiner interno quando pretendia rolar a página, ou vice-versa. O WebKit tem bugs persistentes aqui (veja o arquivo de referência). Use rolagem aninhada apenas quando não houver alternativa.

• Use entradas mobile semânticas. Rótulos acima dos campos (não ao lado — não há espaço horizontal), type correto, inputmode, autocomplete e enterkeyhint. Esses atributos controlam qual teclado aparece — inputmode="decimal" mostra o teclado numérico para moeda, enterkeyhint="next" permite que os usuários naveguem por um formulário sem dispensar o teclado.

• Trate texto grande como entrada de layout real. Os usuários do iOS podem definir texto maior em todo o sistema, e muitos o fazem. Quebre e reflua — não esconda o significado principal por trás de truncamento. Se um rótulo truncado faz o usuário adivinhar se está vendo "Conta Poupança" ou "Conta Salário", o layout falhou.

• Em celulares, os gráficos apoiam a história; eles não são a história toda. Uma tela de celular pode renderizar talvez 5-6 barras legíveis ou um donut. Isso não é densidade de dados suficiente para o gráfico ser autoexplicativo. Lidere com o número principal e um resumo em texto; use o gráfico como reforço visual.

• Preserve a marca existente e o sistema de design do produto, a menos que o usuário peça uma reformulação mais ampla. A adaptação mobile é sobre layout e interação, não sobre redesenho visual.

Exemplos

Antes de alterar um shell de navegação, uma tabela de dados ou um formulário com botão de envio, leia references/mobile-examples.md. Ele contém código antes/depois para uma barra lateral que se torna uma barra de guias inferior, uma tabela que se torna uma lista de cartões em celulares e um formulário cujo botão de envio permanece acima do teclado.

Fluxo de trabalho

1. Fixar o contexto alvo.
   • dispositivo, navegador, orientação, contexto de uso
   • padrão: iPhone Pro Max + iOS Safari, se não especificado
2. Auditar o shell primeiro.
   • modo de navegação
   • áreas seguras
   • barras fixas/sticky
   • comportamento em paisagem
   • comportamento do teclado
3. Auditar cada tela ou componente.
   • listas e linhas
   • formulários
   • tabelas
   • gráficos
   • estados vazio/erro/carregamento
4. Escolher a divisão definitiva.
   • o que se torna coluna única
   • o que se torna cartões
   • o que se move para uma folha/gaveta
   • o que se torna secundário em Mais
5. Implementar adaptações mobile-first.
   • prefira consultas de contêiner para componentes internos
   • prefira consultas de viewport para mudanças de shell/layout
   • não mantenha comportamento antigo meio-desktop/meio-mobile, a menos que explicitamente necessário
6. Verificar em retrato compacto e paisagem compacto.
   • Safari/WebKit primeiro
   • depois Chromium
7. **Relatar os problemas de maior risco primeiro, depois as alterações concretas e quaisquer lacunas restantes.

Lista de verificação de tela

Shell e navegação

• Manter celulares em paisagem no shell de celular.
• Evitar alternâncias bruscas de md => barra lateral desktop para dispositivos que ainda são celulares.
• Preencher a UI inferior com env(safe-area-inset-bottom).
• Fazer com que as ações sticky fiquem acima da navegação inferior.
• Manter os rótulos mobile curtos.

Listas e linhas

• Permitir que títulos, metadados e valores quebrem em duas linhas quando necessário.
• Reservar espaço estável para preços, saldos e totais.
• Preferir metadados empilhados em vez de metadados inline comprimidos.
• Expor ações com controles visíveis ou uma folha/menu, não hover.
• Dimensionar botões de ação de linha (editar, excluir, visualizar, expandir) para pelo menos 44x44 CSS px — não apenas navegação primária e botões de barra de ferramentas.

Formulários

• Usar uma coluna em celulares compactos.
• Manter o envio visível acima do teclado.
• Usar um CTA primário claro de largura total.
• Dividir fluxos longos em etapas ou divulgação progressiva.
• Evitar type="number" para moeda se formatação ou precisão for importante.

Tabelas e fluxos de importação/revisão

• Converter tabelas editáveis densas em cartões/listas em celulares.
• Se uma tabela verdadeira precisar permanecer, isolar a rolagem horizontal apenas na tabela.
• Manter cabeçalhos sticky e barras de ferramentas para não obscurecer entradas focadas.

Gráficos e estatísticas

• Liderar com o número principal e uma narrativa curta.
• Adicionar legendas compactas e fallback de texto.
• Preferir rolagem horizontal ou comparações paginadas em vez de barras densas ilegíveis.
• Evitar tortas/donuts minúsculos em telas compactas.

Verificação

Para cada verificação abaixo, confirme a condição de aprovação específica e use a ferramenta sugerida. O teste em dispositivo real é o padrão ouro — simuladores são úteis para iteração, mas não podem reproduzir totalmente o tempo do teclado, a inércia de rolagem ou a precisão do toque.

• Retrato e paisagem — O celular permanece no shell mobile em ambas as orientações. Sem quebra de layout, sem estouro de conteúdo, sem mudança repentina para barra lateral desktop ou visualização de vários painéis. Teste a 375px (iPhone SE/mini), 390px (iPhone Pro) e 430px (iPhone Pro Max) em retrato e seus equivalentes em paisagem. Use a barra de ferramentas de dispositivo do Chrome DevTools ou Simulador Xcode.

• Áreas seguras do iOS Safari — O conteúdo não é cortado pela Ilha Dinâmica, cantos arredondados ou indicador de início. Elementos fixos na parte inferior têm preenchimento env(safe-area-inset-bottom) visível (~34px em iPhones com Face ID). Verifique se viewport-fit=cover está definido na tag meta do viewport — sem ele, todos os valores env(safe-area-inset-*) retornam 0. Melhor testado no Simulador Xcode (insets precisos por dispositivo) ou Polypane 26+ (navegador desktop com predefinições reais de áreas seguras). Chrome DevTools 135+ suporta Emulation.setSafeAreaInsetsOverride, mas requer configuração manual.

• Fluxo de formulário com teclado aberto — Foque cada entrada em sequência e verifique: (1) o campo focado rola para a visualização, (2) a ação de envio está visível e tocável, (3) cabeçalhos sticky não obscurecem o campo focado. Esteja ciente de que elementos com position: fixed; bottom: 0 ficam atrás do teclado iOS (o Layout Viewport não encolhe) e position: sticky; bottom: 0 também falha em fixar durante a exibição do teclado (WebKit bug #202120). Playwright e Cypress não podem acionar teclados reais na tela — isso requer teste em dispositivo real ou Simulador Xcode com Safari Web Inspector.

• Texto grande / zoom de exibição — WCAG 1.4.4 (AA) exige texto redimensionável para 200% sem perda de conteúdo. WCAG 1.4.10 (AA) exige refluxo com zoom de 400% (equivalente a viewport de 320px de largura) sem rolagem horizontal. Teste: (1) definindo o zoom do navegador para 200% e verificando se não há truncamento ou sobreposição, (2) definindo viewport para 1280px e zoom para 400% para simular o requisito de refluxo de 320px, (3) ativando Ajustes do iOS > Acessibilidade > Tela e Tamanho do Texto > Texto Maior no máximo. Verifique se a tag meta do viewport não define user-scalable=no ou maximum-scale abaixo de 2.0.

• Movimento reduzido — As animações respeitam prefers-reduced-motion: reduce. As transições ainda comunicam mudanças de estado, mas usam crossfades ou opacidade em vez de movimento. O iOS Safari não suprime automaticamente animações web quando o Movimento Reduzido está ativado — o desenvolvedor deve lidar com isso. Teste via: Aba Rendering do Chrome DevTools > "Emular prefers-reduced-motion", substituições de preferência do Web Inspector do Safari (disponível desde o final de 2022) ou page.emulateMedia({ reducedMotion: 'reduce' }) do Playwright.

• Estados vazio/erro/carregamento — Esses estados são renderizados corretamente na tela compacta. Os esqueletos de carregamento correspondem ao layout mobile, não ao desktop. As mensagens de erro são legíveis sem rolagem.

• Modo autônomo/PWA (quando relevante) — Se o aplicativo suportar display: standalone, verifique se a área da barra de status, o indicador de início e as regiões de gestos são tratadas. svh e dvh resolvem para o mesmo valor no modo autônomo, pois não há barra de ferramentas recolhível (WebKit bug #261185). O WebKit bug #254868 pode causar valores de altura incorretos. O WebKit bug #265578 faz com que a altura do viewport visual seja atualizada tarde quando a UI do Safari anima de volta à visualização.

• Sem rolagem horizontal do documento — Deslizar para a esquerda/direita no corpo da página não produz movimento. Qualquer rolagem horizontal é isolada em um contêiner específico (tabela, carrossel) com affordance de estouro visível e overscroll-behavior: contain para evitar acionar mudanças de UI do Safari (WebKit bug #240861). Para verificação automatizada no Playwright:

  const hasOverflow = await page.evaluate(() =>
    document.documentElement.scrollWidth > document.documentElement.clientWidth
  );
  expect(hasOverflow).toBe(false);
  

Entregável

Ao usar esta habilidade, produza:

• um plano curto de adaptação mobile
• os problemas de maior risco primeiro
• alterações concretas por tela
• verificação realizada
• qualquer incerteza restante sobre dispositivo/navegador