Guia de animações acessíveis com GSAP
Crie animações GSAP acessíveis com matchMedia e prefers-reduced-motion. Simplifique efeitos ScrollTrigger, adicione controles de pausa e teste as preferências de movimento.
A forma padrão de lidar com prefers-reduced-motion no GSAP é usar gsap.matchMedia() com um objeto de condições: o GSAP executa sua função de configuração para a preferência de movimento que corresponder e, quando o usuário altera essa configuração, reverte tudo o que a função criou e a executa novamente.
Normalmente, as equipes chegam a essa solução depois que uma auditoria de acessibilidade aponta um hero com pin vinculado à rolagem ou um marquee em loop, e os designers não querem transformar a página em um PDF estático para resolver o problema.
Verificar a media query é só uma parte do trabalho. Uma implementação acessível com GSAP também precisa de ScrollTriggers mais contidos, um controle de pausa, conteúdo que continue visível caso o script nunca seja executado e uma forma de testar tudo isso. Se você precisa de contexto sobre a media query em si, leia o guia sobre prefers-reduced-motion da OpenReplay. O gsap.matchMedia() exige o GSAP 3.11.0 ou superior.
Principais conclusões
- O
gsap.matchMedia()reverte todas as animações e ScrollTriggers criados em uma função de configuração quando a query deixa de corresponder, de modo que uma alteração na configuração de redução de movimento do sistema operacional entra em vigor sem recarregar a página. - Para movimento reduzido, substitua grandes deslocamentos, rotações e mudanças de escala por um fade curto de opacidade, para que o conteúdo continue aparecendo.
- O branch de movimento reduzido de um ScrollTrigger deve abrir mão de
pinescrube simplesmente aplicar um fade-in em cada elemento conforme ele entra na viewport. - O critério 2.2.2 da WCAG, Colocar em pausa, parar, ocultar (Nível A), exige um controle para pausar, parar ou ocultar movimentos automáticos. Uma verificação de prefers-reduced-motion, por si só, não atende a esse critério.
- Mantenha o conteúdo animado legível em seu estado CSS padrão, para que nada fique em
opacity: 0caso nenhuma animação seja executada.
Ramificando por prefers-reduced-motion no GSAP com gsap.matchMedia()
O gsap.matchMedia() executa uma função de configuração apenas enquanto a query corresponde. Quando a query deixa de corresponder, ele reverte todas as animações e ScrollTriggers que a função criou. Você pode passar um objeto de condições como query, e o handler então lê cada condição como um booleano a partir de context.conditions.
const mm = gsap.matchMedia();
const conditions = {
isMotion: "(prefers-reduced-motion: no-preference)",
isReduced: "(prefers-reduced-motion: reduce)",
};
mm.add(conditions, (context) => {
const { isMotion, isReduced } = context.conditions;
if (isMotion) {
gsap.from(".hero-card", { opacity: 0, x: -200, rotation: -8, duration: 1 });
}
if (isReduced) {
gsap.from(".hero-card", { opacity: 0, duration: 0.4 });
}
});
O objetivo é reduzir o movimento, não eliminá-lo. No branch reduzido, o grande deslocamento horizontal e a rotação se transformam em um fade curto. O card continua aparecendo e ainda chama a atenção para si, mas nada atravessa a tela. O guia de animação acessível do GSAP traz critérios para decidir quando simplificar uma animação e quando removê-la por completo. O matchMedia() encapsula o gsap.context() internamente, então não o envolva em um segundo contexto.
Suavizando o ScrollTrigger para movimento reduzido
O branch de movimento reduzido de um ScrollTrigger deve abrir mão de pin e scrub e aplicar um fade-in em cada elemento conforme ele entra na viewport. O pin assume o controle da rolagem do usuário, e o scrub vincula o movimento a cada gesto de rolagem. Ambos são justamente o que o branch reduzido pretende evitar.
mm.add(conditions, (context) => {
if (context.conditions.isMotion) {
const tl = gsap.timeline({
scrollTrigger: { trigger: ".story", pin: true, scrub: 1, end: "+=200%" },
});
tl.from(".story-step", { opacity: 0, y: 100, stagger: 0.5 });
} else {
gsap.utils.toArray(".story-step").forEach((step) => {
gsap.from(step, { opacity: 0, duration: 0.4, scrollTrigger: { trigger: step } });
});
}
});
Em sua forma mais simples, um ScrollTrigger reproduz a animação uma única vez, quando o elemento gatilho entra na viewport. Isso é ideal para um fade. Você não precisa encerrar nada manualmente: se a preferência mudar, o matchMedia reverte a timeline com pin e monta a versão com fade. Para padrões de pin e scrub no lado de movimento completo, confira o passo a passo de ScrollTrigger da OpenReplay. Replays de sessão podem mostrar usuários rolando rapidamente por seções com pin ou parando no meio de uma animação, o que indica onde o movimento está atrapalhando.
Controles de pausa e um toggle de movimento na página
O critério 2.2.2 da WCAG, Colocar em pausa, parar, ocultar, é de Nível A e exige uma forma de pausar, parar ou ocultar conteúdo em movimento que começa automaticamente, dura mais de cinco segundos e é apresentado junto a outros conteúdos. Respeitar o prefers-reduced-motion não atende ao critério 2.2.2, porque usuários que nunca alteraram a configuração do sistema operacional continuam vendo a animação completa. O documento Understanding do W3C para o critério 2.2.2 também recomenda que, se uma página contiver mais de um elemento em movimento, piscante, com rolagem ou com atualização automática, você forneça um único mecanismo que controle todos eles.
| Critério | Nível | Técnica no GSAP |
|---|---|---|
| 2.2.2 Colocar em pausa, parar, ocultar | A | Botão de pausa que chama timeline.pause() / timeline.play() |
| 2.3.3 Animação a partir de interações | AAA | Branch de movimento reduzido com gsap.matchMedia() |
Os critérios 2.2.2 e 2.3.3 da WCAG tratam de tipos diferentes de movimento. O 2.3.3 se aplica a movimentos disparados por interação do usuário, e o 2.2.2 se aplica a movimentos que a própria página inicia. A visão geral sobre animações acessíveis da OpenReplay aborda as diretrizes de forma mais ampla.
const toggle = document.querySelector("#reduce-motion");
const pauseBtn = document.querySelector("#pause-motion");
toggle.checked = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
toggle.addEventListener("change", gsap.matchMediaRefresh);
mm.add(conditions, (context) => {
const reduce = context.conditions.isReduced || toggle.checked;
pauseBtn.hidden = reduce;
if (reduce) return; // marquee stays static
const tl = gsap.timeline({ repeat: -1 });
tl.to(".marquee-track", { xPercent: -50, duration: 20, ease: "none" });
pauseBtn.textContent = "Pause animation";
const onClick = () => {
tl.paused() ? tl.play() : tl.pause();
pauseBtn.textContent = tl.paused() ? "Play animation" : "Pause animation";
};
pauseBtn.addEventListener("click", onClick);
return () => pauseBtn.removeEventListener("click", onClick);
});
O pause() pausa a instância e pode, opcionalmente, saltar para um tempo específico. Sem argumento, ele para onde o playhead estiver no momento. O play() retoma a partir desse ponto e garante que a instância não esteja pausada nem invertida. O paused() sem argumento funciona como getter, então você pode usá-lo para alternar o estado.
O gsap.matchMediaRefresh() reverte todas as configurações de matchMedia ativas e executa novamente as que ainda correspondem, de modo que o checkbox reconstrói todas as animações imediatamente. A regra em reduce = isReduced || toggle.checked é que o toggle pode acrescentar redução, mas nunca pode sobrepor uma solicitação de movimento reduzido feita pelo sistema operacional. A função de cleanup apenas remove o listener. Não chame context.revert() dentro dela, pois o próprio matchMedia cuida da reversão.
Mantendo o conteúdo visível caso a animação nunca seja executada
O conteúdo animado deve ser totalmente legível em seu estado CSS padrão. Assim, se o script falhar ou nenhum branch do matchMedia for executado, nada fica em opacity: 0 ou visibility: hidden. Isso acontece na prática: um handler de gsap.matchMedia() baseado em um objeto de condições não é executado de forma alguma quando nenhuma das condições corresponde.
/* Avoid: content is invisible until JavaScript reveals it */
.reveal { opacity: 0; }
// Prefer: CSS leaves .reveal visible; GSAP animates from hidden to that state
mm.add(conditions, () => {
gsap.from(".reveal", { opacity: 0, duration: 0.4 });
});
O gsap.from() anima a partir dos valores que você passa até o estado atual do elemento. Isso significa que o estado de repouso permanece visível, e apenas a animação chega a ocultar o elemento. O mesmo vale para o autoAlpha, a propriedade do GSAP que combina opacidade e visibilidade: anime o conteúdo a partir de autoAlpha: 0 em vez de ocultá-lo no CSS com opacity: 0 e visibility: hidden e esperar que um tween o revele.
Ordem de foco quando os elementos se movem
Transformações do GSAP como x, y e scale movem um elemento visualmente, mas não alteram sua posição no DOM. Portanto, o foco do teclado e a ordem de leitura dos leitores de tela seguem a marcação, não a animação. Mantenha o DOM em uma ordem de leitura lógica e não anime propriedades de layout para simular uma ordem diferente.
Não mova um elemento enquanto ele estiver com foco e não torne um elemento interativo clicável antes que ele tenha se acomodado. Um botão deslizando sob o cursor é um alvo que foge. Para texto animado, o SplitText lida com leitores de tela por padrão. Com aria: "auto", ele adiciona um aria-label ao elemento dividido, preenchido com o texto dele, e adiciona aria-hidden aos elementos de linha, palavra e caractere internos. Dessa forma, a árvore de acessibilidade expõe uma única string legível em vez de fragmentos separados. Esse padrão funciona bem em headings, mas o ARIA proíbe aria-label em elementos genéricos, como um <div>, <span> ou <p> simples, e os verificadores de acessibilidade apontam isso como erro. Para esses elementos, ou se o texto dividido contiver links aninhados que precisam ser anunciados, use aria: "none", que não adiciona nenhum atributo ARIA, e forneça uma cópia do texto visível apenas para leitores de tela.
Como testar o movimento reduzido no GSAP?
Teste os dois branches de movimento do GSAP alternando a preferência de movimento reduzido com a página aberta. Como o gsap.matchMedia() reage a mudanças, você deve ver as animações sendo trocadas sem recarregar a página. Ative a configuração de redução de movimento do sistema operacional (consulte as preferências de usuário do prefers-reduced-motion na MDN para saber onde ela fica em cada plataforma) ou emule-a no Chrome. No Chrome DevTools, abra a aba Rendering (Renderização), localize a opção “Emulate CSS media feature prefers-reduced-motion” e selecione prefers-reduced-motion: reduce.
Verifique o seguinte:
- As seções com pin deixam de ficar fixadas.
- O movimento em loop foi removido ou conta com um botão de pausa funcional, acessível pelo teclado.
- Com o JavaScript desativado, todo o conteúdo continua visível.
- O toggle na página reconstrói as animações imediatamente.
Conclusão
Uma implementação acessível com GSAP preserva o design e dá ao usuário controle sobre ele. O matchMedia troca grandes movimentos por fades e se mantém sincronizado com a configuração do sistema operacional, o ScrollTrigger deixa de usar pin no branch reduzido, um botão de verdade pausa tudo o que tem longa duração e o conteúdo permanece visível sem JavaScript. Comece pela animação com pin ou em loop apontada pela sua auditoria, escreva o branch reduzido e o controle de pausa dela e teste ambos com a emulação do DevTools antes de passar para a próxima.
Perguntas frequentes
Como usar o gsap.matchMedia() para movimento reduzido no React?
Crie a instância do matchMedia dentro do effect e retorne uma função de cleanup que chame mm.revert(). Reverter a instância reverte todas as animações e ScrollTriggers criados pelos handlers dela, então um gsap.context() separado é desnecessário. O cleanup é importante em desenvolvimento porque o Strict Mode do React monta, desmonta e remonta os componentes, o que, de outra forma, pode iniciar a mesma animação duas vezes.
Um reset de prefers-reduced-motion em CSS interrompe as animações do GSAP?
Não. Uma regra CSS global que encurta a duração de animações e transições dentro de um bloco prefers-reduced-motion: reduce afeta apenas animações e transições CSS. O GSAP anima via JavaScript, escrevendo valores de estilo inline a cada frame, então seus tweens e ScrollTriggers continuam em execução. Trate o movimento do GSAP com um branch reduzido no gsap.matchMedia() e mantenha o reset de CSS para movimentos controlados por CSS.
O que acontece com uma animação do GSAP em execução quando o usuário altera a configuração de movimento reduzido?
O gsap.matchMedia() a reverte e executa o handler novamente para a nova preferência. A reversão remove os estilos inline adicionados pelas animações e reverte os ScrollTriggers criados no handler, incluindo o pin. Em seguida, o branch que passou a corresponder monta suas animações do zero, então um tween de movimento completo que estava pela metade não é retomado. A versão reduzida começa a partir do estado CSS padrão do elemento.
Gain Debugging Superpowers
Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.
Star on GitHub12k