Skip to content
Skills Library
Programming · Building & coding

motion-perf

/motion-perf

Find and fix animation jank -- the layout thrash, paint storms, and layer explosions that make motion stutter on real devices even when it is smooth on your laptop. Use when animations feel choppy, scroll stutters, or before shipping any animation-heavy page.

Licence
MIT
Last repository change
11.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 11.08.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Find and fix animation jank -- the layout thrash, paint storms, and layer explosions that make motion stutter on real devices even when it is smooth on your laptop. Use when animations feel choppy, scroll stutters, or before shipping any animation-heavy page.

Original author description

Find and fix animation jank -- the layout thrash, paint storms, and layer explosions that make motion stutter on real devices even when it is smooth on your laptop. Use when animations feel choppy, scroll stutters, or before shipping any animation-heavy page.

How it works

  1. The four causes
  2. Workflow
  3. Rules
Original SKILL.md headings · 39 lines, 678 words
SKILL.md preview
---
name: motion-perf
description: Find and fix animation jank -- the layout thrash, paint storms, and layer explosions that make motion stutter on real devices even when it is smooth on your laptop. Use when animations feel choppy, scroll stutters, or before shipping any animation-heavy page.
---

# Motion Perf

Animation runs at 60fps on your machine and stutters on the client's phone. The cause is almost always one of four things, and a profiler finds it in five minutes -- far faster than the usual approach of removing animations one at a time until it improves.

The budget: 16.7ms per frame at 60Hz, and modern phones often target 120Hz, which halves it. Anything the main thread does during an animation eats into that.

## The four causes

**1. Animating layout properties.** `width`, `height`, `top`, `left`, `margin`, `padding` force the browser to recompute geometry every frame -- for the element and often its siblings. This is the single most common cause. `transform` and `opacity` are the only two properties the compositor can animate without touching layout or paint. Almost every layout animation has a transform equivalent: `left` → `translateX`, `width` → `scaleX` (with a counter-scale on children if needed), `height: auto` → `grid-template-rows: 0fr/1fr`.

**2. Layout thrash in a loop.** Reading a layout value (`offsetTop`, `getBoundingClientRect`, `scrollHeight`, `getComputedStyle`) after writing a style forces a synchronous reflow. In a scroll handler or rAF loop, that is a forced reflow per frame. Fix by batching: read all measurements first, then write all styles.

**3. Too many layers.** `will-change: transform` and `translateZ(0)` promote an element to its own compositor layer. That is a real speedup for a few animating elements and a memory disaster for fifty -- especially on mobile, where layer memory is what causes the tab to reload. Apply `will-change` just before an animation and remove it after, or leave it off entirely and let the browser decide.

**4. Main-thread work during animation.** A heavy React re-render, an unthrottled scroll or resize listener, an expensive filter, or a large image decode landing mid-animation blows the frame budget regardless of how clean the animation itself is.

## Workflow

1. **Reproduce on a real device or throttle honestly.** Chrome DevTools Performance panel with 4x-6x CPU throttling, or a mid-range Android. A desktop with a discrete GPU will tell you everything is fine.
2. **Record the interaction.** Perform the janky scroll or transition while recording. Read the frames row: long frames are the jank, and the flame chart under them names the cause.
3. **Classify what you see.**
   - Purple "Layout" bars in every frame → cause 1 or 2. Find the property or the read-after-write.
   - Green "Paint" / "Rasterize" dominating → large repaints; check for animated `box-shadow`, `filter`, `background-position`, or a huge element being repainted.
   - Yellow "Scripting" dominating → cause 4. Find the handler or the re-render.
   - Frames fine but memory climbing / mobile tab reloading → cause 3. Count promoted layers in the Layers panel.
4. **Fix the top cause only, then re-measure.** Changing four things at once teaches nothing about which mattered, and usually two of them were unnecessary.
5. **Verify the whole page, not the fixed component.** Scroll the full page, open and close the modals, resize once. Confirm no listener leaks: navigate away and back twice, then check that scroll and resize listener counts and `ScrollTrigger.getAll().length` are flat.

## Rules

- `transform` and `opacity` for anything animating continuously. Everything else needs a reason.
- Throttle scroll and resize handlers to `requestAnimationFrame`, or replace them with `IntersectionObserver` / `ResizeObserver`, which do not run on every event.
- Never animate `box-shadow` or `filter: blur()` -- both repaint large areas. For a shadow, animate the `opacity` of a pseudo-element carrying the larger shadow. For blur, animate opacity between two pre-blurred layers.
- Images inside animating containers get explicit dimensions and, above the fold, priority loading. A late-decoding image is a layout shift mid-animation.
- Off the main thread where possible: CSS transitions/animations and WAAPI can run on the compositor; a JS rAF loop cannot.
- Reduced motion is a performance feature too -- it is the fallback for low-power devices, not only a preference.
- Measure the cost of the animation library itself. If a page uses one fade and imports a full animation library to do it, the bundle is the performance problem.

Versions

The database has no other skills named motion-perf.

Database snapshot: 13.11.2026 · package version abd95ccf7ba5 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100fixing-motion-performance
    Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.
  • 100fixing-motion-performance
    Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.
  • 100fixing-motion-performance
    Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.
  • 100fixing-motion-performance
    Audit and fix animation performance issues in Angular 21.x — layout thrashing, compositor properties, scroll-linked motion, will-change, blur effects, FLIP technique, and View Transitions API. Use when Angular animations stutter, transitions jank, scroll-linked motion is slow,…
  • 100gsap-performance
    Official GSAP skill for performance — prefer transforms, avoid layout thrashing, will-change, batching. Use when optimizing GSAP animations, reducing jank, or when the user asks about animation performance, FPS, or smooth 60fps.
  • 90motion
    Use when reviewing motion quality, adding animation, transitions, hover effects, making the UI feel more alive, or when animations stutter and transitions jank. Covers three modes -- audit motion code against Disney's 12 principles (file:line findings), add purposeful animations…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.