Why I Didn’t Let AI Handle My Scroll Animation: Astro, React, and TypeScript Architecture

Hoi hoi!

I'm @nyaomaru, a frontend engineer who once panicked because I triggered a fire alarm while roasting chashu at home in the Netherlands. 🐖

This time, I want to write about how I built the corporate website for Necoz B.V.

Necoz | Software Development Studio in Amsterdam

Necoz B.V. is a software development studio based in Amsterdam, the Netherlands. We build well-designed systems, clean architecture, and scalable web applications.

necoz.co

The site is built with:

• Astro for the base structure
• React only where interactive UI is needed
• TypeScript for the main animation control
• responsive behavior for both desktop and mobile
• virtual scrolling to control the scroll amount itself

Because this is a corporate website, I did not want to break SEO.

But I also wanted the motion to feel good.

And I did not want the experience to fall apart on mobile.

When you take these requirements seriously, the important question is not only:

Which technology should I use?

It becomes:

Which responsibility should belong to which layer?

In the end, the hardest part was the animation.

AI was useful. It helped me move fast. It gave me rough ideas and initial implementations.

But the animation it produced was not something I could use as-is.

This article is about why, and how I ended up designing the animation system.

The repository is here:

nyaomaru / necoz

Official Necoz B.V. website with custom scroll animations.

necoz

Necoz B.V. website built with Astro, React islands, and custom scroll / walker animation logic.

Scroll down and enjoy the animations!

You can check it on mobile too 😸

Project Structure

The project is organized like this:

/
├── public/                     # Static files served as-is
├── src/
│   ├── components/
│   │   ├── home/               # Homepage sections
│   │   └── ui/                 # Reusable UI primitives and shared shells
│   │       ├── block/
│   │       ├── button/
│   │       ├── layout/
│   │       ├── mail/
│   │       ├── nyaomaru/
│   │       ├── scene/
│   │       ├── scroll/
│   │       └── text/
│   ├── layouts/                # Shared page layout shells
│   ├── lib/                    # Non-visual shared logic
│   │   ├── nyaomaru/           # Walker controller, scene logic, scene models
│   │   ├── math.ts
│   │   └── site-links.ts
│   ├── pages/                  # Route entrypoints
│   │   ├── index.astro
│   │   └── privacy-policy.astro
│

…

View on GitHub

Let's get into it.

---

🤔 Why I did not use AI-generated animation as-is

AI-generated animation often looks nice at first glance.

It usually has:

• some movement
• some easing
• some visual atmosphere

But when I looked more carefully, I often felt:

The direction is right, but the timing is wrong.

For example:

• the movement was too fast
• everything moved with the same rhythm
• elements did not stop where they should
• there was no pause
• there was no sense of timing

AI can generate the rough idea of "how something moves".

But in real animation, what matters is also:

• where it stops
• where it waits a little
• where one element reacts slightly later
• where the rhythm changes

Animation is not just about moving from position A to position B.

A small pause, a tiny delay, or a slightly different easing curve can completely change how it feels.

I think this is one of the current gaps between AI and human judgment:

AI can produce motion quickly, but humans still have better sensitivity for timing and rhythm.

So I used AI for rough drafts, structure, and experiments.

But I adjusted the final timing by hand.

---

🧑‍🚀 Why Astro?

This site is a corporate website.

So I wanted:

• real HTML content
• good SEO
• fast initial loading
• no unnecessary SPA architecture

That is why I chose Astro.

https://astro.build/

The page structure is mainly built around src/pages/index.astro and src/layouts/Layout.astro.

The header, sections, footer, and base layout are handled by Astro.

<Layout title={DEFAULT_TITLE} description={DEFAULT_DESCRIPTION} canonicalPath="/">
  <main id="top">
    <Header />
    <HeroIntro />
    <WorkSection />
    <StudioSection />
    <ContactSection />
    <NyaomaruWalker />
  </main>
  <Footer />
</Layout>

The layout also switches between native scrolling and virtual scrolling.

<body class:list={[virtualScroll ? "virtual-scroll-body" : "native-scroll-body"]}>
  {virtualScroll ? <VirtualScroll><slot /></VirtualScroll> : <slot />}
</body>

What I like about Astro is that I do not have to turn the whole site into JavaScript.

Astro lets me output clean HTML first, and then hydrate only the parts that need client-side behavior.

For a corporate website, this is very useful.

In this project, I wanted:

• solid page structure
• metadata and SEO
• client-side animation only where necessary

Astro did not make the animation better by itself.

But it helped me separate structure and behavior cleanly.

That separation was very important.

---

⚖️ I used React, but not for everything

The site also uses React.

But it is not a full React app.

The responsibility is divided like this:

• Astro owns the page structure
• React owns small interactive UI parts
• TypeScript owns the animation system

For example, the mail dialog is hydrated with client:load.

<div class="contact-links">
  <MailDialogTrigger client:load />
  <SocialLinks />
</div>

The dialog trigger itself is a React component.

export default function MailDialogTrigger() {
  const [isOpen, setIsOpen] = useState(false);

  useEffect(() => {
    if (!isOpen) return;

    const previousOverflow = document.body.style.overflow;
    document.body.style.overflow = "hidden";

    return () => {
      document.body.style.overflow = previousOverflow;
    };
  }, [isOpen]);

  // ...
}

This is a good use case for React.

There is local UI state.

There is user interaction.

There is a dialog.

But that does not mean the entire website needs to become a React application.

This was an important decision:

Using React does not mean everything has to be React.

React is great for UI.

But I did not want React to become responsible for the motion system.

---

🌊 Animation is controlled by TypeScript, not React state

The core animation logic lives under src/lib/nyaomaru/.

It handles things like:

• the walking character
• scene progression
• scroll-based state updates
• DOM measurement
• animation phases

Some of the main files are:

File	Responsibility
walker-controller.ts	Controls the main walker progression
work-scene.ts	Controls the work section scene
studio-scene.ts	Controls the studio section scene
contact-scene.ts	Controls the contact section scene

This is not a purely declarative animation system.

It is much more direct:

• read the current scroll position
• determine the active scene
• calculate progress
• calculate the pose
• update the DOM

A simplified version looks like this:

const update = () => {
  const scrollY = getSceneScrollY();
  const activeSceneState = getActiveSceneState(scrollY);

  if (!activeSceneState) return;

  const progress = getSceneProgress(scrollY, activeSceneState.snapshot);
  const pose = activeSceneState.scene.getPose(
    progress,
    activeSceneState.snapshot,
  );

  walker.style.transform = `translate(${pose.x}px, ${pose.y}px)`;
  walker.dataset.phase = pose.phase;
};

const requestUpdate = () => {
  cancelAnimationFrame(rafId);
  rafId = window.requestAnimationFrame(update);
};

The flow is simple:

1. read the scroll value
2. find the active scene
3. calculate progress
4. calculate the pose
5. apply it to the DOM

This was easier to tune than putting everything into React state.

React is strong for UI state.

But animation timing often needs a thinner, more direct control layer.

This does not mean React is bad for animation.

It only means that, for this project, the responsibilities were different:

• React was for UI
• TypeScript was for motion

That separation worked well.

---

💎 Why I did not avoid direct DOM manipulation

In modern frontend development, we often try to avoid direct DOM manipulation.

Usually, I agree with that direction.

Declarative UI is easier to reason about in many cases.

But scroll-driven animation is a little different.

Sometimes, the important state is not:

What state does this component have?

It is:

What is actually visible on the screen right now?

For this project, I needed to measure things like:

• getBoundingClientRect()
• viewport width
• which block is currently visible
• whether the desktop or mobile layout is active
• where the walker is currently positioned

This was similar to what I learned while building a browser game before:

Building a Browser Game with React: What Doesn’t work well (Run Away From Work)

nyaomaru

nyaomaru

nyaomaru

Follow

Apr 8

Building a Browser Game with React: What Doesn’t work well (Run Away From Work)

#gamedev #typescript #react #webdev

37 reactions

3 comments

6 min read

The animation depends on the actual layout.

So the DOM is not just an output target.

It is also something the animation system has to observe.

In this case, directly measuring the DOM made the intention clearer.

It also avoided unnecessary indirection.

So I did not avoid direct DOM manipulation completely.

I used it only where it made sense.

---

😿 Responsive design was not only a CSS problem

The site also supports mobile.

But responsive behavior here was not only about changing layout with CSS.

For several sections, I have different block structures for desktop and mobile.

For example, the hero, work, and studio sections have:

• desktop blocks
• mobile blocks

The visible block changes depending on the viewport.

The TypeScript animation logic also uses a 430px mobile breakpoint and changes things like scene progress, landing positions, and offsets.

const workStack = isMobileViewport()
  ? getVisibleElement("[data-work-mobile-origin]")
  : getVisibleElement("[data-work-scene-display]");

const stackRect = workStack.getBoundingClientRect();
const walkerRect = walker.getBoundingClientRect();

const shotX =
  walkerRect.right +
  (isMobileViewport() ? MOBILE_SHOT_OFFSET_X : SHOT_OFFSET_X);

The markup also separates desktop and mobile blocks.

<div class="block block-three block-three--desktop">...</div>
<div class="block block-three block-three--mobile">...</div>

So responsive design in this project affected:

• DOM structure
• scroll progression
• animation targets
• movement distance
• position correction

If I handled only the visual layout, the desktop version might feel good, but the mobile version would break quickly.

For scroll-driven animation, responsive design is not only layout adjustment.

It is also motion redesign.

---

📏 Why I used virtual scroll

One of the most important parts of this site is virtual scrolling.

The layout uses VirtualScroll.astro, and inside that layer, a custom scroll controller runs.

The goal was not just to make scrolling look fancy.

The real goal was to separate:

• visual scroll
• scene scroll
• scrollbar behavior
• smooth scroll following
• animation progression

In the implementation, I separate visualScrollY and sceneScrollY.

const applyScroll = () => {
  const visualScrollY = getVisualScrollY();
  const sceneScrollY = getSceneScrollY();

  content.style.top = `${-visualScrollY}px`;
  setScrollState({ sceneScrollY, visualScrollY });
  window.dispatchEvent(new CustomEvent("necoz:virtual-scroll"));
};

The scroll values are read like this:

export const getVisualScrollY = () => window.__necozScrollY ?? window.scrollY;

export const getSceneScrollY = (visualScrollY = getVisualScrollY()) =>
  window.__necozSceneScrollY ?? visualScrollY;

This separation was very important.

If everything depends directly on native scroll, it becomes harder to control the rhythm.

For example, I wanted to adjust cases like:

• the page visually moved down, but the scene should wait a little more
• the footer area needs denser animation
• mobile should use a different scroll progression
• some scenes should feel slower or more deliberate

With virtual scroll, I can separate:

how much the page visually moves

from:

how much the animation scene progresses

That means I can design the time axis myself.

This was the main reason I used virtual scroll.

Not because it looks cool.

But because I wanted control over animation time.

For scroll-driven animation, scroll is not just movement.

Scroll is input.

And if scroll is input, it needs to be designed carefully.

---

🤖 Where AI was useful

At this point, it might sound like I do not trust AI.

That is not true.

AI was very useful for:

• generating rough drafts
• trying implementation patterns
• splitting responsibilities
• getting something working quickly
• exploring ideas before committing to one direction

As a tool for the first step, AI is excellent.

But final animation tuning was different.

For example, walking, falling, and landing phases were separated like this:

export const lerp = (start: number, end: number, progress: number) =>
  start + (end - start) * progress;

if (progress > secondFallStart) {
  return {
    x: lerp(layout.secondFallX, layout.landingX, secondFallProgress),
    y: lerp(
      layout.secondRunY,
      layout.landingY,
      Math.pow(secondFallProgress, HERO_FALL_EASING_POWER),
    ),
    phase: "second-fall",
  };
}

if (progress > secondRunStart) {
  return {
    x: lerp(layout.firstFallX, layout.secondFallX, secondRunProgress),
    y: layout.secondRunY,
    phase: "second-run",
  };
}

This kind of adjustment required a repeated loop:

• look at the animation
• feel that something is slightly wrong
• adjust a function or a number
• check it again
• repeat

AI helped me move fast.

But speed alone was not enough.

For this kind of site, the character walks, the scene changes, and the rhythm follows the scroll.

The final feeling had to be adjusted by hand.

I think this is one of the areas where frontend engineers will still matter in the AI era.

Not only writing code faster.

But deciding whether the result actually feels good.

---

💖 What I learned from this architecture

The main lessons from this project are:

• separate HTML structure and animation behavior
• separate UI state and animation state
• treat scroll as input, not just movement
• responsive animation requires motion redesign, not only layout changes
• direct DOM measurement can be valid when the screen itself is part of the state
• AI is useful for speed, but timing and rhythm still need human judgment

For scroll-driven animation, this kind of separation made the system much easier to reason about.

---

🎯 Summary

For the Necoz B.V. website, I used:

• Astro for page structure and initial HTML
• React for small interactive UI parts
• TypeScript for the main animation control
• direct DOM measurement where needed
• responsive motion logic for desktop and mobile
• virtual scroll to redesign scroll progression

The biggest benefit was that I could keep SEO and initial rendering stable while still keeping control over the motion system.

AI helped a lot.

But there is still a gap between:

animation that moves

and:

animation that feels alive

So I did not let AI handle everything.

I used it to move faster, organize ideas, and create rough versions.

But I kept the final timing and rhythm in my own hands.

In the end, I think what I was really building was not just a layout or an animation.

I was designing time along the scroll.

Thanks for reading!

If you found this interesting, the repository is public.

A star ⭐ would make me very happy 😸

https://github.com/nyaomaru/necoz