Orb — Animated SwiftUI Visualizer Skill

Decision Tree

What are you building?
|
|-- Modify existing OCMiniOrb?
|   |-- Add/change state? -> See: Existing Implementation
|   |-- Tune layers? -> See: references/existing-impl.md
|   \-- Add audio reactivity? -> Bind audioLevel to scaleEffect
|
|-- New orb variant?
|   |-- Siri iOS 18 style (edge glow)? -> T1: MeshGradient + T2: AnimatedRectangle mask
|   |-- Classic Siri (layered rotation)? -> T3: Layer rotation with Figma assets
|   |-- Particle sphere (Jarvis)? -> T6: 3D particle system in Canvas
|   |-- Kaaba/Diamond? -> See: references/variants.md
|   \-- Glow button shadow? -> T7: Angular gradient + blur
|
|-- Performance issue?
|   |-- Dropped frames? -> Check: fractal conditional removal, Canvas vs SwiftUI shapes
|   |-- High CPU idle? -> Ensure TimelineView pauses when not visible
|   \-- Memory growth? -> Check particle pool / recycle bin pattern
|
\-- Accessibility?
    \-- .accessibilityReduceMotion -> guard !reduceMotion else { return }

Quick Reference: 7 Techniques

Existing Implementation (OCMiniOrb)

Path: packages/uikit/Sources/OCDesignKit/Components/OCMiniOrb.swift Storybook: apps/storybook/Sources/Shared/MiniOrbPage.swift Spec: docs/ux/orb/mini-clawd-spec.md

6-layer stack in ZStack:

States: OrbDisplayState — .idle, .thinking, .speaking, .listening Colors: OCColors.voiceOrb{State}Start/End, .voiceHighlight, .voiceParticle

Performance Rules (NON-NEGOTIABLE)

1. •Canvas over shapes — Use Canvas for particle systems (single draw call per layer)
2. •Conditional hierarchy — Remove fractal/smoke from view tree when idle: if state == .thinking { ... }
3. •30fps cap — TimelineView(.animation(minimumInterval: 1.0 / 30.0))
4. •Reduce motion — @Environment(\.accessibilityReduceMotion) guards ALL animation starts
5. •Pool particles — Recycle bin pattern (linked list, not array append/remove)
6. •No SpriteKit — Pure SwiftUI + Canvas + optional Metal
7. •Target — 60fps at 48pt on iPhone 12 / M1 Mac

Compositing Recipe: New Orb

// Minimal orb skeleton
struct MyOrb: View {
    let state: OrbDisplayState
    var size: CGFloat = 48
    @Environment(\.accessibilityReduceMotion) private var reduceMotion

    var body: some View {
        ZStack {
            // 1. Glow (always)
            Circle().fill(RadialGradient(...)).blur(radius: size * 0.25)
            // 2. Base (always)
            Circle().fill(RadialGradient(...)).scaleEffect(breatheScale)
            // 3. Active layers (conditional)
            if state != .idle {
                activeLayer(size)  // Canvas-based
            }
            // 4. Glass (always)
            Circle().fill(...).background(.ultraThinMaterial.opacity(0.15))
            // 5. Highlights (always)
            eyeDots(size)
        }
        .frame(width: size * 1.3, height: size * 1.3)
        .accessibilityLabel("Assistant \(state.label)")
    }
}

Key Helper: sinInRange

func sinInRange(_ range: ClosedRange<Float>, offset: Float, timeScale: Float, t: Float) -> Float {
    let amplitude = (range.upperBound - range.lowerBound) / 2
    let midPoint = (range.upperBound + range.lowerBound) / 2
    return midPoint + amplitude * sin(timeScale * t + offset)
}

Used by MeshGradient (T1) and AnimatedRectangle (T2) for organic motion.

References

External Sources

• •metasidd/PrototypeSiriAnimation — iOS 18 Siri mesh gradient prototype
• •Rudrank Riyam — Siri Animation — MeshingAIProgressView deep dive
• •Hacking with Swift — MeshGradient — API reference
• •Amos Gyamfi — Siri Clone Gist — Layer rotation approach
• •insidegui/MeshBuddy — Visual MeshGradient editor

Related Skills

• •pencil — Visual design prompts and character art for orb avatars (concept → prompt)
• •swiftui-animation — General SwiftUI animation patterns (broader scope)
• •swiftui-performance-audit — Runtime perf diagnostics (when orb causes frame drops)

Technique Map

• •6-layer ZStack compositing — Ambient glow, base orb, fractal (conditional), glass, smoke, eyes; because layering order determines visual hierarchy and performance.
• •Canvas over shapes for particles — Single draw call per layer; because SwiftUI shapes = many draw calls; Canvas = one.
• •Conditional hierarchy — Remove fractal/smoke when idle; because redundant layers drain GPU when not visible.
• •30fps cap for TimelineView — minimumInterval: 1.0/30.0; because 60fps for decorative layers wastes budget.
• •Reduce motion guard — @Environment(.accessibilityReduceMotion) on ALL animation; because accessibility compliance is non-negotiable.
• •sinInRange helper — Organic motion for MeshGradient and AnimatedRectangle; because procedural variation feels more natural than linear.
• •Pool particles — Recycle bin pattern, not array append/remove; because mid-frame allocation causes frame drops.

Technique Notes

7 techniques: T1 MeshGradient, T2 AnimatedRectangle, T3 layer rotation, T4 hue-shift, T5 Metal ripple, T6 particle sphere, T7 angular glow. OCMiniOrb path: OCDesignKit/Components/OCMiniOrb.swift. Target: 60fps at 48pt on iPhone 12.

Prompt Architect Overlay

Role Definition: Animated SwiftUI orb builder. Siri-style mesh gradients, particle spheres, AI assistant visualizers. Encodes 7 compositing techniques with performance rules and accessibility compliance.

Input Contract: Accepts orb variant (Siri iOS 18, classic Siri, particle sphere, Kaaba/Diamond), modification target (existing OCMiniOrb or new), or performance issue. State (idle/thinking/speaking/listening) if modifying existing.

Output Contract: Layer-by-layer compositing recipe, technique references, performance rules checklist. SwiftUI code snippets. Accessibility labels. References to techniques.md, existing-impl.md, variants.md.

Edge Cases & Fallbacks: If frame drops→check conditional hierarchy, Canvas vs shapes, particle count. If modify OCMiniOrb→reference existing-impl.md. If audio reactive→bind audioLevel to scaleEffect. If Metal needed→orb skill T5; metal-shaders for MSL.