Skip to content
delta

Add GSAP animations

Load GSAP once for the whole site and give it a small set of named animations that take their timing from your motion tokens.

Recipe
Add GSAP to my site and set up a motion baseline: a small set of named animations that every page can use. Start with get-design-context, get-tokens, get-notes, get-site-assets (include site.js) and get-site-scripts. Do not change anything yet. 1. Look for motion that is already there: scroll reveals, typing effects or other animation code in site.js, the templates and the designed pages, and any animation library that is already loaded. List what you find, and ask me whether to keep it, replace it with GSAP, or leave those parts alone. 2. Find the motion tokens. This recipe uses the Delta seed names: --duration-fast, --duration-base, --duration-slow, --curve-standard and --curve-entrance. a. If the site has them, use them. b. If the site uses a different design system, look for its own duration and easing values (for example transition or motion variables). Show me a table that matches each seed name to the site's name, and wait for my approval. The setup then reads the site's names. c. If the site has no motion values at all, offer to create the missing tokens with update-tokens, with proposed values (for example 150ms, 250ms and 400ms, and two cubic-bezier curves). Wait for my approval. Do not add tokens without it. 3. Load GSAP 3.15.0 from jsDelivr with patch-site-scripts, in the footer insert, with the defer attribute: gsap.min.js, then ScrollTrigger.min.js and CustomEase.min.js from https://cdn.jsdelivr.net/npm/[email protected]/dist/. Use this exact version, never "latest". If I want no third-party scripts, stop and tell me: the three files must then be put on my own server (WordPress does not accept script files in the Media Library), and you load them from there. 4. Write the motion setup once, at the end of site.js, with patch-site-assets: a. Register ScrollTrigger and CustomEase. b. Read the motion tokens from step 2 with getComputedStyle. Change durations to seconds (150ms is 0.15). Make one CustomEase for each curve token from its four cubic-bezier numbers. Set gsap.defaults to the base duration and the standard curve, so a change to a token changes every animation. c. Use gsap.matchMedia: run the animations only when prefers-reduced-motion is no-preference. With reduced motion, everything shows at once, with no movement. d. Keep content visible when JavaScript fails: hide an element only from the script, just before it animates, never with CSS alone. e. Give each animation a name that HTML can use as data-motion: fade, fade-up, stagger (the children of the element come in one after the other) and parallax (a small vertical drift on scroll). All four use ScrollTrigger: fade, fade-up and stagger run once, when the element comes into view; parallax follows the scroll. f. Animate only opacity and transform, so the layout never moves. g. If soft navigation is on (get-feature soft-navigation), run the setup again after each page change, and kill the old ScrollTriggers first. 5. Make a sketchbook board called Motion with create-sketchbook-board and set-board. Show each data-motion name on a few sample blocks, with enough height to scroll. Tell me what you checked: each animation, a page refresh, and the result with reduced motion turned on. 6. After my approval, add a Motion part to the design system notes with patch-notes: the data-motion names and what each one does, that timing comes from the tokens, that new animations are added to the set in site.js and not written in a page, and that animations move only opacity and transform. Show me each change as a diff and wait for my approval before you write it.