Project 2: Lost in the Scroll Project

Project 2: Lost in the Scroll

project-2-brief.md

Project 2: Lost in the Scroll

Theme: Teaching Through Story Question: Can you explain what you learned by telling a story about it? Weight: 50% of course grade Due: Week 10 (Final Presentations)

Overview

You're building a scrollytelling site — a single-page narrative that traces your JavaScript learning journey through a personal metaphor. This isn't a tutorial. It's not a blog post. It's a designed, animated, scroll-driven story that makes someone who's never written code understand what it felt like to learn.

Every concept you've learned this quarter — variables, events, classList, design tokens, localStorage — becomes a chapter in your story. Every animation technique you learn over the next five weeks — CSS transitions, GSAP timelines, ScrollTrigger — becomes part of how you tell it.

The metaphor is yours. The story is yours. The scroll is your medium.

Chapters vs. Tools

Not every concept needs its own section. Some are transformative "aha" moments worth a full chapter. Others are techniques you'll use along the way.

Chapters (The Story Beats)

These are the transformative moments — what it felt like to learn.

Note: These are working titles. Use them as-is or rename them to fit your metaphor.

Chapter	Concept	The Moment
First Contact	console.log, DevTools	"I can talk to the browser"
Naming Things	Variables (let, const)	"I can hold and name things"
The Switch	Conditionals, classList	"I can make the page respond"
Listening	Events, addEventListener	"I can react to the user"
The System	Design tokens, CSS custom properties	"I see the pattern now"
The Memory	localStorage	"Things can persist"
The Scroll	ScrollTrigger, scroll-driven motion	"The page itself is the interaction"

Tools Along the Way

These are techniques used to accomplish chapters — not their own story beats.

document.querySelector — how you grab things
documentElement — the root for theming
matchMedia / prefers-color-scheme / prefers-reduced-motion — detecting preferences
dataset / data-* — storing state in HTML
CSS transitions, @keyframes — foundational motion
GSAP syntax (gsap.to, timeline) — the animation tool
SVGs — visual assets
Figma variables — where tokens come from

Pick 5–7 chapters for your story. Use the tools as needed to build them.

What You're Building

A personal metaphor — A framing device that maps code concepts to something you already understand
A design system — Figma variables, tokens, exported to CSS custom properties
A scrollytelling site — 5–7 scroll sections, each chapter explaining a concept through your metaphor
CSS motion — Transitions and keyframes for foundational animation
GSAP animations — Timelines with intentional easing for entrance sequences
ScrollTrigger — Scroll-driven reveals, at least one scrubbed animation
A pinned section — Your "showpiece" moment where scroll controls the narrative
Accessibility — prefers-reduced-motion alternative, keyboard navigation, semantic HTML

Requirements

The Metaphor

Choose a metaphor that maps JS concepts to something personal
Each section connects a code concept to a chapter in your metaphor
A non-coder could follow the story without understanding the code
The metaphor is consistent — it doesn't break or shift mid-story

Design System

Figma design with all sections designed before coding
Figma variables: color primitives, semantic tokens, typography, spacing
Exported to tokens.css with CSS custom properties
Tokens used consistently throughout the site (no hardcoded values)

Content & Structure

5–7 scroll sections, each covering a JS concept
Real, written content (not placeholder text)
Visual assets that support the metaphor (illustrations, photos, icons)
Clear narrative arc: beginning → development → resolution

CSS Motion (Week 6)

CSS transitions on interactive elements (hover, focus)
At least one @keyframes animation (hero entrance or repeating element)
Performant properties used (transform, opacity)

GSAP Animation (Week 7)

GSAP loaded via CDN
gsap.to() or gsap.from() used for entrance animations
At least one gsap.timeline() sequencing 3+ elements
At least 2 different easing values that match your story's tone

ScrollTrigger (Week 8)

ScrollTrigger plugin loaded and registered
All sections have scroll-triggered animations
At least one section uses scrub for progress-linked animation
Start/end points are calibrated (tested, not default)

Advanced Scroll (Week 9)

At least one pinned section (your showpiece moment)
Peer review completed and feedback addressed
Deployed to GitHub Pages

Accessibility

prefers-reduced-motion check wraps all GSAP animations
Content is fully readable with animations disabled
Keyboard navigable (Tab through all interactive elements)
Semantic HTML (proper heading hierarchy, landmarks)
Color contrast passes WCAG AA on all token pairs
Focus states visible

Metaphor Options

Choose one of these or discover your own:

1. The Kitchen

Variables are ingredients. Functions are recipes. Events are timers going off. Conditionals are taste tests. The design system is your mise en place — everything in its place before you cook.

2. The Garden

Variables are seeds. The DOM is soil. Events are weather. Conditionals are seasons. localStorage is the root system that persists underground even when nothing is visible above.

3. The Map

Each concept is a landmark on a journey. The switch is a fork in the road. Tokens are the legend. Scroll is the path you walk.

4. The Mixtape

Each concept is a track on a mixtape. Variables are samples. Events are drops. Conditionals are bridges between sections. The design system is the album art system that ties it all together visually.

Discover Your Own

Use this prompt with an LLM (ChatGPT, Claude, etc.):

"I'm a design student learning JavaScript for the first time. I've learned about variables, events, conditionals, classList, localStorage, and design tokens. I need a metaphor that maps these programming concepts to something I already understand well — something from my life, hobbies, or interests. The metaphor should feel personal, not generic. Ask me about my interests and help me find one that fits."

The test: Can your partner explain your metaphor back to you after hearing it once? If not, simplify.

Progressive Build Schedule

You build this project over 5 weeks. Each week adds a layer:

Week	Focus	You Add
5	The Blueprint	Metaphor, Figma design, design system, tokens.css
6	The Rough Cut	HTML/CSS structure, content, CSS transitions
7	The Pulse	GSAP animations on 3+ sections, all content written
8	The Scroll	ScrollTrigger on all sections, scrub on 1+
9	The Deep	Pinned section, peer review, polish, deploy
10	The Showcase	Final submission + presentation

Weekly milestones are checked but not graded separately. The final rubric evaluates the complete site.

Evaluation

Criteria	Weight	What We're Looking For
Story & Metaphor	25%	Does the metaphor work? Is the story clear, personal, engaging? Would a non-coder understand the journey?
Interaction & Motion	30%	Does scroll pacing feel right? Do animations support narrative? Is there a showpiece? Does easing have personality?
Technical Execution	25%	GSAP + ScrollTrigger correct? Tokens consistent? No major bugs? Deployed?
Accessibility	20%	Reduced-motion alternative? Keyboard navigable? Color contrast? Semantic HTML?

Exemplary Work

The metaphor is original and illuminating — it makes code make sense
Scroll pacing feels cinematic — you want to keep scrolling
Animations serve the story, not the other way around
Technically clean — no console errors, smooth performance
Accessible by default — reduced motion, keyboard, contrast all handled

Common Pitfalls

Metaphor is too literal ("variables are like boxes") — go deeper, make it personal
Animation overload — every element doesn't need to animate
Content is an afterthought — the story IS the project, not the animation
Scroll pacing too fast — test: can someone read the text before it scrolls away?
Pinned section breaks layout — test at multiple viewport sizes
Forgetting prefers-reduced-motion — add it the same day you add GSAP

Submission

Deploy to GitHub Pages
Submit the live URL to Canvas
Link from your portfolio (navigation or projects page)
Ensure repository is public
Present in Week 10 (5–7 minutes):
- Live scroll-through demo
- Explain your metaphor
- Walk through ONE section's code
- What surprised you?
- What would you add with more time?

The desk critique test applies: Be ready to explain any line of code in your project.

Starter Structure

the-thread/
├── index.html
├── styles/
│   ├── tokens.css        ← design tokens (load first)
│   ├── layout.css         ← section structure, grid
│   └── animations.css     ← motion styles
├── scripts/
│   └── main.js            ← GSAP + ScrollTrigger logic
├── assets/
│   ├── images/            ← visual assets for your story
│   └── svg/               ← any SVG graphics
└── README.md

Connection to Course

This project synthesizes everything you've learned:

From Week 0: DevTools, console — you'll explain these in your story
From Week 1: Variables, events — chapters in your narrative
From Week 2: The Switch, tokens, localStorage — the heart of the story
From Week 3: Persistence, preferences — the deeper meaning
From Week 4: SVG — visual assets for your sections
New (Weeks 5–9): Design systems in Figma, CSS motion, GSAP, ScrollTrigger — how you tell the story

Everything connects. Nothing is throwaway.

Stretch Goals

For students who want to push further:

Horizontal scroll section
Parallax backgrounds with depth layers
Progress indicator linked to scroll position
Dynamic text reveals (words appearing as you scroll)
Dark/light mode toggle integrated into the scrollytelling site
Sound design (ambient audio that responds to scroll position)
Mobile-optimized scroll experience

Resources

ScrollTelling Inspiration

The Pudding — Data-driven visual essays
NYT Snow Fall — The original scrollytelling piece
Apple AirPods Pro — Product storytelling through scroll

GSAP & ScrollTrigger

GSAP Getting Started — Official docs
ScrollTrigger Docs — Plugin reference
GSAP Easing Visualizer — Find your easing personality

Design Systems

Open Props — Token system reference
Figma Variables Guide — Official Figma docs

Accessibility

web.dev: prefers-reduced-motion — Motion accessibility
MDN: Semantic HTML — Structure reference

Project Brief: Lost in the Scroll

short-brief.md

Project Brief: Lost in the Scroll

Theme: Teaching Through Story Question: Can you explain what you learned by telling a story about it? Weight: 50% of course grade Due: Week 10 (Final Presentations)

The Idea

You're building a scrollytelling site — a single-page narrative that traces your JavaScript learning journey through a personal metaphor.

This isn't a tutorial or a blog post. It's a designed, animated, scroll-driven story that makes someone who's never written code understand what it felt like to learn.

Every concept you've learned this quarter — variables, events, classList, design tokens, and localStorage — becomes a chapter in your story. Every animation technique you learn over the next five weeks — CSS transitions, GSAP timelines, ScrollTrigger — becomes part of how you tell it.

The metaphor is yours. The story is yours. The scroll is your medium.

Chapters vs. Tools

Not every concept needs its own section. Some are transformative "aha" moments worth a full chapter. Others are techniques you'll use along the way.

Chapters (The Story Beats)

These are the transformative moments — what it felt like to learn.

Note: These are working titles. Use them as-is or rename them to fit your metaphor.

Chapter	Concept	The Moment
First Contact	console.log, DevTools	"I can talk to the browser"
Naming Things	Variables (let, const)	"I can hold and name things"
The Switch	Conditionals, classList	"I can make the page respond"
Listening	Events, addEventListener	"I can react to the user"
The System	Design tokens, CSS custom properties	"I see the pattern now"
The Memory	localStorage	"Things can persist"
The Scroll	ScrollTrigger, scroll-driven motion	"The page itself is the interaction"

Tools Along the Way

These are techniques used to accomplish chapters — not their own story beats.

document.querySelector — how you grab things
documentElement — the root for theming
matchMedia / prefers-color-scheme / prefers-reduced-motion — detecting preferences
dataset / data-* — storing state in HTML
CSS transitions, @keyframes — foundational motion
GSAP syntax (gsap.to, timeline) — the animation tool
SVGs — visual assets
Figma variables — where tokens come from

Pick 5–7 chapters for your story. Use the tools as needed to build them.

What You're Making

A personal metaphor — a framing device that maps code concepts to something you already understand
A design system — Figma variables and tokens exported to CSS custom properties
A scrollytelling site — 5–7 scroll sections, each chapter explaining a concept through your metaphor
Motion that serves the story — CSS transitions, GSAP timelines, and ScrollTrigger animations
An accessible experience — reduced-motion support, keyboard navigation, semantic HTML

How We'll Build It

You build this over five weeks. Each week adds one layer:

Week	Focus	What You Add
5	The Blueprint	Metaphor, Figma design, design system, tokens.css
6	The Rough Cut	HTML/CSS structure, content, CSS transitions
7	The Pulse	GSAP animations, all content written
8	The Scroll	ScrollTrigger on all sections, scrub on 1+
9	The Deep	Pinned section, peer review, polish, deploy
10	The Showcase	Final submission + presentation

Each week has its own brief with specific deliverables. Weekly milestones are checked but not graded separately — the final rubric evaluates the complete site.

Finding Your Metaphor

Your metaphor maps JavaScript concepts to something you already know well. Here are some starting points:

The Kitchen — Variables are ingredients. Functions are recipes. Events are timers going off. Conditionals are taste tests. The design system is your mise en place.

The Garden — Variables are seeds. The DOM is soil. Events are weather. Conditionals are seasons. localStorage is the root system that persists underground.

The Map — Each concept is a landmark on a journey. The switch is a fork in the road. Tokens are the legend. Scroll is the path you walk.

The Mixtape — Each concept is a track. Variables are samples. Events are drops. Conditionals are bridges. The design system is the album art that ties it together.

Discover Your Own — Use this prompt with an LLM:

"I'm a design student learning JavaScript for the first time. I've learned about variables, events, conditionals, classList, localStorage, and design tokens. I need a metaphor that maps these programming concepts to something I already understand well — something from my life, hobbies, or interests. The metaphor should feel personal, not generic. Ask me about my interests and help me find one that fits."

The test: Can your partner explain your metaphor back to you after hearing it once? If not, simplify.

Evaluation

Criteria	Weight	What We're Looking For
Story & Metaphor	25%	Does the metaphor work? Is the story clear, personal, engaging? Would a non-coder follow the journey?
Interaction & Motion	30%	Does scroll pacing feel right? Do animations support narrative? Is there a showpiece? Does easing have personality?
Technical Execution	25%	GSAP + ScrollTrigger correct? Tokens consistent? No major bugs? Deployed?
Accessibility	20%	Reduced-motion alternative? Keyboard navigable? Color contrast? Semantic HTML?

What Exemplary Work Looks Like

The metaphor is original and illuminating — it makes code make sense
Scroll pacing feels cinematic — you want to keep scrolling
Animations serve the story, not the other way around
Technically clean — no console errors, smooth performance
Accessible by default — reduced motion, keyboard, contrast all handled

Starter Structure

lost-in-the-scroll/
├── index.html
├── styles/
│   ├── tokens.css        ← design tokens (load first)
│   ├── layout.css         ← section structure, grid
│   └── animations.css     ← motion styles
├── scripts/
│   └── main.js            ← GSAP + ScrollTrigger logic
├── assets/
│   ├── images/            ← visual assets for your story
│   └── svg/               ← any SVG graphics
└── README.md

Final Submission (Week 10)

Deploy to GitHub Pages
Submit the live URL to Canvas
Link from your portfolio (navigation or projects page)
Ensure the repository is public
Present in Week 10 (5–7 minutes):
- Live scroll-through demo
- Explain your metaphor
- Walk through ONE section's code
- What surprised you?
- What would you add with more time?

The desk critique test applies: be ready to explain any line of code in your project.

Resources

Scrolltelling Inspiration: The PuddingLinks to an external site.

NYT Snow FallLinks to an external site.

Apple AirPods ProLinks to an external site.

Design Systems: Open PropsLinks to an external site.

Figma Variables GuideLinks to an external site.

Accessibility: web.dev: prefers-reduced-motionLinks to an external site.

MDN: Semantic HTMLLinks to an external site.

Start Here

student-hub/01-start-here.md

Start Here

Primary Resource

GSAP Scroll

Use this as your reference for scroll-driven motion patterns.

Why We Are Using Issues

Creating issues is part of the development process used on real teams.

For this project, issues are used to:

break a large project into manageable tasks
make progress visible over time
document blockers and debugging attempts
create clear proof of what was completed

You are not making issues as extra paperwork. You are practicing production workflow.

What To Do First

Step 1: Run the Issue Setup Automation

In your GitHub repo, click the Actions tab.
Open Setup Project Issues.
Click Run workflow.
Enter your name exactly as you want it to appear in issue titles.
Leave mode set to create_missing.
Run the workflow and wait for the summary.

Step 2: Review the Created Issues

Open the Issues tab.
Confirm the workflow created:
- Project 2 Master Checklist
- Story + Structure
- GSAP Motion Foundation
- ScrollTrigger Core
- Pinned Showpiece
- ScrollSmoother Setup
- Tokens + Theme Modes
- Assets + Accessibility + QA
- Reflection + README + Submission
Open the master issue and confirm the sub-issue numbers are linked.

Step 3: Use the Automation Again If You Need To Sync Open Issues

If the template issue bodies change later and your issues are still open:

Go back to Actions.
Run Setup Project Issues again.
Change mode to sync_open.
Review the updated issue bodies before you continue.

If GitHub Actions is unavailable in your repo, use manual issue creation from the templates instead.

If you want to use a coding agent, improve each open issue before you start coding. First time? Follow the step-by-step first run; then use Working with Coding Agents as your reference.

Step 4: Start Building

Build your project using Project Structure Suggestion.
Work through sub-issues one at a time.
Close each sub-issue when complete.
Check off the matching line in your master issue.

Step 5: Final Verification

Validate your work against Final Turn-In Spec.
Submit your links in Canvas.

Rule Of Focus

Complete Required items first.
Do not add stretch effects until required items are stable.

Final Turn-In Specification

student-hub/03-final-turn-in-spec.md

Final Turn-In Specification

This is the final completion contract for Project 2.

1) Required Submission Links

Students must submit:

Live GitHub Pages URL
Public GitHub repository URL

Recommended:

Portfolio page URL that links to this project

The README (in the repo) contains your project documentation and reflection; graders read it there.

Issue tracking must also be complete before final turn-in:

All required Project 2 sub-issues are closed
Project 2 Master Checklist is up to date and fully checked off

2) Core Build Requirements

Story + Structure

6-8 total sections
At least 5 JavaScript concepts represented
Complete written narrative

ScrollTrigger

Reference:

ScrollTrigger Docs
8+ total ScrollTrigger instances
5+ trigger-and-play reveals
2+ scrubbed interactions
1+ pinned showpiece section
Pinned showpiece includes 3+ internal animation steps

ScrollSmoother

Reference:

ScrollSmoother Docs
One global ScrollSmoother setup with wrapper/content structure
Smooth value tuned for readability
2+ smoother-enhanced moments
Disabled or bypassed for reduced-motion users

If ScrollSmoother is unavailable:

Instructor-approved alternative scroll-feel implementation

GSAP Motion

References:

GSAP Core Docs
GSAP Timeline Docs
10+ intentional GSAP tweens
2+ GSAP timelines
2+ distinct easing choices used intentionally
Majority of motion uses performant properties (transform, opacity)

Design System + Theme

tokens.css exists and is used consistently
Light mode implemented
Dark mode implemented
System mode implemented (prefers-color-scheme)
Mode preference persists (for example with localStorage)

Visual Assets

5+ SVG assets (custom or intentionally adapted), unless instructor-approved exception
3+ image/illustration assets supporting the narrative
Images are optimized for web
Non-decorative images use meaningful alt text

3) Accessibility + Quality

prefers-reduced-motion support is fully implemented
All content remains readable with motion disabled
Keyboard navigation works across the full experience
Semantic headings and landmarks are present
Color contrast meets WCAG AA for body text
No blocking console errors
No markers: true in production

4) Testing Requirements

Tested at one desktop width and one mobile width
Tested in at least two browsers (Chrome + one other)
Deployed build matches local final version
No broken links or missing assets

4b) Issue Tracking Requirements

All required Project 2 sub-issues are closed
Project 2 Master Checklist reflects the final state of the project
Final issue evidence is present where needed

5) README (Project Documentation + Reflection)

Your repo must include a README.md that serves as both project documentation and reflection. A separate reflection page (e.g. reflection.html) is optional; the required reflection content must live in the README.

README.md must include:

Project title (as H1)
Optional: Video Demo URL (if you created a walkthrough video)
Description: Multiple paragraphs that explain what the project is and how it works, what the main files contain and do (e.g. index.html, styles/, scripts/main.js, tokens, motion approach), and key design choices and why you made them. Aim for at least several hundred words; in the neighborhood of 750 words is a good target.
Links: Live site URL, repo URL (and optional portfolio link)
Tech stack: HTML, CSS, JS, GSAP, ScrollTrigger, ScrollSmoother (or equivalents)
Reflection (in the README):
- Metaphor summary (1 paragraph)
- One section you're most proud of, and why
- One technical bug you solved, and how
- One accessibility decision you made
- What you would improve with more time

AI is allowed for drafting, but the final README and code explanations must reflect your own understanding.

Optional template — you may use this structure as a starting point:

# YOUR PROJECT TITLE
#### Video Demo:  <optional URL>
#### Description:
[Multiple paragraphs: what the project is, what key files do, design choices. Aim for ~750 words or at least several hundred.]

#### Links
- Live site:
- Repo:

#### Tech stack
HTML, CSS, JavaScript, GSAP, ScrollTrigger, ScrollSmoother

#### Reflection
- **Metaphor summary:**
- **One section I'm most proud of:**
- **One technical bug I solved:**
- **One accessibility decision:**
- **What I'd improve with more time:**

Suggested Project Structure

student-hub/04-project-structure-suggestion.md

Suggested Project Structure

Use this structure unless your instructor approves a different organization.

lost-in-the-scroll/
├── index.html
├── reflection.html (optional — reflection content can live in README.md)
├── styles/
│   ├── tokens.css
│   ├── styles.css
│   └── animations.css (if needed)
├── scripts/
│   └── main.js
├── assets/
│   ├── svg/
│   └── images/
└── README.md

Notes

Required reflection content (metaphor summary, proudest section, bug solved, accessibility decision, what to improve) belongs in README.md. A separate reflection.html page is optional.
Load tokens.css before other style files.
Keep all GSAP + ScrollTrigger + ScrollSmoother logic in scripts/main.js.
Keep asset file names clean and predictable (chapter-01.svg, hero-bg.webp, etc.).

Copy This Template (Student Steps)

student-hub/06-copy-this-template.md

Copy This Template (Student Steps)

Create Your Repo

Go to: Use this template
Repo name format: project-2-lost-in-the-scroll-[yourname]
Visibility: Public
Click Create repository from template

Clone + Run

git clone https://github.com/<your-username>/project-2-lost-in-the-scroll-<yourname>.git
cd project-2-lost-in-the-scroll-<yourname>

First 5 Minutes

Open docs/01-start-here.md
Create issue Project 2 Master Checklist
Create all required sub-issues listed in that master issue
Push once after initial setup

Before You Submit

Check all required items in docs/03-final-turn-in-spec.md
Verify deployed URL is current

Assignment: Issue-Based Project Management Workflow (Project 2)

student-hub/07-assignment-kickoff-template-and-tracking.md

Assignment: Issue-Based Project Management Workflow (Project 2)

Assigned: Monday, March 2, 2026
Due: Before next class (Wednesday, March 4, 2026 at class start)

Goal

Standardize your workflow using the class template repo and issue tracking, then continue your existing project build.

You are not restarting from zero.

Why This Uses Issues

This assignment uses issues because issue-based planning is a core development skill.

You will use issues to:

split project work into clear, testable units
track progress section-by-section
document blockers when debugging
produce evidence for completion and grading

Steps

Create your repo from template
Use this template
Name your repo using this format:
scrollytelling-[project-title]-[firstname]
Example: scrollytelling-the-long-way-down-jordan
If your title is not final yet, use: scrollytelling-[firstname]-project-2
Move your current project into this new repo
Keep the template docs/ and .github/ISSUE_TEMPLATE/ folders.
Enable GitHub Pages for the new repo.
Create issue from template:
- Project 2 Master Checklist
Create all required sub-issues listed in your master issue.
Complete kickoff build targets:

Full project structure present
Story draft is at least 90% complete
ScrollTrigger is registered and active in at least one section
ScrollSmoother setup is in place (#smooth-wrapper, #smooth-content)

What To Submit In Canvas

New repo URL
Live GitHub Pages URL
Link to your Project 2 Master Checklist issue
Screenshot of one working scroll-triggered section

Grading (10 points, Complete/Incomplete style)

2 pts: Template repo created correctly
2 pts: Existing project work migrated (not restarted)
2 pts: Project 2 Master Checklist issue created and updated
2 pts: GitHub Pages live and current
2 pts: One working ScrollTrigger section + ScrollSmoother shell

If You Get Stuck

If blocked for more than 20 minutes, open issue template:

Blocker Report

Include error details and what you already tried.

Working with Coding Agents

student-hub/09-working-with-coding-agents.md

Working with Coding Agents

First time? Follow the step-by-step first run to do one full cycle (improve issue → approve → work → verify → close), then use this doc as your reference.

TL;DR

Give the agent your assignment docs, your repo, and the issue you want to work on.

Use the agent to improve the issue first. Approve the issue before any code is written. Then let the agent work one issue at a time, review the output in the browser and the diff, and close the issue only after verification.

GitHub is the shared workflow. Your agent can live in VS Code, Codespaces, Codex, Claude Code, Copilot, or another tool.

The Core Loop

Capture the task as a GitHub issue.
Ask the agent to improve the issue without coding.
Approve or edit the improved issue.
Ask the agent to work the issue in the repo.
Review the result and test it.
Close the issue with evidence.

Your job is not to type every line yourself. Your job is to approve the plan and review the output.

Give the Agent Good Context

Before you ask an agent to help, hand it the same materials you would hand a teammate:

the assignment document or brief
your repo URL or local repo
the issue body or issue URL
planning artifacts such as your Motion Map, Figma, or reference links

For this project, that usually means:

Build 7-1 for structure, layout, and real content expectations
Build 7-2 for GSAP, reduced-motion, and motion requirements
Motion Map for what moves, how it moves, and which GSAP method you plan to use

Always say Do not start coding yet when you want the agent to improve the issue first.

Prompt: Improve This Issue

Here is my assignment context:
[paste the relevant assignment text or a short summary]

Here is my repo:
[paste the repo URL or say that the local repo is already open]

Here is my issue:
[paste the issue URL or the issue body]

Improve this issue so it is specific enough to build from.
- Rewrite the title if needed.
- Add a clear outcome.
- Turn the requirements into a Definition of Done checklist.
- Name likely files, selectors, links, and constraints.
- Add verification steps.

Do not start coding yet. I want the improved issue text first so I can review it.

Review the Issue Before Any Code Is Written

Use these four checks before you approve an issue:

Scope

Is this one job? If one issue tries to cover structure, content, animation, QA, and deployment at once, split it.

Specificity

Does it name the actual files, selectors, methods, or artifacts? Animate the hero is vague. .hero__title fades up with gsap.from() is specific.

Order

Does the issue make sense in sequence? Do not work on a ScrollTrigger interaction before GSAP is loaded and the target section exists.

Completeness

Does the Definition of Done match the assignment requirements and evaluation criteria? If the rubric checks reduced motion, the issue should check reduced motion.

If the issue is not ready, edit it or re-prompt the agent. Do not move to code until the issue is clear enough to review against later.

Prompt: Work This Issue

Work this approved issue in my repo.

Follow the Goal, Definition of Done, Files / Links, Constraints, and Verification sections exactly.
- Work one issue at a time.
- Do not change files outside the listed scope without asking first.
- Keep the implementation aligned with the assignment requirements and linked references.

When you are done, report:
- What changed
- How you verified it
- Open risks or follow-ups

Do not close the issue for me until I verify it.

Work One Issue at a Time

Default to one issue at a time, especially while you are still learning how to review agent output.

Good defaults:

start with one open issue
let the agent finish that issue only
review the browser, console, and diff
then move to the next issue

If you want tighter control, tell the agent to stop after each issue and wait for approval before continuing.

Verify Before Closing

Do not close an issue because the code exists. Close it because you verified it.

Minimum review loop:

open the browser and test the feature
open DevTools and check the console
read the diff
compare the result against the issue checklist
add evidence, then close

If the work is incomplete, reopen the issue or leave it open and revise the issue body.

Prompt: Verify and Close This Issue

Compare the current work against this issue.

- Check each Definition of Done item.
- List anything incomplete, unclear, or risky.
- Draft a completion comment using:
  - What changed
  - How I verified it
  - Open risks or follow-ups
  - Ready for human review

Only tell me to close the issue if all checks pass.

Motion Tasks Need Extra Context

Agents can only follow the motion plan they can see.

If the issue depends on your Motion Map, do not assume the agent can open Milanote. Link the Motion Map in the issue, then paste the important notes directly into the issue body:

which elements animate
which selectors those elements use
which GSAP methods apply
the motion intent
reduced-motion behavior
any reference examples you want it to match

For example, instead of writing animate the first section, write:

.hero__title enters with gsap.from() from y: 40
.hero__subtitle enters second in the same timeline
#first-contact h2 slides in from the left
#variables p uses a staggered reveal
reduced-motion users should see the content immediately with no animation

Worked Example: Build 7-1

Build 7-1 is mostly a structure and content problem. A good issue focuses on the live page structure, real content, and readable layout before polish.

Example issue shape:

Goal: Build the full rough-cut page structure from the Figma blueprint.
Definition of Done: linked CSS files, semantic sections, all chapters present, real content in every section, readable desktop and mobile layout.
Files / Links: index.html, styles/variables.css, styles/styles.css, scripts/main.js, Figma blueprint.
Constraints: use tokens instead of hardcoded repeated values, keep heading hierarchy intact, no placeholder text.
Verification: browser check on desktop and mobile width, console check, screenshot of the full page flow.

Worked Example: Build 7-2 Before and After

Before

Title: Animate hero and two sections

Make the site more animated with GSAP. Do the hero and two other sections.

This is too vague to review or build from.

After

Title: Build 7-2 hero and section entrance animations

Goal
Implement the Build 7-2 motion requirements for the hero and two content sections so the site has a clear page-load animation pass before ScrollTrigger is added next week.

Definition of Done
- [ ] GSAP is loaded before scripts/main.js
- [ ] All animation code is wrapped in a prefers-reduced-motion check
- [ ] .hero__title and .hero__subtitle animate in a gsap.timeline()
- [ ] #first-contact h2 and #first-contact p animate on page load
- [ ] #variables p uses a staggered reveal
- [ ] At least two easing values are used intentionally
- [ ] CSS initial states are present for animated elements
- [ ] Reduced-motion users see visible content with no animation
- [ ] No console errors

Files / Links
- Likely files: index.html, styles/styles.css, scripts/main.js
- Motion Map: [link]
- Build doc: Build 7-2

Constraints
- Use the motion notes from the Motion Map
- Prefer transform and opacity for motion
- Keep the movement subtle and readable
- Do not add ScrollTrigger yet

Verification
- [ ] Refresh the page and confirm the hero animation runs first
- [ ] Confirm the two additional sections animate on load
- [ ] Turn on prefers-reduced-motion and confirm the content appears with no animation
- [ ] Check the console

This version is specific enough to build, review, and close.

Make Definition of Done Match the Rubric

Your issue checklist should mirror the assignment evaluation criteria. That way, the issue becomes the review sheet.

Build 7-2 is a good example. The evaluation checks:

GSAP loaded correctly
reduced-motion check implemented
hero animation timeline
two section animations
easing and stagger usage
CSS initial states and fallback
animations reflect the Motion Map

A good Definition of Done uses those same ideas as checklist items. If the rubric checks it, the issue should check it too.

Build 7-2 evaluation check	Matching issue checklist item
GSAP loaded correctly	`GSAP is loaded before scripts/main.js`
Reduced motion check implemented	`All animation code is wrapped in a prefers-reduced-motion check`
Hero animation timeline	`.hero__title and .hero__subtitle animate in a gsap.timeline()`
Two section animations	`#first-contact` and `#variables` animation items are listed explicitly
Easing and stagger usage	`At least two easing values are used intentionally` and `#variables p uses a staggered reveal`
CSS initial states and fallback	`CSS initial states are present` and `Reduced-motion users see visible content with no animation`
Animations reflect the Motion Map	`Use the motion notes from the Motion Map`

Completion Comment Format

Use the same completion comment shape every time:

What changed
- Added the GSAP CDN before scripts/main.js
- Built a hero timeline for .hero__title and .hero__subtitle
- Added entrance animations for #first-contact and #variables
- Added reduced-motion fallback styles and logic

How I verified it
- Reloaded the page and confirmed the hero runs first
- Checked the console for errors
- Turned on prefers-reduced-motion and confirmed content appears without animation

Open risks or follow-ups
- Motion timing may need a final polish pass once ScrollTrigger is introduced

Ready for human review
- Yes

What Can Go Wrong

The issue is too vague

Ask the agent to rewrite it with named files, selectors, methods, and verification steps.

The agent starts coding too early

Start the session with Improve this issue and keep the sentence Do not start coding yet in the prompt.

The agent changes files you did not ask it to touch

Tell it to stay within the listed scope and stop if another file needs to change.

The agent asks too many questions in the middle

The issue probably lacks details. Update the issue so the next pass has the missing information.

The code works but misses the design intent

The agent only knows what is written down. Add motion intent, reference links, and tone notes to the issue.

Direct GitHub-Write Workflows

This section is optional.

If your tool can read and write GitHub issues directly, you can let it:

rewrite issue text after you review it
add a completion comment
close the issue after you verify the work

Do not grant write access by default if:

you are still learning how to review diffs
you are not checking the browser after each issue
you do not understand what permissions the tool has

Even when the tool can edit or close issues, you are still responsible for:

approving the issue before coding
reviewing the output
deciding whether the issue is actually done

Final Reminder

Issues first. Code second. Review before closing.

Agent Workflow: Step-by-Step First Run

student-hub/09a-agent-workflow-first-run.md

Agent Workflow: Step-by-Step First Run

This tutorial walks you through one full cycle of the issue-driven agent workflow. You will improve one issue with an agent, approve it, have the agent implement it, verify the result, and close the issue with evidence.

For prompts, troubleshooting, and the full reference, see Working with Coding Agents.

Before You Start

You have already created your Project 2 repo and your master issue + sub-issues (see Start Here).
You have at least one open sub-issue to work on (e.g. GSAP Motion Foundation).
You have an agent available: Cursor, Claude Code, Copilot, Codespaces, or similar.
You know your repo URL (e.g. https://github.com/your-username/your-repo).

Step 1: Pick One Open Issue

Open your repo on GitHub and go to Issues.
Choose one open sub-issue (e.g. GSAP Motion Foundation).
Copy the issue URL (from the browser address bar) or open the issue and copy the issue body (Goal, Definition of Done, etc.).

Checkpoint: You have one issue URL or the full issue text ready to paste into the agent.

Step 2: Ask the Agent to Improve the Issue (No Coding Yet)

Open your agent (Cursor, Claude Code, Copilot, etc.).
If the agent does not already have your repo, tell it your repo URL or that the project is open locally.
Paste the Improve this issue prompt and fill in the placeholders.

Use the exact prompt from Working with Coding Agents — Improve This Issue. It looks like this:

Here is my assignment context:
[paste the relevant assignment text or a short summary — e.g. Build 7-2 for motion, or the issue template name]

Here is my repo:
[paste the repo URL or say that the local repo is already open]

Here is my issue:
[paste the issue URL or the issue body]

Improve this issue so it is specific enough to build from.
- Rewrite the title if needed.
- Add a clear outcome.
- Turn the requirements into a Definition of Done checklist.
- Name likely files, selectors, links, and constraints.
- Add verification steps.

Do not start coding yet. I want the improved issue text first so I can review it.

Send the message and wait for the agent to return improved issue text (not code).

Checkpoint: The agent has returned a revised issue with Goal, Definition of Done, Files/Links, Constraints, and Verification. No code has been written yet.

Step 3: Update the Issue on GitHub and Approve It

Copy the improved issue text from the agent (Goal, Definition of Done, Files/Links, Constraints, Verification).
On GitHub, open the same issue and click Edit.
Replace or merge the issue body with the improved text. Keep the structure clear.
Review using the four checks from Working with Coding Agents — Review the Issue:
- Scope: Is this one job?
- Specificity: Does it name actual files, selectors, or methods?
- Order: Does it make sense in sequence with your other issues?
- Completeness: Does the Definition of Done match the assignment rubric?
If something is missing or wrong, edit the issue or re-prompt the agent. Do not proceed until you are satisfied.
Click Update comment to save.

Checkpoint: The issue on GitHub now has a full, specific Definition of Done and verification steps. You have approved it (or edited it until it is ready).

Step 4: Ask the Agent to Work the Issue

In the same agent session (or a new one), paste the Work this issue prompt.

Use the exact prompt from Working with Coding Agents — Work This Issue. It looks like this:

Work this approved issue in my repo.

Follow the Goal, Definition of Done, Files / Links, Constraints, and Verification sections exactly.
- Work one issue at a time.
- Do not change files outside the listed scope without asking first.
- Keep the implementation aligned with the assignment requirements and linked references.

When you are done, report:
- What changed
- How you verified it
- Open risks or follow-ups

Do not close the issue for me until I verify it.

Make sure the agent knows which issue to work on (paste the issue URL or body again if needed).
Let the agent implement. When it reports done, it should list what changed, how it verified, and any follow-ups.

Checkpoint: The agent has made changes and reported back. You have not closed the issue yet.

Step 5: Verify the Work Yourself

Open your project in the browser (local or GitHub Pages).
Run through the Verification steps from the issue (e.g. refresh and confirm animations run, check console, test reduced motion).
Open DevTools and check the console for errors.
Read the diff (e.g. git diff or the changes in your editor). Confirm only the expected files were changed.
Compare the result to the issue’s Definition of Done checklist.

If something is wrong or incomplete, tell the agent what to fix or leave the issue open and revise. Do not close the issue until you are satisfied.

Checkpoint: You have tested the feature in the browser, checked the console, and confirmed the work matches the issue.

Step 6: Add a Completion Comment and Close the Issue

On GitHub, open the issue and scroll to the comment box.
Add a completion comment using the format from Working with Coding Agents — Completion Comment Format:
- What changed — Short list of what was added or modified.
- How I verified it — What you did in the browser and console.
- Open risks or follow-ups — Anything to polish later or watch for.
- Ready for human review — Yes.
Submit the comment.
Close the issue.

Checkpoint: The issue is closed with a completion comment and evidence. You can check it off in your master issue and move to the next one.

What’s Next?

Use the same 6 steps for every issue you want the agent to help with.
Keep using Working with Coding Agents for prompt text, Motion Map tips, and troubleshooting.
If the agent changes files you didn’t ask for, or the issue was too vague, update the issue or re-prompt with clearer scope.

Issues first. Code second. Review before closing.

Assignment: Agent Workflow First Run

student-hub/09b-assignment-agent-workflow-first-run.md

Assignment: Agent Workflow First Run

Assigned: [Set in Canvas]
Due: [Set in Canvas]

Goal

Complete one full issue-driven agent cycle: improve one sub-issue with a coding agent, approve it, have the agent implement it, verify the result in the browser and console, and close the issue with a completion comment.

You are practicing the loop: approve the plan, review the output. The agent writes and edits code; you decide if the plan is good enough and if the result is correct.

Why This Assignment

Issue-driven agent workflow is a real-world skill. Your job is not to type every line yourself. Your job is to evaluate the plan and judge the output. This assignment gives you one full cycle so you can use the same workflow on the rest of your Project 2 issues.

Prerequisite

You must already have:

Your Project 2 repo created (from the template or Start Here)
Your master issue and all required sub-issues created and linked

You need at least one open sub-issue to use for this assignment (e.g. GSAP Motion Foundation).

Steps

Follow the Step-by-step first run for full detail. Summary:

Pick one open sub-issue (e.g. GSAP Motion Foundation). Copy the issue URL or issue body.
Ask your agent to improve the issue (no coding yet). Use the "Improve this issue" prompt from Working with Coding Agents. Paste your repo URL and the issue. When the agent returns improved issue text, copy it.
Update the issue on GitHub with the improved Goal, Definition of Done, Files/Links, Constraints, and Verification. Review using the four checks (scope, specificity, order, completeness). Approve or edit until the issue is ready to build from.
Ask your agent to work the issue. Use the "Work this issue" prompt from Working with Coding Agents. Let the agent implement. Do not close the issue yet.
Verify the work. Open your project in the browser. Run the verification steps from the issue. Check the console. Read the diff. If something is wrong, fix it or leave the issue open.
Add a completion comment and close the issue. Use the format: What changed / How I verified it / Open risks or follow-ups / Ready for human review. Then close the issue.

What To Submit In Canvas

Link to the closed issue that you improved and had the agent implement
The issue must contain a completion comment in the standard format (What changed / How I verified it / Open risks or follow-ups / Ready for human review)
Optional: screenshot of the working result or the completion comment

Grading (5 points, Complete/Incomplete style)

2 pts: One sub-issue was improved with an agent (improved issue text is visible in the issue body or in a comment)
2 pts: The agent implemented the issue; you verified in the browser and console; the work matches the issue
1 pt: The issue was closed with a completion comment that includes "What changed" and "How I verified it"

If You Get Stuck

Use Working with Coding Agents for the exact prompts and troubleshooting.
If blocked for more than 20 minutes, open a Blocker Report issue and include what you tried and any error details.

Syncing Template Updates

student-hub/10-syncing-template-updates.md

Syncing Template Updates

Why This Exists

If you already created your own repo from this template, new changes to the template do not appear in your repo automatically.

You do not need to start over. You do not need to create a new repo. You only need to copy the updated docs and issue templates into the repo you already use.

Required Patch Update

If your instructor asks you to sync a patch:

Do not create a new repo.
Do not restart the project.
Sync the updated docs and issue templates into your existing repo.
Push one sync commit.
Post proof of the sync.

Preferred proof:

comment on your existing Project 2 Master Checklist issue with the sync commit hash

Acceptable proof:

submit the sync commit hash or repo link in Canvas

Files Included in This Patch

If you are syncing the coding-agent workflow patch, copy these files:

README.md
docs/01-start-here.md
docs/08-progress-tracking-options.md
docs/09-working-with-coding-agents.md
docs/09a-agent-workflow-first-run.md
docs/09b-assignment-agent-workflow-first-run.md
docs/10-syncing-template-updates.md
docs/11-assignment-final-turn-in.md
.github/workflows/setup-project-issues.yml
.github/ISSUE_TEMPLATE/project-2-master-checklist.md
.github/ISSUE_TEMPLATE/story-structure.md
.github/ISSUE_TEMPLATE/gsap-motion-foundation.md
.github/ISSUE_TEMPLATE/scrolltrigger-core.md
.github/ISSUE_TEMPLATE/pinned-showpiece.md
.github/ISSUE_TEMPLATE/scrollsmoother-setup.md
.github/ISSUE_TEMPLATE/tokens-and-theme-modes.md
.github/ISSUE_TEMPLATE/assets-accessibility-qa.md
.github/ISSUE_TEMPLATE/reflection-readme-submission.md
.github/ISSUE_TEMPLATE/blocker-report.md

Recommended Path: Use GitHub Copilot to Apply the Patch

If you already use GitHub Copilot in VS Code, Codespaces, or another GitHub-supported editor, this is the fastest way to sync the patch into your repo.

Before you ask Copilot to make changes:

make sure your project repo is open
commit any unfinished work first
keep the patch file list above nearby so Copilot stays in scope

Prompt Copilot with something like this:

Compare my repo to this template repo:
https://github.com/sicxz/desn378-project-2-student-hub

Bring over only these files:
- README.md
- docs/01-start-here.md
- docs/08-progress-tracking-options.md
- docs/09-working-with-coding-agents.md
- docs/09a-agent-workflow-first-run.md
- docs/09b-assignment-agent-workflow-first-run.md
- docs/10-syncing-template-updates.md
- docs/11-assignment-final-turn-in.md
- .github/workflows/setup-project-issues.yml
- .github/ISSUE_TEMPLATE/project-2-master-checklist.md
- .github/ISSUE_TEMPLATE/story-structure.md
- .github/ISSUE_TEMPLATE/gsap-motion-foundation.md
- .github/ISSUE_TEMPLATE/scrolltrigger-core.md
- .github/ISSUE_TEMPLATE/pinned-showpiece.md
- .github/ISSUE_TEMPLATE/scrollsmoother-setup.md
- .github/ISSUE_TEMPLATE/tokens-and-theme-modes.md
- .github/ISSUE_TEMPLATE/assets-accessibility-qa.md
- .github/ISSUE_TEMPLATE/reflection-readme-submission.md
- .github/ISSUE_TEMPLATE/blocker-report.md

Do not change any project files outside this list.
Show me the diff before committing.
Then make one commit named: docs: sync coding-agent workflow patch

After Copilot proposes the changes:

Review the diff.
Confirm it only touches the files listed in this patch.
Commit and push.
Post proof of sync.

Sync Path A: Terminal, VS Code, or Codespaces Without Copilot

Use this if you already work locally or in Codespaces.

If you have edited any of the files listed above, commit your work first so you can recover it if needed.

git remote add template https://github.com/sicxz/desn378-project-2-student-hub.git
git fetch template
git checkout template/main -- README.md docs/01-start-here.md docs/08-progress-tracking-options.md docs/09-working-with-coding-agents.md docs/09a-agent-workflow-first-run.md docs/09b-assignment-agent-workflow-first-run.md docs/10-syncing-template-updates.md docs/11-assignment-final-turn-in.md .github/workflows/setup-project-issues.yml .github/ISSUE_TEMPLATE/project-2-master-checklist.md .github/ISSUE_TEMPLATE/story-structure.md .github/ISSUE_TEMPLATE/gsap-motion-foundation.md .github/ISSUE_TEMPLATE/scrolltrigger-core.md .github/ISSUE_TEMPLATE/pinned-showpiece.md .github/ISSUE_TEMPLATE/scrollsmoother-setup.md .github/ISSUE_TEMPLATE/tokens-and-theme-modes.md .github/ISSUE_TEMPLATE/assets-accessibility-qa.md .github/ISSUE_TEMPLATE/reflection-readme-submission.md .github/ISSUE_TEMPLATE/blocker-report.md
git commit -m "docs: sync coding-agent workflow patch"
git push

If you already added a template remote earlier, skip the first command.

Sync Path B: GitHub Web UI or Manual Copy

Use this if you do not want to use terminal commands.

Open the template repo in GitHub.
Open each file in the patch list above.
Copy the updated content into the matching file in your own repo.
Commit the changes in GitHub, VS Code, or your editor.
Push the commit and post proof of sync.

This takes longer, but it works.

What About My Existing Issues?

You do not need to recreate your repo or reopen old issues.

Important details:

issue templates only affect new issues you create after the update
existing open issues stay open
existing closed issues stay closed

If you want to use a coding agent on an issue you already opened, either:

edit the issue body so it matches the new structure, or
add a comment that works as an Agent Handoff

If you copied .github/workflows/setup-project-issues.yml into your existing repo, you can also go to Actions and run Setup Project Issues:

use create_missing to create any issue that does not exist yet
use sync_open to refresh the bodies of open issues from the latest templates

A good Agent Handoff comment includes:

the goal
the Definition of Done
the files or links involved
the constraints
the verification steps

Which Path Should I Use?

GitHub web UI is the baseline. GitHub Copilot is the recommended fast path if you already use it. Terminal sync is the next fastest option if you are comfortable in a repo. Manual copy still works if you want the safest, most explicit route.

Choose the path that fits the tools you already use.

FINAL: Lost in the Scroll

student-hub/11-assignment-final-turn-in.md

FINAL: Lost in the Scroll

For the full checklist in repo form, see Final Turn-In Spec.

Due: Week 10 — Wednesday, March 11, 2026 (before presentations)
Points: 200
Weight: 50% of course grade

Overview

This is your final submission for Project 2: Lost in the Scroll.

You've spent five weeks building a scrollytelling site that traces your JavaScript learning journey through a personal metaphor. This submission is the complete, deployed, polished version.

What you are turning in: A live, deployed scrollytelling site + public repository with a README that documents the project and includes your reflection.

What to Submit

Paste both links into the Canvas text box:

Live site URL (GitHub Pages)
Public GitHub repository URL

Your README is in the repo; we will read it there.

Before you submit, make sure your Project 2 issue tracking is complete:

all required Project 2 sub-issues are closed
your Project 2 Master Checklist issue is updated and fully checked off

Final Deliverable Requirements

Story + Structure

6–8 total sections (hero + 5–7 story chapters)
At least 5 JavaScript concepts represented as story chapters
Complete written narrative — no placeholder text, no lorem ipsum
A clear personal metaphor that maps code concepts to something you understand

ScrollTrigger

8+ ScrollTrigger instances total
5+ trigger-and-play reveals (animation fires when element enters viewport)
2+ scrubbed interactions (scroll position controls animation progress)
1+ pinned showpiece section with 3+ internal animation steps

ScrollSmoother

One global ScrollSmoother setup using #smooth-wrapper / #smooth-content structure
Smooth value tuned for readability
2+ smoother-enhanced moments (effects, speed-based depth, etc.)
Disabled or bypassed for prefers-reduced-motion users

If ScrollSmoother was unavailable for your setup, you must have received instructor approval for an alternative.

GSAP Motion

10+ intentional GSAP tweens across the site
2+ GSAP timelines used for sequencing
2+ distinct easing choices used intentionally (not all power2.out)
Majority of motion uses performant properties (transform, opacity)

Design System + Theme

tokens.css (or variables.css) exists and is used consistently
Light mode implemented
Dark mode implemented
System mode implemented (prefers-color-scheme)
Mode preference persists via localStorage

Visual Assets

5+ SVG assets (custom or intentionally adapted) — unless instructor-approved exception
3+ image/illustration assets supporting the narrative
Images optimized for web
Non-decorative images use meaningful alt text

Accessibility + Quality

prefers-reduced-motion fully implemented — all content readable with motion disabled
Keyboard navigation works across the full experience
Semantic headings and landmarks present
Color contrast meets WCAG AA for body text
No blocking console errors
No markers: true left in production code

Testing

Tested at one desktop width and one mobile width
Tested in at least two browsers (Chrome + one other)
Deployed build matches your local final version
No broken links or missing assets

Issue Tracking

All required Project 2 sub-issues are closed
Project 2 Master Checklist reflects the final state of the project
Final issue evidence is present where needed

README (Project Documentation + Reflection)

Your repo must include a README.md that documents the project and includes your reflection. A separate reflection page (e.g. reflection.html) is optional; the required reflection content must be in the README.

README.md must include:

Project title (as H1)
Optional: Video Demo URL (if you created a walkthrough video)
Description: Multiple paragraphs that explain what the project is and how it works, what the main files contain and do, and key design choices and why you made them. Aim for at least several hundred words; in the neighborhood of 750 words is a good target.
Links: Live site URL, repo URL (and optional portfolio link)
Tech stack: HTML, CSS, JS, GSAP, ScrollTrigger, ScrollSmoother (or equivalents)
Reflection (in the README):
- Metaphor summary (1 paragraph)
- One section you're most proud of, and why
- One technical bug you solved, and how
- One accessibility decision you made
- What you would improve with more time

Your reflection is part of the final submission and is considered in evaluation (e.g. under Story & Metaphor and Technical Execution).

Presentation (Week 10 — In Class)

5–7 minutes per student:

Live scroll-through — show the full site, top to bottom
Explain your metaphor — what is it, why did you choose it
Walk through ONE section's code — pick your strongest, explain it line by line
What surprised you?
What would you add with more time?

The desk critique test applies: be ready to explain any line of code in your project.

Evaluation Rubric

Criteria	Weight	Points	What I'm Looking For
Story & Metaphor	25%	50	Does the metaphor work? Is the story clear, personal, and engaging? Would a non-coder follow the journey? Is the writing complete and intentional?
Interaction & Motion	35%	70	Does scroll pacing feel right? Do animations serve the narrative — not just decorate it? Is there a showpiece section? Does easing have personality? Does the scrub feel intentional?
Technical Execution	30%	60	GSAP + ScrollTrigger used correctly? ScrollSmoother configured? Tokens consistent? No major bugs? Deployed and matching local? Code is organized and readable?
Accessibility	10%	20	Reduced-motion alternative works? Keyboard navigable? Color contrast passes? Semantic HTML? Content readable with all motion disabled?

Total: 200 points

Grade Scale

Level	Description
Exemplary (90–100%)	The metaphor is original and illuminating. Scroll pacing feels cinematic — you want to keep scrolling. Animations serve the story. Technically clean — no console errors, smooth performance. Accessible by default. Presentation is confident and clear.
Proficient (80–89%)	Metaphor works and story is complete. Motion supports the narrative with minor pacing issues. Technical requirements met with small bugs. Accessibility basics covered.
Developing (70–79%)	Metaphor is present but thin. Story has gaps or placeholder content. Some ScrollTrigger patterns implemented but not all requirements met. Accessibility partially addressed.
Beginning (60–69%)	Metaphor is unclear or disconnected. Major sections incomplete. Fewer than half the technical requirements met. Accessibility not addressed.
Incomplete (below 60%)	Site not deployed, major sections missing, or no evidence of scroll-driven motion.

Week 10: The Showcase

week-10/week-overview.md

Week 10: The Showcase

Unit 2: Teaching Through Story Interaction Question: Can you explain what you built and why?

Final Prep Source Of Truth

Before presentations, verify completion using:

../week-9/resources/project-2-implementation-checklist.md

If students are missing items, prioritize shipping and explanation readiness over new features.

Overview

This is presentation week. No new content. No new assignments. Students present their scrollytelling sites — "The Long Way Down" — in 5–7 minute presentations.

Presentation Format

Time: 5–7 minutes per student

Structure:

Live Demo (2–3 minutes)
- Scroll through the site live (projector or screen share)
- Let the work speak first — don't over-explain during the scroll
The Metaphor (1 minute)
- What's your metaphor and why did you choose it?
- How did it evolve from your Week 5 pitch?
Code Walkthrough (1–2 minutes)
- Open ONE section's code (HTML + JS)
- Explain: what does this code do? How does the ScrollTrigger work?
- Show the timeline or pin config — explain the values
Reflection (1 minute)
- What surprised you about this process?
- What would you do differently with more time?

The Desk Critique Test

The instructor may point to any line of code and ask: "What does this do?" If you can't explain it, it's a red flag — but this is a learning moment, not a punishment.

Day Schedule

Option A: Full Class Presentations

Duration: Full class period

Time	Activity	Description
0:00	Setup	Students load their sites, test projector/screen share
0:10	Presentations	5–7 min each, 1 min transition between
—	Q&A	Brief instructor/peer questions after each
Last 10	Closing	Final thoughts, course reflection, what comes next

Option B: Split Across 2 Days

If the class is large, split presentations across Day 1 and Day 2.

Final Deliverables

Due at time of presentation:

Deliverable	Where
Deployed scrollytelling site	GitHub Pages URL
Site linked from portfolio	Navigation or projects page
Repository public	GitHub
README updated	Project description, metaphor, tech used

Evaluation

The final rubric from the project brief applies:

Criteria	Weight	What We're Looking For
Story & Metaphor	25%	Does the metaphor work? Clear, personal, engaging? Would a non-coder follow?
Interaction & Motion	30%	Scroll pacing, animation intention, showpiece moment, easing personality
Technical Execution	25%	GSAP + ScrollTrigger correct, tokens consistent, deployed, no bugs
Accessibility	20%	Reduced motion, keyboard, contrast, semantic HTML

Presentation quality does not add or subtract from the project grade — but inability to explain code may indicate an integrity concern per the desk critique test.

Instructor Notes

Keep presentations moving. 7 minutes max. Use a timer visible to students.
Ask at least one code question per student. Make it supportive, not adversarial.
Celebrate range — a "Kitchen" metaphor and a "Mixtape" metaphor solving the same problem shows the strength of the approach.
Note common themes for future course iterations: what patterns worked? What tripped everyone up?
If a student's site isn't deployed, they can present from localhost but should deploy by end of day.
Take screenshots of student work for course documentation (with permission).

After Presentations

All final grades submitted via Canvas rubric
Optional: share a "class gallery" page linking to all student sites
Optional: course feedback survey
Students should keep their GitHub repos public — this is portfolio work

Build: The Pulse

week-8/build/build-8-1-the-pulse.md

Build: The Pulse

Points: 25 Time Estimate: 60–90 minutes Prerequisite: Week 5 GSAP Express + Build 7-1: The Rough Cut + Motion Map (Week 6)

TL;DR

Bring your Motion Map to life. Load GSAP, wrap everything in a reduced-motion check, and build entrance animations for your hero and at least 2 story sections. Reference your Motion Map for what to animate and how.

Submit

Push to GitHub
Submit GitHub Pages URL to Canvas

Overview

Your site has structure (Build 7-1). Your Motion Map has the plan. Now you connect them.

This week you're building the animations — not the triggers. Everything will animate on page load right now, even sections below the fold. That's expected. Think of it like rehearsing choreography without the curtain cues. Next week (Week 8), ScrollTrigger adds the scroll-driven timing so animations fire when the user reaches each section.

Open your Milanote Motion Map. Every annotation, every arrow, every GSAP method label — that's your implementation guide. Start with the hero, then move to the sections you're most confident about.

What You're Building

GSAP loaded via CDN in your scrollytelling project
A prefers-reduced-motion check wrapping all animation code
A hero entrance timeline with sequenced tweens
Entrance animations for 2+ story sections
CSS initial states with reduced-motion fallbacks

Requirements

Core

GSAP loaded via CDN (before main.js)
prefers-reduced-motion check wraps all animation code
Hero entrance timeline with 2+ sequenced .from() tweens
2 additional sections with entrance animations
At least 2 different easing values used
At least 1 stagger animation on grouped elements (paragraphs, list items, cards)
CSS initial states (opacity: 0) for all GSAP-animated elements
@media (prefers-reduced-motion: reduce) restores visibility in CSS
No console errors

Stretch Goals

All sections from your Motion Map animated
A gsap.fromTo() used for precise start/end control
Scale or rotation animation on at least one element
Timeline position parameters used (-=0.3, +=0.1) for overlap/delay
Showpiece section has a more complex animation sequence (3+ tweens)
Different motion direction per section (fade up, slide left, scale in)

Step-by-Step Guide

Step 1: Link GSAP

Add the GSAP CDN script to your index.html, before your main.js:

<!-- Before closing </body> tag -->
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script src="scripts/main.js"></script>

Do NOT add ScrollTrigger this week. You're building animations first, triggers next week.

Test: Open your site, open DevTools Console, type gsap and press Enter. You should see the GSAP object, not an error.

Step 2: Set Up the Reduced Motion Check

This is the first thing in your main.js (or after your theme code if you did Practice 7-1):

// ========================================
// ANIMATION — The Pulse
// ========================================

// Respect motion preferences
const prefersReducedMotion = window.matchMedia(
  '(prefers-reduced-motion: reduce)'
).matches;

if (!prefersReducedMotion) {
  // ALL animation code goes inside this block
}

This is not optional. Every GSAP animation in this project lives inside this check. Users who prefer reduced motion see fully visible content with zero animation.

Step 3: Build the Hero Timeline

Open your Motion Map. What did you plan for the hero?

A timeline lets you sequence multiple animations. Each .from() tween animates an element from a starting state to its natural CSS position:

if (!prefersReducedMotion) {
  // Hero entrance timeline
  const heroTl = gsap.timeline();

  heroTl
    .from('.hero__title', {
      opacity: 0,
      y: 40,
      duration: 0.8,
      ease: 'power2.out',
    })
    .from(
      '.hero__subtitle',
      {
        opacity: 0,
        y: 20,
        duration: 0.6,
        ease: 'power2.out',
      },
      '-=0.4'
    );
}

Key concepts:

gsap.timeline() creates a sequence — animations play one after another
.from() animates FROM these values TO the element's natural CSS state
'-=0.4' is a position parameter — this tween starts 0.4s before the previous one ends (overlap)
y: 40 means "start 40px below" — the element slides up into place

Adapt the selectors (.hero__title, .hero__subtitle) to match YOUR HTML class names.

Step 4: Choose Your Easing

Easing is personality. The same animation with different easing feels completely different.

Section Mood	Suggested Easing	Feels Like
Grand / welcoming	`power2.out`	Confident arrival
Energetic / surprising	`back.out(1.7)`	Slight overshoot, playful
Methodical / structured	`power2.out` + `stagger`	Orderly reveal
Dramatic / pivotal	`power4.out`	Heavy, deliberate
Gentle / reflective	`power1.out`	Soft fade

Visit the GSAP Ease Visualizer to see them in action. Pick at least 2 different easings across your sections.

Step 5: Animate 2 Story Sections

Pick the 2 sections from your Motion Map you're most confident about. Each should use a different approach than the hero.

Approach A: Individual elements with a timeline

// Section: first-contact
const section1Tl = gsap.timeline();

section1Tl
  .from('#first-contact h2', {
    opacity: 0,
    x: -30,
    duration: 0.6,
    ease: 'power2.out',
  })
  .from(
    '#first-contact p',
    {
      opacity: 0,
      y: 20,
      duration: 0.5,
    },
    '-=0.2'
  );

Approach B: Stagger on grouped elements

// Section: variables — paragraphs reveal one by one
gsap.from('#variables p', {
  opacity: 0,
  y: 20,
  duration: 0.5,
  stagger: 0.15,
  ease: 'power2.out',
});

Approach C: Scale + fade for visual elements

// Section: the-switch — image/visual scales in
const section3Tl = gsap.timeline();

section3Tl
  .from('#the-switch h2', {
    opacity: 0,
    y: 20,
    duration: 0.6,
    ease: 'back.out(1.7)',
  })
  .from(
    '#the-switch .visual',
    {
      opacity: 0,
      scale: 0.8,
      duration: 0.6,
      ease: 'back.out(1.4)',
    },
    '-=0.3'
  );

Adapt the selectors and values to match YOUR sections and YOUR Motion Map annotations.

Step 6: Set CSS Initial States

Every element GSAP animates needs to start invisible in CSS. Otherwise, you'll see a flash of content before the animation plays.

Add to your animations.css (or wherever your animation styles live):

/* ========================================
   GSAP INITIAL STATES
   Elements start invisible; GSAP reveals them
   ======================================== */
.hero__title,
.hero__subtitle,
#first-contact h2,
#first-contact p,
#variables p,
#the-switch h2,
#the-switch .visual {
  opacity: 0;
}

/* ========================================
   REDUCED MOTION FALLBACK
   Show everything if user prefers no animation
   ======================================== */
@media (prefers-reduced-motion: reduce) {
  .hero__title,
  .hero__subtitle,
  #first-contact h2,
  #first-contact p,
  #variables p,
  #the-switch h2,
  #the-switch .visual {
    opacity: 1;
  }
}

Update these selectors to match the elements YOU are animating. Every element in your GSAP code needs a matching line in both blocks.

Step 7: Test and Debug

Open your site in the browser. Does the hero animate on load?
Open DevTools Console. Any red errors? Fix them before continuing.
Scroll down. Do the section animations play? (Yes — they all fire on load. That's expected this week.)
Test reduced motion:
- macOS: System Settings → Accessibility → Display → Reduce motion
- Or: DevTools → Rendering panel → Emulate prefers-reduced-motion: reduce
- All content should be fully visible, no animation
Disable JavaScript (DevTools → Settings → Debugger → Disable JavaScript). Is content still visible? If not, your CSS initial states need a <noscript> fallback.

About Page Load vs. Scroll

Right now, everything animates at once on page load — including sections you haven't scrolled to yet. You might scroll down and find content already in its final position because the animation already played.

This is intentional. You're building the animations this week and the triggers next week.

Think of it this way:

This week: Choreography practice — you rehearse the moves
Next week (ScrollTrigger): The curtain rises on cue — animations play when the audience sees them

Your Motion Map planned both the what (animation type, GSAP method) and the when (scroll position, trigger points). This week handles the what. Week 8 handles the when.

Evaluation

Criteria	Points
GSAP loaded via CDN, no console errors	3
`prefers-reduced-motion` check wraps all animations	3
Hero entrance timeline with 2+ sequenced tweens	5
2 additional sections with entrance animations	6
At least 2 different easing values used	3
CSS initial states + reduced-motion fallback	3
Animations reference Motion Map intent	2

Common Issues

Problem	Fix
`gsap is not defined`	GSAP script must load before `main.js`. Check `<script>` tag order in your HTML.
Hero text invisible, never appears	You set `opacity: 0` in CSS but GSAP isn't running. Check the Console for errors. Check your `prefersReducedMotion` wrapper — maybe you accidentally put code outside it.
`.from()` glitch (flash of final state)	Use `gsap.fromTo()` instead for explicit start/end, or add `immediateRender: true` to the tween.
Stagger has no effect	Your selector only matches one element. `stagger` needs multiple elements — check that the class/selector matches more than one.
Animation feels wrong	Change the easing. `ease: "power2.out"` is the safe default. Visit the Ease Visualizer.
Page is blank when JS is off	Your CSS sets `opacity: 0` but has no fallback. Add the `@media (prefers-reduced-motion: reduce)` block and consider a `<noscript>` style.
Everything animates at once	That's expected this week. ScrollTrigger (Week 8) fixes this.
Timeline tweens play at wrong time	Check your position parameters. `'-=0.4'` means overlap by 0.4s. No position parameter means "after previous tween ends."

Connection to Next Week

Right now your site has a problem: everything animates at once on page load, even sections you haven't scrolled to yet. That's the problem ScrollTrigger solves in Week 8.

Think of this week as building the animations, next week as building the triggers. Your Motion Map planned both — now you've implemented the first half.

Next week you'll wrap each section's animation in a scrollTrigger config, and suddenly the choreography plays on cue.

Resources

Build: Three Chapters

week-8/build/build-8-2-three-chapters.md

Build: Three Chapters

Points: 10 (Complete/Incomplete) Time Estimate: 60–90 minutes Prerequisite: Build 7-2: The Pulse

TL;DR

Animate entrance sequences for 3 story sections using GSAP timelines. Finish writing all section content.

Submit

Push to GitHub
Submit GitHub Pages URL to Canvas

Overview

Your hero has a timeline. Now extend that pattern to your story sections. Each chapter in your scrollytelling site should have its own entrance animation — but not the same one. Different content deserves different motion.

This is also the week to finish all your content. Every section needs real text by Sunday.

What You're Doing

Step 1: Set Up Section Animations

For each section you're animating, create a new timeline. Pattern:

if (!prefersReducedMotion) {
  // Hero timeline (from Practice 7-1)
  const heroTl = gsap.timeline();
  heroTl
    .from('.hero__title', { opacity: 0, y: 40, duration: 0.8, ease: 'power2.out' })
    .from('.hero__subtitle', { opacity: 0, y: 20, duration: 0.6 }, '-=0.4');

  // Chapter 1 timeline
  const ch1Tl = gsap.timeline();
  ch1Tl
    .from('#first-contact h2', { opacity: 0, x: -30, duration: 0.6, ease: 'power2.out' })
    .from('#first-contact p', { opacity: 0, y: 20, duration: 0.5 }, '-=0.2');

  // Chapter 2 timeline
  const ch2Tl = gsap.timeline();
  ch2Tl
    .from('#variables h2', { opacity: 0, duration: 0.6, ease: 'power3.out' })
    .from('#variables p', { opacity: 0, y: 20, duration: 0.5, stagger: 0.1 }, '-=0.2');

  // Chapter 3 timeline
  const ch3Tl = gsap.timeline();
  ch3Tl
    .from('#the-switch h2', { opacity: 0, y: 20, duration: 0.6, ease: 'back.out(1.7)' })
    .from('#the-switch p', { opacity: 0, duration: 0.4 }, '-=0.2')
    .from('#the-switch .visual', { opacity: 0, scale: 0.8, duration: 0.6, ease: 'back.out(1.4)' });
}

Step 2: Vary Your Approach

Don't use the same animation for every section. Consider:

Section Mood	Suggested Motion	Easing
Mysterious / discovery	Fade in (opacity only)	`power2.out`
Energetic / breakthrough	Slide + scale	`back.out(1.7)`
Methodical / structured	Stagger items	`power2.out` with `stagger: 0.1`
Dramatic / pivotal	Large Y offset, slow	`power4.out`
Gentle / reflective	Small fade, longer duration	`power1.out`

Step 3: CSS Initial States

Every element that GSAP animates needs CSS to handle the no-JS / reduced-motion case:

/* Elements GSAP will animate */
.section h2,
.section p,
.section .visual {
  opacity: 0;
}

/* Show them if no motion or no JS */
@media (prefers-reduced-motion: reduce) {
  .section h2,
  .section p,
  .section .visual {
    opacity: 1;
  }
}

/* noscript fallback */
noscript ~ main .section h2,
noscript ~ main .section p {
  opacity: 1;
}

Step 4: Finish All Content

Every section needs real text. Use your metaphor map from the Week 5 Reflect. For each section:

Open your metaphor map
Re-read the JS concept for that chapter
Write 2–3 paragraphs connecting the concept to your metaphor
Keep it conversational — you're telling a story, not writing documentation

Complete Criteria

3+ sections have GSAP timeline entrance animations (beyond hero)
Each animated section uses a distinct animation approach
At least 2 different easing values used across sections
CSS initial states set for all GSAP-animated elements
prefers-reduced-motion respected (elements visible when motion disabled)
ALL sections have real, written content
Pushed to GitHub, live on Pages

Common Issues

Q: All my animations play at once on page load — sections below the fold animate before I see them. A: That's expected this week. Next week, ScrollTrigger solves this by only playing animations when you scroll to them.

Q: My page is blank until animations finish. A: You probably have opacity: 0 on too many elements without a proper fallback. Check your reduced-motion media query.

Q: How many timelines should I have? A: One per section is a good pattern. You'll reorganize them next week when adding ScrollTrigger.

Connection to This Week

Right now your site has a problem: everything animates at once on page load, even sections you haven't scrolled to. That's the problem ScrollTrigger solves next week. Think of this week as building the animations, next week as building the triggers.

Practice: The Scroll

week-8/practice/practice-8-1-the-scroll.md

Practice: The Scroll

Points: 10 Time Estimate: 45–60 minutes

TL;DR

Convert your GSAP animations to scroll-triggered. Use markers to debug. Add scrub to one section.

Submit

Push to GitHub
Submit GitHub Pages URL to Canvas

Overview

Last week, all your animations fired on page load. Sections below the fold animated before you even scrolled to them. That's the problem ScrollTrigger solves.

This practice session converts your existing GSAP animations into scroll-triggered ones. When you scroll to a section, its animation plays. The page comes alive as you move through it.

What You're Building

Your existing scrollytelling site, but now each section's animation is triggered by scroll position.

Requirements

Core

ScrollTrigger loaded and registered
At least 3 sections have scroll-triggered animations
trigger element set correctly for each
start values adjusted (not all default)
markers: true used during development
prefers-reduced-motion still wraps everything

Stretch Goals

scrub on at least 1 section
toggleActions configured for at least 1 animation
gsap.utils.toArray() used to batch-animate similar sections

Step-by-Step

Step 1: Load ScrollTrigger

Add the ScrollTrigger plugin to your HTML (after GSAP, before your script):

<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/ScrollTrigger.min.js"></script>
<script src="scripts/main.js"></script>

gsap.registerPlugin(ScrollTrigger);

Step 2: Convert One Section

Take your simplest section animation and add ScrollTrigger. Before:

gsap.from('#variables h2', {
  opacity: 0,
  y: 30,
  duration: 0.8,
  ease: 'power2.out'
});

After:

gsap.from('#variables h2', {
  opacity: 0,
  y: 30,
  duration: 0.8,
  ease: 'power2.out',
  scrollTrigger: {
    trigger: '#variables',
    start: 'top 80%',
    markers: true
  }
});

Scroll to that section. The animation should play when the section enters the viewport. Check the markers to confirm the trigger position.

Step 3: Understand Start/End

start and end use the format: "[trigger position] [viewport position]".

Value	Meaning
`"top 80%"`	When trigger's TOP hits 80% from viewport TOP (common for section reveals)
`"top center"`	When trigger's TOP hits viewport CENTER
`"top top"`	When trigger's TOP hits viewport TOP (used for pinning)
`"center center"`	When trigger's CENTER hits viewport CENTER

Adjust start for each section until it feels right. Sections with more content might trigger earlier (top 85%). Short sections might trigger later (top 60%).

Step 4: Convert a Timeline

For sections with timelines:

const switchTl = gsap.timeline({
  scrollTrigger: {
    trigger: '#the-switch',
    start: 'top 75%',
    markers: true
  }
});

switchTl
  .from('#the-switch h2', { opacity: 0, y: 30, duration: 0.6 })
  .from('#the-switch p', { opacity: 0, y: 20, duration: 0.5 }, '-=0.2');

Step 5: Try Scrub (Stretch)

Pick one section and add scrub:

gsap.from('#the-system .visual', {
  scale: 0.5,
  opacity: 0,
  ease: 'none',
  scrollTrigger: {
    trigger: '#the-system',
    start: 'top 80%',
    end: 'center center',
    scrub: 1,
    markers: true
  }
});

Scroll slowly through that section. The animation should progress as you scroll — and reverse if you scroll back up. scrub: 1 adds 1 second of smoothing so it doesn't feel janky.

Evaluation

Criteria	Points
ScrollTrigger loaded and registered	2
3+ sections scroll-triggered	3
Start values calibrated (not all default)	2
Markers present for debugging	1
Reduced motion check in place	2

Troubleshooting

ScrollTrigger not defined: Plugin not loaded. Check your <script> tag order: GSAP → ScrollTrigger → your script. Check the URL for typos.

Animation plays immediately, ignoring scroll: You forgot to add the scrollTrigger object to your tween/timeline. The GSAP animation still works — it just doesn't know about scrolling.

Markers don't appear: Make sure markers: true is inside the scrollTrigger object, not in the tween properties. Also check: are you scrolled past the trigger? Markers might be above or below your current view.

Section animates too early: Change start to trigger later: "top 60%" instead of "top 80%". Use markers to visualize.

Scrub feels laggy: Increase the scrub smoothing value: scrub: 2 or scrub: 0.5. Or simplify the animation — fewer properties = smoother performance.

Connection to Course

ScrollTrigger is the core technology of your final project. This week gets the fundamentals working. Next week (Week 9), you'll add pinning — locking a section in place while content animates within it. That's the "showpiece" technique.

Reflect: Visual Notes — Scroll Timeline Map

week-8/reflect/reflect-8-1-visual-notes.md

Reflect: Visual Notes — Scroll Timeline Map

Points: 10 (Complete/Incomplete) Time Estimate: 15–20 minutes

TL;DR

Map your scroll timeline: which sections trigger where, what animates, and what the user sees at each scroll position.

Submit

Scroll map uploaded to Canvas

The Prompt

Draw a vertical scroll timeline for your site. For each section, show:

Trigger point — Where in the scroll does the animation start?
Animation type — Trigger-and-play or scrub?
What animates — Which elements? What motion?
What the user sees — What's in the viewport at this scroll position?

Think of it as a scroll storyboard — a bird's-eye view of the entire scroll experience.

Format: Vertical timeline with sections marked along it. Annotate each section with trigger type, animation, and pacing notes.

Evaluation

Criteria	Points
All sections shown on scroll timeline	3
Trigger points and animation types labeled	3
Pacing notes (where it's fast, slow, breathing room)	2
Clear visual format (not just a list)	2

Week 8 Day 1 Lecture Plan: ScrollTrigger Without Overwhelm

week-8/resources/scrolltrigger-lecture-plan.md

Week 8 Day 1 Lecture Plan: ScrollTrigger Without Overwhelm

Class length: 90 minutes Goal for today: Students understand ScrollTrigger mental model and implement one working section.

Outcomes

By the end of class, students can:

Explain trigger, start, end, and markers
Register ScrollTrigger correctly
Convert one existing GSAP animation into a scroll-triggered animation
Debug trigger timing using markers

Run of Show

Time	Segment	Instructor Moves	Student Output
0:00-0:08	Opening context	Show one polished scrollytelling reference and point out where scroll controls pacing	Shared mental model
0:08-0:18	Concept framing	Explain: "scroll is timeline control" (not decoration)	Vocabulary ready
0:18-0:35	Live demo 1	Add plugin, register, convert one tween to use `scrollTrigger`	Students mirror setup
0:35-0:45	Live demo 2	Show `start`/`end` changes and markers in real time	Students see debugging workflow
0:45-1:15	Build sprint	Students implement on one section; you rotate for blockers	One working section each
1:15-1:25	Debug clinic	Group top bugs and fixes on board	Shared troubleshooting notes
1:25-1:30	Exit check	Quick thumbs check against 4-item exit ticket	Progress verified

Live Demo Script (Minimal)

1) Load scripts in order

<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/ScrollTrigger.min.js"></script>
<script src="scripts/main.js"></script>

2) Register plugin

gsap.registerPlugin(ScrollTrigger);

3) Convert one tween

gsap.from('#chapter-1 h2', {
  opacity: 0,
  y: 24,
  duration: 0.7,
  ease: 'power2.out',
  scrollTrigger: {
    trigger: '#chapter-1',
    start: 'top 80%',
    end: 'top 50%',
    markers: true
  }
});

4) Add scrub on one visual

gsap.to('#chapter-1 .chapter-visual', {
  y: -40,
  ease: 'none',
  scrollTrigger: {
    trigger: '#chapter-1',
    start: 'top bottom',
    end: 'bottom top',
    scrub: 1,
    markers: true
  }
});

Exit Ticket (End of Class)

ScrollTrigger plugin is loaded and registered
One section animation is tied to scroll
Markers visible and used for tuning
Student can explain why their start value makes sense

Homework (Light, High Value)

Finish writing any remaining story text (target: 100%)
Implement GSAP motion pass across all sections before Wednesday studio
Keep markers on while building; remove before final submission

Week 8 Resources: The Scroll

week-8/resources/week-8-resources.md

Week 8 Resources: The Scroll

Assigned (Before Day 2)

Resource	Type	Time
GSAP ScrollTrigger Tutorial	Video	10 min
Browse 2 scrollytelling examples (see Learn 8-1)	Analysis	15 min

Reference

Resource	Why
ScrollTrigger Docs	Full API reference
ScrollTrigger start/end	Start and end value syntax
ScrollTrigger scrub	Scrub modes explained

Video

Resource	Time	Why
GSAP ScrollTrigger in 3 Minutes	3 min	Quick visual overview
GreenSock: ScrollTrigger 101	12 min	Official detailed tutorial
Fireship: Scroll Animations	5 min	Quick demo of scroll-driven effects

Deep Dive

Resource	Why
ScrollTrigger Demos (CodePen)	Official CodePen collection — fork and experiment
Smashing Magazine: Practical Guide to ScrollTrigger	In-depth walkthrough with real examples

Tools

Tool	Use
ScrollTrigger Visualizer	Debug tool for complex scroll setups
GSAP CodePen Starter (ScrollTrigger)	Pre-configured starter for experimentation

Inspiration: Scrollytelling

Site	What to Notice
The Pudding	How data reveals through scroll — notice trigger vs. scrub choices
Apple AirPods Pro	Product scrub animations — scroll controls playback
How the Virus Got Out (NYT)	Map animation driven by scroll position
Boat (SBS Australia)	Graphic novel scrollytelling — atmospheric use of scroll

Cheat Sheet: ScrollTrigger

// REGISTER PLUGIN (once, at top of file)
gsap.registerPlugin(ScrollTrigger);

// BASIC: trigger-and-play
gsap.from('.element', {
  opacity: 0, y: 30,
  scrollTrigger: {
    trigger: '.section',       // element to watch
    start: 'top 80%',          // when to start
    markers: true              // debugging (remove for prod!)
  }
});

// TIMELINE with ScrollTrigger
const tl = gsap.timeline({
  scrollTrigger: {
    trigger: '.section',
    start: 'top 75%',
  }
});
tl.from('.heading', { opacity: 0, y: 30 })
  .from('.text', { opacity: 0, y: 20 }, '-=0.2');

// SCRUB: animation linked to scroll
gsap.to('.element', {
  x: 200,
  scrollTrigger: {
    trigger: '.section',
    start: 'top center',
    end: 'bottom center',
    scrub: 1,                  // 1s smoothing
  }
});

// START/END VALUES
'top 80%'      // trigger top at 80% of viewport
'top center'   // trigger top at viewport center
'top top'      // trigger top at viewport top (pinning)
'center center' // trigger center at viewport center
'bottom bottom' // trigger bottom at viewport bottom

// BATCH (animate many similar sections)
gsap.utils.toArray('.section').forEach(section => {
  gsap.from(section.querySelector('h2'), {
    opacity: 0, y: 30,
    scrollTrigger: { trigger: section, start: 'top 80%' }
  });
});

Week 8: The Scroll

week-8/week-overview.md

Week 8: The Scroll

Unit 2: Teaching Through Story Interaction Question: How does scroll become your storytelling medium?

Cohort Focus (Current Run)

This week is intentionally lean to protect build time and debugging time.

Checkpoints

Monday target: Full HTML/CSS site, deployed in a new repo, story draft at 90%
Wednesday target: GSAP motion implemented across the full story, story writing complete
End of week target: ScrollTrigger pass started and stable on core sections

Use These Docs First

Instructor run-of-show: resources/scrolltrigger-lecture-plan.md
Student checklist: ../week-9/resources/project-2-implementation-checklist.md
Instructor execution map: ../project-2-instructor-execution-plan.md

Workload Guardrail

No extra busywork deliverables this week beyond what moves the shipped site forward.

Learning Outcomes

By the end of this week, students will be able to:

Load the ScrollTrigger plugin and register it with GSAP
Convert existing GSAP animations to scroll-triggered animations
Configure trigger, start, and end parameters for precise scroll control
Use markers: true for debugging scroll trigger positions
Implement scrub to link animation progress to scroll position
Calibrate scroll pacing to match reading speed
Disable scroll animations for prefers-reduced-motion users

Two-Day Breakdown

Day 1: Scroll as Trigger

Duration: 90 minutes

Time	Activity	Description
0:00	Opening	Demo: scroll through a site where elements appear on scroll. "Last week everything played at once. Now it responds to you."
0:10	ScrollTrigger Concept	Scroll position as a timeline. The page is a playback device. Show the mental model.
0:20	Setup	Load ScrollTrigger via CDN. `gsap.registerPlugin(ScrollTrigger)`.
0:30	Live Code: First ScrollTrigger	Take a `gsap.from()` and add `scrollTrigger: { trigger: '.section' }`. Show the magic.
0:40	Trigger, Start, End	What triggers the animation? When does it start? When does it end? Show markers.
0:55	Break	—
1:05	Practice Start	Students convert their section animations to scroll-triggered. Add markers. Adjust start/end.
1:35	Closing	Homework: finish converting all sections, start experimenting with scrub

Deliverables assigned:

Learn 8-1: Scroll as Medium (before Day 2)
Practice 8-1: The Scroll (start in class, due before Day 2)

Day 2: Scrub + Pacing

Duration: 90 minutes

Time	Activity	Description
0:00	Opening	Side-by-side: animation that triggers-and-plays vs. animation that scrubs with scroll. "Feel the difference."
0:10	Scrub Deep Dive	`scrub: true` vs `scrub: 1` (smoothing). When to use each. How scrub turns scroll into a slider.
0:25	Live Code: Scrubbed Section	Build a section where elements progress with scroll — text fades in, images scale, colors shift.
0:40	Pacing Workshop	"Test: can someone read the text before it scrolls away?" Students swap laptops and test each other's scroll pacing.
0:55	Break	—
1:05	Scrollytelling Examples Analysis	Look at 2-3 professional scrollytelling pieces. Identify: trigger-and-play vs. scrubbed sections. When do they use each?
1:20	Work Time	Students refine scroll triggers, add scrub to at least 1 section, remove markers.
1:35	Closing	Preview: "Next week: pinning — locking a section in place while content animates inside it."

Deliverables assigned:

Build 8-1: The Story Flows (all sections scroll-triggered, due Sunday)
Reflect 8-1: Visual Notes (scroll timeline map, due Sunday)

Activities

Type	Activity	Points	Due
Learn 8-1	Scroll as Medium	—	Before Day 2
Practice 8-1	The Scroll	10	Before Day 2
Build 8-1	The Story Flows	10	Sunday
Reflect 8-1	Visual Notes	10	Sunday

See learn/, practice/, build/, and reflect/ folders for activity files.

Required For Current Run

To keep workload focused, prioritize these items:

Required: practice/practice-8-1-the-scroll.md
Required: GSAP + writing completion target from ../week-9/resources/project-2-implementation-checklist.md (Checkpoint 2)
Optional if time is tight: learn/learn-8-1-scroll-as-medium.md
Optional if time is tight: reflect/reflect-8-1-visual-notes.md

If needed, collect one checklist snapshot instead of multiple separate progress artifacts this week.

Topics Covered

Concept	Depth	Notes
ScrollTrigger plugin	Deep	Loading, registering, basic config
`trigger`	Hands-on	Which element triggers the animation
`start` / `end`	Hands-on	When animation begins/ends relative to viewport
`markers`	Practical	Debugging tool — shows trigger positions
`scrub`	Deep	Linking animation progress to scroll position
Scroll pacing	Conceptual	Reading speed vs. scroll speed
toggleActions	Practical	What happens on enter/leave/re-enter

Project Milestone

Project 2: "The Long Way Down" — Week 8 checkpoint

ScrollTrigger plugin loaded and registered
ALL sections have scroll-triggered animations
trigger element correctly set for each section
start and end values calibrated (not default)
At least 1 section uses scrub for progress-linked animation
Markers removed for production
prefers-reduced-motion disables all scroll animations
Pacing tested with a partner

Assigned Reading/Tutorials

Resource	Type	Required
ScrollTrigger Getting Started	Docs	Yes
GSAP ScrollTrigger Tutorial	Video (10 min)	Yes

Key Vocabulary

Term	Definition
ScrollTrigger	GSAP plugin that triggers animations based on scroll position
trigger	The element whose position in the viewport triggers the animation
start	When the animation starts — e.g., `"top 80%"` means "when trigger's top hits 80% down the viewport"
end	When the animation ends — defines the scroll range
markers	Visual debugging aids showing trigger start/end positions
scrub	Links animation progress to scroll progress — scroll forward = animate forward, scroll back = animate back
toggleActions	Four actions for: onEnter, onLeave, onEnterBack, onLeaveBack

Common Struggles & Solutions

Struggle	Solution
ScrollTrigger not working	Check: is the plugin loaded after GSAP and before your script? Did you call `gsap.registerPlugin(ScrollTrigger)`?
Animation triggers too early or too late	Use `markers: true` to see exactly where triggers fire. Adjust `start` and `end` values.
Scrub feels janky	Use `scrub: 1` instead of `scrub: true`. The number adds smoothing (in seconds).
Can't see markers	They're tiny labels at the right edge of the viewport. Scroll slowly and look for green/red lines.
Animation plays but doesn't reverse on scroll back	For scrub animations, this happens automatically. For trigger-and-play, set `toggleActions: "play none none reverse"`.
Page is really long and performance drops	Simplify animations. Use fewer properties per tween. Avoid animating `box-shadow` or `filter` on scroll.

Code Patterns Introduced

Loading ScrollTrigger

<!-- In HTML, after GSAP, before your script -->
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/ScrollTrigger.min.js"></script>
<script src="scripts/main.js"></script>

Registering the Plugin

gsap.registerPlugin(ScrollTrigger);

Basic Scroll-Triggered Animation

gsap.from('#variables h2', {
  opacity: 0,
  y: 30,
  duration: 0.8,
  ease: 'power2.out',
  scrollTrigger: {
    trigger: '#variables',
    start: 'top 80%',     // when section top hits 80% of viewport
    markers: true          // remove for production!
  }
});

Timeline with ScrollTrigger

const sectionTl = gsap.timeline({
  scrollTrigger: {
    trigger: '#the-switch',
    start: 'top 75%',
    end: 'bottom 25%',
    markers: true
  }
});

sectionTl
  .from('#the-switch h2', { opacity: 0, y: 30, duration: 0.6 })
  .from('#the-switch p', { opacity: 0, y: 20, duration: 0.5 }, '-=0.2')
  .from('#the-switch .visual', { opacity: 0, scale: 0.9, duration: 0.5 });

Scrubbed Animation

gsap.to('#the-system .progress-bar', {
  width: '100%',
  ease: 'none',
  scrollTrigger: {
    trigger: '#the-system',
    start: 'top center',
    end: 'bottom center',
    scrub: 1,              // smooth scrubbing (1 second lag)
    markers: true
  }
});

Complete Pattern with Reduced Motion

gsap.registerPlugin(ScrollTrigger);

const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

if (!prefersReducedMotion) {
  // Hero (no scroll trigger — plays on load)
  const heroTl = gsap.timeline();
  heroTl
    .from('.hero__title', { opacity: 0, y: 40, duration: 0.8, ease: 'power2.out' })
    .from('.hero__subtitle', { opacity: 0, y: 20, duration: 0.6 }, '-=0.4');

  // Each section — scroll triggered
  gsap.utils.toArray('.section--chapter').forEach(section => {
    gsap.from(section.querySelectorAll('h2, p'), {
      opacity: 0,
      y: 30,
      duration: 0.6,
      stagger: 0.15,
      ease: 'power2.out',
      scrollTrigger: {
        trigger: section,
        start: 'top 80%',
      }
    });
  });
}

Accessibility Focus

ScrollTrigger animations must be wrapped in the same prefers-reduced-motion check
When reduced motion is enabled: content should appear immediately (no animation, but content is visible)
Test: enable "Reduce Motion" in System Settings → Accessibility, reload your site. All content should be visible and readable.
Scrubbed animations especially need reduced-motion handling — content shouldn't be locked behind scroll progress

Connections

Connects To	How
Week 7	GSAP animations become scroll-triggered
Week 9	ScrollTrigger expanded with pinning and parallax
Week 6	CSS fallbacks still work when JS/motion disabled
Project 2	This is the core technology of the final deliverable

Instructor Notes

The "trigger-and-play → scrub" progression is key. Start simple (trigger fires, animation plays), then show scrub as the mind-bending moment.
Markers are the most important debugging tool. Insist students use them during development.
The pacing workshop (Day 2) is critical. Students need to feel each other's sites to understand that scroll speed ≠ reading speed.
Common confusion: start: "top 80%" means "when the TOP of the trigger element reaches 80% from the TOP of the viewport." Draw this on the board.
The gsap.utils.toArray().forEach() pattern is powerful but might confuse students who haven't seen .forEach(). Explain it as "do this for each section" without diving deep into array methods.
Remove markers before submission! Students will forget. Remind them.

Materials Checklist

ScrollTrigger CDN link tested
Learn 8-1: Scroll as Medium (learn/learn-8-1-scroll-as-medium.md)
Practice 8-1: The Scroll (practice/practice-8-1-the-scroll.md)
Build 8-1: The Story Flows (build/build-8-1-the-story-flows.md)
Reflect 8-1: Visual Notes (reflect/reflect-8-1-visual-notes.md)
Resources page updated
Scrollytelling analysis examples selected
Trigger position diagram ready (whiteboard or slides)

Build: The Story Flows

week-9/build/build-9-1-the-story-flows.md

Build: The Story Flows

Points: 10 (Complete/Incomplete) Time Estimate: 60–90 minutes Prerequisite: Practice 8-1: The Scroll

TL;DR

All sections scroll-triggered. At least one uses scrub. Pacing tested. Markers removed.

Submit

Push to GitHub
Submit GitHub Pages URL to Canvas

Overview

Your scrollytelling site is becoming real. This week's build turns it from "a page with animations" into "a story that unfolds as you scroll." The difference is pacing, trigger placement, and the right mix of trigger-and-play vs. scrubbed animations.

What You're Doing

Step 1: Convert ALL Remaining Sections

Every section of your site should now have scroll-triggered animations. Use the pattern from Practice 8-1.

Efficient approach: If most sections animate the same way (fade-in headings and paragraphs), batch them:

if (!prefersReducedMotion) {
  // Hero — plays on load (no ScrollTrigger)
  const heroTl = gsap.timeline();
  heroTl
    .from('.hero__title', { opacity: 0, y: 40, duration: 0.8, ease: 'power2.out' })
    .from('.hero__subtitle', { opacity: 0, y: 20, duration: 0.6 }, '-=0.4');

  // All chapter sections — scroll-triggered
  gsap.utils.toArray('.section--chapter').forEach(section => {
    const tl = gsap.timeline({
      scrollTrigger: {
        trigger: section,
        start: 'top 80%',
      }
    });

    tl.from(section.querySelector('h2'), {
      opacity: 0, y: 30, duration: 0.6, ease: 'power2.out'
    });

    tl.from(section.querySelectorAll('p'), {
      opacity: 0, y: 20, duration: 0.5, stagger: 0.15
    }, '-=0.2');
  });
}

Then customize specific sections with unique animations.

Step 2: Add Scrub to Your Best Section

Pick the section that deserves the most attention — the one where you want the reader to slow down and feel the content. Add scrub:

const systemTl = gsap.timeline({
  scrollTrigger: {
    trigger: '#the-system',
    start: 'top center',
    end: 'bottom center',
    scrub: 1,
  }
});

systemTl
  .from('#the-system h2', { opacity: 0, y: 20 })
  .from('#the-system .token-list', { opacity: 0, x: -30 })
  .from('#the-system .visual', { scale: 0.8, opacity: 0 });

Step 3: Test Pacing

The reading test: Open your site. Scroll at a natural reading pace. For each section, ask:

Can I read all the text before the next section starts?
Does the animation help me understand the content, or distract from it?
Is there enough "breathing room" between sections?

If scrolling feels exhausting, your sections might be too dense or your animations too aggressive.

Step 4: Remove Markers

Delete every markers: true from your code. They're debugging tools — they don't belong in production.

Step 5: Final Content Check

Read through your entire site top to bottom. Fix any:

Typos or unclear explanations
Missing content in any section
Metaphor inconsistencies (does it hold all the way through?)
Broken visual assets

Complete Criteria

ALL sections have scroll-triggered animations
At least 1 section uses scrub
start values are calibrated per section (not all "top 80%")
ALL markers removed
prefers-reduced-motion wraps all animation code
Content complete and proofread
Pushed to GitHub, live on Pages

Common Issues

Q: My forEach loop doesn't work. A: document.querySelectorAll() returns a NodeList, not an array. Use gsap.utils.toArray() instead — it handles the conversion.

Q: Scrub animation feels disconnected from content. A: The scroll range might be too wide. Tighten start and end so the animation happens while the content is in view. Use "top center" to "bottom center" as a starting point.

Q: Some sections look better without animation. A: That's fine. Not every section needs to animate. A simple fade-in is enough for some sections. The closing section especially might benefit from being still.

Connection to This Week

After this build, your site is a functional scrollytelling piece. Next week you'll add the "showpiece" — a pinned section where the viewport locks and content animates within it. Think about which section deserves that treatment.

Engage: Peer Review

week-9/engage/engage-9-1-peer-review.md

Engage: Peer Review

Points: 10 (Complete/Incomplete) Time Estimate: 30 minutes (in-class)

TL;DR

Swap sites with a partner. Test. Give structured feedback. Receive feedback. Document it.

Submit

Submit your completed feedback form for your partner's site (Canvas)
Note the 2 changes you'll make based on feedback you received

The Protocol

Setup (2 minutes)

Pair up with someone you haven't worked with recently
Open each other's GitHub Pages URL on YOUR device (not theirs)
Have the feedback form ready (below)

Round 1: Review Partner's Site (15 minutes)

Scroll through their site at your own pace. Then fill out the feedback form:

Feedback Form:

Question	Your Answer
1. What's the metaphor? Can you explain it in one sentence?
2. Where did you feel confused or lost? (Be specific — which section?)
3. Where did you feel delight? What moment made you go "oh, nice"?
4. Is the scroll pacing comfortable? Too fast? Too slow? Which sections?
5. Does the pinned section work? What's the effect?

Accessibility Tests:

Test	Pass?	Notes
Tab through the entire site — can you reach all content?	Y/N
Enable Reduce Motion (System Settings → Accessibility) — is all content visible?	Y/N
Is text readable against backgrounds? Any contrast issues?	Y/N

One Thing to Keep: What's the strongest part of this site?

One Thing to Change: What would have the biggest impact if improved?

Round 2: Swap Roles (15 minutes)

Now your partner reviews YOUR site using the same form.

Debrief (2 minutes)

Tell your partner:

The 2 changes you plan to make based on their feedback
One thing that surprised you about their feedback

Why This Matters

Your site has lived in your head for 4 weeks. You know what every section means because you wrote it. A fresh pair of eyes tells you what ACTUALLY communicates — and what only makes sense to you.

The best work survives contact with an audience.

Evaluation

Criteria	Points
Feedback form completed for partner's site	5
2 planned changes documented based on received feedback	3
Accessibility tests performed	2

Practice: The Deep

week-9/practice/practice-9-1-the-deep.md

Practice: The Deep

Points: 10 Time Estimate: 45–60 minutes

TL;DR

Add a pinned "showpiece" section to your scrollytelling site. Optional: add parallax to a background element.

Submit

Push to GitHub
Submit GitHub Pages URL to Canvas

Overview

Pinning is the signature move of scrollytelling. The viewport locks. The scroll bar keeps moving. But instead of scrolling past, the section stays fixed while content changes within it. It's how Apple sells AirPods, how the NYT tells data stories, and how you're going to create the "whoa" moment in your site.

What You're Building

One pinned section in your scrollytelling site — the showpiece. Choose the section that deserves the most attention. This is where your metaphor hits hardest, where the concept clicks, where the reader slows down and pays attention.

Requirements

Core

One section pinned with pin: true
Timeline animates content while pinned (at least 3 content changes)
scrub linked to scroll (not trigger-and-play)
Scroll range appropriate (not too short, not exhausting)
Pin releases cleanly (no layout jump below)

Stretch Goals

Parallax effect on at least one background element
Multiple content "steps" within the pin (text swaps or image swaps)
Progress indicator showing position within pinned section
Horizontal scroll section

Step-by-Step

Step 1: Choose Your Showpiece Section

Look at your metaphor map. Which chapter is the turning point? The "aha" moment? That's your pinned section. For many students, "The System" (design tokens) or "The Switch" (first moment of control) are strong candidates.

Step 2: Restructure the HTML

Your pinned section needs internal "steps" — content that swaps or layers:

<section class="section section--pinned" id="the-system">
  <div class="pin-content">
    <div class="pin-step" id="step-1">
      <h2>First, you see the pieces</h2>
      <p>Colors. Fonts. Spacing values. Just raw ingredients...</p>
    </div>
    <div class="pin-step" id="step-2">
      <h2>Then you name them</h2>
      <p>Surface. Text. Accent. Suddenly they have purpose...</p>
    </div>
    <div class="pin-step" id="step-3">
      <h2>Then you see the system</h2>
      <p>Change one value. Everything updates. That's the power...</p>
    </div>
  </div>
</section>

Step 3: Style for Stacking

.section--pinned {
  position: relative;
  min-height: 100vh;
}

.pin-content {
  position: relative;
  width: 100%;
  height: 100vh;
}

.pin-step {
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  opacity: 0;
  max-width: 800px;
  text-align: center;
}

.pin-step:first-child {
  opacity: 1; /* first step visible by default */
}

Step 4: Build the Pin Timeline

if (!prefersReducedMotion) {
  const pinTl = gsap.timeline({
    scrollTrigger: {
      trigger: '#the-system',
      start: 'top top',
      end: '+=200%',        // pin for 2x viewport height of scroll
      pin: true,
      scrub: 1,
      markers: true         // remove before submission!
    }
  });

  // Step 1 is visible by default
  // Fade out step 1, fade in step 2
  pinTl
    .to('#step-1', { opacity: 0, duration: 0.5 })
    .from('#step-2', { opacity: 0, y: 20, duration: 0.5 })
    .to('#step-2', { opacity: 0, duration: 0.5 }, '+=0.5')
    .from('#step-3', { opacity: 0, y: 20, duration: 0.5 });
}

Step 5: Test the Scroll Range

Scroll through the pinned section. Ask:

Is there enough scroll to read each step?
Does the transition between steps feel smooth?
Does the pin release feel natural (no jarring jump)?

Adjust end: "+=200%" — make it larger for more scroll time, smaller for less.

Step 6: Add Parallax (Stretch)

For a background element that moves at a different speed:

gsap.to('.section__bg-image', {
  y: -80,
  ease: 'none',
  scrollTrigger: {
    trigger: '.section',
    start: 'top bottom',
    end: 'bottom top',
    scrub: true
  }
});

Evaluation

Criteria	Points
Pinned section working (pin: true, content animates)	4
At least 3 content changes within the pin	3
Scrub linked to scroll	2
Clean pin release (no layout issues)	1

Troubleshooting

Pinned section overlaps content below it: ScrollTrigger adds pin-spacing automatically. If it's not working, check for overflow: hidden on parent elements — that breaks pinning.

Content below the pin jumps when pin releases: This is usually a pin-spacing issue. Make sure you're not setting the section's height in CSS in a way that conflicts with ScrollTrigger's calculations.

Steps change too fast / too slow: Adjust end: "+=200%". More percentage = more scroll time. Also adjust the duration values in your timeline — they're relative to the total scroll range.

Pin works in Chrome but breaks in Safari: Add anticipatePin: 1 to your ScrollTrigger config. This helps Safari handle the pin transition.

Connection to Course

This is your last practice session. After this, you have the Build assignment to polish and deploy. Week 10 is presentations. Make the pinned section count — it's the moment that makes your site memorable.

Reflect: Visual Notes — Final Reflection

week-9/reflect/reflect-9-1-visual-notes.md

Reflect: Visual Notes — Final Reflection

Points: 10 (Complete/Incomplete) Time Estimate: 20 minutes

TL;DR

Final reflection on the project. What did you learn about storytelling through code?

Submit

Written or visual reflection uploaded to Canvas

The Prompt

This is the last Reflect of the project. Answer these questions — in writing, as a sketch, or as an annotated screenshot:

The Metaphor: Did your metaphor hold up? Did it change from what you planned in Week 5? How?
The Hardest Part: What was the most frustrating or challenging part of this project? How did you get past it?
The Best Part: What's your favorite section or moment in your site? Why?
The Code: Pick one code pattern you're proud of understanding (a timeline, a ScrollTrigger config, the reduced-motion check). Explain what it does in plain language.
The Growth: Look at your Week 0 visual notes. Compare what you knew then to what you know now. What's the biggest change?
If I Had More Time: What would you add, change, or refine?

Why This Matters

Week 10 presentations ask you to reflect out loud. This written reflection is your prep. The students who do this well present with confidence.

Evaluation

Criteria	Points
All 6 questions addressed	6
Honest and specific (not generic)	2
Code explanation is accurate	2

Project 2 Implementation Checklist (Week 8-10)

week-9/resources/project-2-implementation-checklist.md

Project 2 Implementation Checklist (Week 8-10)

Use this as the single source of truth for progress. Prioritize Must items first.

Checkpoint 1: Week 8 Monday (Structure Ready)

Must

Full HTML/CSS structure is built (all planned sections exist)
Site deployed in a new GitHub repo
Story draft is at least 90% complete

Should

Semantic structure in place (main, section, heading hierarchy)
Tokens are used consistently (no major hardcoded style drift)

Could

One section already has a simple GSAP entrance animation

Checkpoint 2: Week 8 Wednesday (Motion Foundation)

Must

Story is 100% written
GSAP motion implemented across hero + core story sections
prefers-reduced-motion guard is active for all GSAP code
No blocking console errors

Should

At least 2 easing values chosen intentionally for story tone
Motion pacing tested with one partner

Could

First ScrollTrigger section implemented and tuned with markers

Checkpoint 3: Week 9 Monday (Scroll Implementation)

Must

ScrollTrigger is registered and active
All major sections are scroll-triggered
At least one section uses scrub
Trigger timing is calibrated (start/end, not all defaults)

Should

One showpiece section starts using pin: true
Partner can read content comfortably at normal scroll pace

Could

Simple parallax layer added to one section

Checkpoint 4: Week 9 Wednesday (Debug + Polish)

Must

Pinned showpiece section works without layout jumps
Markers removed in production build
Accessibility pass complete (keyboard, contrast, reduced motion)
Site is deployed and current on GitHub Pages

Should

Lighthouse check completed (Performance + Accessibility)
README updated with metaphor and tech stack

Could

Optional polish (progress indicator, extra section transitions)

Final Readiness: Week 10 Presentation

Must

Live site URL works from a clean browser session
Portfolio links to the project
Student can explain one section's HTML + GSAP + ScrollTrigger code
Student can explain at least one bug they solved and how

Should

5-7 minute presentation flow rehearsed once

Debug Priority Order (When Time Is Tight)

Shipping blockers (deploy broken, JS crashing, unreadable content)
Accessibility blockers (reduced motion, keyboard, contrast)
Story clarity + pacing issues
Visual polish and stretch features

Week 9 Resources: The Deep

week-9/resources/week-9-resources.md

Week 9 Resources: The Deep

Assigned (Before Day 1)

Resource	Type	Time
GreenSock: ScrollTrigger Pinning	Video (pin section)	8 min
Study one pinned section on Apple AirPods Pro page	Analysis	7 min

Reference

Resource	Why
ScrollTrigger pin docs	Official pin reference
WebAIM Contrast Checker	WCAG AA/AAA contrast testing
Lighthouse (Chrome DevTools)	Performance + accessibility auditing

Video

Resource	Time	Why
GSAP: Advanced ScrollTrigger	15 min	Pinning, parallax, horizontal scroll — comprehensive
Kevin Powell: Parallax Scrolling	10 min	CSS and JS parallax approaches, designer-friendly

Deep Dive

Resource	Why
ScrollTrigger Demos (CodePen)	Official demo collection — study pinning patterns
Inclusive Components by Heydon Pickering	Accessible interaction patterns reference
Squoosh.app	Image compression tool for performance optimization

Inspiration: Advanced Scrollytelling

Site	What to Notice
Apple AirPods Pro	Multiple pinned sections with scrubbed 3D animation
Femme Fatale	Horizontal scroll + pinning
Active Theory	Aggressive pinning — notice when it feels good vs. exhausting
The Boat (SBS)	Pinned graphic novel panels — atmospheric scroll pacing

Cheat Sheet: Pinning + Parallax

// PINNING: lock section, animate content within
const pinTl = gsap.timeline({
  scrollTrigger: {
    trigger: '#section',
    start: 'top top',        // pin when section reaches viewport top
    end: '+=200%',           // pin for 2x viewport height of scroll
    pin: true,               // lock the section
    scrub: 1,                // link to scroll
    anticipatePin: 1,        // helps Safari
  }
});

pinTl
  .from('.step-1', { opacity: 0, y: 20 })
  .to('.step-1', { opacity: 0 }, '+=0.3')
  .from('.step-2', { opacity: 0, y: 20 });

// PARALLAX: background moves slower than foreground
gsap.to('.bg-image', {
  y: -100,                   // moves up 100px over scroll range
  ease: 'none',
  scrollTrigger: {
    trigger: '.section',
    start: 'top bottom',
    end: 'bottom top',
    scrub: true,             // true = no smoothing
  }
});

// HORIZONTAL SCROLL (stretch goal)
const track = document.querySelector('.h-track');
gsap.to(track, {
  x: () => -(track.scrollWidth - window.innerWidth),
  ease: 'none',
  scrollTrigger: {
    trigger: '#h-section',
    start: 'top top',
    end: () => '+=' + track.scrollWidth,
    pin: true,
    scrub: 1,
  }
});

Week 9: The Deep

week-9/week-overview.md

Week 9: The Deep

Unit 2: Teaching Through Story Interaction Question: What separates good from great?

Cohort Focus (Current Run)

Week 9 is a checklist and debugging week, not a "new busywork" week.

Checkpoints

Monday target: Full ScrollTrigger implementation in place + showpiece pin started
Wednesday target: Debugged, polished, and deployment ready
End of week target: Final site ready for Week 10 showcase

Use This Checklist As Source Of Truth

resources/project-2-implementation-checklist.md

In-Class Priority

Most class time should be implementation and blocker removal, with short, focused demos only.

Learning Outcomes

By the end of this week, students will be able to:

Implement a pinned ScrollTrigger section that locks in the viewport while content animates
Create parallax effects using different scroll speeds on layered elements
Conduct structured peer review of a scrollytelling site
Test for accessibility: keyboard navigation, reduced motion, color contrast
Optimize animation performance using Lighthouse and DevTools
Deploy a production-ready site to GitHub Pages
Identify and fix common scroll-animation bugs (layout shifts, z-index issues, pin spacing)

Two-Day Breakdown

Day 1: Pinning + Parallax

Duration: 90 minutes

Time	Activity	Description
0:00	Opening	Show a pinned section from a professional site. "The viewport stops. The content keeps moving. That's pinning."
0:10	Pinning Explained	How `pin: true` works. The section locks in place. ScrollTrigger adds space for the scroll range. `start: "top top"`, `end: "+=100%"`.
0:25	Live Code: Pinned Section	Build a pinned section with content that animates within it — text fades in/out, images swap, progress bar fills.
0:45	Parallax Concept	Layers moving at different speeds create depth. Simple technique: different `y` offsets at different scroll rates.
0:55	Break	—
1:05	Practice Start	Students add one pinned section to their site. Choose which section is the "showpiece." Optional: add parallax to a background.
1:35	Closing	Homework: refine pinned section, prepare for peer review Day 2

Deliverables assigned:

Practice 9-1: The Deep (start in class, due before Day 2)

Day 2: Peer Review + Polish

Duration: 90 minutes

Time	Activity	Description
0:00	Opening	"Your site is built. Now it needs another pair of eyes."
0:05	Peer Review Protocol	Walk through the feedback form. What to look for: clarity, pacing, metaphor, accessibility, delight.
0:15	Engage: Peer Review	Swap with a partner. 15 minutes to scroll through, test, and fill out feedback form. Then swap roles.
0:45	Break	—
0:55	Feedback Debrief	What surprised you? What common issues appeared? Quick group discussion.
1:05	Polish Workshop	Remaining time: address peer feedback, performance pass (Lighthouse), final content edit.
1:30	Closing	Final build due Sunday. Presentation prep for Week 10.

Deliverables assigned:

Build 9-1: The Refinement (final polish + deploy, due Sunday)
Engage 9-1: Peer Review (in-class)
Reflect 9-1: Visual Notes (final reflection, due Sunday)

Activities

Type	Activity	Points	Due
Learn 9-1	Scrollytelling Craft	—	Before Day 1
Practice 9-1	The Deep	10	Before Day 2
Engage 9-1	Peer Review	10	Day 2
Build 9-1	The Refinement	10	Sunday
Reflect 9-1	Visual Notes	10	Sunday

See learn/, practice/, build/, engage/, and reflect/ folders for activity files.

Required For Current Run

To preserve debugging time, keep Week 9 requirements lean:

Required: build/build-9-1-the-refinement.md
Required: engage/engage-9-1-peer-review.md
Required: Checklist completion in resources/project-2-implementation-checklist.md (Checkpoint 4)
Optional if time is tight: learn/learn-9-1-scrollytelling-craft.md
Optional if time is tight: reflect/reflect-9-1-visual-notes.md

Topics Covered

Concept	Depth	Notes
ScrollTrigger `pin`	Deep	Pinned sections, pin-spacing, layout implications
Parallax scrolling	Practical	Layered y-offsets at different speeds
Horizontal scroll	Exposure	Shown as stretch goal, not required
Performance optimization	Practical	Lighthouse, will-change, GPU layers
Peer review	Structured	Feedback form with specific criteria
Cross-browser testing	Practical	Chrome, Firefox, Safari quick check
Deployment	Practical	GitHub Pages, clean URLs

Project Milestone

Project 2: "The Long Way Down" — Week 9 checkpoint (FINAL before submission)

At least 1 pinned section ("showpiece" moment)
Peer review completed and feedback documented
Peer feedback addressed (at least 2 changes based on feedback)
prefers-reduced-motion fully implemented
Keyboard navigable (Tab through all sections)
Color contrast passing WCAG AA
Semantic HTML verified (heading hierarchy, landmarks)
Markers removed
Performance: no major jank or lag
Deployed to GitHub Pages
Linked from portfolio

Key Vocabulary

Term	Definition
Pinning	Locking a section in the viewport while scroll-linked content animates within it
Pin-spacing	Extra space ScrollTrigger adds to the page to accommodate the pinned section's scroll range
Parallax	Layers moving at different speeds to create a sense of depth
Lighthouse	Chrome DevTools audit tool for performance, accessibility, best practices
GPU acceleration	Using the graphics card for animation — triggered by `transform` and `opacity`
will-change	CSS hint that tells the browser to optimize an element for upcoming changes
Peer review	Structured feedback from a classmate focused on specific criteria

Common Struggles & Solutions

Struggle	Solution
Pinned section breaks layout below it	ScrollTrigger adds `pin-spacing` automatically. If layout shifts, check for elements with `position: fixed` or `z-index` conflicts.
Pinned section is the wrong height	Adjust `end: "+=100%"` — this means "pin for 100% of viewport height of scroll." Change the percentage to adjust scroll range.
Parallax looks choppy	Use `scrub: 1` for smoothing. Reduce the Y offset. Simpler parallax performs better.
Peer feedback is vague	Guide students: "Don't say 'it's good.' Say 'I got confused at section 3 because the metaphor shifted.' Be specific."
Lighthouse score is low	Common fixes: compress images, remove unused CSS, add `loading="lazy"` to images below the fold.
Site looks different in Safari	ScrollTrigger generally handles cross-browser, but test pinned sections in Safari specifically. Some CSS transforms render differently.

Code Patterns Introduced

Pinned Section

const showpieceTl = gsap.timeline({
  scrollTrigger: {
    trigger: '#the-system',
    start: 'top top',
    end: '+=150%',          // pin for 1.5x viewport height of scroll
    pin: true,
    scrub: 1,
  }
});

// Content animates while pinned
showpieceTl
  .from('#the-system .step-1', { opacity: 0, y: 30 })
  .to('#the-system .step-1', { opacity: 0 }, '+=0.5')
  .from('#the-system .step-2', { opacity: 0, y: 30 })
  .to('#the-system .step-2', { opacity: 0 }, '+=0.5')
  .from('#the-system .step-3', { opacity: 0, y: 30 });

Simple Parallax

gsap.to('.section__bg', {
  y: -100,
  ease: 'none',
  scrollTrigger: {
    trigger: '.section',
    start: 'top bottom',
    end: 'bottom top',
    scrub: true,
  }
});

Horizontal Scroll (Stretch Goal)

const horizontal = gsap.timeline({
  scrollTrigger: {
    trigger: '#horizontal-section',
    start: 'top top',
    end: () => '+=' + document.querySelector('.horizontal-track').scrollWidth,
    pin: true,
    scrub: 1,
  }
});

horizontal.to('.horizontal-track', {
  x: () => -(document.querySelector('.horizontal-track').scrollWidth - window.innerWidth),
  ease: 'none'
});

Accessibility Focus

This is the full audit week. Before submission, check:

Keyboard: Tab through the entire site. Can you reach all content?
Reduced motion: Enable "Reduce Motion" in System Settings. Is all content visible? No animation?
Color contrast: Run a contrast checker on all text/background pairs from your tokens
Semantic HTML: Check heading hierarchy (h1 → h2 → h3, no skipping)
Landmarks: <main>, <section>, <header> present?
Screen reader test: Turn on VoiceOver (Cmd+F5 on Mac). Navigate by headings. Does the content make sense?

Connections

Connects To	How
Week 7	GSAP timelines now used inside pinned sections
Week 8	ScrollTrigger config extended with pin and parallax
Week 10	This is the last build week — Week 10 is presentation
Project 2	Final submission due Sunday

Instructor Notes

Pinning is the "wow" moment of the course. Demo it well on Day 1.
The peer review protocol needs to be STRUCTURED. Without guidance, students say "it looks good" and learn nothing. The feedback form is essential.
Some students will be behind. That's okay — the peer review still helps them identify priorities.
Horizontal scroll is a stretch goal. Only advanced students should attempt it. Pin-spacing math is tricky.
The accessibility audit is real, not performative. Walk students through VoiceOver briefly if they've never used it.
Remind students: markers off, site deployed, linked from portfolio. These are easy points to lose.

Materials Checklist

Pinning demo file prepared
Parallax example ready
Peer review feedback form printed/shared
Learn 9-1: Scrollytelling Craft (learn/learn-9-1-scrollytelling-craft.md)
Practice 9-1: The Deep (practice/practice-9-1-the-deep.md)
Engage 9-1: Peer Review (engage/engage-9-1-peer-review.md)
Build 9-1: The Refinement (build/build-9-1-the-refinement.md)
Reflect 9-1: Visual Notes (reflect/reflect-9-1-visual-notes.md)
Resources page updated

Project 2: Lost in the Scroll Project

Project 2: Lost in the Scroll

Overview

Chapters vs. Tools

Chapters (The Story Beats)

Tools Along the Way

What You're Building

Requirements

The Metaphor

Design System

Content & Structure

CSS Motion (Week 6)

GSAP Animation (Week 7)

ScrollTrigger (Week 8)

Advanced Scroll (Week 9)

Accessibility

Metaphor Options

1. The Kitchen

2. The Garden

3. The Map

4. The Mixtape

Discover Your Own

Progressive Build Schedule

Evaluation

Exemplary Work

Common Pitfalls

Submission

Starter Structure

Connection to Course

Stretch Goals

Resources

ScrollTelling Inspiration

GSAP & ScrollTrigger

Design Systems

Accessibility

Project Brief: Lost in the Scroll

The Idea

Chapters vs. Tools

Chapters (The Story Beats)

Tools Along the Way

What You're Making

How We'll Build It

Finding Your Metaphor

Evaluation

What Exemplary Work Looks Like

Starter Structure

Final Submission (Week 10)

Resources

Start Here

Primary Resource

Why We Are Using Issues

What To Do First

Step 1: Run the Issue Setup Automation

Step 2: Review the Created Issues

Step 3: Use the Automation Again If You Need To Sync Open Issues

Step 4: Start Building

Step 5: Final Verification

Rule Of Focus

Project 2 Completion Checklist (Reference)

Required Submission Links

Build + Story

Motion + Scroll

Scroll Feel

Design + Theme

Assets

Accessibility + QA

README (Project Documentation + Reflection)

Final Turn-In Specification

1) Required Submission Links

2) Core Build Requirements

Story + Structure

ScrollTrigger

ScrollSmoother

GSAP Motion

Design System + Theme

Visual Assets

3) Accessibility + Quality

4) Testing Requirements

4b) Issue Tracking Requirements

5) README (Project Documentation + Reflection)

Step 1: Run `Setup Project Issues`

Step 3: Re-Run in `sync_open` Mode When Needed