responsivo-web

Habilidade de codificação. Crie e verifique UIs web que funcionam em qualquer largura de tela (de telefones de 320px a monitores de 2560px) usando uma abordagem mobile-first que funciona com qualquer stack: CSS puro, Tailwind, Bootstrap, SCSS, CSS modules, CSS-in-JS, React/Vue/Svelte/Angular ou templates renderizados no servidor. Inclui um verificador Playwright que varre mais de 150 larguras, além de telefones em paisagem, e mede quebras reais de layout: rolagem horizontal, texto cortado ou sobreposto, alvos de toque cobertos ou muito pequenos, imagens esticadas, meta viewport ausente ou com zoom bloqueado.

O que é responsivo-web?

A habilidade 'Responsive Web' é uma ferramenta completa para desenvolvedores e agentes de IA que precisam construir e verificar layouts web verdadeiramente responsivos, com suporte a telas de 320px a 2560px. Ela combina uma metodologia de construção mobile-first com um verificador automático baseado em Playwright que escaneia centenas de larguras, incluindo as bordas de breakpoints e telefones em paisagem. O principal objetivo é eliminar bugs de layout que frequentemente passam despercebidos em testes manuais com apenas algumas resoluções. A habilidade é agnóstica de tecnologia, funcionando com qualquer stack CSS (Tailwind, Bootstrap, SCSS, CSS modules, CSS-in-JS, etc.) e frameworks (React, Vue, Svelte, Angular, ou templates server-side). Ela detecta e diagnostica problemas mensuráveis como overflow horizontal, texto cortado/sobreposto, alvos de toque pequenos demais, imagens esticadas e viewport meta ausente. O fluxo de trabalho incentiva um ciclo de correção focado nas menores larguras primeiro, fornecendo diagnósticos precisos (como "elemento X tem largura fixa de 600px") em vez de apenas apontar erros, tornando-a ideal para integração em agentes de codificação autônomos como Claude Code, Cursor ou Codex.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/isikenes35/responsive-web/tree/HEAD

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

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

Documentação

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:

  1. Construa mobile-first: escreva o layout para que ele se adapte sozinho e precise de poucos breakpoints.
  2. 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 @theme no 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 .html está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 parte min(100%, ...) é o que impede isso).
  • Linhas que devem quebrar: display: flex; flex-wrap: wrap; gap: … com um flex-basis sensato.
  • Tamanhos: width: 100%; max-width: 40rem em vez de width: 640px. Tipografia fluida e espaçamento com clamp(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.

QuebradorPor que quebraUse em vez disso
width/min-width fixa em px em contêineresmais largo que um telefone de 320pxmax-width + width:100%, %, fr, minmax()
filho flex/grid com conteúdo longofilhos padrão definem min-width: auto e se recusam a encolhermin-width: 0 no filho (ou minmax(0,1fr))
palavras longas, URLs, e-mails, códigossem oportunidade de quebraoverflow-wrap: anywhere em contêineres de texto
white-space: nowrap em botões/rótulos/navtexto não pode quebrar, empurra a largurapermitir quebra, ou reticências com min-width:0 + um title
imagens, vídeos, iframes, embedslargura intrínseca > telamax-width:100%; height:auto; aspect-ratio para embeds
tabelascolunas não podem encolher abaixo do conteúdoenvolva em contêiner overflow-x:auto, ou empilhe linhas em telas pequenas
blocos pre/codeespaços em branco preservadosoverflow-x:auto no bloco
100vwinclui a barra de rolagem, então é ~15px mais largo no desktop100% (ou 100dvw apenas para sangria total com cuidado)
height fixa em caixas com textoo texto quebra em mais linhas em telefones e derrama/cortamin-height, ou sem altura
posicionamento absoluto de conteúdonão ocupa espaço; colide em outras largurasfluxo normal/grid; absoluto apenas para decoração
height: 100vh em heróisbarras do navegador móvel e telas curtas em paisagem cortammin-height: 100svh (com fallback 100vh antes)

Nunca esconda o sintoma

  • Sem overflow-x: hidden em html/body para parar a rolagem lateral. Esconde o bug enquanto o conteúdo ainda está cortado (e quebra position: sticky). Encontre o elemento que é muito largo. O verificador relata esse mascaramento como clipped-offscreen.
  • Sem user-scalable=no ou maximum-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: 16px ou mais em telefones, caso contrário o iOS Safari amplia ao focar. Use type, inputmode e autocomplete adequados.
  • 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 com viewport-fit=cover.

Tipografia, mídia, navegação, conteúdo

  • rem para tipo, clamp() para títulos, comprimento de linha limitado (max-width: 65ch ou mais), line-height sem unidade.
  • Imagens: srcset/sizes para fotos, atributos width/height ou aspect-ratio para evitar mudança de layout, object-fit: cover quando a proporção da caixa diferir da imagem (caso contrário, ela estica).
  • Navegação: em telas pequenas use um <button> real com aria-expanded/aria-controls que 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-overflowa página rola lateralmente; nomeia o elemento que se destaca e o que o força a ficar largo
clipped-offscreenconteúdo cortado na borda da tela (geralmente escondido por overflow-x:hidden no body)
occluded-targetum link/botão está coberto por outro elemento (ou por uma barra fixa em toda posição de rolagem)
small-targetalvo de toque abaixo de 24px e apertado por vizinhos
text-spill / text-clippedo texto sai de sua caixa / é cortado por um tamanho fixo + overflow:hidden
text-overlaptexto de dois blocos não relacionados desenhado um sobre o outro
distorted-mediaimagem/vídeo esticado (proporção da caixa ≠ proporção natural, sem object-fit)
viewport-meta, layout-viewportmeta 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

  1. Corrija a menor largura com falha primeiro. O mobile é a base, e corrigi-lo geralmente corrige o resto.
  2. 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.md lista causas e correções para cada verificação.
  3. Reexecute (--quick), repita, depois faça uma execução completa. Pare quando houver 0 erros e cada aviso estiver corrigido ou tiver um motivo.
  4. 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.

Habilidades Relacionadas