orb

name	orb
description	[WHAT] Build animated SwiftUI orbs — Siri-style mesh gradients, particle spheres, and AI assistant visualizers. [HOW] 7 compositing techniques (MeshGradient, Canvas particles, Metal shaders, layer rotation, angular glow, hue-shift, animated masks) with code patterns and performance rules. [WHEN] Use when building or modifying animated orb UIs, voice chat visualizers, AI thinking indicators, Siri-style glows, particle effects, or the Kingly Clawd avatar. [WHY] Animated orbs require precise layering, 60fps budgets, accessibility compliance, and cross-platform (iOS/macOS) consistency. This skill encodes battle-tested patterns. Triggers: "orb", "siri animation", "mesh gradient", "voice visualizer", "particle sphere", "glow effect", "animated gradient", "MeshGradient", "Canvas animation", "TimelineView", "OCMiniOrb", "Clawd orb", "kaaba", "diamond orb", "ripple effect", "audio reactive"
triggers	["orb animation","siri clone","mesh gradient","voice visualizer","particle sphere","glow shadow","animated orb","canvas particle","metal shader ripple","audio reactive UI"]

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

#	Technique	API	Best For	Ref
T1	MeshGradient	MeshGradient(width:height:points:colors:)	Siri iOS 18 edge glow	references/techniques.md#t1
T2	AnimatedRectangle	Custom Shape + animatableData	Breathing border mask	references/techniques.md#t2
T3	Layer Rotation	ZStack + .rotationEffect + .hueRotation	Classic Siri icon	references/techniques.md#t3
T4	Hue-Shift Gradient	TimelineView + shiftHue()	Color cycling backgrounds	references/techniques.md#t4
T5	Metal Ripple	ShaderLibrary.Ripple + .layerEffect	Tap/activation ripple	references/techniques.md#t5
T6	3D Particle Sphere	Canvas + sphere projection math	Jarvis orb, particle clouds	references/techniques.md#t6
T7	Angular Glow	AngularGradient + .blur	Button glow shadows	references/techniques.md#t7

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:

Layer	What	How
1. Ambient Glow	RadialGradient + .blur(size*0.25)	Opacity pulse 0.2-0.35, 2s
2. Base Orb	RadialGradient circle	Breathe 0.98-1.02, 3s; audio in speaking
3. Fractal	Canvas + TimelineView(1/30fps)	6 Fibonacci rings, conditional on state
4. Glass	RadialGradient + .ultraThinMaterial	Static 0.85x
5. Smoke	4 orbiting blobs in Canvas	3-6s rotation per blob
6. Eyes	2 white circles	Dim to 0.4 in thinking

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

File	Content
references/techniques.md	Full code for all 7 techniques with copy-paste patterns
references/existing-impl.md	OCMiniOrb layer-by-layer analysis, modification guide
references/variants.md	Kaaba/Diamond, particle sphere, mesh orb variant specs

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.