Web Responsivo: mobile-first, qualquer stack, verificado
O objetivo é um layout que funciona em qualquer largura, não em cinco larguras de dispositivos escolhidas.
Os bugs vivem no meio: 412px, 905px, o pixel onde max-width: 767px e min-width: 769px ambos
param de se aplicar. Portanto, esta habilidade tem duas metades que sempre andam juntas:
- Construa mobile-first: escreva o layout para que ele se adapte sozinho e precise de poucos breakpoints.
- Comprove: execute
scripts/check_responsive.py, que renderiza a página e mede o layout em cada largura. "Parece bom para mim" a partir de uma ou duas capturas de tela não conta como prova. Pronto significa que o verificador relata 0 erros.
O verificador vê apenas a página renderizada (caixas DOM e estilos computados), portanto não importa como o CSS foi escrito. É isso que o faz funcionar para qualquer tecnologia.
0. Leia o projeto primeiro
Antes de escrever CSS, gaste um minuto descobrindo:
- Como os estilos são escritos aqui: Tailwind (
tailwind.config.*ou@themeno CSS), variáveis Bootstrap/SCSS, CSS modules, styled-components/emotion, estilos escopados Vue/Svelte, arquivos CSS puros. Escreva novo código no mesmo sistema com os mesmos tokens. Um segundo sistema de estilização é um bug de manutenção. - Os breakpoints existentes, e reutilize-os. Não invente novos a menos que o conteúdo precise de um.
- Como ver a página: um arquivo
.htmlestático, ou um servidor de desenvolvimento (npm run dev,php artisan serve,python manage.py runserver,rails s,dotnet watch...). Você precisa de uma URL ou caminho de arquivo para o verificador.
references/stacks.md mostra a sintaxe mobile-first e a localização de breakpoints para stacks comuns.
1. Construa mobile-first
Escreva estilos base para a tela menor, sem media query. Adicione layout à medida que o espaço cresce, usando
consultas min-width. Telefones recebem o CSS mais simples, o conteúdo empilha naturalmente e cada breakpoint apenas
adiciona coisas. A maneira desktop-first (escrever para desktop, depois remendar com max-width) deixa lacunas
entre os remendos, e essas lacunas são onde a maioria dos bugs responsivos aparece.
Se o código já for desktop-first, não o reescreva. Escreva suas partes novas ou alteradas mobile-first dentro de suas convenções e corrija o que o verificador encontrar.
Prefira layouts que se adaptam sem breakpoints
- Grades:
grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr)). Colunas aparecem conforme o espaço permite, sem breakpoint e sem transbordar em 320px (a partemin(100%, ...)é o que impede isso). - Linhas que devem quebrar:
display: flex; flex-wrap: wrap; gap: …com umflex-basissensato. - Tamanhos:
width: 100%; max-width: 40remem vez dewidth: 640px. Tipografia fluida e espaçamento comclamp(min, preferido, max). - Um componente que aparece em slots de larguras diferentes (sidebar vs. coluna principal): use consultas de contêiner
(
container-type: inline-size+@container), para que ele responda ao seu slot, não à janela. - Adicione um breakpoint onde o conteúdo quebra (estreite a janela até que algo pareça errado), não em uma largura de dispositivo.
Quebradores de layout conhecidos. Verifique cada um ao escrevê-lo.
| Quebrador | Por que quebra | Use em vez disso |
|---|---|---|
width/min-width fixa em px em contêineres | mais largo que um telefone de 320px | max-width + width:100%, %, fr, minmax() |
| filho flex/grid com conteúdo longo | filhos padrão definem min-width: auto e se recusam a encolher | min-width: 0 no filho (ou minmax(0,1fr)) |
| palavras longas, URLs, e-mails, códigos | sem oportunidade de quebra | overflow-wrap: anywhere em contêineres de texto |
white-space: nowrap em botões/rótulos/nav | texto não pode quebrar, empurra a largura | permitir quebra, ou reticências com min-width:0 + um title |
| imagens, vídeos, iframes, embeds | largura intrínseca > tela | max-width:100%; height:auto; aspect-ratio para embeds |
| tabelas | colunas não podem encolher abaixo do conteúdo | envolva em contêiner overflow-x:auto, ou empilhe linhas em telas pequenas |
blocos pre/code | espaços em branco preservados | overflow-x:auto no bloco |
100vw | inclui a barra de rolagem, então é ~15px mais largo no desktop | 100% (ou 100dvw apenas para sangria total com cuidado) |
height fixa em caixas com texto | o texto quebra em mais linhas em telefones e derrama/corta | min-height, ou sem altura |
| posicionamento absoluto de conteúdo | não ocupa espaço; colide em outras larguras | fluxo normal/grid; absoluto apenas para decoração |
height: 100vh em heróis | barras do navegador móvel e telas curtas em paisagem cortam | min-height: 100svh (com fallback 100vh antes) |
Nunca esconda o sintoma
- Sem
overflow-x: hiddenemhtml/bodypara parar a rolagem lateral. Esconde o bug enquanto o conteúdo ainda está cortado (e quebraposition: sticky). Encontre o elemento que é muito largo. O verificador relata esse mascaramento comoclipped-offscreen. - Sem
user-scalable=nooumaximum-scale=1. Bloquear o zoom é uma falha de acessibilidade (WCAG 1.4.4). - Sem verificações de largura em JavaScript ou sniffing de user-agent para layout. Consultas de mídia/contêiner CSS fazem isso
sem flicker. JS é bom para comportamento (
matchMedia), não para layout. - Não altere o teste para fazê-lo passar (aumentar
--min, adicionar ignorados para fazer os erros desaparecerem).
Toque, entrada, viewport
<meta name="viewport" content="width=device-width, initial-scale=1">em todo cabeçalho de página.- Alvos de toque com pelo menos 24x24px (WCAG 2.2 AA). Mire em 44x44px para botões e controles de ícone em telas sensíveis ao toque, e mantenha espaço entre vizinhos.
- UI apenas com hover (menus, tooltips que revelam conteúdo) precisa de
@media (hover: hover)e uma alternativa de toque. - Campos de formulário
font-size: 16pxou mais em telefones, caso contrário o iOS Safari amplia ao focar. Usetype,inputmodeeautocompleteadequados. - Telefones curtos em paisagem (320–430px de altura) são reais. Headers fixos mais banners de cookies não devem cobrir
mais de cerca de um terço da tela. Recolha ou encolha-os em alturas curtas
(
@media (max-height: 500px)). - Dispositivos com entalhe: use padding
env(safe-area-inset-*)apenas junto comviewport-fit=cover.
Tipografia, mídia, navegação, conteúdo
rempara tipo,clamp()para títulos, comprimento de linha limitado (max-width: 65chou mais), line-height sem unidade.- Imagens:
srcset/sizespara fotos, atributoswidth/heightouaspect-ratiopara evitar mudança de layout,object-fit: coverquando a proporção da caixa diferir da imagem (caso contrário, ela estica). - Navegação: em telas pequenas use um
<button>real comaria-expanded/aria-controlsque abre o menu. Mostre links embutidos a partir da largura onde eles realmente cabem. - Mantenha a paridade de conteúdo: não remova conteúdo no mobile porque foi difícil encaixá-lo. Reordene, condense ou recolha-o.
references/patterns.md tem CSS pronto para cópia para cada um destes (grid, nav, tabela, formulário, herói, cards, mídia).
2. Verifique: execute o verificador
Configuração única (Python 3.9+):
pip install playwright
python -m playwright install chromium
Execute-o contra a página renderizada. Inicie o servidor de desenvolvimento primeiro, se houver um.
python <skill-dir>/scripts/check_responsive.py http://localhost:5173/ --out responsive-report
python <skill-dir>/scripts/check_responsive.py site/index.html --out responsive-report # arquivo estático
- Várias páginas: passe várias URLs. Verifique cada página ou rota que você alterou, mais uma que use o layout compartilhado (header/footer).
- SPA que renderiza tarde:
--wait-for "#app main". Páginas logadas:--storage-state state.json. - Loop interno durante a correção:
--quick(~5–10 s). Execute uma execução completa antes de dizer que terminou (~20–40 s por página). - Código de saída: 0 = sem erros, 1 = erros encontrados (ou avisos com
--strict), 2 = não foi possível executar.
O que ele faz: varre 320→1920px em passos de 10px mais larguras comuns de dispositivos mais ambos os lados de cada breakpoint encontrado no CSS da própria página. Ele recarrega larguras chave com emulação móvel real (toque, meta viewport) e verifica quatro telefones curtos em paisagem. Em cada largura ele mede:
| Erro (deve corrigir) | Significado |
|---|---|
horizontal-overflow | a página rola lateralmente; nomeia o elemento que se destaca e o que o força a ficar largo |
clipped-offscreen | conteúdo cortado na borda da tela (geralmente escondido por overflow-x:hidden no body) |
occluded-target | um link/botão está coberto por outro elemento (ou por uma barra fixa em toda posição de rolagem) |
small-target | alvo de toque abaixo de 24px e apertado por vizinhos |
text-spill / text-clipped | o texto sai de sua caixa / é cortado por um tamanho fixo + overflow:hidden |
text-overlap | texto de dois blocos não relacionados desenhado um sobre o outro |
distorted-media | imagem/vídeo esticado (proporção da caixa ≠ proporção natural, sem object-fit) |
viewport-meta, layout-viewport | meta viewport ausente/bloqueando zoom; telefone renderiza na largura do desktop |
Avisos (corrija-os ou explique por que não): touch-target (controles <44px em larguras de toque), small-text
(<12px em telefones), input-zoom (inputs <16px), fixed-coverage (barras fixas/sticky >35% de uma tela curta).
O relatório (report.md, report.json) agrupa os resultados assim:
1. **horizontal-overflow** em 320-610px; 568x320 - `body > main.wrap > div.promo` "Fresh coffee..."
- pior: 296 px além da borda direita em 320px
- pistas: permanece exatamente 600px de largura em cada largura com falha: uma largura fixa - use max-width/%/fr/minmax em vez disso
- close-up: responsive-report/closeups/01-horizontal-overflow-320.png
A linha de pistas é o diagnóstico. Leia-a antes de abrir o CSS.
3. Loop de correção
- Corrija a menor largura com falha primeiro. O mobile é a base, e corrigi-lo geralmente corrige o resto.
- Corrija a causa raiz para a qual as pistas apontam, na fonte que o projeto usa (a classe Tailwind, o
partial SCSS, o componente estilizado), não com uma substituição pontual.
references/checks.mdlista causas e correções para cada verificação. - Reexecute (
--quick), repita, depois faça uma execução completa. Pare quando houver 0 erros e cada aviso estiver corrigido ou tiver um motivo. - Algo intencionalmente quebra uma regra (uma forma decorativa sangrando fora da tela, uma sobreposição deliberada
em uma colagem de herói)? Marque esse elemento
data-responsive-ignore="text-overlap"(nomes de verificação separados por espaço) e adicione um comentário no código dizendo por quê. Ignorar conteúdo real para obter uma execução verde é o mesmo que não testar.
4. Olhe para isso
O verificador encontra o que está quebrado de forma mensurável. Alguns problemas não são mensuráveis: quebras estranhas (uma
palavra órfã em um botão), um último item de grade solitário, grandes gutters vazios em 1920px+, um corte de imagem que
corta o assunto, um menu tecnicamente bom mas difícil de usar. Abra as capturas de tela que a execução
salvou (screens/320.png, 375, 768, 1024, 1440 e os closeups/) e olhe para elas. Se você
não puder visualizar imagens, diga isso no relatório em vez de reivindicar revisão visual.
Ao relatar problemas visuais ao usuário, descreva os elementos pelo que e onde eles estão ("o selo de preço na foto do produto", "o segundo card na grade do menu"), não por nomes de classe. Os usuários não leem seletores DOM. Mantenha os seletores em suas próprias anotações para encontrar o código.
5. Solicitações apenas de auditoria
Se o usuário pedir para verificar ou auditar um site (não corrigi-lo), execute o verificador completo primeiro e relate os resultados agrupados por gravidade e faixa de largura, com capturas de tela, antes de tocar no código. Pergunte antes de corrigir se o escopo for grande.
6. Informe ao usuário o que foi verificado
Termine com um resumo curto e factual:
- o que você alterou (arquivos, componentes);
- o que foi testado: páginas,
N larguras 320–1920px, telefones em paisagem; resultado do verificador (0 erros, 1 aviso); - cada aviso restante e por que permanece;
- onde estão as capturas de tela;
- o que não foi verificado. O verificador usa apenas Chromium, portanto peculiaridades do Safari/Firefox, teclados de dispositivos reais, zoom de 200% apenas com texto, RTL e páginas atrás de login sem um estado de armazenamento não são cobertos a menos que você os tenha testado separadamente.
Arquivos de referência
references/patterns.md: CSS mobile-first pronto para cópia para blocos de construção comuns. Leia-o ao construir um novo layout ou componente.references/stacks.md: como mobile-first e breakpoints se parecem em Tailwind, Bootstrap, SCSS, CSS modules, CSS-in-JS, MUI/Chakra, Vue/Svelte/Angular, templates de servidor, além de como servir cada um para o verificador.references/checks.md: cada resultado do verificador com causas típicas, correções e falsos positivos conhecidos. Leia-o quando a causa de um resultado não for óbvia.scripts/selftest/run_selftest.py: prova que o verificador ainda captura cada tipo de bug (14 fixtures). Execute-o após editar o verificador.