The definitive guide — a Next.js site built around motion and scroll

High-end motion sites (the Awwwards kind) use 3 complementary layers, never a single library:

Optional: Three.js / React Three Fiber only if a 3D scene exists.

Excluded as redundant: Website Builder Setup (duplicates UI/UX Pro Max), Taste Skill (overlaps Impeccable + Design Motion Principles), Claude Design Skillstack (only if 3D enters the picture).

3.1 Create the Next.js project

If the project folder is empty (or holds only .claude\), create the app inside it. The trailing dot is essential for the skills and the project to land in the same folder:

cd C:\path\to\your\folder
npx create-next-app@latest .

Recommended answers in the installer:

If the Next.js project already exists: skip straight to 3.2.

3.2 Install the motion libraries

npm install gsap lenis motion

The skills teach Claude to use those libraries, but they install none of them. You do the installing.

3.3 Check

npm run dev

Open http://localhost:3000 and the default Next.js page should appear. The folder should hold, side by side:

your-project\
├── .claude\skills\      ← installed skills
├── app\                 ← Next.js pages
├── node_modules\
├── package.json         ← with gsap, lenis and motion listed
└── ...

The skills CLI installs into the project by default (the global scope is the one requiring -g, and you should never use it). Run all of it from inside the project folder:

cd C:\path\to\your\project

npx skills add greensock/gsap-skills --copy -a claude-code -y
npx skills add LottieFiles/motion-design-skill --copy -a claude-code -y
npx skills add kylezantos/design-motion-principles --copy -a claude-code -y
npx skills add emilkowalski/skills --copy -a claude-code -y
npx skills add vercel-labs/agent-skills --copy -a claude-code -y
npx skills add nextlevelbuilder/ui-ux-pro-max-skill --copy -a claude-code -y

npx impeccable install   # its own installer: pick Claude Code at the prompt

Flags:

• (no -g) → project scope: installs into .claude\skills\ in the current folder
• --copy → copies instead of symlinking (on Windows, a symlink can demand Developer Mode; a copy is committable to git)
• -a claude-code → for Claude Code alone, with no spillover to other agents
• -y → no interactive questions

Management afterward: npx skills list · npx skills update · npx skills remove [name]

Step 1 — Design foundation → Impeccable

Before invoking the skill, write the briefing. Save it as BRIEFING.md at the project root, holding:

• The basics: what the site is, its goal, its audience (and on which device they arrive), brand and tone of voice, sections and content
• Motion specifics: the personality of the movement (elegant and restrained? cinematic? playful?), 3–5 concrete visual references, each with the specific thing that pleases you in it, and anti-references (what you want to avoid)

Then invoke:

/impeccable init

Use the BRIEFING.md file as the basis for every answer in the interview.
If something is missing from the briefing, then ask me.

That generates PRODUCT.md and DESIGN.md, which every following skill respects. The more decisions you take in the briefing, the fewer the AI takes on its own in the code.

Step 2 — Design system and base screens → UI UX Pro Max

Build a landing page for [niche, goal, sections] using Next.js App Router

⚠️ Ask for everything static at this stage, with no animation yet. The react-best-practices skill (Vercel) already acts on its own to guarantee performant components.

Step 3 — The scroll foundation (MANDATORY: without it nothing animates)

This step was missing from the first version of the flow, and it is cause number 1 of "I followed everything and nothing animated". The 4 classic failure causes in Next.js:

1. Components without 'use client': animation runs in no Server Component
2. gsap.registerPlugin(ScrollTrigger) absent: nothing fires, with no visible error
3. Lenis and ScrollTrigger out of sync: triggers fire at the wrong moment or never
4. A missing useGSAP hook: animations break on navigation between pages

The foundation prompt (paste it into Claude Code):

Fix and set up the scroll animation foundation for this Next.js App Router project:
1. Create a client component "SmoothScrollProvider" that initializes Lenis in the root layout
2. Sync Lenis with GSAP ScrollTrigger properly: lenis.on('scroll', ScrollTrigger.update)
   and drive Lenis from gsap.ticker with lagSmoothing disabled
3. Register ScrollTrigger once in a shared gsap setup file
4. Install and use the @gsap/react useGSAP hook for all animation components
5. Verify every animation component has 'use client'
Then add a simple test: fade-in the first section heading on scroll, so I can confirm it works.

Test before continuing: the heading should fade in and the scroll should feel smooth, with inertia. Move on once it works and no sooner, because every animation depends on this base.

Step 4 — Where to animate → Skills for Design Engineers

find animation opportunities in this codebase

It returns where motion adds value and what should stay static, an antidote against animating everything.

Step 5 — Choreography → Motion Design Skill (LottieFiles)

Choreograph the entrance sequence for the hero section
Choreograph the scroll journey through the [features] section

It defines timing, easing and order, with no code yet. Ask it to save the result in a MOTION.md.

Step 6 — Implementation (the full catalog sits in section 6)

• Scroll → GSAP Skills (pinning, scrubbing, reveals, parallax…)
• Micro-interactions → Motion.dev Animations + Design Motion Principles (hover, modals, magnetic button, page transitions)

The rule: one animation at a time, test it in the browser, commit.

Step 7 — Audit (three passes, in this order)

improve the animations in this codebase          ← Emil Kowalski (8 categories)
Audit the motion design in this codebase          ← Design Motion Principles (anti-slop, HTML report)
/impeccable critique                              ← Impeccable
/impeccable polish

Step 8 — Accessibility and performance → Vercel Agent Skills

Review my UI and check accessibility
Review this codebase for React performance issues

It checks prefers-reduced-motion (mandatory on a site full of animation) and the 40+ performance rules.

Step 9 — Continuous guard

npx impeccable detect

Run it before each delivery (or in CI): it fails if design anti-patterns come back.

A prerequisite: Step 3 (the foundation) working. Implement in the order below, from the easy ones to the advanced.

Level 1 — Easy

Smooth scroll (Lenis): already handled by the Step 3 foundation.

Scroll-triggered reveal (fade/slide/zoom):

Add scroll-triggered reveal animations to all sections: elements fade up and in when entering
the viewport, with a subtle stagger between children. Use ScrollTrigger with toggleActions,
respect prefers-reduced-motion.

Scroll progress (a reading bar):

Add a thin scroll progress bar fixed at the top of the page that fills proportionally
to page scroll, using ScrollTrigger with scrub.

Infinite marquee:

Create an infinite marquee of [logos/text] that scrolls continuously and reacts to scroll:
it speeds up and reverses direction based on scroll velocity.

Level 2 — Scroll-linked (scroll as the timeline)

Scrubbing:

Create a scroll-linked animation for [section]: the timeline progress maps 1:1 to scroll
position using ScrollTrigger scrub: true. At 50% scroll the animation is at 50%.

Parallax:

Add parallax depth to the hero: background, midground and foreground layers move at
different speeds on scroll using ScrollTrigger scrub with different y distances per layer.

Zoom on scroll:

Make the [image/scene] scale from 1 to 1.4 linked to scroll position with
ScrollTrigger scrub, centered transform-origin.

Velocity/skew:

Add a velocity-based skew effect: images skew slightly based on scroll speed
(ScrollTrigger getVelocity), easing back to 0 when scrolling stops.

Level 3 — Structural

Pinning (sticky sections):

Pin the [section] to the viewport while its inner content animates through 3 steps as the
user scrolls, then release. Use ScrollTrigger pin: true with a scrubbed timeline —
make sure pinning works with Lenis.

Horizontal scroll:

Create a horizontally scrolling section: vertical scroll moves a row of [cards/panels]
horizontally. Pin the section, translate x with scrub, and set the scroll distance to
match the content width.

Text reveal (split text):

Animate the [headline] with SplitText: reveal line by line with a masked slide-up as it
enters the viewport. Split paragraph text word by word with a scrubbed opacity stagger.

(SplitText is free in GSAP today.)

Level 4 — Advanced (leave these for last)

Image sequence / canvas scrub (the Apple style): export the video as an image sequence first (120 JPG frames in public/sequence/, for example). Then:

Create an Apple-style canvas image sequence: preload the frames from /public/sequence/,
draw them to a canvas, and scrub through the frames with ScrollTrigger linked to a
pinned section.

Scrollytelling (pinning + scrubbing + text reveal composed together):

Build a scrollytelling section with 4 steps: the visual stays pinned while scroll advances
a master timeline; at each step the text block swaps and the [chart/scene] updates.
Use one scrubbed ScrollTrigger timeline with labels per step.

⚠️ Scroll snap: a conflict with Lenis

The native CSS scroll-snap-type fails to work alongside Lenis, since the two fight over control of the scroll. Use the official Lenis snap module:

Add section snapping using the official Lenis Snap module (lenis/snap), so scrolling
settles on each section — do NOT use CSS scroll-snap-type, it conflicts with Lenis.

If an animation "fails to happen":

This scroll animation isn't firing — check for missing 'use client', ScrollTrigger
registration, Lenis sync, and markers. Add ScrollTrigger markers temporarily to debug.

The markers: true option shows on screen where the triggers sit, and this is how you debug ScrollTrigger.

Golden rules:

1. One animation at a time → test it in the browser → commit. Asking for everything at once makes errors impossible to isolate.
2. Never skip Step 3 (the foundation), which is cause number 1 of "nothing animates".
3. After each block of animations, run improve the animations in this codebase.
4. A rich briefing means a result with no "AI look". A decision on paper beats a decision the AI takes in the code.
5. prefers-reduced-motion is no option: the skills handle it, but check it in the final audit.
6. A beautiful animation that stutters the scroll wins no award, because performance is part of motion.

• Smooth Scrolling in Next.js with Lenis & GSAP (2026)
• Best JavaScript Scroll Animation & Scrollytelling Libraries 2026
• GSAP vs Framer Motion
• Skills catalog: index-skills-02.html (Skills Hub)