How to make scroll animations responsive: our open-source method

Why animated websites have become so common

When we build a home page, we want it to move. Front-end developers share this reflex, and at Nualt we are no exception. Sections that stay pinned on screen while the visitor scrolls, transitions that open the content from the top of the page and photos that change as the reader moves down account for much of what sets a custom website apart from a theme, and these effects are now within everyone's reach.

A few years ago, an ambitious scroll animation was expensive to write, and that cost acted as a safeguard. With AI, a working animated section with smooth scrolling and reveal effects on top now takes a few minutes to produce. We touched on this in our article on recent Next.js vulnerabilities and during our workshop on the limits of vibe coding, where the same pattern appeared. The easier a tool becomes to use, the more often it is used without its full depth being visible.

What responsive design changes for an animated site

For an animated website, that depth shows up the moment the page is opened on a screen other than the designer's. A conventional site reorganises itself fairly naturally between a large screen, a tablet and a phone. A scroll animation, on the other hand, needs a certain screen height to play out, a mouse for some effects, and a machine powerful enough to keep it smooth. When one of these conditions is missing, the animation does not degrade gracefully on its own, and it breaks.

Responsive design therefore remains a permanent constraint, and producing an animation in five minutes changes nothing about the work needed to make it hold on every screen. It is simply less on our minds when we write it.

What we observed on a client project

The site in question belongs to L'Essence d'Être, an executive coaching practice. Its home page opens with a transition from the top of the page, followed by a services section that stays pinned while the visitor scrolls and a method column whose photo is replaced as the reader progresses. On the MacBook where it was built, everything worked.

Then the client opened it on a 1366 × 768 laptop. The photo in the method column was cropped. On an iPad in landscape mode, the pinned column was taller than the screen. On another laptop, a block of colour overlapped the photo at the top of the page. With the developer tools open on the side, the navigation bar changed colour at the wrong moment.

Each symptom received its own fix, a rule for the iPad in landscape, a height cap for the laptop, a manual offset for the colour block. Each fix worked on the targeted device and weakened the next one. We quickly saw where this logic was heading, with breakpoints multiplying, JavaScript and CSS no longer switching on at quite the same moment, and a list of devices that could never be complete.

The problem lay upstream of the animation library. Where each animation should exist had never been settled once and for all, and the JavaScript and the CSS each answered that question on their own.

responsive-motion, our open-source method for responsive scroll animations

Rather than keep stacking fixes, we went back to the question from the beginning and turned the answer into a method. We still had to choose what form to give it. Coding agents such as Claude Code, Codex or Cursor are now part of a developer's daily work, and they are just as inclined as we are to add an animation in five minutes and forget about small screens. The format that seemed most useful was therefore a skill, meaning a folder of rules and recipes that the agent reads before working on an animated site, and which imposes the same discipline on it as on us.

The result is published in responsive-motion, a public repository under the MIT licence. It contains seven rules, a five-level model, thirteen layout recipes, measurement scripts for six screen formats, and an anti-patterns file that records, for each rule, the mistake that led to it. The examples are written with GSAP and Tailwind, although each recipe is first of all a layout idea, and the syntax carries over to other libraries.

Once the skill is installed, describing the symptom is enough to trigger it, for example "the photo in the pinned section is cropped at 1366 × 768". It measures first, states which files it intends to touch, works on one section at a time, then checks the result on all six formats. It is not allowed to rebuild an entire page to fix a single photo.

As we did with the authentication module for Medusa, we are publishing it because the problem is not specific to our project. Anyone who builds animated sites with a coding agent runs into it, and a method kept in a private repository only serves one studio. It is a work in progress, drawn from a single site with a single technical stack. Recipes for Framer Motion, Motion One or native scroll-driven animations are still missing, and results from real devices that would contradict the model are welcome. The repository will evolve with our next projects and with whatever the community chooses to contribute.

Three rules for an animated website that holds on every screen

The skill rests on three simple ideas, which apply to any animated site, with or without a coding agent.

Reason in terms of the space actually available

We often think in terms of screen resolution, yet resolution says nothing about the space the site actually has. Take a laptop sold as "15-inch Full HD", which means 1920 × 1080. Windows applies a default scaling of 125% or 150% depending on the model. At 150%, the browser has only 1280 × 720 pixels left. Remove the tab bar, the address bar and sometimes a bookmarks bar, and the page is left with about 1280 × 630 pixels. A section designed for a height of 800 pixels does not fit. A 1366 × 768 laptop or an iPad in landscape also loses around a hundred pixels of height to the browser.

A list of devices is therefore an insufficient guide, since the available space depends on system scaling, the browser and whatever the user has open alongside it. The method reasons on the smallest possible space in each situation, and gives each animation the height below which it no longer fits.

Decide once where an animation exists

Whether an animation exists depends on a single criterion, which combines the screen's width, its height and the presence of a real mouse. This criterion is written once, then shared between the JavaScript that runs the animation and the CSS that lays out the page. This is exactly what was missing on the original site, where each made its own decision.

Based on this criterion, each section of the site sits in exactly one of five levels, and each level falls back on a layout that already exists.

• Scene. Large screen, enough height, real mouse. The animation plays in full.
• Expansion only. Large screen and mouse, but not enough height. The entry transition plays unchanged, and what follows scrolls normally instead of staying pinned.
• Flat. Large screen with reduced height, or a touch screen. The desktop layout without animation, one image per step.
• Mobile. Narrow screen. The mobile layout, without animation.
• Light. Reduced motion enabled in the system settings, data saver mode, or a low-powered machine. No effects, whatever the format.

The "expansion only" level is the one people forget. On a short laptop with a mouse, the tendency is to cut everything. Yet the entry transition from the top of the page fits in any space, since it does not depend on the height of what follows. It therefore keeps playing, and only the pinned section gives way.

The "light" level answers a different question from the first four. They concern screen format, whereas this one concerns the machine and the visitor's preferences. A powerful but short laptop is entitled to the entry transition. A visitor who has reduced motion in their system settings gets no effects at all, even on a large screen. Mixing the two produces sites that cut animations on an iPad Pro and keep them on an old desktop PC.

There is no "tablet" level, and this is deliberate. When an animation does not fit, it falls back on the desktop layout without animation or on the mobile layout, two versions that already exist and have already been tested.

Verify with measurements

Looking at a page on three devices and finding it correct is not enough. An overlap of a few pixels goes unnoticed by eye and becomes obvious to the client on their own screen. The skill therefore checks each animation on six screen formats, with small scripts run in the browser's developer tools. They measure the actual positions of elements and compare edges to the pixel, and they check that the pinned section fits within the available height, that cards on the same row are aligned, and that the navigation bar takes the right colour in both scroll directions.

We run one full pass across the formats, fix everything it reveals, run a confirmation pass, and stop there. Without that limit, we fall back into the loop of fixing device by device.

At Nualt, animation is decided when the project is designed

Scroll animations have their place on a custom website. They shape the first impression, they guide reading and, as we explained in the article on the impact of design, they contribute to the credibility a visitor grants a business before reading a single line. We therefore keep designing them.

This project changed the moment at which we decide on them. The question of which screens an animation exists on is now settled when it is designed, based on the space actually available to the client's visitors, and the answer is written in a single place in the code. On small formats, the site falls back on a layout that has been designed and tested, never on an improvised version.

The skill helps us keep this discipline from one project to the next, including when part of the code is produced with an agent. We will update it as other sites teach us something, and it is open to anyone who wants to contribute.