Performance Doctor

Performance Doctor finds and fixes slow animations.

It combines source analysis and local-runtime profiling to find and fix animation performance issues before they ship.

/motion audit

It grades animations using the same S-to-F system as MotionScore Audit, producing a report with fix recommendations that your agent can then follow.

Install

/motion audit the homepage

Performance Doctor is part of the Motion AI Kit. Installing AI Kit sets up the /motion skill, including its performance audit, for every supported editor. Follow the AI Kit install guide.

Usage

Run the audit by asking your agent to run a performance audit (adding /motion might be required in some agents):

By default, this will run a broad search of CSS, Motion, GSAP and Anime.js APIs in your codebase.

It's possible to limit the scope by passing a directory or filename:

/motion audit @components/Button

Additionally, you can request to scope the audit to specific types of animations, or specific APIs:

Can you perform a /motion audit of all scroll animations

It's also possible to perform a runtime analysis of a page by mentioning "runtime", a specific page, or passing a URL:

/motion performance audit on the homepage

Overall rank

The report starts with an easily-scannable letter grade. This represents the overall grade across all discovered animations.

## Rank

:'██████::
'██... ██:
.██:::..::
. ██████::
:..... ██:
'██::: ██:
. ██████::
:......:::

Breakdown

Next, you'll receive a full breakdown describing the absolute number of animations for each tier, and the percentage of animations that this tier represents. The idea is for this graph to be top-heavy (more S, A and B tier animations than below).

## Breakdown

S █████████████████░░░░░░░░░  2 · 68%
A ░░░░░░░░░░░░░░░░░░░░░░░░░░  0 ·  0%
B ░░░░░░░░░░░░░░░░░░░░░░░░░░  0 ·  0%
C ████████░░░░░░░░░░░░░░░░░░  1 · 32%
D ░░░░░░░░░░░░░░░░░░░░░░░░░░  0 ·  0%
F ░░░░░░░░░░░░░░░░░░░░░░░░░░  0 ·  0%

Findings

In findings, there's an entry for every actionable animation that explains:

• What: Filename, line numbers and tier

• Why: The values being animated, what parts of the render pipeline they trigger

• Impact: Is it worth fixing/changing?

• Improvements: How to improve performance (where possible)

For instance, an animation like this:

<motion.div
  animate={{
    scale: [1, 2, 2, 1, 1],
    rotate: [0, 0, 180, 180, 0],
    borderRadius: ["0%", "0%", "50%", "50%", "0%"],
  }}
  transition={{ repeat: Infinity }}
/>

Will flag that borderRadius triggers paint on every frame, and that we can animate clipPath instead, which is compositor-only (S-tier):

<motion.div
  animate={{
    scale: [1, 2, 2, 1, 1],
    rotate: [0, 0, 180, 180, 0],
    clipPath: [
      "inset(0% round 0%)",
      "inset(0% round 0%)",
      "inset(0% round 50%)",
      "inset(0% round 50%)",
      "inset(0% round 0%)",
    ],
  }}
  transition={{ repeat: Infinity }}
/>

Anti-patterns

This lists general patterns that can affect animation performance, like detecting filter: blur(>10px), long running off-screen animations, excessive use of will-change etc.

For example, the animation from before is repeat: Infinity, so this part of the report will suggest that performance could be improved by swapping animate to whileInView, thereby only running the animation while inside the viewport.

<motion.div
  whileInView={keyframes}
  transition={{ repeat: Infinity }}
/>

Accessibility

This part of the report looks for things like support for prefers-reduced-motion or rapidly flashing animations and suggest ways to fix.

Top 3 Recommendations

The report concludes with the top 3 priority fixes. This is a summary of the worst offenders, so you can ask your LLM to "fix the top 3 issues", or simply "fix" to fix everything in the report.

Tiers

The broad tier list used for grading animations is as follows:

The full explanation of these grades can be found in the MotionScore methodology. For deeper editorial background, read the Web Animation Performance Tier List.