UIKit Animation Debugging

Overview

CAAnimation issues manifest as missing completion handlers, wrong timing, or jank under specific conditions. Core principle 90% of CAAnimation problems are CATransaction timing, layer state, or frame rate assumptions, not Core Animation bugs.

Red Flags — Suspect CAAnimation Issue

If you see ANY of these, suspect animation logic not device behavior:

• Completion handler fires on simulator but not device
• Animation duration (0.5s) doesn't match visual duration (1.2s)
• Spring animation looks correct on iPhone 15 Pro but janky on older devices
• Gesture + animation together causes stuttering (fine separately)
• [weak self] in completion handler and you're not sure why
• ❌ FORBIDDEN Hardcoding duration/values to "match what actually happens"
  • This ships device-specific bugs to users on different hardware
  • Do not rationalize this as a "temporary fix" or "good enough"

Critical distinction Simulator often hides timing issues (60Hz only, no throttling). Real devices expose them (variable frame rate, CPU throttling, background pressure). MANDATORY: Test on real device (oldest supported model) before shipping.