Communitygithub.com

apple-motion

Pure Apple-grade UI motion, spatial transitions, spring physics, gesture tracking, hero bounds morphing, interactive back/dismiss, micro-interactions, and haptic choreography across Jetpack Compose, SwiftUI/UIKit, Web/React, and Flutter (no backdrop glass/shader material styling). Use whenever building, tuning, or auditing animations, page transitions, card-to-screen zoom morphs, predictive back gestures, swipeable sheets, sliding tabs, rolling counters, scroll parallax, press feedback, or whenever motion feels sluggish, choppy, wobbly, mechanical, abrupt, or needs Apple-style unhurried fluidity and continuity.

apple-motion 是什么?

apple-motion is a Claude Code agent skill that pure Apple-grade UI motion, spatial transitions, spring physics, gesture tracking, hero bounds morphing, interactive back/dismiss, micro-interactions, and haptic choreography across Jetpack Compose, SwiftUI/UIKit, Web/React, and Flutter (no backdrop glass/shader material styling). Use whenever building, tuning, or auditing animations, page transitions, card-to-screen zoom morphs, predictive back gestures, swipeable sheets, sliding tabs, rolling counters, scroll parallax, press feedback, or whenever motion feels sluggish, choppy, wobbly, mechanical, abrupt, or needs Apple-style unhurried fluidity and continuity.

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dev-hkm/apple-motion/tree/HEAD

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Apple Motion Engineering

How Apple makes software stop feeling like disconnected frames and start feeling like one calm, continuous physical world — responsive on frame 1, silky and unhurried into rest, completely interruptible mid-flight, and spatially coherent from click to dismiss.

Synthesized from Apple WWDC (Designing Fluid Interfaces 2018, Animate with springs 2023, Enhance UI animations 2024), Janum Trivedi's Wave engine, Rauno Freiberg (Invisible Details), Jakub Krehel, Dan Saffer (Microinteractions), Emil Kowalski (apple-design, animate, choreograph, gestures, review-animations), fluid-design, and production Jetpack Compose motion implementations. Purely focused on motion, timing, geometry morphs, gestures, and haptics.


Why Apple Motion Feels Unhurried, Soft & Cohesive

  1. Instant Lift-Off, Long Feather Settle: Apple curves (cubic-bezier(0.32, 0.72, 0, 1)) and perceptual springs travel 70–80% of the distance in the first ~30% of time, then glide delicately down to sub-pixel velocity over the remaining ~70%. Your eye feels zero lag on touch yet watches an unhurried, peaceful landing.
  2. Physics Over Fixed Timers (C^1 Continuity): Springs integrate live position and instantaneous velocity. When a user catches a closing sheet or reverses a navigation push mid-flight, motion redirects cleanly without snapping or restarting from zero.
  3. Trigger Decides Bounce ("Read the Trigger, Not the Component Name"): Tap-opened drawers, modals, and screens take zero bounce (dampingRatio = 0.88–1.0, bounce = 0.0) — nothing threw them. Visible overshoot (damping ≈ 0.80, bounce = 0.15–0.20) is earned only by physical momentum (a flick/throw) or small tactile accents.
  4. Spatial Traceability (Cause-and-Effect Continuity): Panels never teleport out of thin air. Cards expand from their clicked Rect and shrink smoothly back into it on back/dismiss; popovers grow out of their trigger corner; underlying tabs stay mounted at depth (0.94..1.0) so peeking never flashes blank.
  5. Single Progress Source of Truth: Foreground translation, corner radius morph (cardRadius -> 0dp -> 30dp peel), underlying Z-depth scale, and backdrop scrim are derived from one normalized scalar so layers never drift out of sync during partial gestures.
  6. Continuous Corners & Concentricity: Nested radii share a geometric center ($R_{\text{inner}} = \max(R_{\text{min}}, R_{\text{outer}} - \text{padding})$) and animate continuously alongside bounds (~22.37% app icon squircle proportion $\rightarrow 0 \rightarrow$ hardware bezel).
  7. Compact Shared Vocabulary: Every component pulls from one shared 3–5 token motion system rather than ad-hoc timers, making tabs, cards, sheets, buttons, and typography settle in unified rhythm.

Pre-Flight Gate: Should This Animate & How Much?

Before writing animation code, check frequency tier and purpose:

Trigger FrequencyDecisionTarget Behavior
100+ times/day (keyboard shortcuts, command palette toggle, rapid typing)0ms InstantZero transition delay; velocity > ornament.
Tens of times/day (tab switches, hover tooltips, list navigation)Calm Micro-Motion120–240ms crisp ease-out or short in-place cross-dissolve (Tab). Zero bounce.
Occasional (card opens, push details, sheets, modals, pull-to-dismiss)Full Spatial ContinuityHero bounds morph, depth parallax (0.94), 360–460ms feather tail.
Rare / First-Time (payment success checkmark, onboarding milestone)Signature DelightEarned overshoot (bounce ≈ 0.25–0.30), choreographed accent sequence.

Every animation must serve at least one real purpose: Spatial Continuity, Immediate Feedback, State Indication, Reflow Smoothing, or Deliberate Delight. Never animate layout properties when visuals suffice.


Canonical Motion Tokens & Core Equations

1. Canonical Apple Cubic-Bezier Curves

Token(x1, y1, x2, y2)Default BudgetPrimary Use
AppleSheet(0.32, 0.72, 0.0, 1.0)420–500ms (full sheets/screens)Steep launch + ultra-long soft deceleration tail (260ms for predictive back finish).
AppleSilk(0.28, 0.11, 0.14, 1.0)200–240ms (micro) / 360–380ms (content)Warm, unhurried cross-dissolves, opacity/content transitions, tab switches.
AppleEaseOut(0.23, 1.0, 0.32, 1.0)150–250msStrong UI ease-out for floating popovers, menus, tooltips (125ms), hover/press exits.
AppleInOut(0.77, 0.0, 0.175, 1.0)250–360msOn-screen repositioning of persistent elements without entering/exiting.
AppleEase(0.25, 0.1, 0.25, 1.0)150–200ms (400ms toasts)Quiet fades and subtle background color shifts.

Hard Rule: Never use ease-in on UI entrances or exits (starts slow at frame 1, causing perceived input lag). Reserve linear exclusively for time-progress gauges (hold-to-confirm rings, continuous marquees). Never loop a spring (repeatForever) — springs slow near seams and stutter.

2. Perceptual Spring Presets & Cross-Platform Equivalents ($m = 1$)

RoleSwiftUI (duration, bounce)Compose (dampingRatio, stiffness)Physics cWhen to Use
Calm Structural (.smooth)(0.50s, 0.00)(0.92f, 210f) (gentle)25.1–26.7Background parallax, large calm state transitions.
Screen Navigation(0.41s, 0.10)(0.90f, 240f)27.9Stack push/pop, predictive-back cancel recovery, hero return.
Fluid Content / Hero(0.39s, 0.12)(0.88f, 260f)28.4Card-to-screen hero morphs, App Store card expand (0.42, 0.82).
Layout Reflow(0.38s, 0.12)(0.88f, 270f)28.9Sliding segmented pills, animateContentSize, accordions.
Tactile Control (.snappy)(0.50s / 0.33s, 0.15)(0.80f, 360f)21.4 / 32.3Responsive toggles, switches, snap-back after minor drag.
Press Down(0.31s, 0.14)(0.86f, 420f)35.3Instant pointerdown / ACTION_DOWN compression (scale ~0.97).
Press Release / Pop(0.36s, 0.32)(0.68f, 300f)23.6Touch-up spring rebound; micro action pills (0.72f, 380f).
Momentum Flick Release(0.30s, 0.20)(0.80f–0.85f, 360f)33.5Flicked drawer/sheet/PiP detent snap carrying gesture velocity.

3. Essential Physics Equations

  • SwiftUI bounce $\leftrightarrow$ dampingRatio ($\zeta$): $\zeta = 1 - b$ for $b \ge 0$; $\zeta = 1 / (1 + b)$ for $b < 0$.
  • Perceptual response $R$ (sec) $\rightarrow$ Compose/Motion (stiffness k, damping c): $$k = \left(\frac{2\pi}{R}\right)^2 m, \qquad c = \frac{4\pi \cdot \zeta \cdot m}{R}$$
  • Momentum Projection (WWDC18 — project flick before choosing snap detent): $$\text{projectedDelta}(v_0, d) = \frac{v_0}{1000} \cdot \frac{d}{1 - d} \qquad (d = 0.998\text{ scroll},\ 0.990\text{ crisp snap})$$
  • Rubber-Banding Past Boundaries: $$\text{offset}(x', D) = \frac{x' \cdot D \cdot 0.55}{D + 0.55 \cdot |x'|}$$
  • Relative Spring Velocity (for UIKit / unit-normalized animators): $$v_{\text{rel}} = \frac{v_{\text{gesture}}}{\text{targetValue} - \text{currentValue}}$$

Decision Matrix: Which Pattern Do I Build?

ScenarioRecommended Apple ArchitectureDetailed Reference
Opening detail screen from a clicked card/tileHero Bounds Morph (HeroBoundsRegistry + scale/center translation + continuous corners + hide source slot during flight) or SwiftUI .matchedTransitionSource + .navigationTransition(.zoom)02-navigation-and-hero-morph.md
Multi-tab bottom bar + stacked detail pagesLayer 0 SaveableStateProvider zero-remount host (tabTransform cross-dissolve) + Layer 1 depth parallax (0.94..1.0) & optical scrim02-navigation-and-hero-morph.md
Android 14+ swipe back / iOS edge peelPredictiveBackHandler with quadratic softening c = 0.7r + 0.3*(1-(1-r)^2), vertical touchY tilt, 0dp -> 30dp corner bevel morph, navigationSpring cancel02-navigation-and-hero-morph.md, 04-jetpack-compose-cookbook.md
Bottom sheet / media swipe-to-dismiss / PiP throw1:1 snapTo drag + 0.55 rubber-band + projectOffset detent choice + hand release VelocityTracker straight to spring (2D independent X/Y for PiP)03-gestures-scroll-and-haptics.md
Dropdowns, menus, tooltips, modalsAnchor transformOrigin at clicked trigger (TopEnd / var(--transform-origin)), scale 0.94 -> 1.0 + opacity over 160–220ms AppleEaseOut (never scale(0))02-navigation-and-hero-morph.md, 05-swiftui-web-crossplatform.md
Compact pill expanding both width & heightAsymmetric Dynamic Island morph: container leads (0.35s, 0.85), fast exit (130ms + scale 0.82 + tiny blur), delayed soft enter (popLayout)02-navigation-and-hero-morph.md, 03-gestures-scroll-and-haptics.md
Scroll-linked header collapse / parallax / listsRead scroll inside GPU draw phase (graphicsLayer / visualEffect) — zero recomposition; coarsen chrome toggles to discrete threshold crossings03-gestures-scroll-and-haptics.md
Buttons, sliders, toggles, wheel pickers, numbersInstant pointerdown scale (0.965) + haptic tick on threshold crossings + tabular numeric odometer slides03-gestures-scroll-and-haptics.md, 04-jetpack-compose-cookbook.md
Reviewing/debugging sluggish, jittery, or bouncy UICheck against the 12 Deadly Sins + Symptom -> Root Cause matrix + automated grep/rg checks06-audit-and-anti-patterns.md

Reference Documentation Map (Load On Demand)

Read the specific reference file(s) matching the current engineering task:


Standard Implementation & Polish Workflow

  1. Consolidate Tokens First: Before touching components, verify whether the repo already defines curves/springs (AppMotion.kt, Swift Animation extension, CSS tokens). Extend them — never create competing parallel animation tokens.
  2. Pass the Frequency & Purpose Check: Confirm whether the interaction should be instant (0ms for 100+/day shortcuts), calm (Tab/Micro), or full spatial continuity (Hero / Sheet).
  3. Derive Multi-Layer Motion From One Scalar: Bind container bounds/translation, corner radii progression, depth parallax scale (0.94..1.0), and scrim opacity to a single normalized progress Animatable / motion value so interruption stays rock-solid.
  4. Keep Compositor-Only at 120Hz: Translate/scale/rotate/fade inside graphicsLayer / visualEffect / CSS transform & opacity. Coarsen raw scroll offsets into boolean threshold triggers.
  5. Pair Physical Touch + Accessibility: Wire pointerdown compression + single threshold-crossing haptics, and verify a Reduce Motion branch (replace travel/zoom with 150ms crossfades while keeping 1:1 finger tracking).
  6. Audit Before Shipping: Walk through the 10-Point Checklist and run the platform rg/grep verification scans in 06-audit-and-anti-patterns.md.

相关技能