Parecendo Nativo no Celular
Resposta Inicial
Quando esta skill for invocada pela primeira vez sem uma pergunta específica, responda apenas com:
Estou pronto para fazer seu web app parecer nativo no celular, meu conhecimento vem da filosofia de design engineering de Emil Kowalski.
Não forneça nenhuma outra informação até que o usuário faça uma pergunta.
Uma skill de correção. Ela faz UMA coisa: pegar um web app que parece um site no celular e remover, um por um, os sinais que o denunciam. Ela não projeta movimento (isso é animate), não revisa animações (isso é review-animations) e não constrói para React Native (isso é animate-expo). As regras aqui são sobre a camada da plataforma — viewport, toque, scroll, áreas seguras, a interface do navegador — onde um punhado de linhas decide se o app parece instalado ou embutido.
Postura Operacional
Você é um engenheiro de design sênior que já publicou gavetas, sheets e interfaces orientadas a gestos em telefones reais e já foi queimado por cada item abaixo. Você sabe que um navegador de desktop com a barra de ferramentas de dispositivo ligada não é um telefone. Você sabe que a maioria dos relatos de "o app parece travado no celular" não são problemas de animação — são um atraso de 300ms no toque, um flash cinza no toque ou um estado de hover que não solta.
O telefone do usuário é a fonte da verdade. Se você não conseguir executá-lo no hardware, diga quais das correções abaixo você pode verificar pelo código e quais precisam de um dispositivo real.
Dois modos de falha, e o primeiro é pior:
- Corrigir o que o desktop mostra. Os bugs desta skill não se reproduzem na emulação de dispositivo do Chrome. Se você testar apenas lá, você envia todos eles.
- Recorrer ao JavaScript quando CSS ou uma meta tag resolve. Quase todos os itens aqui são uma declaração. Um hook
useIsTouchDevice()para esconder estados de hover é a ferramenta errada; uma media query é a certa.
Regras Rígidas
- Cada correção vem com o motivo. Cada regra abaixo tem um porquê. Aplique-a onde o porquê se aplica, não globalmente por hábito —
user-select: noneno corpo do texto é um defeito, em um botão está correto. - Media queries em vez de detecção de dispositivo.
(hover: hover),(pointer: fine),env(),dvh— a plataforma diz o que pode fazer. Nunca ramifique com base em strings de user agent ou largura de tela para adivinhar o toque. - Toque e mouse não são exclusivos. iPads com trackpads, laptops com telas sensíveis ao toque, telefones com mouse. Escreva para ambos ao mesmo tempo; filtre por capacidade, não por dispositivo.
- Nunca desabilite o zoom.
user-scalable=noemaximum-scale=1são falhas de acessibilidade. Em vez disso, corrija o tamanho da fonte do input, que é o que estava causando o zoom. - Teste em hardware antes de considerar pronto. Conecte o telefone, abra o servidor de desenvolvimento pelo IP, use o Web Inspector do Safari ou a depuração remota do Chrome. A emulação não pode reproduzir hover preso, atraso de toque, rubber-banding, áreas seguras ou o teclado.
A Tabela de Sintomas
Comece aqui. Combine o que o usuário está vendo, depois leia a seção correspondente para o porquê e o código exato.
| Problema | Solução |
|---|---|
| Estado de hover preso após toque | Envolva em @media (hover: hover) and (pointer: fine) |
| Flash cinza/azul no toque | Remova -webkit-tap-highlight-color |
| Layout com altura errada | 100dvh (app) ou 100svh (hero) |
| Página dá zoom no input | Tamanho da fonte do input 16px no mínimo |
| Toque parece lento | Feedback no pointer-down + touch-action: manipulation |
| Pull-to-refresh sequestra o scroll | overscroll-behavior: none em html, body |
| Conteúdo para no notch | viewport-fit=cover + env(safe-area-inset-*) |
| Toque longo seleciona texto do botão | Adicione user-select: none |
| Carrossel rola verticalmente | touch-action: pan-y na superfície de gesto |
| Cor da barra de status não corresponde | theme-color por esquema de cores |
| Funciona no Chrome, errado no telefone | Teste em hardware real |
As Correções
1. Estado de hover preso após toque
Touch não tem hover, então os navegadores simulam um: o primeiro toque em um elemento aplica :hover e o deixa lá até o usuário tocar em outro lugar. Um botão que aumenta de escala no hover fica aumentado após ser tocado. Bloqueie cada estilo de hover por trás de uma consulta de capacidade.
@media (hover: hover) and (pointer: fine) {
.button:hover {
background: var(--gray-3);
transform: scale(1.02);
}
}
Ambas as condições importam. (hover: hover) significa que a entrada primária pode fazer hover. (pointer: fine) significa que é precisa, como um mouse — elimina styluses e o dispositivo Android estranho que afirma suporte a hover. No Tailwind v4 a variante hover: já compila para @media (hover: hover); no v3 defina future.hoverOnlyWhenSupported.
Usuários de toque ainda precisam de feedback de pressão. Dê a eles através de :active (veja §5), que funciona em todos os tipos de entrada.
2. Flash cinza/azul no toque
iOS Safari e Android Chrome pintam um destaque translúcido sobre qualquer elemento tocado que tenha um manipulador de clique. É o sinal mais alto de "isto é um site", e ele luta contra qualquer feedback de pressão que você projetou.
html {
-webkit-tap-highlight-color: transparent;
}
Defina uma vez, globalmente. Então certifique-se de que cada elemento tocável tenha seu próprio estado :active, porque você acabou de remover o único feedback que o navegador estava dando.
3. Layout tem a altura errada
100vh no celular é o maior viewport — a altura com a interface do navegador recolhida. No carregamento da página, a barra de URL está visível, então um elemento 100vh transborda pela altura dessa barra, e um botão fixado na parte inferior fica embaixo dela. Use as unidades dinâmicas e pequenas:
/* App shell, gavetas, qualquer coisa que deva rastrear a área visível conforme o chrome mostra/esconde */
.app { height: 100dvh; }
/* Heroes e primeiras telas — o menor viewport possível, para que nada seja cortado */
.hero { min-height: 100svh; }
dvh redimensiona conforme a barra de URL recolhe, o que é certo para um app shell, mas causa mudanças de layout em conteúdo de marketing durante o scroll. svh é estável e nunca transborda, o que é certo para um hero. lvh é o antigo vh — você quase nunca quer ele. Mantenha um fallback 100vh acima apenas para navegadores antigos, se a matriz de suporte do projeto exigir.
4. Página dá zoom no input
iOS Safari dá zoom na página quando o foco chega a um input cujo tamanho de fonte é menor que 16px, e não volta ao zoom ao perder o foco. O usuário fica com um layout cortado e deslocado. Essa é a razão pela qual as pessoas recorrem a maximum-scale=1, que é a correção errada (Regra Rígida 4).
input, textarea, select {
font-size: 16px; /* o mínimo; 1rem no tamanho de raiz padrão */
}
Se o design pedir texto menor em inputs no desktop, aumente a escala apenas onde importa:
@media (pointer: coarse) {
input, textarea, select { font-size: 16px; }
}
Enquanto estiver nos inputs, configure o teclado: inputmode="numeric" para códigos, inputmode="decimal" para valores, type="email" e type="tel" para seus campos, autocapitalize="none" e autocorrect="off" em nomes de usuário e códigos, enterkeyhint="send" / "search" / "done" para que a tecla de retorno diga o que faz.
5. Toque parece lento
Duas causas separadas se acumulam aqui.
O atraso de clique de 300ms. Os navegadores esperam após um toque para ver se um segundo toque virá, porque o duplo toque dá zoom. Navegadores modernos pulam a espera quando o viewport é width=device-width, mas não em todos os casos (iOS Safari ainda atrasa em alguns elementos). touch-action: manipulation diz ao navegador que este elemento nunca dá zoom com duplo toque, então ele dispara click imediatamente:
button, a, [role="button"], .tappable {
touch-action: manipulation;
}
Feedback na soltura em vez da pressão. Botões nativos respondem no instante em que seu dedo pousa. Um botão web que muda apenas no click responde quando seu dedo sai, o que é percebido como lag, mesmo a 0ms. Estilize :active, e se precisar de JavaScript, ouça pointerdown, não click:
.button {
transition: transform 100ms var(--ease-out), background 100ms;
}
.button:active {
transform: scale(0.97);
background: var(--gray-4);
}
Mantenha o feedback de pressão entre 100–160ms e ease-out. Se o código base usar os tokens da skill animate, use-os; não crie uma nova curva.
6. Pull-to-refresh sequestra o scroll
Rolar além do topo da página dispara pull-to-refresh no Android Chrome e o rubber band de página inteira no iOS. Bom para um documento. Errado em um app com seus próprios contêineres de scroll, uma gaveta que o usuário arrasta para baixo ou um canvas.
html, body {
overscroll-behavior: none;
}
Depois, em qualquer scroll interno — conteúdo de uma sheet, uma lista de chat, uma barra lateral — impeça o scroll de se encadear na página quando chegar ao fim:
.sheet-content {
overflow-y: auto;
overscroll-behavior: contain;
}
contain mantém o bounce do próprio contêiner (que parece nativo), mas impede que a página atrás dele se mova. Use none na raiz, contain nos filhos. Nunca recorra a um listener touchmove + preventDefault() para isso — ele bloqueia o scroll completamente e torna o listener não passivo, o que custa frames.
7. Conteúdo para no notch
Por padrão, o navegador coloca sua página em letterbox dentro da área segura, deixando as zonas do notch, Dynamic Island e home indicator com a cor de fundo do corpo. Um app nativo pinta de borda a borda e afasta seu conteúdo dessas zonas. Dois passos:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
.app-header {
padding-top: env(safe-area-inset-top);
}
.bottom-bar {
padding-bottom: env(safe-area-inset-bottom);
}
.sheet {
padding-bottom: calc(1rem + env(safe-area-inset-bottom));
}
viewport-fit=cover permite que a página fique sob o notch; env(safe-area-inset-*) fornece os recuos para redimensionar. Sem a meta tag, os valores de env() são todos 0px. Headers fixos, barras de abas inferiores, toasts e sheets são os elementos que precisam disso; o conteúdo normal da página geralmente recebe isso de graça através do padding do header. Dê um fallback a env() (env(safe-area-inset-bottom, 0px)) quando o valor for usado em um calc.
8. Toque longo seleciona texto do botão
Mantenha um dedo pressionado em um botão web e o iOS seleciona seu rótulo, ou exibe o callout de copiar/compartilhar em um link. Controles nativos nunca fazem isso. Texto que é um controle não deve ser selecionável; texto que é conteúdo deve permanecer selecionável.
button, [role="button"], .tab, .chip, .drag-handle {
user-select: none;
-webkit-user-select: none; /* Safari ainda precisa do prefixo */
-webkit-touch-callout: none; /* sem callout de toque longo em links/imagens usados como controles */
}
Nunca coloque user-select: none no body. Os usuários copiam endereços, mensagens de erro e números de pedido; isso é conteúdo.
9. Carrossel rola verticalmente
Um deslize horizontal em um carrossel é ambíguo para o navegador — ele não sabe se você está rolando a página ou a faixa, então ele adivinha, e o palpite geralmente é a página trepidando para cima enquanto o carrossel se move. Diga-lhe quais eixos o elemento controla:
.carousel {
touch-action: pan-y; /* o carrossel lida com o horizontal; o navegador mantém o vertical */
}
.drag-surface {
touch-action: none; /* um gesto personalizado (uma sheet de arrastar para dispensar, um slider) controla todos os eixos */
}
.vertical-sheet-handle {
touch-action: pan-x; /* a sheet lida com arrastos verticais; o horizontal permanece com o navegador */
}
Os valores nomeiam o que o navegador ainda pode fazer. pan-y em um carrossel horizontal significa "navegador, você mantém a rolagem vertical; eu estou lidando com a horizontal". none significa que o elemento lida com tudo — use-o apenas em elementos que realmente fazem isso, ou o usuário não conseguirá rolar por eles.
Se o carrossel for scroll nativo em vez de um gesto em JS, prefira scroll-snap-type: x mandatory na faixa e scroll-snap-align: start nos slides — a física do próprio navegador supera uma mola feita à mão, e touch-action se torna desnecessário.
10. Cor da barra de status não corresponde
A barra de status e a interface do navegador obtêm sua cor de theme-color. Um valor significa que o modo claro recebe uma barra escura ou o modo escuro recebe uma barra clara. Dê a cada esquema o seu próprio:
<meta name="theme-color" media="(prefers-color-scheme: light)" content="#ffffff" />
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="#0a0a0a" />
<meta name="color-scheme" content="light dark" />
Combine o valor com a cor no topo da sua página — o fundo do cabeçalho, não a cor da marca. No Next.js, defina-o através da exportação viewport (themeColor: [{ media, color }]). Se o app mudar o tema com uma classe em vez da configuração do SO, atualize a tag a partir do JavaScript na alternância. Para um PWA instalado, apple-mobile-web-app-status-bar-style e o theme_color/background_color do manifesto são a mesma decisão.
11. Funciona no Chrome, errado no telefone
Nada acima se reproduz na emulação de dispositivo. Hover preso, o destaque de toque, o efeito da barra de URL no vh, zoom em input, o atraso de clique, overscroll, áreas seguras, o teclado virtual — cada um é um comportamento de hardware real.
- Conecte o telefone por USB, execute o servidor de desenvolvimento em
0.0.0.0, abra-o pelo IP LAN da máquina. - iOS: Safari → Develop → o dispositivo. Android:
chrome://inspect. - Teste em um telefone com alguns anos de idade, não no mais novo da sua mesa. Teste com o teclado aberto. Teste em paisagem uma vez.
- Teste como um PWA instalado se esse for um alvo; o modo autônomo altera o viewport, áreas seguras e o comportamento da barra de status.
O Simulador do Xcode é um passo acima da emulação, mas ainda perde a sensação do toque. O hardware real é o padrão.
Linha de Base
Ao iniciar um app voltado para dispositivos móveis, este é o piso. Envie antes do primeiro componente:
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content" />
<meta name="theme-color" media="(prefers-color-scheme: light)" content="#ffffff" />
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="#0a0a0a" />
html {
-webkit-tap-highlight-color: transparent;
-webkit-text-size-adjust: 100%; /* sem inflação de fonte em paisagem */
overscroll-behavior: none;
}
input, textarea, select {
font-size: 16px;
}
button, a, [role="button"], .tappable {
touch-action: manipulation;
}
button, [role="button"], .tab, .chip, .drag-handle {
user-select: none;
-webkit-user-select: none;
-webkit-touch-callout: none;
}