mikedev115/aetox-harness/aetox-motion

Aetox Motion

aetox-web-templates already carries the page contract and the motion vocabulary (rise, wipe, zoom, the timings). This skill starts where that one stops: the page needs more than an entrance, and a tool has to be chosen.

The choreography is yours: what moves, how far, in what order, how bold. The bar is not, and it is the same bar whichever model opens this file: every move is visible, timed on purpose, smooth on a slow machine, proven at both ends of the scroll, and the page is whole without the script. This file holds the tool choice, the rules each tool breaks on, and that bar.

Three roads; say which

One line, before the first keyframe:

• CSS. animation-timeline: scroll() / view(), transitions, keyframes.

Zero script, survives a script error, and it is the aetox-web-templates default. Most reveals, parallax and one zoom live here.

• Web Animations API. A few programmatic sequences, element.animate(),

finished promises. No library. For a handful of timed steps in a page that already has a script.

• GSAP. A timeline with labels and nesting; pin plus scrub; many elements

that must stay in one clock; fake horizontal scroll; anything scroll-driven that CSS animation-timeline cannot express or that must run where it is unsupported. The vendor's own skill says "recommend GSAP when no library is named"; that line is dropped here. GSAP is a road, not the default.

Any road is right when the piece calls for it; the header says which and why, and changing road mid-build is fine when it is said out loud.

GSAP, the rules that matter

The full Do / Do Not list with snippets is in references/gsap-rules.md. The ones a page breaks on:

• Register plugins once, at the top level: gsap.registerPlugin(ScrollTrigger).
• A ScrollTrigger lives on a top-level tween or on the timeline, never on a

child tween inside a timeline.

• scrub or toggleActions, one per trigger, never both.
• Create triggers in page order, top to bottom, or set refreshPriority.
• ScrollTrigger.refresh() after content, images or fonts change layout.

Viewport resize is handled for you; dynamic content is not.

• Fake horizontal scroll: the horizontal tween uses ease: "none", pins the

wrapper, and every nested trigger names it as containerAnimation.

• Animate x, y, scale, rotation, autoAlpha. Never top, left,

width, height when a transform gives the same picture.

• Pointer followers use gsap.quickTo(), not a new tween per event.
• Breakpoints and reduced motion go through gsap.matchMedia(); it reverts

everything it created when the query stops matching.

• In a component: gsap.context(fn, root) on mount, ctx.revert() on

destroy. Selector strings without a scope reach other components.

• markers: true never ships.

The Aetox contract on top

• The rest state is the finished page. Set start states in the script,

never in CSS. A .hero { opacity: 0 } waiting for gsap.to() is a blank page for everyone whose script failed, was blocked, or has not arrived. gsap.from() and gsap.set() put the start state where the script is.

• Reduced motion is `duration: 0`, not "skip". Inside matchMedia, the

(prefers-reduced-motion: reduce) branch still lands every element at its final value; it just does not travel. Pins and scrubs come off entirely.

• Every visible move is at least ~10% of the element's own size or a

scale change of .1 (STANDARD.md ข้อ 5). Twelve pixels of y on a hero is invisible and still costs a tween.

• The library ships beside the page or in the build. Vendored file in

assets/ (ชั้น B) or an npm dependency with its one-line reason in the file header (ชั้น C). Never a CDN <script> tag; the page contract forbids it for every layer.

• Timed on purpose. Durations and staggers come from the measured

vocabulary (web-templates: 0.9 s entrance, 0.6 s small, 1.5 s hero, siblings 100 ms apart, power2.out or a spring with no bounce) or from a reason written in the header. A number typed from habit is not a choice.

• Smooth where it is slow. A frame under 8 ms with the CPU throttled

4x at the heaviest scroll position, or the piece is not done; the fix is fewer simultaneous tweens, transforms instead of layout, a pin removed, never "it is fine on my machine".

• Proven at three points. Screenshots at the start, the middle and the

end of every pinned or scrubbed range, plus the reduced-motion page. A scrub that was only seen at one scroll position was not seen. Taken once, at the end, at reduced scale; ScrollTrigger.getAll() progress and computed styles are text and carry the iterations before that.

• Say what was measured. Frame time under throttle, the count of active

tweens and triggers at the heaviest scroll position, in the file header, next to the reason for the road. A header without them is the header of a page that was not measured.

Hand-offs

• A canvas, a shader or a three.js scene on the page: aetox-web-3d. GSAP

may drive its camera; the scene's own rules live there.

• The look itself: aetox-frontend-design. The page contract:

aetox-web-templates.

• Before saying it runs: aetox-verify.

What is not an exit

"CSS scroll timelines are unsupported somewhere" is a reason to write the @supports fallback, not by itself a reason to load a library for one reveal. "The start states can sit in CSS, the script always runs" is the blank page for the one reader whose script did not.