opendevbrowser 0.0.31 → 0.0.33

package/skills/opendevbrowser-design-agent/scripts/validate-skill-assets.sh

@@ -100,6 +100,8 @@ const skillDocMarkers = [
   "plan_invalid",
   "plan_accepted",
   "recommendedNextCommands",
+  "nextStepGuidance.readiness",
+  "social/pinterest",
   "canvas.plan.set",
   "canvas.history.undo",
   "canvas.history.redo",
@@ -129,7 +131,9 @@ const designWorkflowMarkers = [
   "handshake_read",
   "plan_invalid",
   "plan_accepted",
-  "recommendedNextCommands"
+  "recommendedNextCommands",
+  "guidance.nextStepGuidance",
+  "guidance.paramsExamples"
 ];
 
 const workflowOutputMarkers = {
@@ -145,7 +149,9 @@ const workflowOutputMarkers = {
     "handshake_read",
     "plan_invalid",
     "plan_accepted",
-    "recommendedNextCommands"
+    "recommendedNextCommands",
+    "guidance.nextStepGuidance",
+    "guidance.paramsExamples"
   ]
 };
 

package/skills/opendevbrowser-motion-design/SKILL.md

@@ -0,0 +1,129 @@
+---
+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 `nextStepGuidance.readiness` and `doNotProceedIf` before selecting motion patterns. Read `meta-prompt.md`, `ranked-references.json`, `visual-evidence.json`, `screenshot-index.json`, and the referenced PNG 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. 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`
+- console and network stability checks
+- viewport matrix checks
+- reduced-motion checks
+- `/canvas` preview evidence when using design-agent canvas workflow
+
+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.

package/skills/opendevbrowser-motion-design/artifacts/accessibility-reduced-motion.md

@@ -0,0 +1,37 @@
+# Accessibility And Reduced Motion
+
+Motion must satisfy WCAG 2.2 SC 2.3.3 Animation from Interactions and respect `prefers-reduced-motion`.
+
+## Essential Versus Non-essential Motion
+
+Essential motion is required to understand spatial continuity, preserve orientation, or complete a task. Non-essential motion is decorative, atmospheric, or brand-only. Non-essential motion must be disableable. Essential motion still needs a reduced alternative that preserves meaning.
+
+## Required Rules
+
+- Provide a `prefers-reduced-motion` path for every selected pattern.
+- Preserve all information in the reduced path.
+- Do not remove task feedback, labels, focus, or completion state when reducing motion.
+- Do not rely on motion-only feedback; pair it with text, state, color, icon, or ARIA where relevant.
+- Avoid vestibular triggers: large parallax, zoom, spinning, unbounded loops, forced pinning, and long-distance travel.
+- Keep keyboard order and visual order coherent.
+- Keep focus stable before, during, and after animation.
+- Provide pause, disable, or non-looping behavior for decorative repeated animation.
+- Screen-reader alternatives must describe state changes when animation communicates status.
+- Use ARIA live regions for async status only when they are relevant and not noisy.
+
+## Reduced-motion Examples
+
+- Shared element transition becomes fade-through or instant route change with heading focus.
+- Pinned scroll stage becomes stacked static sections.
+- Parallax becomes a static layered image.
+- Skeleton shimmer becomes a static skeleton with loading text.
+- Drag overshoot becomes direct snap to final target.
+- Lottie or Rive loop becomes a poster frame.
+
+## Blocking Failures
+
+- Reduced motion removes content.
+- Reduced motion leaves content hidden because the reveal animation never runs.
+- Focus moves to an invisible or offscreen element.
+- A hover animation is the only affordance.
+- A loop cannot be paused or stopped.

package/skills/opendevbrowser-motion-design/artifacts/device-breakpoint-posture.md

@@ -0,0 +1,40 @@
+# Device And Breakpoint Posture
+
+Motion must adapt to posture, pointer, viewport height, power, and refresh rate. Do not assume desktop timing scales down.
+
+## Posture Matrix
+
+| Posture | Motion Changes |
+|---|---|
+| Mobile portrait | Shorter duration, shorter travel, no default parallax, avoid pinned scroll, larger gesture thresholds, protect touch targets. |
+| Mobile landscape | Reduce vertical choreography, avoid blocking short viewports, keep primary actions visible. |
+| Tablet portrait | Moderate travel, sheet or side panel based on density, touch-friendly drag thresholds. |
+| Tablet landscape | Can use wider spatial transitions, but preserve reading order and pointer/touch parity. |
+| Laptop and desktop | Fine pointer allows hover and richer route continuity, but keyboard parity remains required. |
+| Large monitor | Avoid excessive travel across long distances; anchor transitions to local regions. |
+| Short viewport | Disable pinning, reduce stage count, avoid vertical reveal dependency. |
+| Coarse pointer | Prefer press/tap feedback, larger handles, drag thresholds, no hover-only affordance. |
+| Fine pointer | Hover/focus microinteractions allowed with keyboard equivalent. |
+| Trackpad | Scroll and inertia can be richer, but must not fight native scroll. |
+| Touch gesture context | Use interruptible, retargetable, threshold-based motion. |
+| Keyboard-only context | Motion cannot change focus order or hide reachable controls. |
+| Reduced-power devices | Prefer opacity, transform, static skeletons, fewer simultaneous animations. |
+| High-refresh displays | Validate smoothness at high refresh and avoid timing tied to frame counts. |
+| Foldable/device posture | Treat `device-posture` as experimental progressive enhancement only. Default to responsive breakpoints first. |
+
+## What Changes By Posture
+
+- Duration: shorter on phones, reduced-power devices, and repeated workflows.
+- Distance: local on mobile and large monitors; never force long travel across the screen.
+- Pinned-scroll allowance: desktop only by default, disabled on short viewports and most phones.
+- Parallax allowance: off by default on mobile and reduced motion.
+- Gesture thresholds: larger for touch, smaller for precision pointer, always cancellable.
+- Touch target protection: animation must not shrink active targets below usable size.
+- Density: reduce stagger count and choreography in dense content.
+- Viewport-height constraints: no stage should require more height than the viewport can provide.
+- Fallback behavior: static, stacked, and readable content must exist for every scroll stage.
+- Reduced-motion handling: remove travel, pinning, parallax, loops, and non-essential gesture flourish.
+
+## Foldable Rule
+
+`device-posture` is experimental. Use it only as progressive enhancement after the default responsive layout and motion contract already work without it.

package/skills/opendevbrowser-motion-design/artifacts/motion-anti-patterns.md

@@ -0,0 +1,29 @@
+# Motion Anti-patterns
+
+Do not ship these motion failures.
+
+- Decorative motion without user value.
+- Missing progress owner for route, state, scroll, or gesture animation.
+- Competing scroll observers for the same narrative.
+- Layout-property animation in hot paths.
+- Long-distance mobile travel.
+- Default parallax without vestibular and reduced-motion review.
+- Pinned scroll without escape condition.
+- Hover-only affordance.
+- Hidden focus or reading-order changes.
+- Reduced motion that removes meaning.
+- Unbounded loops.
+- Fake progress.
+- Unapproved runtime dependency.
+- Haptic spam.
+- Index-keyed animated lists.
+- Non-interruptible gesture animation.
+- Motion-only status feedback.
+- Skeleton shimmer that never resolves.
+- Shared element transition with unstable identity.
+- WebGL or canvas motion without static accessible equivalent.
+- Animation cleanup leaks after unmount or route change.
+
+## Fix Pattern
+
+For every anti-pattern, either remove the motion, reduce it to a simpler pattern, or rewrite the motion contract with a clear owner, fallback, and evidence plan.