How to Identify and Prioritize Animation Improvements in a Codebase: A 4-Phase Workflow

Identify and prioritize animation improvements by mapping your motion surface, auditing against eight concrete categories, and ranking findings by leverage (impact ÷ effort) before writing self-contained implementation plans.

The emilkowalski/skills repository provides a battle-tested framework for systematically improving UI motion without guesswork. This article breaks down the complete workflow defined in skills/improve-animations/SKILL.md and the audit catalog in skills/improve-animations/AUDIT.md, giving you a reproducible method to identify and prioritize animation improvements across any codebase.

Phase 1: Recon – Map the Motion Surface

Before writing fixes, you must understand what motion currently exists and where it lives. This reconnaissance phase captures four critical data points to identify animation improvements effectively.

What to capture	Why it matters	How to locate
Framework / libraries	Determines API constraints (CSS, WAAPI, Framer Motion, React Spring).	Inspect package.json and import statements like import { motion } from "framer-motion".
Token conventions	Ensures cohesion when refactoring; look for reusable easing curves.	Search global CSS variables (--ease-out), Tailwind config, or design-system docs.
Frequency map	High-frequency elements (keyboard shortcuts, command palettes) usually should not animate.	Grep for transition or animation in high-traffic components; count usage statistics.
Personality	Playful vs. crisp products dictate acceptable bounce and duration.	Review UI style guides and existing motion patterns.

Run this one-liner to locate motion code in a typical React project:

grep -R -E "transition|animation|@keyframes|motion\.|animate=\{|useSpring" src/

For targeted sweeps, the repository recommends specific patterns documented in skills/improve-animations/AUDIT.md under Useful sweeps.

Phase 2: Audit – Evaluate Against Eight Categories

With your motion map complete, evaluate every animated snippet against eight concrete categories defined in skills/improve-animations/AUDIT.md. For each finding, record the file:line, evidence (exact code), and severity.

Severity Levels and Target Values

Severity is coded strictly as HIGH, MEDIUM, or LOW (see line 74 of SKILL.md). Target values must be copied exactly from the audit catalog—never approximate.

For example, lines 28-33 of AUDIT.md mark any ease-in on UI entrances as HIGH severity. The recommended replacement is defined on lines 30-34:

--ease-out: cubic-bezier(0.23, 1, 0.32, 1);

Example Audited Finding

/* src/components/Button.tsx:42 */
.button {
  transition: all 400ms ease-in; /* HIGH severity: ease-in on UI entrances */
}

The audit covers eight categories including purpose, easing, physicality, interruptibility, performance, accessibility, cohesion, and missed opportunities.

Phase 3: Vet and Prioritize by Leverage

Raw findings require manual vetting to reject false positives. Confirm that each animation is not a deliberate design decision (e.g., an intentionally slow modal backdrop) and deduplicate overlapping issues.

The Leverage Formula

Rank validated findings by leverage, calculated as impact ÷ effort. Use this table layout suggested in lines 69-73 of SKILL.md:

| # | Severity | Category | Location | Finding | Fix summary |

| --- | --- | --- | --- | --- | --- |

Sort descending by leverage to surface quick wins—high-impact, low-effort fixes that improve perceived performance immediately.

Phase 4: Write Self-Contained Plans

For each prioritized finding, generate an implementation plan following skills/improve-animations/PLAN-TEMPLATE.md. A valid plan must include:

• Exact file path and current code excerpt.
• Target values (cubic-bezier, duration, spring config) copied verbatim from AUDIT.md.
• Step-by-step instructions executable without additional context.
• Verification steps (slow-motion playback, frame-by-frame inspection).

Save plans under plans/ with monotonic numeric prefixes, such as 001-fix-button-ease-out.md.

Minimal Plan Example

# 001 – Replace ease-in on Button.tsx

**Location**: src/components/Button.tsx:42  
**Current**:

```css
transition: all 400ms ease-in;

Target: transition: all 400ms var(--ease-out); (see AUDIT.md line 30)

Steps

1. Replace ease-in with var(--ease-out).
2. Run npm run lint to ensure no style violations.
3. Verify with Chrome DevTools → Animations panel at 3× speed.

Verification

• ✅ Visual feel: faster entry, no noticeable delay.
• ✅ Performance: no new layout thrash (check Chrome Performance tab).

## Key Reference Files

The `emilkowalski/skills` repository structures animation improvement workflows through these definitive files:

- **[`skills/improve-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/SKILL.md)** – Complete workflow definition for the four-phase process.
- **[`skills/improve-animations/AUDIT.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/AUDIT.md)** – Eight-category audit playbook with exact target values like `cubic-bezier(0.23, 1, 0.32, 1)`.
- **[`skills/improve-animations/PLAN-TEMPLATE.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/PLAN-TEMPLATE.md)** – Boilerplate for self-contained implementation plans.
- **[`skills/review-animations/STANDARDS.md`](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/STANDARDS.md)** – Reference for easing, duration, and accessibility standards (including `prefers-reduced-motion` handling).

## Summary

- **Recon first**: Map libraries, tokens, and frequency before touching code.
- **Audit systematically**: Check every animation against eight categories in [`AUDIT.md`](https://github.com/emilkowalski/skills/blob/main/AUDIT.md), recording file:line, evidence, and severity.
- **Prioritize by leverage**: Calculate `impact ÷ effort` to rank fixes; reject false positives during vetting.
- **Write executable plans**: Use the template from [`PLAN-TEMPLATE.md`](https://github.com/emilkowalski/skills/blob/main/PLAN-TEMPLATE.md) with exact target values and verification steps.
- **Never approximate**: Copy cubic-bezier values and duration tokens exactly as specified in the audit catalog.

## Frequently Asked Questions

### How do I find all animation code in a large codebase?

Use recursive grep patterns targeting transition properties, keyframes, and animation libraries. The recommended command from [`skills/improve-animations/AUDIT.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/AUDIT.md) is `grep -R -E "transition|animation|@keyframes|motion\.|animate=\{|useSpring" src/`. For CSS-specific issues like performance-killing `transition: all` declarations, run `grep -R -n "transition: all" src/ | grep -v "node_modules"`.

### What makes an animation issue "HIGH" severity?

According to line 74 of [`skills/improve-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/SKILL.md), severity reflects user impact and violation of core principles. A **HIGH** severity finding includes using `ease-in` easing on UI entrances (lines 28-33 of [`AUDIT.md`](https://github.com/emilkowalski/skills/blob/main/AUDIT.md)) or animating high-frequency interactions like keyboard shortcuts, which creates perceived lag.

### How do I handle accessibility when improving animations?

Reference [`skills/review-animations/STANDARDS.md`](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/STANDARDS.md) for the `prefers-reduced-motion` media query pattern. Always wrap animation changes in `@media (prefers-reduced-motion: no-preference)` or provide reduced-motion alternatives that respect user system preferences.

### Should I fix every finding in the audit?

No. After vetting to remove false positives and duplicates, prioritize by leverage (`impact ÷ effort`). Low-effort fixes with high user impact—such as changing `ease-in` to `var(--ease-out)` on primary buttons—should precede complex architectural changes like refactoring from CSS transitions to the Web Animations API.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}