playbooks

home / skills / dylantarre / animation-principles / implementation-debugging

implementation-debugging skill

/skills/12-by-problem-type/implementation-debugging

This skill helps you debug animation issues using Disney's principles as diagnostic guidance to identify timing, staging, and drawing problems.

npx playbooks add skill dylantarre/animation-principles --skill implementation-debugging

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
3.3 KB
---
name: implementation-debugging
description: Use when animation doesn't work as expected, has bugs, or behaves inconsistently
---

# Implementation Debugging

Debug animation issues using Disney's principles as diagnostic framework.

## Problem Indicators
- Animation doesn't play at all
- Animation plays but looks wrong
- Works in dev, broken in production
- Inconsistent across browsers
- Animation triggers at wrong time
- Flickering or visual glitches

## Diagnosis by Principle

### Timing
**Issue**: Animation timing is off
**Debug**: Check duration values. Verify units (ms vs s). Check if CSS transition is being overridden. Inspect computed styles.

### Straight Ahead vs Pose-to-Pose
**Issue**: Keyframes not hitting
**Debug**: Verify all keyframe percentages. Check for typos in property names. Ensure values are animatable.

### Staging
**Issue**: Animation hidden or clipped
**Debug**: Check z-index, overflow, opacity. Verify element is in viewport. Check for `visibility: hidden`.

### Solid Drawing
**Issue**: Visual glitches during animation
**Debug**: Look for subpixel rendering issues. Add `transform: translateZ(0)` for GPU layer. Check for layout thrashing.

### Follow Through
**Issue**: Animation ends abruptly or wrong state
**Debug**: Check `animation-fill-mode`. Verify end state matches CSS. Check for competing animations.

## Common Bugs

| Symptom | Likely Cause | Fix |
|---------|--------------|-----|
| No animation | Property not animatable | Use transform instead of changing property directly |
| Flicker at start | No initial state | Set initial values explicitly |
| Wrong end state | Fill mode | Add `forwards` to animation |
| Choppy motion | Layout thrashing | Animate only transform/opacity |
| Works once only | Animation not reset | Remove and re-add class, or use JS |

## Quick Fixes

1. **Check DevTools Animation panel** - See timeline
2. **Verify animatable properties** - Not all CSS animates
3. **Add `animation-fill-mode: forwards`** - Keep end state
4. **Force GPU layer** - `will-change: transform`
5. **Check for `!important`** - May override animation

## Troubleshooting Checklist

- [ ] Is animation class/trigger being applied? (DevTools Elements)
- [ ] Are properties animatable? (`display` is not, `opacity` is)
- [ ] Check computed styles for overrides
- [ ] Is element visible? (opacity, visibility, display, z-index)
- [ ] Any JavaScript errors blocking execution?
- [ ] Check Animation panel in DevTools
- [ ] Test in incognito (no extensions)
- [ ] Compare working vs broken environment

## Code Pattern

```js
// Debug: Log animation events
element.addEventListener('animationstart', (e) => {
  console.log('Animation started:', e.animationName);
});

element.addEventListener('animationend', (e) => {
  console.log('Animation ended:', e.animationName);
});

// Debug: Check computed animation
const styles = getComputedStyle(element);
console.log('Animation:', styles.animation);
console.log('Transition:', styles.transition);

// Reset animation
element.classList.remove('animate');
void element.offsetWidth; // Trigger reflow
element.classList.add('animate');
```

## DevTools Tips

1. **Elements > Styles**: Check computed animation values
2. **Performance tab**: Record and analyze frames
3. **Animations panel**: Slow down, replay, inspect
4. **Console**: Log animation events

Overview

This skill helps diagnose and fix animations that don’t run, look wrong, or behave inconsistently by applying Disney’s 12 principles as a practical debugging framework. It focuses on concrete checks, quick fixes, and DevTools techniques to identify timing, staging, and rendering issues. Use it to get animations from brittle or broken to smooth and predictable.

How this skill works

The skill inspects animation symptoms and maps them to likely causes based on animation principles like Timing, Staging, and Follow Through. It guides you through targeted checks in DevTools, computed styles, and JavaScript event logging, then recommends minimal fixes (CSS or JS) that restore correct behavior. It also includes a troubleshooting checklist and reproducible debug patterns to reset or replay animations reliably.

When to use it

  • Animation doesn’t play or never triggers
  • Motion looks wrong, choppy, or jumps between states
  • Works in development but fails in production or other browsers
  • Animation triggers at the wrong time or ends abruptly
  • Flickering, clipping, or visual glitches during animation

Best practices

  • Animate transform and opacity to avoid layout thrashing
  • Explicitly set initial and end states; use animation-fill-mode: forwards when needed
  • Verify units and durations (ms vs s) and check for CSS overrides
  • Use DevTools Animations panel to replay, slow down, and inspect keyframes
  • Force GPU compositing for flaky rendering with will-change: transform or translateZ(0)

Example use cases

  • A CSS keyframe animation works locally but breaks after bundling—compare computed styles and check for overwritten rules
  • An element flickers at animation start—set explicit initial values and verify visibility/overflow
  • A complex sequence ends in the wrong visual state—inspect animation-fill-mode and competing animations
  • Cross-browser inconsistency—confirm animatable properties and test in incognito to rule out extensions
  • Animation runs once and won’t replay—reset by removing class, forcing reflow, then re-adding the class

FAQ

What if my animation still drops frames after fixes?

Profile the animation in the Performance panel, reduce work on the main thread, and convert heavy layout/paint changes to transform/opacity animations.

How do I confirm a property is animatable?

Check the computed styles in DevTools and the CSS spec; if a property is not animatable, switch to transform equivalents.