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

> Learn to identify and prioritize animation improvements in your codebase with a 4-phase workflow. Map motion, audit, rank by leverage, and create implementation plans for better performance.

- Repository: [Emil Kowalski/skills](https://github.com/emilkowalski/skills)
- Tags: how-to-guide
- Published: 2026-07-28

---

**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`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/SKILL.md) and the audit catalog in [`skills/improve-animations/AUDIT.md`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/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:

```bash
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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/SKILL.md)). Target values must be copied exactly from the audit catalog—never approximate.

For example, lines 28-33 of [`AUDIT.md`](https://github.com/emilkowalski/skills/blob/main/AUDIT.md) mark any `ease-in` on UI entrances as **HIGH** severity. The recommended replacement is defined on lines 30-34:

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

```

### Example Audited Finding

```css
/* 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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/001-fix-button-ease-out.md).

### Minimal Plan Example

```markdown

# 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.