/core-animation-layer-workflow

name: core-animation-layer-workflow
description: Guide Core Animation layer-backed rendering and animation decisions for Apple apps, including CALayer trees, layer-backed AppKit and UIKit views, SwiftUI bridges, implicit and explicit CAAnimation, CATransaction, CAMediaTiming, model versus presentation layers, shape, gradient, replicator, emitter, text, tiled, and metal layers, performance diagnosis, and Xcode or Instruments validation handoffs. Use when a task mentions Core Animation, QuartzCore, CALayer, CAAnimation, CATransaction, CAShapeLayer, CAGradientLayer, CATextLayer, CAReplicatorLayer, modelLayer, presentationLayer, layerClass, wantsLayer, or layer-backed animation repair.

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

Inputs

• `request`: optional free-text task description used to classify the Core Animation question.
• `target_framework`: optional framework emphasis such as `swiftui`, `appkit`, `uikit`, or `mixed`.
• `target_platforms`: optional platform list such as `ios`, `macos`, `tvos`, `visionos`, or `mixed-apple`.
• `current_code`: optional relevant files or snippets.
• `symptom`: optional issue such as snap-back, flicker, blurry contents, wrong timing, missed hit test, or performance drop.
• Defaults:
• Apple docs-first guidance always applies
• higher-level Apple UI framework animation is preferred unless Core Animation solves a concrete problem
• Xcode or Instruments validation is reported as a handoff unless actually run

Outputs

• `status`
• `success`: the request belongs to this workflow and a layer recommendation is ready
• `handoff`: another skill owns the next step after Core Animation-aware classification
• `blocked`: docs, target platform, code, or validation context is insufficient for an honest recommendation
• `path_type`
• `layer-ownership`
• `implicit-animation`
• `explicit-animation`
• `model-presentation-repair`
• `performance-diagnosis`
• `handoff`
• `output`
• classified layer job
• chosen ownership boundary
• chosen layer or animation primitive
• model/presentation behavior to preserve
• documented Apple behavior relied on
• validation