Android edge-to-edge: revise insets, teclado e barras no Jetpack Compose

ANÁLISE EDITORIAL

Uma tela pode ocupar toda a área do celular e, ainda assim, deixar o botão principal escondido atrás da barra de navegação. A Skill oficial edge-to-edge, publicada no repositório android/skills, orienta um agente a revisar esse tipo de problema em aplicativos Android feitos com Jetpack Compose. Ela trata a ativação do desenho até as bordas, o espaço seguro para conteúdo interativo, o teclado e a legibilidade das barras do sistema. O trabalho útil aqui não é aplicar um modificador em toda a árvore visual, mas identificar quem já consome cada inset para não criar margens duplicadas.

O que esta Skill faz de verdade

O SKILL.md fixado nesta curadoria propõe uma sequência de inspeção. Primeiro, localizar as Activities e verificar se cada uma já chama enableEdgeToEdge(). Depois, procurar listas, botões flutuantes e campos de texto que possam ser encobertos pelas barras do sistema ou pelo teclado. Por fim, escolher um único método apropriado de aplicação de insets em cada região da tela, construir o aplicativo e conferir a interface em configurações distintas.

Isso não instala uma biblioteca nova no projeto nem altera a versão do Android por conta própria. A Skill é um documento para orientar um agente com acesso ao código. O resultado depende das APIs realmente presentes, da arquitetura da interface e de revisão humana. Na consulta de 14 de outubro de 2026, a API do GitHub indicava 7.803 estrelas para o repositório completo, não para esta Skill isolada. A quantidade pode mudar e não equivale a um teste de segurança.

Para quem serve

A proposta é útil para equipes que mantêm um aplicativo Jetpack Compose e veem uma lista terminar sob a barra de navegação, um botão flutuante ficar difícil de tocar ou um campo desaparecer quando o teclado abre. Também ajuda numa migração planejada para as regras de exibição do Android 15, desde que a equipe possa comparar a tela antes e depois. Um agente pode levantar pontos de atenção e sugerir alterações; não substitui o responsável pelo desenho da experiência, pelos testes de acessibilidade e pela aprovação da mudança.

Não é uma Skill genérica para interfaces web, Flutter ou telas Android inteiramente baseadas em Views. O arquivo original estabelece Compose e targetSdk 35 ou superior como pré-requisitos. Se o projeto ainda usa outro alvo, a mudança de SDK deve ser avaliada como trabalho próprio, com testes de compatibilidade, e não executada silenciosamente para satisfazer a Skill.

Compatibilidade e pré-requisitos

Confira no projeto a versão do targetSdk, as versões de Compose e AndroidX Activity, as Activities afetadas e o uso de Material 2, Material 3 ou componentes personalizados. A documentação oficial explica a exibição edge-to-edge no Compose e observa que aplicativos direcionados ao Android 15, API 35, recebem esse comportamento por padrão nesse sistema. Ainda pode ser necessário ajustar o conteúdo e garantir comportamento consistente nas versões anteriores. A chamada enableEdgeToEdge() pertence à API AndroidX Activity; confirme a dependência e o código já existente antes de sugerir nova chamada.

É necessário um agente que consiga ler o repositório e propor edições em Kotlin e no manifesto. Para verificar o resultado, a equipe precisa de uma compilação funcional e de emulador ou dispositivo com modos de navegação e tamanhos de tela relevantes. Como a Skill foi consultada no commit 5bda39f154fb859a08d45e2392f3568e049f83fb, compare-a com a documentação e dependências do projeto antes de aplicar trechos literalmente. Não fizemos uma execução independente em um aplicativo.

Instalação recomendada

Baixe o ZIP documental auditado do Bastidores. Antes de extrair, compare o SHA-256 publicado nesta página. Dentro dele há somente SKILL.md, LICENSE e ORIGEM.md. Leia primeiro a origem e a licença, depois examine as instruções da Skill. Coloque SKILL.md na pasta edge-to-edge do diretório de Skills aceito pelo seu agente e reinicie a sessão se a ferramenta só descobrir Skills na inicialização.

O catálogo oficial de Skills Android também documenta a instalação pelo comando android skills add edge-to-edge. Essa rota consulta o fornecedor e pode obter uma revisão diferente do commit fixado aqui. Use o ZIP quando precisar reproduzir a cópia auditada; use o comando oficial quando a política do projeto permitir acompanhar a versão atual do mantenedor. Não execute os dois caminhos na mesma pasta sem conferir qual arquivo ficará ativo.

Configuração antes do primeiro uso

Crie um branch de trabalho e registre as telas que serão revisadas, com capturas reais do seu aplicativo feitas pela sua equipe, se for permitido. Não inclua dados de clientes, tokens ou credenciais no pedido ao agente. Informe a ele se há Scaffold, barras Material, diálogos em tela cheia e campos que acionam o teclado. Peça primeiro um inventário de Activities e composables afetados e um plano por tela, sem autorizar alterações de imediato. O primeiro passo da Skill prevê essa inspeção.

Combine um limite explícito para o escopo: por exemplo, corrigir uma Activity e uma lista de teste, sem mudar targetSdk, tema ou navegação global. O uso de WindowInsets pode ser distribuído entre componentes pais e filhos. Peça ao agente que indique onde os insets são consumidos hoje e por que um novo padding não duplicará o existente. Se uma API citada na Skill não existir na versão do projeto, confirme a alternativa na documentação de insets do Compose, em vez de alterar dependências às cegas.

Primeiro uso seguro e resultado esperado

Comece por uma tela que tenha lista e ação na parte inferior. Peça ao agente para localizar a Activity, registrar se enableEdgeToEdge() já é chamado antes de setContent e mostrar como a tela trata os innerPadding de um Scaffold. Se a lista precisa chegar visualmente até a borda, a Skill mostra como passar o padding ao conteúdo da lista e consumi-lo uma única vez. Revise o diff antes de aceitar. Para campos de entrada, confira adjustResize no manifesto e observe a abertura do teclado em um dispositivo ou emulador, sem inferir sucesso apenas de uma compilação.

O resultado esperado é uma tela cujo conteúdo decorativo pode alcançar as bordas, mas botões, texto e itens importantes continuam visíveis e tocáveis acima das áreas do sistema. Teste navegação por gestos e por três botões, tema claro e escuro, rotação quando aplicável e abertura do teclado. A orientação Android distingue o desenho sob as barras da proteção dos controles interativos. Salve evidências de antes e depois no seu ambiente; a ilustração acima não é essa evidência.

Permissões e riscos

O ZIP não executa código e não pede conta Android. O risco começa ao conceder ao agente acesso de escrita ao repositório, execução de build ou permissão para instalar dependências. Uma alteração ampla de insets pode deslocar cabeçalhos, cortar conteúdo em telas menores ou criar padding em dobro. Exija revisão do diff e teste por tela antes de mesclar. Não autorize a ele elevar targetSdk nem alterar todos os manifestos só porque a Skill usa a palavra “MUST”. A decisão de compatibilidade pertence à equipe do aplicativo.

A legibilidade das barras também requer cuidado. Ícones claros sobre uma imagem clara podem desaparecer, e uma proteção visual excessiva pode esconder o desenho edge-to-edge. A Skill trata contraste e barras do sistema, mas a revisão deve considerar o tema, o fundo que aparece sob cada barra e os critérios de acessibilidade do produto. Diálogos em tela cheia e superfícies personalizadas precisam de teste específico. Faça backup ou use controle de versão antes de aceitar qualquer modificação do agente.

Erros comuns e como investigar

Se o conteúdo ganhou uma margem exagerada, procure dois lugares aplicando o mesmo inset: por exemplo, Scaffold no pai e safeDrawingPadding() no filho. Inspecione também componentes Material 3, que podem administrar sua própria área segura. Se a barra de navegação cobre o último item de uma lista, verifique o contentPadding da lista, não apenas o padding do contêiner externo. A Skill distingue esses casos e traz exemplos de listas e botões flutuantes.

Se o teclado encobre um campo, confirme o modo de redimensionamento da Activity e a combinação de imePadding, insets já consumidos e foco. Uma correção feita para gestos pode não funcionar com navegação por três botões; teste ambos os modos. Se um ícone de status ou navegação ficar ilegível, confira cores e contraste no fundo real da tela. Para problemas de compilação, compare os nomes das APIs com as versões AndroidX do projeto e leia o erro exato antes de trocar de biblioteca. Não trate uma captura de tela como prova de que todos os estados interativos foram cobertos.

Versão, licença e download local

A cópia oferecida fixa o commit 5bda39f154fb859a08d45e2392f3568e049f83fb, cuja pasta system/edge-to-edge contém o texto da Skill. O LICENSE.txt do repositório traz a licença Apache 2.0, que permite redistribuição com os avisos exigidos. Mantivemos o texto original e a licença no pacote; ORIGEM.md registra URLs, commit e hashes dos arquivos. Não há SDK, executáveis, scripts, dependências, credenciais ou aplicação de exemplo.

O download local é separado do botão que abre o repositório oficial. SHA-256 do ZIP: 5ebbbc8a05c271c346fbffc9506eea4ac0b5b307f77c11f5c3fa6b26e1cd9e5b. Depois de baixar, calcule o hash do arquivo obtido e compare-o com esse valor. A versão do repositório pode evoluir; esta página descreve apenas o commit identificado acima e não promete compatibilidade automática com revisões posteriores.

Fontes primárias

A curadoria conferiu o SKILL.md no commit fixado, o texto da licença, a página oficial da Skill, o guia edge-to-edge para Compose e a referência de insets. Use essas fontes para conferir detalhes antes de mudar código de produção.