Mudança de layout cumulativa (CLS)

TL;DR — Cumulative Layout Shift (CLS) mede quanto conteúdo numa página se move sozinho enquanto você tenta ler ou tocar nele — a imagem que carrega tarde e empurra o texto para baixo, o botão que salta justo quando você vai clicar nele. A pontuação começa em 0, e 0,1 ou menos é bom. A maior parte vem de elementos que não reservaram espaço antes de carregar.

O que é CLS

Você já sentiu isso mesmo que nunca tenha ouvido o termo. Você está lendo um artigo, um anúncio ou uma imagem termina de carregar acima de onde está olhando, e de repente a página inteira pula para baixo. Ou você vai tocar em “Cancelar” e um banner aparece, fazendo seu toque acertar “Confirmar”. Esse movimento inesperado é uma mudança de layout, e Cumulative Layout Shift é a forma que o Google usa para dar um número ao quanto isso é ruim.

É uma das três Core Web Vitals — o trio de métricas de experiência na página que o Google acompanha, junto com Largest Contentful Paint (a velocidade com que o conteúdo principal carrega) e Interaction to Next Paint (a rapidez com que a página responde quando você toca). CLS é a métrica de estabilidade visual: a página fica parada?

Como a pontuação funciona (aproximadamente)

CLS é uma pontuação, não um tempo. Um CLS de 0,05 não significa 50 milissegundos de nada — é um número sem unidade. Quanto maior for a parte da tela que se move e quanto mais longe ela se mover, maior (e pior) será a pontuação.

As metas são simples:

• 0,1 ou menos — bom.
• 0,1 a 0,25 — precisa melhorar.
• Acima de 0,25 — ruim.

Um detalhe importante: mudanças que acontecem logo depois que você faz algo — toca num botão, abre um menu — não contam contra a página, porque foi você quem as causou e você as espera. Só o movimento inesperado conta.

Por que acontece (e como corrigir)

Quase toda mudança de layout se resume à mesma coisa: algo carregou e ocupou um espaço que a página não havia reservado. Os principais casos são:

• Imagens e vídeos sem dimensões. O navegador não sabe a altura da imagem até ela chegar, então o texto abaixo é empurrado para baixo quando isso acontece. A correção: sempre dê às imagens atributos de width e height (ou um aspect-ratio de CSS) para que o navegador mantenha o espaço.
• Anúncios, embeds e iframes. O mesmo problema — reserve espaço para eles.
• Fontes da web. Quando uma fonte personalizada substitui a fonte de fallback, o texto pode ser refluído.
• Elementos que aparecem depois. Banners de cookies, caixas de “você também pode gostar”, qualquer coisa inserida acima do conteúdo que você já está vendo.

A regra mental é: se algo vai aparecer depois, deixe um espaço do tamanho certo para isso para que nada mais precise se mover quando aparecer.

Quer ver a fórmula de verdade, a regra da “janela de sessão”, por que as pontuações de CLS de laboratório e de campo divergem e a lista completa de causas e correções? Mude para a aba Avançado.

TL;DR — CLS é a Core Web Vital de estabilidade visual. Cada mudança recebe uma pontuação como impact fraction × distance fraction; a própria métrica é a maior janela de sessão de mudanças (≤ 1 s entre mudanças, janela de ≤ 5 s) — não a soma da vida útil, que era usada antes de junho de 2021. Bom é ≤ 0,1, precisa melhorar ≤ 0,25, ruim > 0,25, no percentil 75 dos dados de campo. Só mudanças visíveis na viewport contam; mudanças até 500 ms depois de uma entrada discreta são excluídas (rolagem não é). As causas são imagens/vídeos/anúncios/ iframes/embeds sem dimensões, fontes da web e conteúdo inserido acima do conteúdo existente; as correções são reservar espaço, font-display/size-adjust e animação apenas com transform. A armadilha a evitar: o Lighthouse (laboratório) costuma registrar quase 0 porque não interage com a página nem executa todo o ciclo de vida — dados de campo (CrUX) são o que o Google mede.

O que o CLS mede

O enquadramento do Google: “Cumulative Layout Shift (CLS) is a stable Core Web Vital metric. It’s an important, user-centric metric for measuring visual stability because it helps quantify how often users experience unexpected layout shifts.” (Tradução: “Cumulative Layout Shift (CLS) é uma métrica Core Web Vital estável. É uma métrica importante e centrada no usuário para medir a estabilidade visual porque ajuda a quantificar com que frequência as pessoas vivenciam mudanças de layout inesperadas.”) A palavra fundamental é inesperado — conteúdo que se move sozinho, não porque o usuário fez algo.

Ele faz parte do trio de Core Web Vitals com Largest Contentful Paint (carregamento) e Interaction to Next Paint (capacidade de resposta). Enquanto LCP e INP são medidos em milissegundos, CLS é a exceção: uma pontuação de proporção sem unidade. Isso confunde muita gente. Um CLS de 0,05 não é 50 ms. Ele não tem unidade de tempo alguma.

A fórmula: impacto × distância

Para cada mudança, o Google define assim:

layout shift score = impact fraction × distance fraction

• Fração de impacto “measures how unstable elements impact the viewport area between two frames” — a área visível combinada que os elementos em movimento ocuparam (antes e depois), como proporção da viewport. (Tradução: “mede como elementos instáveis afetam a área da viewport entre dois quadros.”)
• Fração de distância é “the greatest horizontal or vertical distance any unstable element has moved in the frame divided by the viewport’s largest dimension (width or height, whichever is greater).” (Tradução: “a maior distância horizontal ou vertical que qualquer elemento instável percorreu no quadro, dividida pela maior dimensão da viewport (largura ou altura, a que for maior).”)

As duas dimensões importam de forma independente. Um elemento pequeno que atravessa a maior parte da tela e um elemento grande que quase não se desloca podem receber pontuações muito diferentes. No exemplo trabalhado do web.dev, uma fração de impacto de 0.75 e uma fração de distância de 0.25 produzem uma pontuação de mudança de layout de 0.1875.

Janelas de sessão: a parte que todo mundo entende errado

Este é o fato mais distorcido sobre CLS — e aquele que eu mais quero que você guarde. CLS não é a soma de todas as mudanças ao longo da vida da página. Já foi assim — isso mudou em junho de 2021.

Hoje: “CLS measures the largest burst of layout shift scores for every unexpected layout shift that occurs during the entire lifecycle of a page.” (Tradução: “CLS mede o maior surto de pontuações de mudanças de layout para cada mudança inesperada que ocorre durante todo o ciclo de vida de uma página.”) Um surto é uma janela de sessão: “one or more individual layout shifts occur in rapid succession with less than 1-second in between each shift and a maximum of 5 seconds for the total window duration.” (Tradução: “uma ou mais mudanças de layout individuais ocorrem em rápida sucessão, com menos de 1 segundo entre cada mudança e duração total máxima da janela de 5 segundos.”) CLS é a pontuação da maior janela desse tipo — não a soma, nem a média.

Por que a mudança? A definição antiga, que somava tudo, punia discretamente páginas de longa duração. Um aplicativo de página única ou um feed de rolagem infinita acumulava mais CLS simplesmente por existir por mais tempo, mesmo que cada mudança individual fosse pequena e bem espaçada. A equipe Chrome Speed Metrics passou a usar uma janela de sessão máxima para não penalizar a duração e escolheu o máximo em vez da média para evitar um resultado perverso em que corrigir uma mudança pequena e secundária pudesse piorar sua pontuação. Quando a mudança foi lançada, nenhum domínio recebeu uma pontuação pior, a maioria não mudou e uma parcela de páginas com interface lenta e rolagem infinita melhorou. Se você ler um texto antigo que ainda diz “soma de todas as mudanças”, ele está desatualizado.

O que conta — e o que não conta

Três exclusões determinam o que realmente entra na sua pontuação:

• O que está abaixo da dobra não conta. Só mudanças de conteúdo visíveis na viewport atual são pontuadas. Uma mudança no fim de uma página longa que o usuário nunca rola até alcançar não tem impacto. Na prática, isso significa que corrigir mudanças na viewport quase sempre traz um ROI maior do que perseguir mudanças muito abaixo na página.
• Mudanças iniciadas pelo usuário ganham uma janela de 500 ms. “Layout shifts that occur within 500 milliseconds of user input will have the hadRecentInput flag set, so they can be excluded from calculations.” (Tradução: “mudanças de layout que ocorrem até 500 milissegundos depois da entrada do usuário terão a flag hadRecentInput definida e poderão ser excluídas dos cálculos.”) A posição do Google: mudanças “that occur in response to user interactions… are generally fine, as long as the shift occurs close enough to the interaction that the relationship is clear to the user.” (Tradução: “que ocorrem em resposta a interações do usuário… geralmente não são um problema, desde que a mudança ocorra perto o bastante da interação para que a relação fique clara para o usuário.”) Abrir um acordeão ou expandir um menu é um movimento esperado, então é perdoado.
• Mas rolagem não é passe livre. A exclusão de 500 ms só se aplica a eventos discretos — toque, clique, tecla. Gestos contínuos (rolagem, pinça de zoom) não acionam a janela de exclusão. Se o conteúdo mudar enquanto alguém rola, isso ainda conta. Essa distinção está errada em muita cobertura; acerte-a.

Limiares e de onde vem a pontuação

“To provide a good user experience, sites should strive to have a CLS score of 0.1 or less,” (Tradução: “para oferecer uma boa experiência de usuário, os sites devem buscar uma pontuação CLS de 0,1 ou menos,”) medida no “the 75th percentile of page loads, segmented across mobile and desktop devices.” (Tradução: “o percentil 75 dos carregamentos de página, segmentado entre dispositivos móveis e desktop”.) As faixas completas são:

• Bom: ≤ 0,1
• Precisa melhorar: 0,1 – 0,25
• Ruim: > 0,25

A linha de 0,1 não é arbitrária. A pesquisa de usuários do Google descobriu que “levels of shift from 0.15 and higher were consistently perceived as disruptive, while shifts of 0.1 and lower were noticeable but not excessively disruptive.” (Tradução: “níveis de mudança de 0,15 ou mais eram percebidos consistentemente como perturbadores, enquanto mudanças de 0,1 ou menos eram perceptíveis, mas não excessivamente perturbadoras.”) Eles chegaram a 0,1 em vez de um limite mais rígido em parte porque embeds de terceiros (anúncios, redes sociais) causam mudanças com tanta frequência que um padrão mais apertado seria impraticável na web real.

A parte do “percentil 75 dos dados de campo” é essencial, e nos leva à maior armadilha de medição.

Laboratório vs. campo: por que os números divergem

É aqui que a maioria das pessoas se dá mal. O Lighthouse e outras ferramentas de laboratório frequentemente registram um CLS próximo de 0,0 enquanto os dados de campo — e o Google — mostram algo muito pior. A diferença não significa que alguma das ferramentas esteja sendo desonesta; é uma questão de escopo. Uma execução de laboratório é um carregamento de página único, curto e roteirizado: ela não rola, não clica e não permanece ativa, então captura apenas as mudanças do carregamento inicial. Os dados de campo (CrUX) agregam visitas reais de muitos usuários, dispositivos e navegações ao longo de uma janela móvel, e CLS é definido durante o ciclo de vida inteiro da página — menus abrindo, conteúdo lazy carregando enquanto o usuário rola, anúncios tardios preenchendo o espaço, por quanto tempo a sessão durar. Uma execução curta de laboratório estruturalmente não consegue ver a maior parte disso.

Portanto, a regra prática é: use dados de laboratório para depurar uma mudança específica e dados de campo para conhecer sua pontuação real. O Google classifica usando dados de campo do Chrome User Experience Report (CrUX), exibidos no PageSpeed Insights e no Search Console. Se o Lighthouse registrar 0,0, mas o PageSpeed Insights mostrar 0,18, trate o número de campo como o que representa seus usuários reais — depois reproduza a mudança no laboratório interagindo com a página como um visitante real faria. Há mais duas diferenças de escopo importantes: a maioria das ferramentas, incluindo o Lighthouse, não propaga mudanças de layout de iframe para a pontuação do documento pai, embora o CrUX possa refleti-las, e o RUM baseado na API Layout Instability herda esse mesmo ponto cego de iframes — então seu monitoramento de usuários reais pode explicar menos um número do CrUX que parece pior do que mostra sua atribuição própria.

As causas comuns

Em ordem aproximada de frequência com que as vejo:

1. Imagens e vídeos sem dimensões. Sem altura reservada, tudo abaixo salta quando a mídia carrega.
2. Anúncios, embeds e iframes sem espaço reservado. Redes de anúncios fornecem tamanhos dinâmicos; embeds não informam sua altura antes de carregar.
3. Conteúdo injetado dinamicamente acima do conteúdo existente. Banners de cookies, barras de notificação, widgets “relacionados”, promoções que carregam tarde — qualquer coisa que empurre para baixo o que já está na tela.
4. Fontes da web (FOIT/FOUT). Quando a fonte personalizada substitui o fallback, o texto é refluído se suas métricas forem diferentes.
5. Animações em propriedades que acionam layout. Animar top, left, margin, box-shadow ou box-sizing força o navegador a refazer o layout da página a cada quadro.

As correções

Cada correção reflete sua causa:

• Imagens/vídeos — reserve o espaço. Defina os atributos width e height para que o navegador calcule a proporção e mantenha a caixa; combine com img { height: auto; width: 100%; } para comportamento responsivo, ou use a propriedade CSS aspect-ratio. Essa é a correção de CLS com maior alavancagem na maioria dos sites.
• Anúncios/embeds/iframes — reserve espaço também. Use min-height ou aspect-ratio no contêiner; para espaços de anúncio, a orientação do Google Publisher Tag é direta: “Setting a fixed height and width directly on the ad slot div is the most effective way to do this.” (Tradução: “definir diretamente uma altura e uma largura fixas no div do espaço de anúncio é a forma mais eficaz de fazer isso.”) Para espaços de vários tamanhos, reserve o maior tamanho configurado. Empurre o conteúdo que carrega tarde para baixo, para que qualquer mudança residual fique abaixo da dobra.
• Conteúdo dinâmico — não o insira no fluxo. Reserve um placeholder com o tamanho final ou sobreponha o conteúdo em vez de injetá-lo. Skeletons só ajudam se corresponderem exatamente às dimensões finais — um skeleton alguns pixels mais curto que o conteúdo real ainda causa uma mudança. Prefira carregamentos iniciados pelo usuário (“Carregar mais”) a inserções surpresa.
• Fontes — corresponda às métricas. font-display: optional é o único valor com risco de CLS efetivamente zero; swap minimiza o texto invisível, mas pode causar deslocamento na troca. Melhor ainda, use as substituições de métricas CSS — size-adjust, ascent-override, descent-override, line-gap-override — para dimensionar a fonte fallback de modo que ela corresponda à fonte da web e a troca seja imperceptível. Faça preload das fontes críticas.
• Animações — apenas transform. Anime com transform (translate, scale, rotate) em vez de top/left/margin. Animações baseadas em transform são compostas e não acionam layout, então não deslocam nada.

Como o CLS se encaixa nas classificações (mantenha a proporção)

CLS é uma entrada do sinal de experiência na página do Google. O Google diz que as Core Web Vitals são usadas por seus sistemas de classificação — mas a documentação atual da Pesquisa não publica um peso exato para CLS, uma regra de desempate ou uma garantia de classificação. Portanto, trate qualquer mecanismo específico (incluindo “é um desempate”) como uma aproximação operacional, não como um fato documentado. Meu conselho constante em tudo que escrevo sobre Core Web Vitals: entre na faixa “bom” e siga em frente. A maioria dos sites não verá um ganho significativo de classificação ou de negócio ao reduzir 0,08 para 0,02, e uma única pontuação raramente explica sozinha um resultado de receita ou conversão. CLS é requisito básico — você quer passar da barra, mas ele não deve virar o centro do seu programa de SEO em detrimento de LCP, INP ou, francamente, do seu conteúdo.

Duas observações operacionais que eliminam muita confusão:

• O CrUX atrasa cerca de 28 dias. É uma janela móvel de 28 dias, então uma correção que você publica hoje não aparecerá completamente no PageSpeed Insights ou no Search Console por semanas. Não entre em pânico se o número não mudar na manhã seguinte.
• O elemento atribuído frequentemente não é a causa raiz. A API Layout Shift Attribution informa qual elemento se moveu, mas, como observa o web.dev, “it’s possible that these elements are only indirectly related to the ‘root cause’ of layout instability.” (Tradução: “é possível que esses elementos estejam apenas indiretamente relacionados à ‘causa raiz’ da instabilidade de layout.”) O texto que saltou geralmente é vítima de uma imagem sem dimensões acima que carregou tarde — corrija a causa, não o sintoma. Trabalhe com um ciclo de tempo até o gatilho: anote o horário inicial da mudança e verifique o que mais mudou nessa mesma janela — uma requisição de rede terminando, uma imagem ou fonte chegando, um redimensionamento ou uma alteração de classe/estilo — e trate o nó atribuído como uma pista, não como prova, até associá-lo a esse gatilho.

Resumo de IA

Uma versão condensada da versão Avançada:

• CLS = estabilidade visual, a Core Web Vital para o movimento inesperado de conteúdo visível. Ele fica ao lado de Largest Contentful Paint e Interaction to Next Paint.
• É uma pontuação sem unidade, não um tempo. 0,05 é uma proporção, não 50 ms.
• Fórmula por mudança: impact fraction × distance fraction — quanto da viewport se moveu, multiplicado pela distância relativa à maior dimensão da viewport.
• A métrica é a maior janela de sessão (≤ 1 s entre mudanças, janela total de ≤ 5 s) — não a soma da vida útil. Isso mudou em junho de 2021 para parar de penalizar páginas duradouras/SPAs; escolheu-se o máximo em vez da média.
• Limiares (percentil 75, dados de campo): Bom ≤ 0,1 · Precisa melhorar ≤ 0,25 · Ruim > 0,25.
• Exclusões: mudanças abaixo da dobra não contam; mudanças até 500 ms de uma entrada discreta (toque/clique/tecla) são excluídas — rolagem não é isenta.
• Causas: imagens/vídeos/anúncios/iframes/embeds sem dimensões; conteúdo injetado acima do conteúdo existente; fontes da web; animação de propriedades que acionam layout.
• Correções: defina width/height ou aspect-ratio; reserve espaço para conteúdo dinâmico (skeletons precisam ter as dimensões exatas); use font-display + size-adjust; anime somente com transform.
• Laboratório ≠ campo. O Lighthouse costuma registrar quase 0 porque não interage com a página nem executa todo o ciclo de vida; dados de campo (CrUX/PageSpeed Insights) são o que o Google usa nas classificações. Mudanças em iframes geralmente não chegam à pontuação do pai nem nas ferramentas de laboratório nem nas de RUM.
• Classificação: uma entrada que o Google diz que seus sistemas usam na experiência na página — não há peso nem regra de desempate documentados, então chegue a “bom” e siga em frente em vez de perseguir um mecanismo específico. O CrUX atrasa cerca de 28 dias; o elemento atribuído frequentemente não é a causa raiz.

Documentação oficial

Documentação de fonte primária do Google e da equipe do Chrome.

Documentação central sobre CLS

• Cumulative Layout Shift (CLS) — a definição canônica, a fórmula impacto × distância, janelas de sessão, limiares e a exclusão hadRecentInput (Milica Mihajlija e Philip Walton).
• Optimize Cumulative Layout Shift — o guia oficial de causas e correções: imagens, anúncios/embeds, conteúdo injetado, fontes e animações.
• Debug layout shifts — como encontrar mudanças no Chrome DevTools, usar a sobreposição Layout Shift Regions e a API LayoutShiftAttribution (Katie Hempenius e Barry Pollard).

Contexto e medição

• Evolving Cumulative Layout Shift in web tooling — por que a métrica passou da soma de todas as mudanças para a maior janela de sessão em junho de 2021 (Annie Sullivan e Hongbo Song, da equipe Chrome Speed Metrics).
• How the Core Web Vitals metrics thresholds were defined — a pesquisa de usuários e os dados de viabilidade por trás das faixas 0,1 / 0,25.
• Getting started with measuring Web Vitals — dados de laboratório vs. campo e por que o CLS de laboratório pode ficar artificialmente baixo.
• Font best practices — font-display, substituições de métricas e preload para CLS causado por fontes.

Anúncios e Pesquisa

• Minimize layout shift — orientação do Google Publisher Tag para reservar espaço de anúncios.
• Understanding Core Web Vitals and Google Search results — como as CWV (incluindo CLS) entram na Pesquisa.

Citações da fonte

Declarações registradas do Google e da equipe do Chrome. Cada link profundo salta para o trecho citado na página de origem.

Google — o que é CLS

• “Cumulative Layout Shift (CLS) is a stable Core Web Vital metric. It’s an important, user-centric metric for measuring visual stability because it helps quantify how often users experience unexpected layout shifts.” (Tradução: “Cumulative Layout Shift (CLS) é uma métrica Core Web Vital estável. É uma métrica importante e centrada no usuário para medir a estabilidade visual porque ajuda a quantificar com que frequência as pessoas vivenciam mudanças de layout inesperadas.”) Ir para a citação
• “CLS measures the largest burst of layout shift scores for every unexpected layout shift that occurs during the entire lifecycle of a page.” (Tradução: “CLS mede o maior surto de pontuações de mudanças de layout para cada mudança inesperada que ocorre durante todo o ciclo de vida de uma página.”) Ir para a citação

Google — a fórmula

• “layout shift score = impact fraction * distance fraction” (Tradução: “pontuação da mudança de layout = fração de impacto * fração de distância”) Ir para a citação
• “The impact fraction measures how unstable elements impact the viewport area between two frames.” (Tradução: “a fração de impacto mede como elementos instáveis afetam a área da viewport entre dois quadros.”) Ir para a citação
• “The distance fraction is the greatest horizontal or vertical distance any unstable element has moved in the frame divided by the viewport’s largest dimension (width or height, whichever is greater).” (Tradução: “a fração de distância é a maior distância horizontal ou vertical que qualquer elemento instável percorreu no quadro, dividida pela maior dimensão da viewport (largura ou altura, a que for maior).”) Ir para a citação

Google — janela de sessão

• “A burst of layout shifts, known as a session window, is when one or more individual layout shifts occur in rapid succession with less than 1-second in between each shift and a maximum of 5 seconds for the total window duration.” (Tradução: “um surto de mudanças de layout, conhecido como janela de sessão, ocorre quando uma ou mais mudanças de layout individuais acontecem em rápida sucessão, com menos de 1 segundo entre cada mudança e duração total máxima da janela de 5 segundos.”) Ir para a citação

Google — limiares e entrada do usuário

• “To provide a good user experience, sites should strive to have a CLS score of 0.1 or less… a good threshold to measure is the 75th percentile of page loads, segmented across mobile and desktop devices.” (Tradução: “para oferecer uma boa experiência de usuário, os sites devem buscar uma pontuação CLS de 0,1 ou menos… um bom limiar de medição é o percentil 75 dos carregamentos de página, segmentado entre dispositivos móveis e desktop.”) Ir para a citação
• “Layout shifts that occur within 500 milliseconds of user input will have the hadRecentInput flag set, so they can be excluded from calculations.” (Tradução: “mudanças de layout que ocorrem até 500 milissegundos depois da entrada do usuário terão a flag hadRecentInput definida e poderão ser excluídas dos cálculos.”) Ir para a citação
• “Layout shifts that occur in response to user interactions (such as clicking or tapping a link, pressing a button, or typing in a search box) are generally fine, as long as the shift occurs close enough to the interaction that the relationship is clear to the user.” (Tradução: “mudanças de layout que ocorrem em resposta a interações do usuário (como clicar ou tocar em um link, pressionar um botão ou digitar numa caixa de pesquisa) geralmente não são um problema, desde que a mudança ocorra perto o bastante da interação para que a relação fique clara para o usuário.”) Ir para a citação

Google — como os limiares foram escolhidos

• “levels of shift from 0.15 and higher were consistently perceived as disruptive, while shifts of 0.1 and lower were noticeable but not excessively disruptive.” (Tradução: “níveis de mudança de 0,15 ou mais eram percebidos consistentemente como perturbadores, enquanto mudanças de 0,1 ou menos eram perceptíveis, mas não excessivamente perturbadoras.”) Ir para a citação

Google — reservando espaço para anúncios

• “Setting a fixed height and width directly on the ad slot div is the most effective way to do this.” (Tradução: “definir diretamente uma altura e uma largura fixas no div do espaço de anúncio é a forma mais eficaz de fazer isso.”) Ir para a citação

Google — elemento atribuído vs. causa raiz

• “elements listed as sources are the elements that shifted during the layout shift. However, it’s possible that these elements are only indirectly related to the ‘root cause’ of layout instability.” (Tradução: “os elementos listados como fontes são os elementos que se deslocaram durante a mudança de layout. No entanto, é possível que esses elementos estejam apenas indiretamente relacionados à ‘causa raiz’ da instabilidade de layout.”) Ir para a citação

Checklist de causas → correções do CLS

Trabalhe de cima para baixo; os dois primeiros itens corrigem a maioria dos casos de CLS no mundo real.

• Toda <img> e <video> tem width + height (ou um aspect-ratio de CSS), com img { height: auto; width: 100%; } para layouts responsivos.
• Espaços de anúncios, iframes e embeds reservam espaço via min-height / aspect-ratio; espaços de anúncios de vários tamanhos reservam o maior tamanho configurado.
• Conteúdo que carrega tarde fica abaixo da dobra sempre que possível, para que qualquer mudança residual não conte.
• Conteúdo injetado (banners de cookies, promoções, widgets “relacionados”) é sobreposto ou pré-reservado — não inserido acima do conteúdo existente.
• Placeholders skeleton correspondem às dimensões exatas do conteúdo final (uma diferença de alguns pixels ainda causa mudança).
• Fontes da web usam font-display: optional quando aceitável, ou swap com size-adjust / ascent-override para corresponder às métricas do fallback; fontes críticas recebem preload.
• Animações usam apenas transform — nunca top, left, margin, box-shadow ou box-sizing.
• Você verificou a pontuação nos dados de campo (PageSpeed Insights / Search Console / CrUX), não apenas no Lighthouse.
• Você reproduziu as mudanças interagindo com a página — rolando, abrindo menus, acionando carregamentos lazy — não apenas no carregamento inicial.
• Mudanças de anúncios/iframes foram verificadas no campo (ferramentas de laboratório frequentemente não as propagam para a pontuação do pai).

Folha de consulta do CLS

Os números

A definição em uma linha

• layout shift score = impact fraction × distance fraction (por mudança).
• CLS = a maior janela de sessão de mudanças — ≤ 1 s entre mudanças, janela total de ≤ 5 s. Não é a soma da vida útil (era assim antes de junho de 2021).
• É uma pontuação sem unidade, não um tempo.

O que é excluído

• Mudanças abaixo da dobra (fora da viewport atual).
• Mudanças até 500 ms de uma entrada discreta (toque/clique/tecla) — hadRecentInput.
• Não são excluídas: mudanças durante rolagem ou pinça (gestos contínuos).

Causas → correções

Armadilhas de medição

• O Lighthouse (laboratório) frequentemente registra ~0 — ele não interage com a página nem executa todo o ciclo de vida. CrUX / PageSpeed Insights (campo) é o que o Google usa nas classificações.
• O CrUX atrasa cerca de 28 dias — as correções levam semanas para aparecer.
• Mudanças em iframes geralmente não chegam à pontuação do documento pai nas ferramentas de laboratório.
• O elemento atribuído é o que se moveu, não necessariamente a causa raiz.

Ferramentas para medir e depurar CLS

Dados de campo (o que o Google usa nas classificações)

• PageSpeed Insights — CLS de campo do CrUX no nível da página e da origem, além de uma execução de laboratório do Lighthouse lado a lado. É a forma mais rápida de ver por conta própria a diferença entre laboratório e campo.
• Search Console — relatório Core Web Vitals — CLS de campo por grupo de URLs em todo o site, agrupado por status.
• CrUX (Chrome User Experience Report) — o conjunto de dados de campo subjacente; explore o histórico pelos painéis do CrUX / BigQuery.

Dados de laboratório (para depuração)

• Chrome DevTools — painel Performance — grave um trace e leia a trilha Layout Shifts; clicar numa mudança destaca os elementos que se moveram e mostra a pontuação da mudança. Live Metrics atualiza o CLS em tempo real enquanto você interage.
• Sobreposição Layout Shift Regions — DevTools → Settings → More tools → Rendering → Layout Shift Regions. Recarregue e as áreas que mudarem piscarão, para que você possa vê-las.
• Lighthouse — CLS rápido de laboratório, mas lembre que ele captura apenas mudanças do carregamento inicial.
• WebPageTest — CLS de laboratório com filmstrip e trace.

RUM (seus próprios dados de campo)

• Biblioteca JavaScript web-vitals — onCLS() informa o CLS de usuários reais dos seus visitantes (~2 KB); é a visão mais precisa do que as pessoas realmente vivenciam.
• PerformanceObserver (layout-shift) — a API bruta que a biblioteca encapsula, além dos sources de LayoutShiftAttribution que indicam quais elementos se moveram.

Como as próprias ferramentas pontuam

Um exemplo ao vivo da métrica descrita nesta página — serviços conhecidos de velocidade de página e monitoramento classificados pelo próprio CLS móvel de usuários reais (dados de campo do Chrome UX Report):

Qual correção de CLS você deve fazer primeiro?

Erros de CLS que escondem o problema real

Tratar uma execução limpa do Lighthouse como prova

O Lighthouse pode terminar antes que um banner de consentimento, anúncio ou mudança acionada por interação aconteça. Use a execução de laboratório para depurar, mas verifique o CrUX ou seu próprio monitoramento de usuários reais antes de declarar que o problema foi corrigido.

Corrigir apenas o elemento que o DevTools diz que se moveu

O elemento que se deslocou frequentemente é a vítima. Um item que carrega tarde acima dele pode ser a causa. Reproduza o trace e examine o que entrou ou mudou de tamanho imediatamente antes do movimento.

Reservar espaço com uma altura fixa estimada

Um placeholder fixo pode criar uma segunda mudança quando o conteúdo responsivo é mais alto ou mais baixo. Use dimensões intrínsecas ou aspect-ratio quando as proporções do conteúdo forem conhecidas.

Animar propriedades de layout

Mudar top, left ou margens pode mover o conteúdo ao redor. Anime com transform quando o efeito não precisar alterar o fluxo do documento.

Diagnostique um problema de CLS pelo sintoma

O CLS de campo é ruim, mas a pontuação de laboratório está próxima de zero

Causa provável: a mudança acontece depois de uma interação, durante uma sessão mais longa ou apenas para um subconjunto de usuários. Correção: reproduza a jornada real enquanto grava o painel Performance e adicione a atribuição de web-vitals ao monitoramento de usuários reais. Confirmação: a interação problemática e o elemento deslocado aparecem no trace ou no registro de RUM.

O texto salta quando a fonte personalizada chega

Causa provável: a fonte fallback e a fonte da web usam métricas diferentes. Correção: faça preload apenas da fonte crítica quando apropriado e corresponda o fallback usando substituições de métricas de fonte. Confirmação: reproduza com o cache desativado e verifique se a trilha Layout Shifts não registra mais a troca.

Um banner ou anúncio empurra a página para baixo

Causa provável: o espaço não tem dimensões reservadas antes que o conteúdo chegue. Correção: aloque um contêiner estável ou coloque a mensagem onde ela não desloque conteúdo visível. Confirmação: limite a velocidade do carregamento e observe se o espaço mantém sua área reservada.

O CLS melhora nos testes, mas não no PageSpeed Insights

Causa provável: o CrUX é um conjunto de dados de campo móvel, não uma verificação imediata de implantação. Correção: verifique a mudança primeiro no laboratório e no RUM, e depois espere a janela de campo virar. Confirmação: sua própria distribuição de campo após o lançamento melhora antes que o agregado público do CrUX acompanhe.

Capture mudanças de layout no navegador

Cole isto no Console do DevTools antes de reproduzir o problema. Ele ignora mudanças associadas a entradas recentes do usuário e imprime a pontuação e os elementos aos quais o navegador atribuiu a mudança.

const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.hadRecentInput) continue;
    console.table({
      value: entry.value,
      time: Math.round(entry.startTime),
      elements: entry.sources?.map((source) => source.node),
    });
  }
});

observer.observe({ type: 'layout-shift', buffered: true });

O nó atribuído é uma pista, não uma prova automática da causa. Compare o timestamp dele com requisições de rede, carregamentos de fontes e inserções no DOM no mesmo trace.

Comprove que uma correção de CLS funcionou

Teste de espaço reservado

Teste a executar: desative o cache, limite a conexão, recarregue e grave a trilha Layout Shifts do painel Performance. Resultado esperado: a mídia ou o embed mantém a mesma área antes e depois de carregar. Interpretação de falha: o contêiner ainda depende de conteúdo tardio para definir suas dimensões. Janela de monitoramento: imediata no trace. Gatilho de rollback: o novo placeholder cria recorte, espaço em branco excessivo ou uma nova mudança num breakpoint responsivo.

Teste de troca de fonte

Teste a executar: recarregue com o cache desativado enquanto observa o texto e a trilha Layout Shifts. Resultado esperado: a transição da fonte fallback para a fonte da web não cria nenhuma mudança mensurável. Interpretação de falha: as métricas do fallback ainda diferem ou a fonte crítica chega tarde demais. Janela de monitoramento: imediata em execuções repetidas de laboratório. Gatilho de rollback: a mudança mantém o texto oculto por mais tempo ou torna a tipografia final materialmente incorreta.

Confirmação no campo

Teste a executar: compare os dados onCLS() pós-lançamento do template alterado com a linha de base pré-lançamento e depois observe o CrUX. Resultado esperado: o p75 de usuários reais melhora sem uma cauda pior nas jornadas importantes. Interpretação de falha: outra fonte tardia ou acionada por interação permanece. Janela de monitoramento: RUM conforme o tráfego chega; CrUX na janela móvel de 28 dias. Gatilho de rollback: CLS ou erros de interação pioram consistentemente depois do lançamento.

Métricas de CLS que vale acompanhar

CLS de usuários reais no p75

Métrica: o CLS no percentil 75 para cada template importante e classe de dispositivo. O que informa: se a maioria das visitas atende à meta de estabilidade visual. Como obter: CrUX, PageSpeed Insights ou RUM com web-vitals. Faixa de referência / realista: bom é 0,1 ou menos; 0,1–0,25 precisa melhorar; acima de 0,25 é ruim. Periodicidade: monitore lançamentos no RUM e revise a tendência de campo móvel mensalmente.

Taxa de visitas ruins

Métrica: a parcela de visitas reais com CLS acima de 0,25. O que informa: se um p75 aceitável esconde uma cauda prejudicial. Como obter: agrupe seus eventos onCLS() por template e jornada. Faixa de referência / realista: estabeleça uma linha de base do site e reduza a faixa ruim; a composição do tráfego torna enganosa uma meta universal. Periodicidade: semanalmente para templates de alto tráfego e depois de lançamentos de layout.

Atribuição de mudanças por causa

Métrica: entradas de layout-shift agrupadas por elemento ou componente. O que informa: qual implementação recorrente é responsável pela maior parte da instabilidade. Como obter: a versão com atribuição de web-vitals ou PerformanceObserver. Faixa de referência / realista: não há uma faixa universal; compare componentes pelo impacto total e pelas visitas afetadas. Periodicidade: revise a cada lançamento de template ou componente.

Recursos que valem seu tempo

Oficiais e aprofundados

• Cumulative Layout Shift (CLS) — a referência canônica.
• Otimizar Cumulative Layout Shift — o guia oficial de correções.
• Depurar mudanças de layout — o fluxo de trabalho do DevTools.
• A evolução de Cumulative Layout Shift nas ferramentas web — a mudança da janela de sessão de junho de 2021, explicada pela equipe que a criou.

De profissionais

• Como corrigir problemas de Cumulative Layout Shift (CLS) — Barry Pollard, Smashing Magazine. Aprofunda-se nos descritores de fonte e no problema de que “o elemento que se deslocou não é a causa raiz”.
• Cumulative Layout Shift na prática — Nic Jansma (Cloudflare; W3C Web Performance WG). A melhor explicação das nuances de medição: lacunas de atribuição de iframe, amostra de atribuição de 5 elementos e discrepâncias entre ferramentas.
• Medir e otimizar Cumulative Layout Shift — DebugBear.
• O guia quase completo de Cumulative Layout Shift — Jess Peck. Tratamento detalhado de casos extremos, incluindo mudanças de navegação em SPAs e nuances da exclusão de gestos contínuos.
• Culpados pelas mudanças de layout — documentação do Chrome DevTools sobre o painel de culpados de CLS — complemento útil ao guia de depuração do web.dev.
• Como corrigir Cumulative Layout Shift (CLS) — Kinsta. Guia prático focado em CMS, cobrindo causas específicas do WordPress (imagens de galerias, widgets que carregam tarde e banners de cookies).
• API Layout Instability — especificação WICG. A API de navegador subjacente ao CLS; útil para criar RUM personalizado ou precisar da semântica exata de hadRecentInput.

Onde isso se encaixa no meu próprio trabalho

• CLS aparece como uma métrica de “requisito básico” em toda a minha cobertura de Core Web Vitals — acompanhe, entre na faixa bom e mantenha a proporção em relação a LCP, INP e seu conteúdo. O Google não publica um peso exato de CLS nem uma regra de desempate, então é uma entrada a observar, não o jogo inteiro.

Estatísticas que vale citar

• O limiar de 0,1 se baseia em pesquisa de percepção. Os estudos de usuários do Google descobriram que mudanças de 0,15 ou mais eram percebidas consistentemente como perturbadoras, enquanto 0,1 ou menos eram perceptíveis, mas não excessivamente perturbadoras. A fonte registra: “levels of shift from 0.15 and higher were consistently perceived as disruptive” (Tradução: “níveis de mudança de 0,15 ou mais eram percebidos consistentemente como perturbadores”). Fonte
• CLS é a Core Web Vital mais fácil de passar. Nas minhas auditorias empresariais, o padrão é consistente: uma grande maioria dos sites passa da barra de CLS (frequentemente ~80%+), mas pouco mais da metade passa nas três vitals juntas — CLS raramente é o que impede a aprovação.
• A mudança de junho de 2021 ajudou, nunca prejudicou. Quando o CLS passou para a maior janela de sessão, nenhuma origem recebeu uma pontuação pior, a maioria não mudou e uma parcela de páginas de rolagem infinita e interfaces lentas melhorou. Fonte
• Mídia sem dimensões ainda está em toda parte. Crawls do setor (Web Almanac) encontram consistentemente uma grande parcela de páginas que publicam imagens sem dimensões explícitas — a causa mais comum de CLS e a mais fácil de corrigir.
• 72% dos sites no mundo agora alcançam um CLS bom (dados do Web Almanac / HTTP Archive de 2025), tornando CLS a Core Web Vital mais fácil de passar — ainda assim, 62% das páginas móveis enviam pelo menos uma imagem sem dimensões explícitas, a causa mais comum. Fonte: HTTP Archive / Web Almanac
• Impacto no negócio: a Rakuten 24 relatou um aumento de 53,37% na receita por visitante para usuários com CLS baixo em comparação com CLS alto — um estudo de caso frequentemente citado, não evidência de que uma pontuação CLS específica cause um resultado empresarial específico em outros sites. Fonte: estudos de caso da corewebvitals.io

Vídeos

• Google Search Central / Chrome for Developers (YouTube) — os walkthroughs de Core Web Vitals e Debug layout shifts, incluindo demonstrações do DevTools da trilha Layout Shifts e da sobreposição Layout Shift Regions. Canal

Teste seus conhecimentos: Cumulative Layout Shift

Cinco perguntas rápidas sobre medir e corrigir a instabilidade visual. Escolha uma resposta para cada uma e depois confira.

Registro de alterações