nezam-motion-3d-progressive

skill_id	nezam-motion-3d
name	nezam-Motion 3d Progressive
tier	3
description	Motion systems (Framer Motion / GSAP), GPU-composited animation, prefers-reduced-motion, and progressive 3D fallback chains.
version	1.0.0
updated	"2026-05-08T00:00:00.000Z"
changelog	[]

Purpose

Define motion and 3D behavior that is expressive, measurable, and safe across reduced-motion and low-power scenarios. Single-responsibility: motion + 3D contract. (Absorbs the previously-proposed nezam-motion-animation.)

Inputs

• docs/DESIGN.md Motion, Components, Responsive Behavior sections.
• Candidate interaction list (page transitions, hover, reveal, 3D scenes).
• Performance constraints from @.cursor/skills/nezam-performance-optimization/SKILL.md.
• Token motion presets from @.cursor/skills/nezam-pro-design-tokens/SKILL.md.

Step-by-Step Workflow

1. Build motion token presets (durations, easings, delays) for micro and macro transitions; export from token system.
2. Restrict animation properties to composited defaults (transform, opacity); justify any non-composited exception with measurement.
3. Define Framer Motion or GSAP timing/variant patterns for reusable components; centralize variants in shared modules.
4. Specify the 3D chain: R3F/WebGL primary → SVG/Canvas fallback → static fallback; document loading order.
5. Add Suspense boundaries and lazy loading requirements for 3D payloads (size budget per scene); use <noscript> static for crawlers.
6. Author prefers-reduced-motion: reduce behavior for each non-essential motion family (cross-fade or instant).
7. Capture jank-risk and CLS-risk scenarios with mitigation notes; validate via DevTools Performance and INP RUM.
8. Use will-change only when measurable; remove after animation completes.

Validation & Metrics

• 60fps target on key interactions (DevTools FPS / Performance pane).
• INP < 200ms for interactive flows (RUM).
• CLS < 0.1 (no layout-shifting animation patterns).
• Reduced-motion parity documented for all animated surfaces.
• 3D scene size budget respected; fallback served on prefers-reduced-motion + low-bandwidth (navigator.connection).

Output Format

• Motion token table (durations, easings, delays).
• Variant-driven animation spec (component / state / event).
• 3D fallback matrix by surface (R3F → Canvas/SVG → static).
• Reduced-motion variants per family.
• Jank-risk register.

Integration Hooks

• /PLAN design for motion spec drafting.
• /SCAN perf a11y for runtime validation.
• /FIX for jank or reduced-motion regressions.
• Pairs with @.cursor/skills/nezam-pro-design-tokens/SKILL.md, @.cursor/skills/nezam-component-library-api/SKILL.md, @.cursor/skills/nezam-performance-optimization/SKILL.md, @.cursor/skills/nezam-a11y-automation/SKILL.md.
• Enforces [.cursor/rules/design-dev-gates.mdc](.cursor/rules/design-dev-gates.mdc) Gates 3 & 4 and [.cursor/rules/nezam-design-gates-pro.mdc](.cursor/rules/nezam-design-gates-pro.mdc).

Anti-Patterns

• Animating top/left/width/height on hot paths (layout thrash).
• Persistent global will-change (forces unnecessary GPU layers).
• 3D scene without fallback or with synchronous large-payload load.
• Reduced-motion handled only by hiding animation, not providing alternative.
• Framer Motion variants duplicated per component (drift).

External Reference

• Framer Motion (https://www.framer.com/motion/) — current.
• GSAP (https://gsap.com/) — current.
• React Three Fiber (https://r3f.docs.pmnd.rs/) — current.
• web.dev Animations performance (https://web.dev/animations/) — current.
• WCAG 2.2 SC 2.3.3 (Animation from Interactions).
• MDN prefers-reduced-motion (current).
• Closest skills.sh/official analog: motion-design / 3d-fallback.