taste-gsap
GSAP implementation craft for agent-built sites: timeline architecture, gsap.context and matchMedia, ScrollTrigger pin and scrub hygiene, SplitText discipline, transform-only animation, refresh-after-fonts, and full prefers-reduced-motion gating. The 90% of award-tier motion is structure, not effects — this is that 90%. Use whenever generating GSAP animation code. Stack on the design-taste core skill and taste-motion.
How do I install this agent skill?
npx skills add https://github.com/madebymustafa/design-taste --skill taste-gsapIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides architectural and performance guidelines for implementing GSAP animations in web projects. It emphasizes accessibility, mobile optimization, and performance best practices. No security issues were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
taste-gsap
GSAP is a scalpel, not a glitter gun. One clean pinned section beats nine parallax layers — and survives a code review.
1. ARCHITECTURE (The Non-Negotiable Shell)
- Wrap every page's animations in a single
gsap.context(() => { ... }, rootElement)— it scopes selectors and gives you instant teardown. - Gate everything through
gsap.matchMedia():(prefers-reduced-motion: no-preference)— all animation lives here. Reduced-motion users get the static, complete page.(min-width: 768px)— heavy effects (pins, scrubs, per-character splits) desktop-only; small screens get fades or nothing.
- The matchMedia callback returns a cleanup function; on SPAs, call
ctx.revert()on unmount. - One timeline per section, named by section; never one giant global timeline with 40 tweens.
- Lenis (free, not ScrollSmoother):
new Lenis({ duration: ~1.1, anchors: true }), pipe it to ScrollTrigger withlenis.on("scroll", ScrollTrigger.update)+gsap.ticker.add(t => lenis.raf(t * 1000))+gsap.ticker.lagSmoothing(0).lenis.stop()during the preloader,lenis.start()after. Never smooth-scroll under reduced motion.
2. PIN & SCRUB HYGIENE (Where Agents Fail Loudest)
- Max two pinned sections per page. Every pin costs the scroll thread. Two is the budget; one is the norm.
- Pins:
pin: true, pinSpacing: true(default — keep it),start: "top top",end: "+=200%"to"+=300%". Longer ends = slower scrub = more jank on mobile. - Horizontal galleries (the signature Awwwards move): pin the section, translate the track (
xonly, neverleft),end: () => "+=" + (track.scrollWidth - innerWidth)so the distance recalculates on resize,scrub: 1, desktop-only. Nativeoverflow-x+ scroll-snap must remain as the no-JS / reduced-motion fallback. - Drag carousels (Magma-school):
Draggable.create(track, { type: "x", inertia: true, bounds: () => ({ minX: -(track.scrollWidth - wrap.offsetWidth), maxX: 0 }) })— bounds as a function so it recalibrates on resize.edgeResistance~0.9, nativeoverflow-x+ snap as the no-JS fallback, and a cursor/UI hint that the strip is draggable. scrub: 0.6–1on heavy sections;scrub: trueonly on trivial tweens. A scrubbed tween without smoothing fights the scroll.- Never pin inside another pin; never start a second pin before the first's spacer ends.
ScrollTrigger.refresh()after fonts/images (window.load+document.fonts.ready) or everything misaligns. - Test pins at 768px width before shipping — pinned sections that trap mobile users are a bug, not a feature (this is why pins live in the
(min-width: 768px)gate). invalidateOnRefresh: trueon refresh-dependent triggers so re-layouts don't drift.
3. WHAT TO ANIMATE (Transform and Opacity Only)
- Animate
x,y,scale,rotation,opacity— nevertop/left/width/height/margin/filter(layout thrash = jank). - Text reveals: line-level splits (
overflow: hiddenwrapper +yPercent: 110→ 0) by default. Character-level only for hero headlines, and only inside the desktop gate. - No
will-changespam — set it on the animated element's wrapper while animating, remove after (or let GSAP manage it). Everywill-changeis a memory promise. - Keep 60fps honesty: no 200-element stagger in one frame, no scrubbing 40 DOM properties. Batch with
gsap.utils.toArrayand stagger — one tween, many targets, cheap.
4. REVEAL PATTERNS (The Professional's Defaults)
- From-states stay in code, not CSS: elements start visible in CSS;
gsap.from(...)withimmediateRender: trueinside the matchMedia gate hides them only when JS + motion are active. If GSAP never loads, the page is complete — this is the safety contract. - Standard reveal:
opacity: 0, y: 40, duration: 0.9, ease: "power3.out", triggertop 82%,once: truefor content sections. - Hero intro: a
gsap.timeline()on load — 80–120ms stagger between elements,ease: "expo.out"orpower4.out, total under 1.4s. The page is a story with a first line, not a slideshow. - Count-ups: tween a proxy object (
gsap.to(obj, { v: target })), writeel.textContentinonUpdate,snapoptional.once: trueon the trigger.
5. THE FULL STACK OF SINS (Each Is a Fail)
- Scroll-jacking the wheel without a smooth-scroll layer (Lenis) and then not testing it — native scroll is a feature.
- Animations that trigger before the content exists (missing
ScrollTrigger.refresh()). - Infinite marquees that aren't paused under reduced motion — kill them in CSS with
@media (prefers-reduced-motion: reduce)too, not just in JS. - Autoplaying anything: hero video, accordions, carousels that move without input. Awwwards confidence is stillness between moments.
- A page whose "wow" depends on animation: if the still screenshot is boring, the animation is makeup, not design.
6. CHECKLIST (Fail the Animation If…)
- No
gsap.context+matchMediagating (reduced-motion users see animation). - More than two pinned sections, or a pin under 768px.
- Any animated layout property (
top/left/width/height). - No
ScrollTrigger.refresh()after fonts/images. - Per-character splits outside the desktop gate.
- Marquee or autoplay without a reduced-motion kill switch.
- The still frame (no JS) isn't a complete, beautiful page.
- Any animation that exists for its own sake — every move serves the story or dies.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/madebymustafa/design-taste/taste-gsap">View taste-gsap on skillZs</a>