core-animation-layer-workflow

Core Animation Layer Workflow

Purpose

Use this skill to decide when Core Animation is the right layer-backed rendering or animation surface, then guide implementation, repair, and validation without confusing layer ownership with SwiftUI, AppKit, or UIKit view ownership.

It is not the default path for ordinary SwiftUI motion, AppKit/UIKit control animation, app architecture, or Xcode execution.

When To Use

• Use this skill when the task mentions Core Animation, QuartzCore, CALayer, CAAnimation, CABasicAnimation, CAKeyframeAnimation, CAAnimationGroup, CATransaction, CAMediaTiming, presentationLayer, modelLayer, or layer trees.
• Use this skill when the task mentions layer-backed AppKit views, wantsLayer, UIView.layer, layerClass, custom CALayer subclasses, shape layers, gradient layers, text layers, tiled layers, emitter layers, replicator layers, or transform layers.
• Use this skill when the work needs model-layer versus presentation-layer reasoning, implicit-animation repair, explicit-animation timing, hit-testing during animation, layer-content scaling, or layer-backed performance diagnosis.
• Recommend swiftui-animation-workflow when SwiftUI-native state animation, transitions, phase/keyframe animation, or reduce-motion behavior is enough.
• Recommend appkit-app-architecture-workflow or swiftui-app-architecture-workflow when the real issue is ownership, view structure, scene structure, or lifecycle.
• Recommend xcode-build-run-workflow when the next step is build, preview, simulator, screenshot, runtime diagnostics, Instruments handoff, or project-file validation.

Single-Path Workflow

1. Classify the layer job:
   • view backing layer
   • custom layer drawing
   • implicit property animation
   • explicit CAAnimation
   • layer tree composition
   • model/presentation mismatch
   • layer bridge from SwiftUI, AppKit, or UIKit
   • performance or rendering artifact diagnosis
2. Apply the Apple docs gate:
   • read the relevant Apple documentation first
   • state the documented behavior being relied on before recommending implementation
   • if Apple docs and the current code disagree, stop and surface the conflict
   • if no relevant Apple docs can be found, say that explicitly before proceeding
3. Decide whether Core Animation is justified:
   • stay in SwiftUI, AppKit, or UIKit when their animation helpers cover the behavior clearly
   • use Core Animation when the task needs layer tree composition, presentation-layer inspection, custom layer subclasses, specialized layer types, or lower-level timing
   • consider SpriteKit, SceneKit, Metal, AVFoundation, or Canvas when the task is really game, 3D, GPU rendering, video, or SwiftUI drawing work
4. Choose the layer ownership boundary:
   • UIKit view backing layer
   • AppKit layer-backed view
   • standalone sublayer tree owned by a view/controller/representable
   • custom layer class with explicit inputs
   • SwiftUI bridge via representable or hosting boundary
5. Choose the animation path:
   • implicit animation through property changes and transactions
   • explicit animation object when timing, repeat, key path, fill behavior, or presentation continuity requires it
   • disabled actions when layout or data updates must not animate
   • framework-level animation when Core Animation is unnecessary
6. Check model and presentation behavior:
   • update the model layer to the intended final value
   • use presentation layer only for in-flight visual state, hit testing, or diagnostics
   • avoid leaving animations that visually finish but snap because the model layer was not updated
7. Return one recommendation path with:
   • the layer ownership boundary
   • chosen layer or animation primitive
   • documented behavior relied on
   • artifact, timing, or performance risk
   • validation or handoff step