Communitygithub.com

CharbelElBateh/personal-website

Faça seu web app parecer nativo no celular — os pequenos ajustes de CSS e meta-tags que separam 'um site no navegador' de algo que parece instalado.

O que é personal-website?

Esta skill é um conjunto de regras e técnicas de design engineering para eliminar os sinais mais comuns que denunciam que uma aplicação web não é um app nativo em dispositivos móveis. Ela aborda desde hover states presos após o toque, flashes cinzas no toque, o bug do 100vh, zoom em inputs, atraso no toque, pull-to-refresh que sequestra o scroll, conteúdo escondido sob o notch, seleção indesejada de texto em botões, carrosséis que rolam na direção errada, cores incompatíveis da barra de status e a regra fundamental de testar em hardware real. A skill não cobre animações (que é papel da skill `animate`) nem React Native (que é papel da `animate-expo`). Ela se concentra exclusivamente na camada de plataforma: viewport, toque, scroll, áreas seguras e a interface do navegador. O conteúdo é baseado na filosofia de design engineering de Emil Kowalski e é útil ao construir PWAs, bottom sheets, carrosséis, layouts full-screen ou qualquer interação por toque, ou quando algo 'funciona no Chrome mas parece estranho no celular'. As correções priorizam CSS e meta tags sobre JavaScript, e o uso de media queries de capacidade (como hover e pointer) em vez de detecção de dispositivo.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/CharbelElBateh/personal-website/tree/HEAD/.claude/skills/mobile-native

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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:

  1. 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.
  2. 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

  1. 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: none no corpo do texto é um defeito, em um botão está correto.
  2. 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.
  3. 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.
  4. Nunca desabilite o zoom. user-scalable=no e maximum-scale=1 são falhas de acessibilidade. Em vez disso, corrija o tamanho da fonte do input, que é o que estava causando o zoom.
  5. 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.

ProblemaSolução
Estado de hover preso após toqueEnvolva em @media (hover: hover) and (pointer: fine)
Flash cinza/azul no toqueRemova -webkit-tap-highlight-color
Layout com altura errada100dvh (app) ou 100svh (hero)
Página dá zoom no inputTamanho da fonte do input 16px no mínimo
Toque parece lentoFeedback no pointer-down + touch-action: manipulation
Pull-to-refresh sequestra o scrolloverscroll-behavior: none em html, body
Conteúdo para no notchviewport-fit=cover + env(safe-area-inset-*)
Toque longo seleciona texto do botãoAdicione user-select: none
Carrossel rola verticalmentetouch-action: pan-y na superfície de gesto
Cor da barra de status não correspondetheme-color por esquema de cores
Funciona no Chrome, errado no telefoneTeste 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;
}

Individual skills in this repo

This repo contains 13 individual skills — each has its own dedicated page.

CharbelElBateh/personal-website

Build animations in React Native and Expo, making the decisions in the order that determines whether they feel right — should it animate, which thread it runs on, which properties, spring or timing, how the gesture hands off, how it degrades. Writes the implementation with Reanimated, Gesture Handler, Expo Router and expo-haptics. Use when animating anything in an Expo app, adding gestures, sheets, screen transitions, press feedback or haptics, or fixing motion that stutters on device. For web animation use `animate`.

CharbelElBateh/personal-website

Build an animation from scratch, making the decisions in the order that determines whether it feels right — should it animate at all, what purpose, which tool, which properties, which curve and duration, how it interrupts, how it exits. Writes the implementation. Use when asked to animate something, add motion, make a component feel alive, or build a transition. For critiquing existing motion use review-animations; for auditing a whole codebase use improve-animations.

CharbelElBateh/personal-website

Reverse-lookup glossary that turns a vague description of a web animation or motion effect into its exact term ("the bouncy thing when a popover opens" → Pop in; "the iOS rubber-band scroll" → Rubber-banding). Use when the user asks "what's it called when…", or describes a motion effect without knowing its name and wants the right word to prompt an AI or designer with. For naming an effect, not designing or building one.

CharbelElBateh/personal-website

Apple's approach to interface design and fluid, physical motion, translated for the web. Use when building or reviewing gesture-driven UI, spring animations, drag/swipe/sheet interactions, momentum and interruptible transitions, translucent materials and depth, typography (optical sizing, tracking, leading), reduced-motion, or the design foundations (feedback, spatial consistency, restraint) behind Apple-style interfaces.

CharbelElBateh/personal-website

Guide to Sonner, the React toast library — install and wire up the Toaster, pick the right toast() call, promise and loading toasts, updating, dismissing and persisting toasts, styling, theming and icons, positioning and multiple toasters. Use when working with Sonner or troubleshooting it — toasts that don't appear, appear twice, lose their styles, ignore Tailwind classes, sit behind a modal, or don't follow dark mode.

CharbelElBateh/personal-website

Try to break a piece of UI by feeding it worst-case data — long names, unbreakable emails, one-letter names, missing fields, huge counts, zero items, long labels, non-Latin text, emoji, extreme numbers — then render it behind a "Demo data / Worst case" toggle and report everything that broke, with the fix for each. Use when the user asks to stress-test, break, or find edge cases in a component or screen, or to "try the worst case". For visual design critique use emil-design-eng; for motion use review-animations.

CharbelElBateh/personal-website

This skill encodes Emil Kowalski's philosophy on UI polish, component design, animation decisions, and the invisible details that make software feel great.

CharbelElBateh/personal-website

Search a codebase or UI for places that don't animate but should, and reject everything that shouldn't. Read-only; it proposes motion with exact values, it does not implement it. Use when the user asks "what could be animated here?" or wants to "make this feel more alive". For fixing existing animations, use improve-animations or review-animations instead.

CharbelElBateh/personal-website

Survey a codebase's animation and motion code as a senior motion advisor, then produce a prioritized audit and self-contained implementation plans for other agents (or cheaper models) to execute. Read-only on source code — it plans improvements, it does not apply them. Use when the user asks to "improve the animations", "audit the motion", "make this app feel better", or wants a roadmap of animation fixes rather than a review of a single diff.

CharbelElBateh/personal-website

Pick the right library for a given frontend task from a curated, opinionated list — numbers, OTP inputs, charts, command menus, virtualization, drag and drop, toasts, state, styling, and more. Only runs when explicitly invoked; it does not trigger on its own.

CharbelElBateh/personal-website

Build multiple genuinely different versions of a UI piece you describe, rendered behind a visual picker so you can flip through them live and promote the one that feels right. Only runs when explicitly invoked; it does not trigger on its own.

CharbelElBateh/personal-website

Reviews animation and motion code against a high craft bar derived from Emil Kowalski's design engineering philosophy. Default to flagging; approval is earned.

CharbelElBateh/personal-website

How to write modern Swift well — modeling with value types, Swift 6 data-race safety and approachable concurrency (@concurrent, main-actor-by-default, actors, task groups), protocols and generics (some vs any), API design, performance and ARC, Swift Testing, macros, and the modern language features agents don't know about yet. Use when writing, reviewing, or migrating Swift, or when a concurrency error, a hang, a data race, a retain cycle, or a performance problem needs fixing.

Habilidades Relacionadas