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.
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:
| Finding | Count |
|---|---|
| Missing | 41 |
| Different | 36 |
| Broken | 20 |
| Extra | 4 |
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.
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.