Guía de animaciones accesibles con GSAP
Crea animaciones GSAP accesibles con matchMedia y prefers-reduced-motion. Simplifica ScrollTrigger, añade controles de pausa y prueba las preferencias de movimiento.
La forma estándar de gestionar prefers-reduced-motion en GSAP es gsap.matchMedia() con un objeto de condiciones: GSAP ejecuta tu función de configuración para la preferencia de movimiento que coincida y, cuando el usuario cambia ese ajuste, revierte todo lo que la función creó y la vuelve a ejecutar.
Los equipos suelen llegar a esto después de que una auditoría de accesibilidad señale un hero fijado con scroll o una marquesina en bucle, y los diseñadores no quieren que la solución convierta la página en un PDF estático.
Comprobar la media query es solo una parte del trabajo. Una configuración de GSAP accesible también necesita ScrollTriggers más sosegados, un control de pausa, contenido que siga visible aunque el script nunca llegue a ejecutarse y una forma de probarlo todo. Si necesitas contexto sobre la media query en sí, consulta la guía de prefers-reduced-motion de OpenReplay. gsap.matchMedia() requiere GSAP 3.11.0 o posterior.
Puntos clave
gsap.matchMedia()revierte todas las animaciones y ScrollTriggers creados en una función de configuración cuando su query deja de coincidir, de modo que un cambio en el ajuste de reducción de movimiento del sistema operativo se aplica sin recargar la página.- Para el movimiento reducido, sustituye los desplazamientos amplios, las rotaciones y los escalados por un fundido de opacidad breve, de forma que el contenido siga apareciendo.
- Una rama de ScrollTrigger para movimiento reducido debe prescindir de
pinyscruby limitarse a hacer aparecer cada elemento con un fundido cuando entra en el viewport. - El criterio WCAG 2.2.2 Pausar, detener, ocultar (Nivel A) exige un control para pausar, detener u ocultar el movimiento automático. Una comprobación de prefers-reduced-motion no lo cumple por sí sola.
- Deja el contenido animado legible en su estado CSS por defecto, para que nada se quede en
opacity: 0si no se ejecuta ninguna animación.
Ramificar según prefers-reduced-motion en GSAP con gsap.matchMedia()
gsap.matchMedia() ejecuta una función de configuración solo mientras su query coincide. Cuando la query deja de coincidir, revierte todas las animaciones y ScrollTriggers que creó la función. Puedes pasar un objeto de condiciones como query, y el handler lee entonces cada condición como un booleano desde 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 });
}
});
El objetivo es reducir el movimiento, no eliminarlo. En la rama reducida, el gran desplazamiento horizontal y la rotación se convierten en un fundido breve. La tarjeta sigue apareciendo y sigue atrayendo la atención, pero nada cruza la pantalla. La guía de animación accesible de GSAP ofrece una rúbrica para decidir cuándo simplificar una animación y cuándo eliminarla por completo. matchMedia() envuelve internamente gsap.context(), así que no lo envuelvas en un segundo contexto.
Suavizar ScrollTrigger para movimiento reducido
Una rama de ScrollTrigger para movimiento reducido debe prescindir de pin y scrub y hacer aparecer cada elemento con un fundido cuando entra en el viewport. El pinning toma el control del scroll del usuario y el scrubbing vincula el movimiento a cada gesto de desplazamiento. Ambas cosas son justo lo que la rama reducida 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 } });
});
}
});
En su forma más sencilla, un ScrollTrigger reproduce su animación una sola vez, cuando el elemento disparador entra en el viewport. Eso encaja bien con un fundido. No tienes que destruir nada manualmente: si la preferencia cambia, matchMedia revierte el timeline fijado y construye la versión con fundido. Para los patrones de pinning y scrub en el lado de movimiento completo, consulta el tutorial de ScrollTrigger de OpenReplay. Las grabaciones de sesión (session replays) pueden mostrar a usuarios que hacen scroll rápidamente para dejar atrás las secciones fijadas o que se detienen a mitad de una animación, lo que indica dónde el movimiento les está estorbando.
Controles de pausa y un interruptor de movimiento en la página
WCAG 2.2.2 Pausar, detener, ocultar es un criterio de Nivel A que exige una forma de pausar, detener u ocultar el contenido en movimiento que se inicia automáticamente, dura más de cinco segundos y se muestra junto a otro contenido. Respetar prefers-reduced-motion no satisface WCAG 2.2.2, porque los usuarios que nunca han cambiado el ajuste de su sistema operativo siguen viendo la animación completa. El documento Understanding del W3C para el criterio 2.2.2 también recomienda que, si una página contiene más de un elemento en movimiento, parpadeante, con desplazamiento o que se actualiza automáticamente, se proporcione un único mecanismo que los controle todos.
| Criterio | Nivel | Técnica en GSAP |
|---|---|---|
| 2.2.2 Pausar, detener, ocultar | A | Botón de pausa que llama a timeline.pause() / timeline.play() |
| 2.3.3 Animación desde interacciones | AAA | Rama de movimiento reducido con gsap.matchMedia() |
WCAG 2.2.2 y 2.3.3 cubren tipos de movimiento distintos. El 2.3.3 se aplica al movimiento desencadenado por la interacción del usuario, y el 2.2.2, al movimiento que la página inicia por sí misma. La visión general sobre animaciones accesibles de OpenReplay trata las pautas en un sentido más amplio.
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);
});
pause() pausa la instancia y, opcionalmente, puede saltar a un tiempo concreto. Sin argumentos, se detiene donde se encuentre el cabezal de reproducción en ese momento. play() reanuda desde ese punto y garantiza que la instancia no esté ni pausada ni invertida. paused() sin argumentos funciona como getter, así que puedes usarlo para alternar el estado.
gsap.matchMediaRefresh() revierte todas las configuraciones de matchMedia activas y vuelve a ejecutar las que siguen coincidiendo, por lo que la casilla de verificación reconstruye todas las animaciones de inmediato. La regla que expresa reduce = isReduced || toggle.checked es que el interruptor puede añadir reducción, pero nunca anular una petición de movimiento reducido del sistema operativo. La función de limpieza solo elimina el listener. No llames a context.revert() dentro de ella, porque matchMedia ya se encarga de la reversión.
Mantener el contenido visible si la animación nunca se ejecuta
El contenido animado debe ser totalmente legible en su estado CSS por defecto. Así, si el script falla o no se ejecuta ninguna rama de matchMedia, nada se queda en opacity: 0 ni en visibility: hidden. Esto ocurre en la práctica: un handler de gsap.matchMedia() basado en un objeto de condiciones no se ejecuta en absoluto cuando no coincide ninguna de las condiciones.
/* 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 });
});
gsap.from() anima desde los valores que le pasas hasta el estado actual del elemento. Eso significa que el estado de reposo sigue siendo visible y que solo la animación llega a ocultar el elemento. Lo mismo se aplica a autoAlpha, la propiedad de GSAP que combina opacidad y visibilidad: anima el contenido desde autoAlpha: 0 en lugar de ocultarlo en CSS con opacity: 0 y visibility: hidden y esperar a que un tween lo revele.
Orden del foco cuando los elementos se mueven
Las transformaciones de GSAP como x, y y scale mueven un elemento visualmente, pero no cambian su posición en el DOM. Por tanto, el foco del teclado y el orden de lectura del lector de pantalla siguen el marcado, no la animación. Mantén el DOM en un orden de lectura lógico y no animes propiedades de layout para simular un orden distinto.
No muevas un elemento mientras tiene el foco y no hagas que un elemento interactivo sea clicable antes de que se haya asentado. Un botón que se desliza bajo el cursor es un objetivo que se escapa. Para el texto animado, SplitText gestiona los lectores de pantalla por defecto. Con aria: "auto", añade un aria-label al elemento dividido, rellenado con su texto, y añade aria-hidden a los elementos de línea, palabra y carácter que contiene. De este modo, el árbol de accesibilidad expone una única cadena legible en lugar de fragmentos sueltos. Ese comportamiento por defecto funciona en encabezados, pero ARIA prohíbe aria-label en elementos genéricos como un <div>, un <span> o un <p> sin más, y los validadores de accesibilidad lo señalan en esos casos. Para esos elementos, o si el texto dividido contiene enlaces anidados que deben anunciarse, usa aria: "none", que no añade ningún atributo ARIA, y proporciona una copia del texto visible solo para lectores de pantalla.
¿Cómo se prueba el movimiento reducido en GSAP?
Prueba ambas ramas de movimiento de GSAP activando y desactivando la preferencia de movimiento reducido con la página abierta. Como gsap.matchMedia() responde a los cambios, deberías ver cómo se intercambian las animaciones sin recargar. Activa el ajuste de reducción de movimiento del sistema operativo (consulta las preferencias de usuario de prefers-reduced-motion en MDN para saber dónde se encuentra en cada plataforma) o emúlalo en Chrome. En Chrome DevTools, abre la pestaña Rendering, busca “Emulate CSS media feature prefers-reduced-motion” y selecciona prefers-reduced-motion: reduce.
Comprueba lo siguiente:
- Las secciones fijadas ya no se fijan.
- El movimiento en bucle ha desaparecido o tiene un botón de pausa funcional al que se puede llegar con el teclado.
- Con JavaScript desactivado, todo el contenido sigue siendo visible.
- El interruptor de la página reconstruye las animaciones de inmediato.
Conclusión
Una configuración de GSAP accesible conserva el diseño y da a los usuarios el control sobre él. matchMedia sustituye los grandes movimientos por fundidos y se mantiene sincronizado con el ajuste del sistema operativo, ScrollTrigger deja de fijar secciones en la rama reducida, un botón real pausa todo lo que dure mucho y el contenido sigue visible sin JavaScript. Empieza por la animación fijada o en bucle que señaló tu auditoría, escribe su rama reducida y su control de pausa, y prueba ambos con la emulación de DevTools antes de pasar a la siguiente.
Preguntas frecuentes
¿Cómo uso gsap.matchMedia() para el movimiento reducido en React?
Crea la instancia de matchMedia dentro del efecto y devuelve una función de limpieza que llame a mm.revert(). Revertir la instancia revierte todas las animaciones y ScrollTriggers que crearon sus handlers, por lo que no hace falta un gsap.context() aparte. La limpieza es importante en desarrollo porque el Strict Mode de React monta, desmonta y vuelve a montar los componentes, lo que de otro modo podría iniciar la misma animación dos veces.
¿Un reset de CSS con prefers-reduced-motion detiene las animaciones de GSAP?
No. Una regla CSS global que acorta la duración de las animaciones y transiciones dentro de un bloque prefers-reduced-motion: reduce solo afecta a las animaciones y transiciones CSS. GSAP anima desde JavaScript escribiendo valores de estilo inline en cada fotograma, así que sus tweens y ScrollTriggers siguen ejecutándose. Gestiona el movimiento de GSAP con una rama reducida de gsap.matchMedia() y mantén el reset de CSS para el movimiento basado en CSS.
¿Qué ocurre con una animación de GSAP en curso cuando el usuario cambia el ajuste de movimiento reducido?
gsap.matchMedia() la revierte y vuelve a ejecutar el handler para la nueva preferencia. La reversión elimina los estilos inline que añadieron las animaciones y revierte los ScrollTriggers creados en el handler, incluido su pinning. A continuación, la rama que pasa a coincidir construye sus animaciones desde cero, por lo que un tween de movimiento completo a medio terminar no se reanuda. La versión reducida parte del estado CSS por defecto del 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