Brief
Say what you want, who it is for and what the visitor should do. Name constraints: colours, fonts, no frameworks.
Level 1 · Foundations
01StartTools and setup02SkillsFind, install, write03PromptingBrief the AI04BuildSteps and full exampleLevel 2 · Motion
05MotionTechniques and recipes06PlaygroundLive experiments07GSAPTimelines and ScrollTrigger08WebGLThree.js and shaders09ExamplesFive portfolio projectsLevel 3 · Production
10Design systemsTokens and rules11ArchitectureStack, structure, cleanup12PerformanceFast on a real phone13Testing and QACheck before you ship14Production and launchPublish and maintainAppendix
15ReferenceFixes and termsTen steps from an empty folder to a finished page. Each has the prompt to paste and, where it matters, the code you should expect back.
Say what you want, who it is for and what the visitor should do. Name constraints: colours, fonts, no frameworks.
Let the AI write one piece at a time. Small pieces are easy to check and easy to undo.
Open the page. Scroll it, shrink it, tab through it. Ask the AI to say what it did not test, and look at that part yourself.
Describe the problem you saw, not the fix you imagine. Then inspect again.
A good brief names the subject, the audience and the one thing a visitor should do at the end. Ask for the section list first, and approve it before any code exists. Changing a list costs seconds. Changing finished code costs a lot more.
I want a minimalist cinematic scroll site about [subject] for [audience]. The visitor should finish by [one action]. Propose the sections, one line each, and wait for my approval before writing any code.You should see: a short list, no code yet.
Ask for three files and name the constraints. Constraints are what stop the result looking like every other template.
Create index.html, style.css and app.js using plain HTML, CSS and JavaScript, no framework. Black background, one accent colour, one pair of Google Fonts. Define all colours as CSS custom properties. Include a hero, three content sections, one call to action and a short footer.Refresh your local server page. You should see an unanimated but complete page.
Lenis gives the page inertia, so the wheel eases instead of stepping. It needs a doctype: without <!doctype html> the browser enters quirks mode and Lenis silently does nothing, which happened during this site’s own testing.
Add Lenis smooth scrolling from the jsDelivr CDN, pinned to lenis@1.1.18 and driven by requestAnimationFrame. Do not start it when prefers-reduced-motion is set.<script src="https://cdn.jsdelivr.net/npm/lenis@1.1.18/dist/lenis.min.js"></script>const reduced = matchMedia('(prefers-reduced-motion: reduce)').matches;
if (!reduced && typeof Lenis !== 'undefined') {
const lenis = new Lenis({ duration: 1.2, smoothWheel: true });
const raf = (t) => { lenis.raf(t); requestAnimationFrame(raf); };
requestAnimationFrame(raf);
}html.lenis, html.lenis body { height: auto; }
.lenis.lenis-smooth { scroll-behavior: auto !important; }Sections should arrive when you reach them, not all on page load. Hide elements only when JavaScript is present, so nothing stays invisible if the script fails.
Reveal every .reveal element once when it enters the viewport: opacity and a 24 px rise, staggered by 80 ms among siblings. Add the hidden state only under a .js class on the html element.document.documentElement.classList.add('js');
const io = new IntersectionObserver((entries) => {
entries.forEach((e) => {
if (e.isIntersecting) { e.target.classList.add('in'); io.unobserve(e.target); }
});
}, { threshold: 0.12 });
document.querySelectorAll('.reveal').forEach((el) => io.observe(el));.js .reveal { opacity: 0; transform: translateY(24px);
transition: opacity .9s, transform .9s cubic-bezier(.2,.7,.2,1); }
.js .reveal.in { opacity: 1; transform: none; }Parallax means background layers move more slowly than the foreground. Speeds between 0.15 and 0.5 read as depth. Past about 0.6 it looks like a bug.
Give the hero three background layers with data-speed 0.2, 0.35 and 0.5, moved with translate3d on scroll. Stop updating after 1.3 viewport heights. Reduce the offsets under 768 px instead of removing them.const layers = [...document.querySelectorAll('[data-speed]')];
addEventListener('scroll', () => {
const y = scrollY;
if (y > innerHeight * 1.3) return;
layers.forEach((l) => {
l.style.transform = `translate3d(0, ${y * (1 - l.dataset.speed)}px, 0)`;
});
}, { passive: true });Pin at most once per page. A horizontal scroll gallery is the classic choice: vertical scroll moves a row of cards sideways while the section stays in place. The wrapper’s height is the track overflow plus one screen.
Turn the six feature cards into one pinned horizontal scroll section. Set the wrapper height from the track width after fonts load and on resize, so scroll distance equals the overflow.const hs = document.querySelector('.hs'), pin = hs.querySelector('.hs-pin'), track = hs.querySelector('.hs-track');
let max = 0;
const measure = () => {
max = Math.max(0, track.scrollWidth - pin.clientWidth);
hs.style.height = (max + pin.offsetHeight) + 'px';
};
addEventListener('resize', measure); measure();
addEventListener('scroll', () => {
const p = Math.min(1, Math.max(0, (64 - hs.getBoundingClientRect().top) / max));
track.style.transform = `translate3d(${-p * max}px, 0, 0)`;
}, { passive: true });.hs-pin { position: sticky; top: 64px; height: calc(100vh - 64px); overflow: hidden; }
.hs-track { display: flex; width: max-content; }The visual stays fixed while text steps scroll past it, and the visual changes with the active step. This site’s scrollytelling is the four-stage loop at the top of this chapter.
Build a scrollytelling section: a sticky visual on the left that changes with the active step, and four text steps on the right. On screens under 900 px, stack them with the visual sticky at the top..scrolly { display: grid; grid-template-columns: 1.1fr .9fr; gap: 56px; align-items: start; }
.scrolly-vis { position: sticky; top: 120px; height: 60vh; }
.step { min-height: 72vh; opacity: .3; transition: opacity .5s; }
.step.on { opacity: 1; }const steps = [...document.querySelectorAll('.step')];
addEventListener('scroll', () => {
let best = 0, bd = Infinity;
steps.forEach((s, i) => {
const r = s.getBoundingClientRect();
const d = Math.abs(r.top + r.height / 2 - innerHeight / 2);
if (d < bd) { bd = d; best = i; }
});
steps.forEach((s, i) => s.classList.toggle('on', i === best));
showVisual(best);
}, { passive: true });Optional, and heavier than everything above. It costs download size and battery on phones. Ask for the cost before agreeing. Cap the pixel ratio, pause when off screen, and reduce the particle count on small screens.
Add a Three.js particle hero using the cdnjs build pinned to an exact version. Sample the points from an image drawn to a canvas. Cap pixel ratio at 2, halve the count under 768 px, and pause rendering when the hero is off screen. Tell me what you could not test.Check three widths: 375, 768 and 1440 px. Then turn on reduced motion. It has to switch off smooth scrolling, parallax and the reveal movement, not only one of them.
Check the page at 375, 768 and 1440 px and list anything overlapping, clipped or unreadable. Make prefers-reduced-motion disable smooth scroll, parallax and reveal movement. Add a skip link, visible focus styles and aria-current on the active menu item.Ask for a harsh review, then fix the three worst problems, then review again. Two rounds beat one long prompt.
Act as a strict art director. Score the page 1 to 10 for hierarchy, pacing and mobile readability. List the three worst problems with where they are, fix them, and score again. Say which checks you could not run.Prompts use the project you filled in at step 01. Replace anything else in square brackets. More load as you scroll.
This is a finished, working site you can run now. It was opened in a headless Chromium window and scrolled from top to bottom: the smooth scroll class was applied, the parallax layers moved, all twenty words lit up, all six reveals fired, the gallery translated by its full width, and the console stayed empty. Save the three files in one folder and serve it with python3 -m http.server 8000.
Six sections in normal flow. Only the word section and the gallery are pinned.
<!doctype html>
<html lang="en-GB">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Northlight</title>
<link rel="stylesheet" href="style.css">
</head>
<body>
<div class="progress" id="progress"></div>
<header class="bar">
<a class="logo" href="#top">Northlight</a>
<nav><a href="#features">Features</a><a href="#gallery">Gallery</a><a href="#contact">Contact</a></nav>
</header>
<main id="top">
<section class="hero">
<div class="layer far" data-speed="0.2"></div>
<div class="layer mid" data-speed="0.4"></div>
<div class="hero-copy">
<p class="eyebrow">A sample site</p>
<h1>Light that follows the long winter.</h1>
<p class="lede">A small demonstration of smooth scroll, parallax, word-by-word text and a pinned horizontal gallery.</p>
<a class="btn" href="#features">Scroll on</a>
</div>
</section>
<section class="words">
<div class="words-pin">
<p id="statement">Every section on this page moves with your scroll position, so the pace of the story is yours to set.</p>
</div>
</section>
<section class="features" id="features">
<h2 class="reveal">Three things this page does</h2>
<div class="cards">
<article class="card reveal" style="--d:0"><h3>Smooth scroll</h3><p>Lenis adds inertia and keeps native scrolling, focus and anchors working.</p></article>
<article class="card reveal" style="--d:1"><h3>Depth</h3><p>Background layers move more slowly than the page, which separates them from the text.</p></article>
<article class="card reveal" style="--d:2"><h3>Pacing</h3><p>Content arrives as it enters the viewport and stays visible when you scroll back.</p></article>
</div>
</section>
<section class="hs" id="gallery">
<div class="hs-pin">
<h2>Gallery</h2>
<div class="hs-track">
<figure><span>01</span><figcaption>Dawn</figcaption></figure>
<figure><span>02</span><figcaption>Ridge</figcaption></figure>
<figure><span>03</span><figcaption>Harbour</figcaption></figure>
<figure><span>04</span><figcaption>Aurora</figcaption></figure>
<figure><span>05</span><figcaption>Dusk</figcaption></figure>
</div>
</div>
</section>
<section class="cta" id="contact">
<h2 class="reveal">Start with an empty folder.</h2>
<a class="btn reveal" href="#top">Back to the top</a>
</section>
</main>
<footer><span>Northlight</span><span>A tutorial example, not a real business.</span></footer>
<script src="https://cdn.jsdelivr.net/npm/lenis@1.1.18/dist/lenis.min.js"></script>
<script src="app.js"></script>
</body>
</html>Colour tokens at the top. The pinned sections use position: sticky inside a taller parent, so the browser does the pinning.
:root {
--bg: #0b0d10; --fg: #eef2f5; --muted: #98a3ad; --line: #232a31; --accent: #7cc4ff;
--pad: clamp(20px, 5vw, 64px);
--bar: 64px;
}
* { box-sizing: border-box; }
html { background: var(--bg); }
body { margin: 0; background: var(--bg); color: var(--fg); font: 400 17px/1.6 system-ui, sans-serif; overflow-x: clip; }
html.lenis, html.lenis body { height: auto; }
.lenis.lenis-smooth { scroll-behavior: auto !important; }
a { color: inherit; }
h1, h2, h3 { font-weight: 500; line-height: 1.08; margin: 0; text-wrap: balance; }
h1 { font-size: clamp(40px, 8vw, 112px); letter-spacing: -0.03em; }
h2 { font-size: clamp(30px, 5vw, 64px); letter-spacing: -0.02em; }
.progress { position: fixed; inset: 0 0 auto 0; height: 2px; background: var(--accent); transform-origin: 0 50%; transform: scaleX(0); z-index: 30; }
.bar { position: fixed; inset: 0 0 auto 0; height: var(--bar); display: flex; justify-content: space-between; align-items: center; padding: 0 var(--pad); z-index: 20; mix-blend-mode: difference; }
.bar nav { display: flex; gap: 24px; }
.bar a { text-decoration: none; font-size: 14px; }
.logo { font-weight: 500; letter-spacing: .02em; }
.btn { display: inline-block; margin-top: 28px; padding: 14px 22px; border: 1px solid var(--line); text-decoration: none; transition: border-color .2s; }
.btn:hover, .btn:focus-visible { border-color: var(--accent); }
.hero { position: relative; min-height: 100svh; display: grid; align-items: end; padding: var(--pad); overflow: hidden; }
.layer { position: absolute; inset: -20% 0; background-repeat: repeat; will-change: transform; }
.layer.far { background-image: radial-gradient(circle, rgba(124,196,255,.35) 1px, transparent 1.5px); background-size: 90px 90px; }
.layer.mid { background-image: radial-gradient(circle, rgba(238,242,245,.5) 1.5px, transparent 2px); background-size: 170px 170px; }
.hero-copy { position: relative; max-width: 960px; padding-bottom: 8vh; }
.eyebrow { color: var(--accent); font: 500 12px/1 ui-monospace, monospace; letter-spacing: .14em; text-transform: uppercase; }
.lede { color: var(--muted); max-width: 52ch; }
.words { height: 220vh; position: relative; }
.words-pin { position: sticky; top: 0; height: 100svh; display: grid; place-items: center; padding: var(--pad); }
#statement { font-size: clamp(26px, 4.4vw, 60px); line-height: 1.2; max-width: 22em; margin: 0; }
#statement .w { opacity: .38; transition: opacity .15s linear; }
.features { padding: 20vh var(--pad); }
.cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(240px, 1fr)); gap: 16px; margin-top: 48px; }
.card { border: 1px solid var(--line); padding: 28px; }
.card p { color: var(--muted); margin: 12px 0 0; }
.js .reveal { opacity: 0; transform: translateY(24px); transition: opacity .9s cubic-bezier(.2,.7,.2,1), transform .9s cubic-bezier(.2,.7,.2,1); transition-delay: calc(var(--d, 0) * 100ms); }
.js .reveal.in { opacity: 1; transform: none; }
.hs { position: relative; }
.hs-pin { position: sticky; top: 0; height: 100svh; display: flex; flex-direction: column; justify-content: center; gap: 32px; overflow: hidden; padding-left: var(--pad); }
.hs-track { display: flex; gap: 16px; width: max-content; will-change: transform; }
.hs figure { margin: 0; width: min(70vw, 520px); aspect-ratio: 4 / 5; border: 1px solid var(--line); display: flex; flex-direction: column; justify-content: space-between; padding: 20px; background: linear-gradient(160deg, #141a20, #0b0d10); }
.hs figure span { font: 500 12px/1 ui-monospace, monospace; color: var(--accent); }
.hs figcaption { font-size: 28px; }
.cta { min-height: 80svh; display: grid; place-content: center; justify-items: start; padding: var(--pad); }
footer { display: flex; justify-content: space-between; gap: 16px; flex-wrap: wrap; padding: 32px var(--pad); border-top: 1px solid var(--line); color: var(--muted); font-size: 14px; }
@media (prefers-reduced-motion: reduce) {
.js .reveal { opacity: 1; transform: none; transition: none; }
#statement .w { opacity: 1; }
.layer { transform: none !important; }
}Smooth scroll, reveals, scroll-driven words, parallax and the gallery, in about seventy lines. One scroll handler does the maths.
(function () {
var reduced = matchMedia('(prefers-reduced-motion: reduce)').matches;
var clamp = function (v, a, b) { return Math.min(b, Math.max(a, v)); };
document.documentElement.classList.add('js');
/* 1. Smooth scroll */
var lenis = null;
if (!reduced && window.Lenis) {
lenis = new Lenis({ lerp: 0.1 });
(function raf(t) { lenis.raf(t); requestAnimationFrame(raf); })(performance.now());
}
document.addEventListener('click', function (e) {
var a = e.target.closest('a[href^="#"]');
if (!a) return;
var target = document.querySelector(a.getAttribute('href'));
if (!target) return;
e.preventDefault();
if (lenis) lenis.scrollTo(target, { offset: -64 }); else target.scrollIntoView();
});
/* 2. Reveal on scroll */
var io = new IntersectionObserver(function (list) {
list.forEach(function (en) { if (en.isIntersecting) { en.target.classList.add('in'); io.unobserve(en.target); } });
}, { threshold: 0.15 });
document.querySelectorAll('.reveal').forEach(function (el) { io.observe(el); });
/* 3. Scroll-driven words */
var statement = document.getElementById('statement');
var words = statement.textContent.trim().split(/\s+/);
statement.innerHTML = words.map(function (w) { return '<span class="w">' + w + '</span>'; }).join(' ');
var wEls = statement.querySelectorAll('.w');
var wrap = document.querySelector('.words');
/* 4. Parallax and horizontal pin */
var layers = document.querySelectorAll('.layer');
var hs = document.querySelector('.hs'), track = document.querySelector('.hs-track'), pin = document.querySelector('.hs-pin');
var maxX = 0;
function measure() {
maxX = Math.max(0, track.scrollWidth - (pin.clientWidth - parseFloat(getComputedStyle(pin).paddingLeft)));
hs.style.height = (maxX + pin.clientHeight) + 'px';
}
var bar = document.getElementById('progress');
function frame() {
var y = window.scrollY, vh = window.innerHeight;
bar.style.transform = 'scaleX(' + clamp(y / (document.documentElement.scrollHeight - vh), 0, 1) + ')';
if (reduced) return;
if (y < vh * 1.3) layers.forEach(function (l) { l.style.transform = 'translate3d(0,' + (y * (1 - parseFloat(l.dataset.speed))) + 'px,0)'; });
var r = wrap.getBoundingClientRect();
var p = clamp(-r.top / (r.height - vh), 0, 1);
wEls.forEach(function (w, i) {
w.style.opacity = (0.38 + 0.62 * clamp((p - 0.1 - (i / wEls.length) * 0.7) / 0.06, 0, 1)).toFixed(3);
});
var h = hs.getBoundingClientRect();
var hp = clamp(-h.top / (hs.offsetHeight - vh), 0, 1);
track.style.transform = 'translate3d(' + (-hp * maxX) + 'px,0,0)';
}
addEventListener('scroll', frame, { passive: true });
addEventListener('resize', function () { measure(); frame(); });
if (document.fonts && document.fonts.ready) document.fonts.ready.then(function () { measure(); frame(); });
measure(); frame();
})();One prompt per step keeps every change small enough to check. The review prompt at the end looks at the page as a whole.
Open a terminal in the project folder and run claude. Press Shift+Tab until plan mode is on, paste the prompt, read the plan, then approve it. Project rules go in CLAUDE.md.
Read CLAUDE.md, brief.md and plan.md. Do step [number] only: [the step]. Change as few lines as possible, then tell me exactly how to check it in the browser, and what you did not check.Act as an art director. Look at the page at 375 and 1440 pixels wide and list the five changes that would make it feel calmer and more deliberate, ranked by impact. Do not change anything yet.Open a terminal in the project folder and run gemini; the first time, it asks whether you trust the folder, so say yes for your project. Paste the prompt. Gemini CLI asks before it edits a file or runs a command: read each request before you accept it. Project rules go in GEMINI.md.
Read GEMINI.md, brief.md and plan.md. Do step [number] only: [the step]. Change as few lines as possible, then tell me exactly how to check it in the browser, and what you did not check.Act as an art director. Look at the page at 375 and 1440 pixels wide and list the five changes that would make it feel calmer and more deliberate, ranked by impact. Do not change anything yet.Open a terminal in the project folder and run codex, then paste the prompt and approve each change. In the ChatGPT app without Codex, attach the files, paste the prompt and copy the changes back yourself. Project rules go in AGENTS.md.
Read AGENTS.md, brief.md and plan.md. Do step [number] only: [the step]. Change as few lines as possible, then tell me exactly how to check it in the browser, and what you did not check.Act as an art director. Look at the page at 375 and 1440 pixels wide and list the five changes that would make it feel calmer and more deliberate, ranked by impact. Do not change anything yet.Split “Add a pinned product section with three features” into changes small enough to check one at a time.
Hint: markup, layout, behaviour, then the still and phone versions.
1. Markup for the section and its three features. 2. The sticky layout. 3. The script that picks the active feature. 4. The reduced-motion version, where the features simply stack. 5. The phone layout. Check and commit after each.
In Chrome DevTools, record a Performance profile while you scroll the hero. Find what runs on every frame.
Hint: long yellow blocks are JavaScript, purple ones are layout.
A parallax that changes top or margin forces layout on every frame. Move it with transform: translate3d() instead, read the scroll position once per frame, and stop the work once the hero has left the screen.
Turn on reduced motion in your system settings and scroll the whole page.
Hint: macOS: Accessibility, Display. Windows: Accessibility, Visual effects, Animation effects off.
Smooth scrolling stops, parallax layers stay put, reveals appear without moving, and the pinned section reads as a normal list. Anything that still moves needs its own prefers-reduced-motion rule.
Now the course project gets its page. Work through the ten steps of this chapter for [subject], one prompt each.
git add -A
git commit -m "Step 4: reveal on scroll"reveal class is visible once you have scrolled past it.// paste into the Console after scrolling to the bottom:
// lists every reveal that never appeared (an empty list is a pass)
[...document.querySelectorAll('.reveal:not(.in)')].map((el) => el.textContent.trim().slice(0, 40));0 of 4 criteria met