Skip to contentSkip to contact
Dennis Khor
Recruiter mode

Writing

Auditing animation parity in a Next.js rebuild

An audit filmed 194 motion behaviours in my Next.js rebuild against the approved prototype and found 101 that did not match. One policy fixed most of them.

Author
Dennis Khor, senior full-stack engineer shipping AI agents in Sydney
Published
Reading time
5 min read
Decision records

The design of this site was approved from a live prototype: plain HTML and JavaScript on three.js and GSAP, with an intro on almost every page. That prototype went to production first, on 28 Sep 2026. Then I rebuilt the site in Next.js beside it, in waves, with parallel builder agents each owning separate files and a parity harness comparing the new pages with the old. How those agents kept the docs true between sessions is in Keeping docs current with Claude Code and tests.

After the fourth wave I opened one of the role pages and its heading's intro was missing. Looking closer, other animations were off too. I could see it, but "it feels wrong" is not a bug report, so before fixing anything the motion had to be measured.

Why the screenshots could not catch it

The parity harness captured both sites deterministically, with seeded randomness and a fixed clock, and diffed them at 1440 x 900 and 390 x 844. It compared settled stills, so it could never have caught this: a page whose intro never plays settles into the same final frame as one whose intro plays perfectly. Motion has to be filmed.

The audit

The audit filmed 194 motion behaviours of the app against the prototype, on every page, with a verifier checking each auditor's findings. 101 did not match:

FindingCount
Missing41
Different36
Broken20
Extra4

One rule caused most of it

The rebuild plan had a port rule, R2, written to protect server rendering: pre-paint gates are inverted, so text is never hidden. The goal was good: every word renders on the server, so crawlers, link previews and readers without JavaScript get the whole page. But applied literally, it meant no intro could start from hidden text, so the builders dropped or flattened every intro that does.

The rest came from three smaller causes. Some islands waited for the largest paint and an idle moment before playing, so their intros started late. React keeps hidden routes mounted, and some of them kept an "already played" flag, so coming back to a page showed it without its intro. And one rule left anything already on screen still.

The lesson: a rule that changes what people see is a design decision, even when it is written as a technical one. R2 sat in an implementation plan, and I never approved it as a visual choice. On this site, visual choices are made from live options I can look at before anything is built, and that now includes rules like this one.

Hidden start, gated per island

The fix was one policy for every page, then one package per page putting the prototype's timelines back as written.

  • The flag. A boot script in the document head sets an attribute, data-pre, on the html element before the first paint, but only when JavaScript runs, the visitor has not switched to less motion, and the system does not ask for reduced motion. The server never renders it, so readers without JavaScript, crawlers and anyone asking for reduced motion always get the finished page.
  • The gate. Each page hides only what the prototype hid before its script ran, with one rule shape: under the flag, an intro's targets sit at opacity 0 until the element that owns the intro is marked live. Gates use opacity or visibility only. The island writes its transform from-states and sets the live mark in the same task, so no frame ever shows text at rest and then jumping.
  • The failsafe. Every gate carries a CSS animation that lifts it after a few seconds, using the prototype's own value for each page: 4 seconds on the home, 3 on a few of the worlds and 6 by default. Being pure CSS, it fires even if the JavaScript dies right after the boot script. An island that starts after its failsafe has fired shows its end state rather than replay over text already read, and a setup that throws lifts its gate at once.
  • The arrival. Each island knows how the page arrived: a fresh load, a link, a dive from the orbit, or the Back and Forward buttons. A page you return to with Back or Forward shows as you left it, the way a browser's back-forward cache restores one. Anything else plays its intro.

What it cost

Intros now mount at hydration instead of waiting for the largest paint, since hidden text is never a candidate for it. The price is that the largest contentful paint moves from the first paint to the intro's first visible frame, as it does on the prototype. I accepted that for parity, then measured it. On Lighthouse's simulated mobile run, the median of 3, every intro page came in under its limit and under the prototype's own figure measured the same day; the home and the CV beat the prototype by about 3 seconds. On desktop, every page painted its largest content within 1.2 seconds, with a performance score of 0.97 or more. Two of the fixes that got the intro pages there:

  • The header's prefetch of the home and the orbit's three.js warm-up now wait until the page has settled. Before, about 300 KB landed ahead of each intro's first frame.
  • The diagram renderer lays out one set of figures per task, which took total blocking time on one role page from 298 ms to 20 ms.

The re-audit

A second pass filmed every page against the prototype before the motion gate passed. Two differences stay, by my decision at the audit: the type stretching with scroll velocity, and the header staying on screen through the navigation's own jumps. Both are listed in the parity register, which records each difference for me to review and never approves one on its own.

What I would do again

  • Film motion. Pixel diffs of settled stills only prove where an animation ends.
  • Fix the policy before the pages: one shared rule and one template covered most of the 101 findings.
  • Put failsafes in CSS, where a dead script cannot take them down.
  • Treat any rule that changes what people see as a design decision, and decide it from something you can look at.

You can watch the failsafe work on this site's own page: the first bay of the stress bench, "Kill it mid-intro", stops the script part way through an intro and lets the CSS lift the gate.

Open to senior AI and software engineering roles: on site or hybrid in Sydney, or remote for Australian and US teams. Read my CV, or paste a job description into Ask about fit for a verdict with cited evidence.

Ask about fit

Paste a job description. You get a verdict, the evidence that matches it with citations, and what the sources do not show.

Open to senior AI and software engineering roles: on site or hybrid in Sydney, or remote for Australian and US teams.

Email meBook 15 minCV