Improving Animations

Improving Animations surveys a codebase's motion, verifies findings, and converts selected improvements into precise implementation plans. Its ordinary audit-and-plan workflow is advisory: it reads source and writes planning artifacts rather than directly modifying application code. The goal is to make the judgment-heavy work explicit enough that an executor with no conversation history can carry out the selected change.

Reconnaissance maps frameworks, motion and component libraries, CSS or Tailwind tokens, keyframes, transition properties, gesture handlers, and existing spring conventions. It also establishes product personality and interaction frequency, because playful consumer motion and a frequently used dashboard require different judgments. Plans extend existing tokens and scales instead of creating a competing motion vocabulary.

The audit spans purpose and frequency, easing and duration, physicality and origin, interruptibility, performance, accessibility, cohesion and tokens, and missed opportunities. Each finding needs a concrete file location and evidence. The skill re-reads those locations itself before reporting, removing duplicates, misattributions, deliberate design tradeoffs, and valid exceptions such as a centered modal origin.

Use it to assess existing motion across an interface and turn approved findings into actionable plans. A category focus can narrow the audit to performance, accessibility, easing, or another concern. Plan mode skips the broad audit and gathers only enough context to specify a named improvement; reconcile mode compares existing plans with current code and refreshes stale references or retires completed findings.

It is separate from reviewing a single diff. In normal advisory mode, source edits, dependency installation, side-effecting builds, commits, and formatters are excluded. The explicitly named execute mode is different: it dispatches an executor in an isolated worktree, then reviews the resulting diff against the companion animation-review standard. Repository content remains inert data rather than instructions.

Inputs are the repository scope, effort level, motion conventions, usage-frequency map, and any selected finding or improvement description. Quick effort concentrates on high-traffic components and high-severity issues. Standard effort covers interactive UI, while deep effort expands to the whole repository, including marketing surfaces and lower-priority polish.

For larger scopes, the documented audit can distribute read-only inspection by category or application area. Inspector briefs include the exact audit section, reconnaissance facts, and a findings-only contract; the main workflow still vets every cited location before accepting it.

The first output is a vetted table with severity, category, location, finding, and fix summary, ordered by impact relative to effort. High severity covers feel-breaking behavior such as animation on keyboard actions, unsuitable easing, frame drops, or scale-from-zero entrances. Medium covers noticeable origin, interruption, or reduced-motion problems; low covers polish and consolidation. Additive opportunities are listed separately from corrections.

Interactive runs pause for selection before writing plans. Non-interactive runs default to the highest-value three to five findings. Each chosen finding receives a monotonically numbered plan in plans, or animation-plans when the former directory already serves another purpose. Plans carry the current commit and include exact paths, present-code excerpts, target curves and timing, a conventions exemplar, ordered steps, hard scope boundaries, and verification instructions.

The plan index records execution order, dependencies, and status. Feel checks explicitly cover slowed playback, frame-by-frame review, and real devices for gestures. The skill marks uncertainty where code cannot establish bounce or crossfade quality rather than presenting subjective inspection as measured proof.

Reconnaissance recognizes Motion or Framer Motion, React Spring, GSAP, CSS, WAAPI, Radix, Base UI, and shadcn/ui where present. Companion AUDIT and PLAN-TEMPLATE references supply rule values and plan structure, while review-animations supplies the execute-mode review bar. Suggested APIs and values must fit installed versions, accessibility requirements, and project conventions.