Fixing Motion Performance
Audit and repair stuttering CSS and JS animations by enforcing compositor-safe patterns without forced library migrations.
Overview
Fixing Motion Performance is an agent skill most often used in Ship (also Build frontend) that audits and fixes CSS and JS animation jank using prioritized compositor and layout rules.
Install
npx skills add https://github.com/ibelick/ui-skills --skill fixing-motion-performanceWhat is this skill?
- Slash command modes: apply rules to the conversation or audit a specific file with quoted violations and concrete fixes
- Priority rule table from never-patterns through measurement—critical impact categories first
- Covers CSS, WAAPI, Motion, rAF, and GSAP within the existing stack unless migration is explicitly requested
- Rendering-step glossary: composite (transform, opacity) versus paint and layout costs
- Targets scroll-linked motion, blur, filters, masks, gradients, CSS variables, and will-change misuse
- Rule categories ordered by priority table: never patterns and choose the mechanism marked critical impact
Adoption & trust: 15.9k installs on skills.sh; 2k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your UI animations stutter or scroll-linked motion tanks frame rate because code animates layout, paint-heavy properties, or misuses measurement and will-change.
Who is it for?
Indie frontend devs polishing interactions in production or pre-release PRs where jank shows up on real devices and scroll paths.
Skip if: Pure brand motion design or replacing your animation library by default—the skill audits performance within the stack you already use.
When should I use this skill?
Animations stutter, transitions jank, or you are reviewing CSS/JS animation performance including scroll-linked motion, filters, and layout measurement.
What do I get? / Deliverables
You get violations mapped to prioritized rules with concrete fixes while keeping your existing animation libraries unless you explicitly request a migration.
- File audit listing violations, impact, and concrete code fixes
- Session-wide motion performance constraints applied to new animation work
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Ship perf is the canonical shelf because the skill is invoked when motion already janks in real UI—not only when first authoring animations. Perf subphase matches layout thrashing, scroll-linked motion, and paint-heavy effects—the README frames fixes as performance review, not greenfield design.
Where it fits
Apply motion constraints while adding a reveal-on-scroll section so new code never animates layout by default.
Run a file audit on a modal transition that stutters and patch transform-only paths.
Quote violating snippets in a PR that introduced gradient and blur animations on scroll.
Re-check a hot path component after users report jank on low-end mobile browsers.
How it compares
Performance checker for motion code, not a motion-design aesthetic skill or a greenfield animation template pack.
Common Questions / FAQ
Who is fixing-motion-performance for?
Solo builders and frontend-focused agents who ship React or web UIs with CSS, WAAPI, Motion, rAF, or GSAP and need systematic performance fixes.
When should I use fixing-motion-performance?
In Ship perf when transitions jank; in Build frontend when adding scroll reveals or filters; and in Ship review when auditing animation-heavy components before launch.
Is fixing-motion-performance safe to install?
It is review-and-constraint guidance without declared shell or network tools; check the Security Audits panel on this Prism page for the upstream package.
SKILL.md
READMESKILL.md - Fixing Motion Performance
# fixing-motion-performance Fix animation performance issues. ## how to use - `/fixing-motion-performance` Apply these constraints to any UI animation work in this conversation. - `/fixing-motion-performance <file>` Review the file against all rules below and report: - violations (quote the exact line or snippet) - why it matters (one short sentence) - a concrete fix (code-level suggestion) Do not migrate animation libraries unless explicitly requested. Apply rules within the existing stack. ## when to apply Reference these guidelines when: - adding or changing UI animations (CSS, WAAPI, Motion, rAF, GSAP) - refactoring janky interactions or transitions - implementing scroll-linked motion or reveal-on-scroll - animating layout, filters, masks, gradients, or CSS variables - reviewing components that use will-change, transforms, or measurement ## rendering steps glossary - composite: transform, opacity - paint: color, borders, gradients, masks, images, filters - layout: size, position, flow, grid, flex ## rule categories by priority | priority | category | impact | |----------|----------|--------| | 1 | never patterns | critical | | 2 | choose the mechanism | critical | | 3 | measurement | high | | 4 | scroll | high | | 5 | paint | medium-high | | 6 | layers | medium | | 7 | blur and filters | medium | | 8 | view transitions | low | | 9 | tool boundaries | critical | ## quick reference ### 1. never patterns (critical) - do not interleave layout reads and writes in the same frame - do not animate layout continuously on large or meaningful surfaces - do not drive animation from scrollTop, scrollY, or scroll events - no requestAnimationFrame loops without a stop condition - do not mix multiple animation systems that each measure or mutate layout ### 2. choose the mechanism (critical) - default to transform and opacity for motion - use JS-driven animation only when interaction requires it - paint or layout animation is acceptable only on small, isolated surfaces - one-shot effects are acceptable more often than continuous motion - prefer downgrading technique over removing motion entirely ### 3. measurement (high) - measure once, then animate via transform or opacity - batch all DOM reads before writes - do not read layout repeatedly during an animation - prefer FLIP-style transitions for layout-like effects - prefer approaches that batch measurement and writes ### 4. scroll (high) - prefer Scroll or View Timelines for scroll-linked motion when available - use IntersectionObserver for visibility and pausing - do not poll scroll position for animation - pause or stop animations when off-screen - scroll-linked motion must not trigger continuous layout or paint on large surfaces ### 5. paint (medium-high) - paint-triggering animation is allowed only on small, isolated elements - do not animate paint-heavy properties on large containers - do not animate CSS variables for transform, opacity, or position - do not animate inherited CSS variables - scope animated CSS variables locally and avoid inheritance ### 6. layers (medium) - compositor motion requires layer promotion, never assume it - use will-change temporarily and surgically - avoid many or large promoted layers - validate layer behavior with tooling when performance matters ### 7. blur and filters (medium) - keep blur animation small (<=8px) - use blur only for short, one-time effects - never animate blur continuously - never animate blur on large surfaces - prefer opacity and translate before blur ### 8. view transitions (low) - use view transitions only for navigation-level changes - avoid view transitions for interaction-heavy UI - avoid view transitions when interrup