---
name: opendevbrowser-motion-design
description: Deterministic motion and animation design guidance for OpenDevBrowser agents building web and mobile UI with real-browser temporal evidence.
version: 1.0.0
---

# Motion Design Skill

Use this skill when a task asks for animation, motion language, transition systems, scroll choreography, gesture motion, reduced-motion audits, browser replay evidence, or motion-heavy UI implementation.

## Pack Contents

- `artifacts/motion-terminology.md`
- `artifacts/motion-pattern-catalog.md`
- `artifacts/platform-framework-guide.md`
- `artifacts/device-breakpoint-posture.md`
- `artifacts/accessibility-reduced-motion.md`
- `artifacts/performance-frame-budget.md`
- `artifacts/open-dev-browser-motion-evidence.md`
- `artifacts/motion-release-gate.md`
- `artifacts/motion-anti-patterns.md`
- `assets/templates/motion-contract.v1.json`
- `assets/templates/motion-audit-report.v1.md`
- `assets/templates/motion-viewport-matrix.v1.json`
- `assets/templates/motion-release-gate.v1.json`
- `scripts/motion-workflow.sh`
- `scripts/validate-skill-assets.sh`

## Quick Start

1. Load `opendevbrowser-best-practices` first for OpenDevBrowser runtime rules.
2. Load `opendevbrowser-design-agent` for the parent UI implementation workflow, design contract, `/canvas`, and real-surface validation.
3. Load `opendevbrowser-motion-design` for motion language, pattern selection, platform policy, device posture, reduced motion, frame budget, and temporal proof.
4. Validate this pack before relying on its assets. From the loaded `opendevbrowser-motion-design` skill root, run:

```bash
./scripts/validate-skill-assets.sh
./scripts/motion-workflow.sh contract-first
./scripts/motion-workflow.sh temporal-proof
```

## InspireDesign Harvest Inputs

When an InspireDesign harvest bundle is available, inspect top-level `ready`, `productSuccess`, `artifactAuthority`, `evidenceAuthority`, manifest-backed evidence, `nextStepGuidance.readiness`, and `doNotProceedIf` before selecting motion patterns. Treat `nextStepGuidance.readiness` as recovery or continuation context, not the design-ready gate by itself. For canonical Pinterest pin-media harvests, require `ready=true`, `productSuccess=true`, `artifactAuthority=product_ready`, `evidenceAuthority=pin_media_ready`, and manifest-backed `pin-media-index.json`; `snapshot_ready` and `motion_ready` are not substitutes for pin-media readiness. Read `meta-prompt.md`, `ranked-references.json`, `visual-evidence.json`, `screenshot-index.json`, `motion-evidence.json`, `pin-media-evidence.json`, `pin-media-index.json`, and the referenced PNG or pin-media files only after the bundle is ready or while following recovery guidance. Treat harvested motion posture as evidence-backed design intent, not permission to add dependencies or copy source-brand choreography. Pinterest video or GIF pin-media can support sampled saved-media cues through `media-analysis.json` when pin-media-ready; `motion-evidence.json` remains the browser replay authority for captured page choreography. FFmpeg and FFprobe are optional host tools for media-analysis facts only; missing binaries degrade `media-analysis.json` without blocking pin-media readiness, and invalid env or config paths stay diagnostic instead of silently falling back. Carry accepted cues into the motion contract with explicit reduced-motion behavior, device posture, frame budget, and temporal proof requirements.

## Motion Contract

Motion is a contract field, not decoration. Before implementation, fill `assets/templates/motion-contract.v1.json` and connect it to the design-agent `motionSystem`, `performanceModel`, `responsiveSystem`, and `accessibilityPolicy` fields.

The contract must define:

- intent and user value
- selected patterns from `artifacts/motion-pattern-catalog.md`
- timing tokens, easing tokens, and spring tokens
- driver ownership for scroll, viewport, gesture, route, and state transitions
- device and breakpoint posture from `artifacts/device-breakpoint-posture.md`
- `prefers-reduced-motion` behavior from `artifacts/accessibility-reduced-motion.md`
- performance budget from `artifacts/performance-frame-budget.md`
- verification plan from `artifacts/open-dev-browser-motion-evidence.md`

## Pattern Selection

Choose patterns by user job, not visual novelty. Start with the smallest motion grammar that clarifies hierarchy or state:

- no-motion for stable task surfaces
- opacity or fade-through for low-attention state changes
- shared element, FLIP, or layout transition when continuity is the point
- sheet, modal, popover, toast, and progressive disclosure motion for containment
- scroll reveal, parallax, pinned stage, or scroll snap only when the narrative depends on viewport progress
- gesture, inertia, spring settle, interruptibility, and haptics only when direct manipulation matters
- Lottie, Rive, 3D transform, or WebGL/spatial motion only when the illustration or spatial model carries meaning

Every selected pattern needs a reduced-motion fallback, device posture, and temporal evidence.

## Platform And Framework Policy

Frameworks are implementation primitives, not permission to add dependencies. Prefer existing project libraries and platform primitives. New runtime dependencies require separate explicit approval and must be recorded in `libraryPolicy`.

Use `artifacts/platform-framework-guide.md` for CSS transitions, CSS keyframes, Web Animations API, View Transition API, CSS scroll-driven animations, Motion for React with `motion/react`, GSAP 3.x, Anime.js 4.x, react-spring, Lottie, Rive, Three.js, react-three-fiber, Spline/WebGL advisory, SwiftUI, UIKit/Core Animation, Jetpack Compose, Android MotionLayout, React Native Reanimated 4.x, Flutter animation APIs, and haptics.

## Device Posture

Motion must change across phones, tablets, laptops, desktops, large monitors, short viewports, coarse pointers, fine pointers, keyboard-only use, reduced-power devices, high-refresh displays, and foldable posture. Use `artifacts/device-breakpoint-posture.md` and `assets/templates/motion-viewport-matrix.v1.json` before coding responsive animation.

## Reduced Motion

Reduced motion is mandatory. Follow WCAG 2.2 SC 2.3.3 and `prefers-reduced-motion`. The reduced path must preserve meaning and task completion. It may remove travel, parallax, pinning, looping, and large transform distance, but it must not hide information, reorder focus, or remove feedback.

## Verification

Prove motion in a real browser. Static code review is not enough for timing, choreography, scroll stages, or gesture behavior.

Required evidence for motion-heavy work:

- `snapshot`
- `screenshot`
- `debug-trace-snapshot`
- `screencast-start`
- interaction or scroll sequence
- `screencast-stop`
- browser replay artifact inspection: omitted screencast output writes `.opendevbrowser/screencast/<uuid>` and JSON responses include `artifact_path`; explicit caller paths remain intentional exceptions
- console and network stability checks
- viewport matrix checks
- reduced-motion checks
- `/canvas` preview evidence when using design-agent canvas workflow

Treat `screencast-start` and `screencast-stop` as the `screencast / browser replay` lane for temporal proof. Reduced-motion validation must run in the browser and prove the alternate path preserves meaning, focus order, and task completion, not only that CSS media queries exist.

Use `scripts/motion-workflow.sh temporal-proof` and `artifacts/open-dev-browser-motion-evidence.md`.

## Anti-patterns

Do not ship motion when any of these are true:

- the motion has no user value
- the progress owner is unclear
- multiple scroll observers fight the same narrative
- layout properties animate in hot paths
- reduced motion removes meaning
- hover is the only affordance
- mobile travel is long enough to disorient
- pinned scroll traps reading order or focus
- gesture animation cannot be interrupted or retargeted
- a new dependency was added without approval

Use `artifacts/motion-anti-patterns.md` before release.

## Related Skills

- `opendevbrowser-best-practices`: runtime, CLI, browser, evidence, and release governance.
- `opendevbrowser-design-agent`: parent UI design, InspireDesign harvest review, and `/canvas` implementation workflow.
- `opendevbrowser-motion-design`: motion-specific terminology, pattern catalog, platform policy, device posture, reduced motion, performance, and temporal evidence.
