Responsive Conversion — Web para Mobile e Padroes de Interacao

Converte interface pensada para desktop em interface que funciona de verdade em telas pequenas, e define os padroes de modal, formulario e confirmacao que a conversao expoe. Diferente da skill 02 (que decide como a interface vai parecer antes de existir), esta skill audita e conserta o que ja existe.

Governanca Global

Esta skill segue GLOBAL.md, policies/execution.md, policies/handoffs.md, policies/token-efficiency.md, policies/stack-flexibility.md, policies/evals.md e policies/visual-diff-precision.md (validar correção de layout comparando screenshot antes/depois — decompor em passes de zoom, não afirmar "corrigido" a partir de uma olhada única).

Para catalogo completo de bugs com snippet de fix por framework (Tailwind, CSS puro, styled-components), consultar docs/skill-guides/responsive-conversion.md apenas quando necessario.

Em telas alteradas, complemente a comparação visual com teclado, zoom, conteúdo longo e estados relevantes; marque cada verificação indisponível. skills/91-unslop/references/evidencia-web.md separa o que foi observado do que ainda é hipótese.

Fronteira com skills vizinhas:

02-ui-ux-design define ancora estetica, tokens e wireframe antes de codar — esta skill nao redefine estetica, herda a que ja existe
52-ui-polish cuida do acabamento micro (border radius concentrico, alinhamento optico) depois que o layout esta correto — layout quebrado nao se resolve com polish
22-accessibility-specialist e dona de WCAG completo — esta skill cobre so o subconjunto que colide com mobile (hit area, focus trap em modal, zoom de input)
57-mobile-ux-foundations define, antes desta, onde o elemento deve morar pela zona do polegar, como o tema escuro se comporta, como tratar espera acima de 1s e como desenhar login/onboarding — esta skill executa o layout dentro dessas restricoes
58-i18n-localization trata a quebra causada pelo conteudo (texto traduzido cresce, RTL inverte a direcao); esta skill trata a quebra causada pela largura da tela. A raiz costuma ser a mesma — container que se recusa a crescer — entao o fix de min-w-0 daqui frequentemente resolve os dois

Quando Usar

converter tela/app pensado para desktop em versao mobile funcional
corrigir componente que nao ocupa a largura esperada ou corta conteudo
resolver scroll horizontal indevido ou layout que "estoura" a tela
definir comportamento de modal, drawer ou bottom sheet em telas pequenas
especificar fluxo de confirmacao para acao destrutiva ou irreversivel
auditar formulario que fica inutilizavel em mobile

Quando Nao Usar

escolher paleta, tipografia ou direcao visual do zero (isso e 02-ui-ux-design)
ajustar detalhe de acabamento em layout que ja funciona (isso e 52-ui-polish)
auditoria completa de acessibilidade WCAG (isso e 22-accessibility-specialist)
decidir sistema de animacao e motion tokens (isso e 12-motion-design)

Entradas Esperadas

codigo da interface existente (componentes, paginas, CSS/Tailwind)
descricao do sintoma observado, se houver ("nao pega 100%", "corta no meio")
breakpoints e ancora estetica ja definidos (skill 02), se existirem
print/screenshot do bug, quando disponivel

Saidas Esperadas

relatorio de auditoria com sintoma → causa raiz → fix aplicado, por ocorrencia
codigo corrigido nos arquivos reais
checklist de conversao marcado
padroes de modal/confirmacao especificados para os fluxos destrutivos encontrados

Protocolo de Auditoria

Rodar nesta ordem. Cada fase alimenta a seguinte — pular fase gera fix superficial que reaparece.

Fase 1 — Inventario de viewport

Mapear onde o layout assume largura de desktop:

# Larguras fixas em px (o suspeito numero 1)
grep -rn "width: *[0-9]\{3,\}px\|w-\[[0-9]\{3,\}px\]\|min-width: *[0-9]\{3,\}px" src/ app/

# Alturas de viewport legadas (quebram com barra do browser mobile)
grep -rn "100vh\|h-screen\|min-h-screen" src/ app/

# Grids com contagem fixa de coluna
grep -rn "grid-cols-[3-9]\|grid-template-columns" src/ app/

Cada hit e um candidato — nao um bug confirmado. Confirmar na Fase 2.

Fase 2 — Reproduzir em viewport real

Nao confiar em "parece ok no devtools responsivo". Testar em 3 larguras que quebram coisas diferentes:

Largura	Representa	O que quebra tipicamente
320px	iPhone SE / Android pequeno	Largura fixa, botao com texto longo, tabela
390px	iPhone padrao atual	Grid de 2 colunas apertado, modal com padding grande
768px	Tablet retrato / limiar	Layout que troca de sidebar para hamburger no ponto errado

Quando houver Playwright no projeto (skill 05), preferir teste automatizado de viewport a inspecao manual — o teste vira regressao.

Fase 3 — Classificar e corrigir

Usar o catalogo abaixo. Fix sem entender a causa raiz reaparece na proxima tela.

Fase 4 — Verificar sem regressao

Reconferir as 3 larguras da Fase 2 e a largura desktop original — conversao mobile que quebra o desktop nao e conversao, e troca de bug. Largura que quebrou volta pra Fase 3 pra reclassificar a causa raiz (o fix provavelmente resolveu o sintoma numa largura e criou outro numa diferente) — nao ajustar o CSS até "parecer ok" sem reclassificar.

Catalogo de Bugs — Sintoma, Causa, Fix

1. Componente nao ocupa 100% da largura

O sintoma mais comum e quase sempre a mesma causa raiz: item de flex/grid tem min-width: auto por default, entao ele se recusa a encolher abaixo do conteudo, e o container "estoura" em vez de caber.

Sintoma	Causa	Fix
Filho de flex nao encolhe, empurra layout	`min-width: auto` implicito no flex item	`min-w-0` no filho (CSS: `min-width: 0`)
Coluna de grid estoura o container	Mesma causa, em grid	`min-w-0` no item ou `grid-template-columns: minmax(0, 1fr)`
Texto longo sem espaco empurra tudo	Palavra sem quebra (URL, hash, email)	`break-words` / `overflow-wrap: anywhere`
`w-full` nao surte efeito	Pai tem largura intrinseca (`w-fit`, `inline-block`, tabela)	Corrigir o pai, nao o filho
Componente com largura correta mas conteudo vaza	`overflow` nao definido	`overflow-hidden` no container so depois de confirmar que nao esconde conteudo util

Regra: min-w-0 no filho de flex/grid resolve a maioria absoluta destes casos. Aplicar antes de tentar qualquer outra coisa.

2. Altura de viewport quebrada em mobile

100vh no mobile nao e a altura visivel — browsers mobile contam a viewport sem descontar a barra de endereco, entao o conteudo fica cortado atras dela.

Unidade	Comportamento	Quando usar
`100vh`	Altura maxima (barra recolhida) — corta conteudo	Nunca em mobile sem fallback
`100dvh`	Altura dinamica real, acompanha a barra	Default para tela cheia em mobile
`100svh`	Altura minima (barra visivel)	Quando o conteudo nunca pode ficar escondido
`100lvh`	Altura maxima explicita	Background decorativo que pode passar por baixo

Fallback para browsers antigos: declarar 100vh primeiro e 100dvh na linha seguinte — quem nao entende dvh ignora a segunda.

.tela-cheia {
  height: 100vh;
  height: 100dvh;
}

3. Safe area — notch, ilha dinamica e barra de gestos

Conteudo colado na borda em iPhone fica embaixo do notch (topo) ou da barra de gestos (base). Exige duas coisas juntas — falta uma, nao funciona:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">

.header-fixo  { padding-top: env(safe-area-inset-top); }
.barra-inferior { padding-bottom: env(safe-area-inset-bottom); }

/* Somar ao padding proprio em vez de substituir */
.barra-inferior { padding-bottom: calc(1rem + env(safe-area-inset-bottom)); }

Afeta: header fixo, bottom navigation, botao flutuante, bottom sheet, modal full-screen.

4. Scroll horizontal indevido

A pagina inteira desliza pro lado. Debug em ordem — o primeiro hit costuma ser o culpado:

// Cole no console: lista todo elemento mais largo que a tela
document.querySelectorAll('*').forEach(el => {
  if (el.offsetWidth > document.documentElement.offsetWidth) console.log(el);
});

Causas por frequencia: largura fixa em px maior que a tela → margem negativa sem overflow-hidden no pai → 100vw (ignora a barra de scroll, use 100%) → grid com grid-cols-N fixo → imagem sem max-width: 100% → tabela sem wrapper com scroll.

Nunca "resolver" com overflow-x: hidden no body — isso esconde o sintoma, mantem o bug e quebra position: sticky dentro da pagina.

5. Grid e posicionamento que colapsam

Padrao desktop	Conversao mobile	Como
Grid de N colunas fixas	Colunas por espaco disponivel	`grid-cols-[repeat(auto-fit,minmax(280px,1fr))]` — sem media query
Sidebar + conteudo	Stack vertical ou drawer	`flex-col md:flex-row`
Tabela de dados	Cards empilhados	Repetir o dado como card < `md`, tabela >= `md`
Toolbar horizontal	Scroll horizontal proprio ou menu "mais"	Wrapper com `overflow-x-auto` so na toolbar, nunca no body
Modal centralizado	Bottom sheet	Ver secao de modais
Icone + label lado a lado	So icone com `aria-label`	Manter hit area de 44px mesmo sem o label

auto-fit + minmax resolve a maioria dos grids sem escrever uma media query — preferir a media query manual so quando a quebra precisa acontecer em ponto especifico do design.

6. Formulario em mobile

Problema	Fix
iOS aplica zoom ao focar input	`font-size: 16px` minimo no input (nao no label)
Teclado errado (numerico, email)	`inputmode` correto: `numeric`, `decimal`, `email`, `tel`
Autofill nao funciona	`autocomplete` semantico (`given-name`, `cc-number`, `one-time-code`)
Teclado cobre o campo focado	`scroll-margin-bottom` no input ou scroll manual no focus
Campos lado a lado ilegiveis	Empilhar sempre em mobile — `grid-cols-1 md:grid-cols-2`
Botao de submit fora do alcance	Fixar no rodape com `env(safe-area-inset-bottom)`
Erro so no topo do form	Erro inline no campo e foco programatico no primeiro invalido
Erro so aparece no submit	Validar no `blur` de cada campo — no submit, o usuario ja perdeu o contexto do que digitou (ver skill 57)
Label vira placeholder e some ao digitar	Label flutuante — placeholder sozinho quebra leitor de tela e apaga a instrucao (ver skill 57)

Modais, Drawers e Bottom Sheets

Qual usar

Situacao	Desktop	Mobile	Motivo
Confirmar acao curta	Modal centralizado	Modal centralizado (pequeno)	Precisa de foco total, conteudo cabe
Formulario medio/longo	Modal centralizado	Bottom sheet ou tela cheia	Modal com scroll interno em tela pequena e hostil
Navegacao secundaria	Sidebar / dropdown	Drawer lateral	Preserva contexto da tela
Selecao de opcao em lista	Dropdown / popover	Bottom sheet	Alcance do polegar
Conteudo imersivo (imagem, leitura)	Modal grande	Tela cheia (rota propria)	Modal full-screen sem URL quebra o botao voltar

Regra de ouro: se o conteudo do modal exige scroll em mobile, provavelmente deveria ser bottom sheet ou uma rota propria — nao um modal menor.

Requisitos nao-negociaveis de todo modal

Falta qualquer um destes e o modal esta quebrado, independente da aparencia:

Focus trap — Tab circula dentro do modal, nunca vaza para a pagina atras
Retorno de foco — ao fechar, foco volta ao elemento que abriu
Escape fecha — e o mesmo caminho de fechar do botao X
Scroll lock no fundo — a pagina atras nao rola junto (cuidado: overflow: hidden no body perde a posicao de scroll no iOS; salvar e restaurar scrollY)
Role e label — role="dialog" + aria-modal="true" + aria-labelledby apontando para o titulo
Clique no backdrop — fecha em modal informativo; nao fecha em modal com formulario preenchido ou confirmacao destrutiva (evita perda acidental)
Respeitar safe area — bottom sheet precisa de padding-bottom: env(safe-area-inset-bottom)

Preferir primitiva acessivel pronta (Radix Dialog, Headless UI, <dialog> nativo) a implementar focus trap na mao — implementacao propria erra em detalhe de teclado quase sempre.

Bottom sheet — comportamento esperado

Sobe da base, ocupa altura pelo conteudo (max-height: 85dvh como teto)
Handle visual no topo indicando que arrasta
Fecha por: arrastar pra baixo, tocar no backdrop, Escape, botao explicito
Conteudo longo rola dentro da sheet, com a sheet ancorada
Nunca ultrapassar 100dvh nem esconder conteudo atras da barra de gestos

Confirmacao de Acoes — Destrutivo, Envio, Cadastro

O erro mais comum e tratar tudo igual: ou confirma tudo (fricção que treina o usuario a clicar "sim" sem ler), ou nao confirma nada (perda de dado real).

Escolher o padrao pela reversibilidade

Tipo de acao	Padrao correto	Nunca fazer
Reversivel e barata (arquivar, marcar lido, remover item do carrinho)	Executar direto + toast com Desfazer (5-10s)	Modal de confirmacao — fricção sem beneficio
Irreversivel comum (excluir registro, cancelar pedido)	Modal de confirmacao com consequencia explicita	Botao destrutivo sem nenhuma confirmacao
Irreversivel catastrofica (excluir conta, apagar workspace, deletar em massa)	Confirmacao com digitacao do nome do recurso	Modal simples de "Tem certeza?"
Envio que gera efeito externo (enviar email, publicar, cobrar cartao)	Revisao antes + estado de loading bloqueante + confirmacao de sucesso	Permitir duplo clique (submit duplo)
Cadastro/formulario longo	Autosave de rascunho + aviso ao sair com dado nao salvo	Perder tudo em navegacao acidental

Preferir Desfazer a Confirmar sempre que a acao for tecnicamente reversivel — undo respeita mais o tempo do usuario e produz menos erro que um modal que ele aprendeu a dispensar.

Anatomia do modal de confirmacao destrutiva

Titulo:     nomeia a acao e o alvo especifico
            "Excluir o projeto Vendas Q4?"
            NAO: "Tem certeza?" / "Confirmar acao"

Corpo:      consequencia concreta e verificavel
            "Os 128 registros e 3 integracoes serao removidos. Nao da pra desfazer."
            NAO: "Esta acao nao pode ser desfeita." (generico, ninguem le)

Botao 1:    verbo da acao, nao "OK" — visual destrutivo
            "Excluir projeto"
            NAO: "Sim" / "Confirmar" / "OK"

Botao 2:    saida segura, e o default do foco
            "Cancelar"

Foco:       inicia no botao seguro, nunca no destrutivo
Escape:     cancela
Backdrop:   NAO fecha (evita dispensar sem querer)

Para acao catastrofica, exigir digitacao literal do nome do recurso e manter o botao desabilitado ate bater exatamente — atrito proposital e desejavel aqui.

Estados obrigatorios de qualquer acao com efeito

Toda acao que chama API precisa dos quatro:

Idle — botao habilitado com verbo claro
Loading — botao desabilitado com indicacao de progresso (previne submit duplo; nao basta esconder o botao)
Sucesso — confirmacao visivel do que aconteceu, com Desfazer quando aplicavel
Erro — mensagem que diz o que falhou e o que fazer, preservando o dado que o usuario digitou

Nunca fechar o modal antes da resposta chegar: fechar otimista em acao destrutiva esconde o erro do usuario.

Anti-Padroes

overflow-x: hidden no body para "resolver" scroll horizontal — esconde o bug e quebra position: sticky
100vh em tela cheia mobile sem fallback dvh
Media query como primeira ferramenta — testar antes min-w-0, auto-fit/minmax, flex-wrap, clamp()
Detectar mobile por user agent para decidir layout — usar largura de container/viewport
Esconder funcionalidade em mobile (hidden md:block) como solucao de layout — mover ou reorganizar, nao amputar
Modal full-screen sem rota propria — quebra o botao voltar do Android
Backdrop que fecha modal de confirmacao destrutiva ou formulario preenchido
Modal de confirmacao para acao trivialmente reversivel — treina o usuario a confirmar no automatico
"Tem certeza?" sem nomear o alvo nem a consequencia
Botao destrutivo como default do foco
Toast de erro que some sozinho em acao critica — erro precisa persistir ate o usuario agir
touch-action: none global para "resolver" scroll — mata gesto legitimo

Checklist de Conversao

Layout:

Testado em 320px, 390px e 768px, alem do desktop original
Zero scroll horizontal em todas as larguras
Filhos de flex/grid com min-w-0 onde encolhem
dvh em vez de vh em tela cheia (com fallback)
viewport-fit=cover + env(safe-area-inset-*) em elementos de borda
Grids usam auto-fit/minmax ou colapsam por breakpoint
Imagens com max-width: 100% e aspect-ratio definido
Tabelas viram cards ou tem wrapper com scroll proprio

Interacao:

Hit area minima de 44x44px em todo alvo de toque
Inputs com font-size >= 16px, inputmode e autocomplete corretos
Modal com focus trap, retorno de foco, Escape e scroll lock
Conteudo longo em mobile usa bottom sheet ou rota propria, nao modal com scroll
Toda acao com API tem os 4 estados (idle, loading, sucesso, erro)
Submit duplo impossivel (botao desabilita no loading)

Confirmacao:

Acao reversivel usa Desfazer, nao modal
Modal destrutivo nomeia alvo e consequencia concreta
Botao de acao usa o verbo, nao "OK"
Foco inicia no botao seguro; backdrop nao fecha
Acao catastrofica exige digitacao do nome do recurso
Formulario longo avisa antes de descartar dado nao salvo

Evidencia de Conclusao

relatorio sintoma → causa → fix para cada ocorrencia corrigida
checklist de conversao marcado, com item nao aplicavel justificado
verificacao nas 3 larguras mobile e na largura desktop original (sem regressao)
quando houver Playwright no projeto, teste de viewport cobrindo os bugs corrigidos

Handoff

Recebe de

02-ui-ux-design — ancora estetica, tokens e breakpoints ja definidos
04-frontend-integration — componentes implementados a auditar

Entrega para

52-ui-polish — layout correto e pre-requisito do polish; despachar depois, nunca antes
22-accessibility-specialist — quando a auditoria revelar problema de acessibilidade alem do subconjunto mobile
05-qa-testing — para transformar os bugs corrigidos em teste de viewport (regressao)
11-reviewer — relatorio e checklist para validacao final

Regra de Codigo Limpo

Comentario so quando o valor nao e obvio — min-w-0 e 100dvh merecem uma linha explicando o porque, ja que parecem arbitrarios para quem nunca caiu no bug. Classe utilitaria autoexplicativa nao precisa de comentario.

Integracao com Pipeline

Orquestrador (skill 09): aciona esta skill quando a task menciona mobile, responsivo ou bug de layout; tipicamente depois de 04-frontend-integration
UI/UX Design (skill 02): dona da direcao estetica — esta skill herda a ancora, nunca a redefine
UI Polish (skill 52): entra depois desta; acabamento sobre layout quebrado e desperdicio
Accessibility (skill 22): dona do WCAG completo; esta skill cobre so o recorte que colide com mobile
QA (skill 05): converte os fixes em teste automatizado de viewport
Context Manager (skill 08): rastreia progresso da auditoria por tela/componente