opendevbrowser 0.0.31 → 0.0.32

package/skills/opendevbrowser-best-practices/scripts/odb-workflow.sh

@@ -18,6 +18,14 @@ CLI_PREFIX="$(render_cli_prefix)"
 PACKAGE_ROOT="$(cd "$script_dir/../../.." && pwd)"
 TRANSCRIPT_PROBE_PATH="$(printf '%q' "$PACKAGE_ROOT/scripts/youtube-transcript-live-probe.mjs")"
 
+print_daemon_preflight() {
+  cat <<EOF
+# Daemon preflight for daemon-backed workflows:
+$CLI_PREFIX status --daemon --output-format json
+# Continue only when data.fingerprintCurrent === true.
+EOF
+}
+
 print_help() {
   cat <<'EOF'
 OpenDevBrowser workflow router
@@ -73,6 +81,7 @@ opendevbrowser_wait sessionId="<session-id>" until="networkidle"
 EOF
     ;;
   inspiredesign)
+    print_daemon_preflight
     cat <<EOF
 # Pair with opendevbrowser-design-agent when the contract will flow into implementation or /canvas work.
 $CLI_PREFIX inspiredesign run --brief "Design a premium docs workspace" --url "https://example.com/reference-a" --url "https://example.com/reference-b" --capture-mode off --include-prototype-guidance --mode json --output-format json
@@ -118,6 +127,7 @@ opendevbrowser_network_poll sessionId="<session-id>" max=100
 EOF
     ;;
   canvas-preflight)
+    print_daemon_preflight
     cat <<EOF
 cat skills/opendevbrowser-best-practices/assets/templates/canvas-handshake-example.json
 cat skills/opendevbrowser-best-practices/assets/templates/canvas-generation-plan.v1.json
@@ -132,6 +142,7 @@ $CLI_PREFIX canvas --command canvas.plan.set --params-file skills/opendevbrowser
 EOF
     ;;
   canvas-feedback-eval)
+    print_daemon_preflight
     cat <<EOF
 cat skills/opendevbrowser-best-practices/artifacts/canvas-governance-playbook.md
 cat skills/opendevbrowser-best-practices/assets/templates/canvas-feedback-eval.json
@@ -151,6 +162,7 @@ npm run test -- tests/tools.test.ts tests/daemon-commands.integration.test.ts
 EOF
     ;;
   release-direct-gates)
+    print_daemon_preflight
     cat <<'EOF'
 mkdir -p artifacts/release/vX.Y.Z
 node scripts/provider-direct-runs.mjs --release-gate --out artifacts/release/vX.Y.Z/provider-direct-runs.json
@@ -158,6 +170,7 @@ node scripts/live-regression-direct.mjs --release-gate --out artifacts/release/v
 EOF
     ;;
   skill-runtime-audit)
+    print_daemon_preflight
     cat <<'EOF'
 npm run build
 node scripts/docs-drift-check.mjs
@@ -174,6 +187,7 @@ OPENCODE_CONFIG_DIR="$WORKDIR/config" CODEX_HOME="$WORKDIR/codex-home" CLAUDECOD
 ./skills/opendevbrowser-continuity-ledger/scripts/validate-skill-assets.sh
 ./skills/opendevbrowser-data-extraction/scripts/validate-skill-assets.sh
 ./skills/opendevbrowser-design-agent/scripts/validate-skill-assets.sh
+./skills/opendevbrowser-motion-design/scripts/validate-skill-assets.sh
 ./skills/opendevbrowser-form-testing/scripts/validate-skill-assets.sh
 ./skills/opendevbrowser-login-automation/scripts/validate-skill-assets.sh
 ./skills/opendevbrowser-product-presentation-asset/scripts/validate-skill-assets.sh
@@ -184,6 +198,7 @@ node scripts/skill-runtime-audit.mjs --out artifacts/skill-runtime-audit/full.js
 EOF
     ;;
   validated-capabilities)
+    print_daemon_preflight
     cat <<EOF
 # Public-first YouTube transcript probe
 node $TRANSCRIPT_PROBE_PATH --url "https://www.youtube.com/watch?v=aircAruvnKk" --youtube-mode auto --out artifacts/capability-fix/youtube-transcript-auto.json
@@ -214,22 +229,29 @@ EOF
   ops-channel-check)
     cat <<EOF
 $CLI_PREFIX serve
+# Daemon preflight for daemon-backed workflows:
+$CLI_PREFIX status --daemon --output-format json
+# Continue only when data.fingerprintCurrent === true.
 $CLI_PREFIX launch --extension-only --wait-for-extension --output-format json
 $CLI_PREFIX status --daemon --output-format json
-# Verify opsConnected=true and extensionHandshakeComplete=true
+# Verify fingerprintCurrent=true, opsConnected=true, and extensionHandshakeComplete=true
 cat skills/opendevbrowser-best-practices/assets/templates/ops-request-envelope.json
 EOF
     ;;
   cdp-channel-check)
     cat <<EOF
 $CLI_PREFIX serve
+# Daemon preflight for daemon-backed workflows:
+$CLI_PREFIX status --daemon --output-format json
+# Continue only when data.fingerprintCurrent === true.
 $CLI_PREFIX launch --extension-only --extension-legacy --wait-for-extension --output-format json
 $CLI_PREFIX status --daemon --output-format json
-# Verify cdpConnected=true while legacy session is active
+# Verify fingerprintCurrent=true and cdpConnected=true while legacy session is active
 cat skills/opendevbrowser-best-practices/assets/templates/cdp-forward-envelope.json
 EOF
     ;;
   mode-flag-matrix)
+    print_daemon_preflight
     cat <<EOF
 cat skills/opendevbrowser-best-practices/assets/templates/mode-flag-matrix.json
 $CLI_PREFIX launch --no-extension --output-format json

package/skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh

@@ -79,6 +79,7 @@ const workflowMarkers = [
   "npx opendevbrowser help",
   "./skills/opendevbrowser-continuity-ledger/scripts/validate-skill-assets.sh",
   "resolve-odb-cli.sh",
+  "./skills/opendevbrowser-motion-design/scripts/validate-skill-assets.sh",
   "CLI_PREFIX"
 ];
 

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

@@ -40,6 +40,7 @@ Use this skill for frontend work that must be visually strong, contract-first, a
 - `scripts/design-workflow.sh`
 - `scripts/extract-canvas-plan.sh`
 - `scripts/validate-skill-assets.sh`
+- Motion authority: `../opendevbrowser-motion-design/SKILL.md`
 - Shared robustness matrix: `../opendevbrowser-best-practices/artifacts/browser-agent-known-issues-matrix.md`
 - Shared canvas workflow baseline: `../opendevbrowser-best-practices/SKILL.md`
 
@@ -72,6 +73,7 @@ Use this skill for frontend work that must be visually strong, contract-first, a
 ## Supporting Surfaces
 
 - Use browser replay (`screencast-start` / `screencast-stop`) during real-surface validation when motion, sequencing, or transition timing matters.
+- Load `opendevbrowser-motion-design` when motion-heavy work needs terminology, pattern catalog decisions, platform/framework policy, device posture, reduced-motion rules, performance budgets, or temporal proof.
 - Treat shader, WebGL, Spline-style, and custom 3D motion references as advisory cues unless current runtime evidence proves support.
 - Desktop observation stays read-only and is only for external window or OS-level evidence around the workflow; it is not a design-surface control lane.
 - Browser-scoped computer use remains a challenge posture knob via `--challenge-automation-mode`, not a desktop-agent capability.
@@ -98,6 +100,7 @@ Use this skill for frontend work that must be visually strong, contract-first, a
 - For non-canvas frontend work, still fill the same design-contract fields before coding so decisions stay consistent across code, preview, and docs.
 - Use one owner for overlays, drawers, sheets, and detail panels; prefer item-backed state over boolean sprawl.
 - If motion depends on scroll or viewport progress, define the driver and reduced-motion fallback before implementation.
+- For animation systems, route the motion-specific decisions through `../opendevbrowser-motion-design/artifacts/motion-pattern-catalog.md`, `../opendevbrowser-motion-design/artifacts/platform-framework-guide.md`, `../opendevbrowser-motion-design/artifacts/performance-frame-budget.md`, and `../opendevbrowser-motion-design/artifacts/open-dev-browser-motion-evidence.md`.
 - Carry advanced motion cues through `designVectors` and `motionSystem` as design intent only; they do not authorize new runtime libraries.
 - Keep `libraryPolicy.motion` and `libraryPolicy.threeD` empty in samples unless a separate runtime change explicitly approves those lanes.
 - Use `artifacts/scroll-reveal-surface-planning.md` whenever the design depends on pinned sections, reveal stages, or viewport-driven sequencing.

package/skills/opendevbrowser-design-agent/artifacts/research-harvest-workflow.md

@@ -4,44 +4,95 @@ Use this workflow before design direction is locked, when the brief references c
 
 ## Goal
 
-Turn live product references into a deterministic pattern board instead of vague inspiration.
+Turn live product references into a deterministic ranked pattern board and motion-aware design brief instead of vague inspiration.
 
 ## Inputs
 
 - A focused brief or design question
-- `3` to `5` reference products or pages
+- `3` to `5` reference products or pages, or a bounded public discovery query
 - The target surface in this repo
 - Constraints that must not be violated:
   - existing design system rules
   - supported libraries and runtime budgets
   - accessibility and responsive requirements
+  - provider policy boundaries for blocked, auth-required, challenge, or rate-limited references
 
-## Evidence Loop
-
-1. Pick reference pages that match the product shape:
-   - dashboard
-   - marketing landing page
-   - onboarding flow
-   - editor
-   - auth/settings surface
-2. Capture the surface with OpenDevBrowser:
-   - `launch`
-   - `goto`
-   - `snapshot`
-   - `screenshot`
-   - `debug-trace-snapshot` when motion, loading, or layout churn matters
-3. Record each page in `assets/templates/reference-pattern-board.v1.json`.
-4. For each reference, extract:
-   - layout recipe
-   - content hierarchy
-   - component families
-   - motion posture
-   - loading and empty-state strategy
-   - token and theming clues
-   - patterns to borrow
-   - patterns to reject
-5. Synthesize only the patterns that fit the repo's current surface, libraries, and runtime budgets.
-6. Translate the synthesis into the design contract before touching `/canvas` or code.
+## Primary Harvest Loop
+
+Prefer the dedicated InspireDesign harvest entrypoint for visual-first research:
+
+```bash
+npx opendevbrowser inspiredesign harvest \
+  --brief "Synthesize a premium docs workspace" \
+  --query "best docs product landing pages" \
+  --provider web/default \
+  --max-references 5 \
+  --visual-evidence required \
+  --browser-mode managed \
+  --mode json
+```
+
+Use explicit references when the team already knows the right examples:
+
+```bash
+npx opendevbrowser inspiredesign harvest \
+  --brief "Extract reusable dashboard patterns" \
+  --url https://example.com/reference-a \
+  --url https://example.com/reference-b \
+  --visual-evidence required \
+  --mode json
+```
+
+Harvest defaults:
+
+- `mode=path`
+- `visualEvidence=required`
+- `maxReferences=5`
+- explicit `--url` references rank before query-discovered candidates during collection
+- the daemon method remains `inspiredesign.run`
+
+## Required Artifact Review
+
+After a successful harvest, inspect these files before `/canvas` or code changes:
+
+1. `advanced-brief.md` for the reference-first creative brief.
+2. `ranked-references.json` for rank, score, confidence, visual strengths, visual risks, rejected references, and selection reasons.
+3. `visual-evidence.json` and `screenshot-index.json` for artifact-relative PNG paths, hashes, byte counts, viewport metadata when available, provenance, and warnings.
+4. PNG files under `visual-evidence/<referenceId>/viewport.png` for actual visual review.
+5. `meta-prompt.md` for borrow guidance, reject guidance, motion posture, accessibility constraints, no-copy warning, and validation gates.
+6. `canvas-plan.request.json` and `design-agent-handoff.json` only after the visual synthesis is accepted.
+
+JSON files are metadata-only. They must not contain base64 screenshots, absolute temp paths, full DOM, or full snapshot text.
+
+## Manual Evidence Fallback
+
+Use the lower-level browser loop only when harvest cannot run or when a single reference needs debugging:
+
+```bash
+npx opendevbrowser launch --no-extension --start-url https://example.com
+npx opendevbrowser goto --session-id <session-id> --url <reference-url>
+npx opendevbrowser snapshot --session-id <session-id>
+npx opendevbrowser screenshot --session-id <session-id> --path ./artifacts/reference.png
+npx opendevbrowser debug-trace-snapshot --session-id <session-id>
+```
+
+Record manual evidence in `assets/templates/reference-pattern-board.v1.json` using the same ranking and screenshot metadata fields as harvest.
+
+## What To Extract
+
+For each accepted reference, extract:
+
+- layout recipe
+- content hierarchy
+- component families
+- motion posture
+- loading and empty-state strategy
+- token and theming clues
+- visual strengths to borrow
+- visual risks and patterns to reject
+- screenshot path, hash, viewport, and warning metadata when available
+
+Synthesize only the patterns that fit the repo's current surface, libraries, runtime budgets, and accessibility policy.
 
 ## What To Borrow From External Patterns
 
@@ -61,21 +112,15 @@ These cues should stay explicit in the pattern board:
   - inspect current stack and assets first
   - combine aesthetics, accessibility, and implementation practicality in one review loop
 
-## OpenDevBrowser Command Pattern
-
-```bash
-npx opendevbrowser launch --no-extension --start-url https://example.com
-npx opendevbrowser goto --session-id <session-id> --url <reference-url>
-npx opendevbrowser snapshot --session-id <session-id>
-npx opendevbrowser screenshot --session-id <session-id>
-npx opendevbrowser debug-trace-snapshot --session-id <session-id>
-```
+## Motion Follow-through
 
-Repeat this for each selected reference. Keep the resulting notes in one pattern board so the design contract has a visible source of truth.
+Load `opendevbrowser-motion-design` before translating harvest motion posture into timing tokens, scroll choreography, gesture motion, reduced-motion behavior, or temporal proof. Harvest motion cues are design intent only; they do not authorize new runtime dependencies or shader, WebGL, Spline, or 3D lanes.
 
 ## Exit Criteria
 
-- The pattern board lists at least `3` live references.
+- The pattern board lists at least `3` live references unless provider policy or discovery diagnostics explain the smaller set.
 - Borrowed and rejected patterns are both explicit.
+- Rank 1 justifies the dominant direction.
+- Screenshot metadata points to existing PNG artifacts or explains skipped or failed visual evidence.
 - The chosen design direction is justified by evidence, not taste alone.
-- The resulting design contract names component families, state ownership, and validation targets before implementation starts.
+- The resulting design contract names component families, state ownership, motion posture, and validation targets before implementation starts.

package/skills/opendevbrowser-design-agent/artifacts/scroll-reveal-surface-planning.md

@@ -2,6 +2,8 @@
 
 Use this when narrative sequencing, pinned sections, or viewport-driven motion is part of the design instead of decorative afterthought.
 
+For broader motion language, pattern selection, device posture, reduced-motion rules, performance budgets, and temporal proof, also load `../opendevbrowser-motion-design/SKILL.md`.
+
 ## 1. Declare The Driver First
 
 Choose one progress owner before writing animation code:

package/skills/opendevbrowser-design-agent/assets/templates/reference-pattern-board.v1.json

@@ -4,30 +4,45 @@
   "references": [
     {
       "id": "ref-001",
+      "rank": 1,
+      "score": 86,
+      "confidence": 0.86,
       "name": "Example product page",
       "url": "https://example.com",
       "surfaceType": "marketing",
       "capturedVia": [
+        "fetch",
         "snapshot",
-        "screenshot"
+        "clone",
+        "dom",
+        "visual"
       ],
       "layoutRecipe": "",
       "contentHierarchy": [],
       "componentFamilies": [],
-      "motionPosture": "",
-      "advancedMotionAdvisory": [],
-      "loadingStrategy": "",
+      "motionPosture": [],
       "tokenNotes": [],
+      "visualStrengths": [],
+      "visualRisks": [],
+      "selectionReason": "",
       "patternsToBorrow": [],
       "patternsToReject": [],
       "whyItWorks": ""
     }
   ],
+  "rejectedReferences": [
+    {
+      "id": "ref-rejected-001",
+      "url": "https://example.com/rejected",
+      "reason": "policy_blocked|auth_required|challenge_detected|rate_limited|not_relevant|duplicate",
+      "fetchStatus": "failed",
+      "captureStatus": "off"
+    }
+  ],
   "synthesis": {
     "dominantDirection": "",
     "sharedStrengths": [],
     "sharedFailuresToAvoid": [],
-    "motionContractDeltas": [],
     "contractDeltas": []
   }
 }

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, read `meta-prompt.md`, `ranked-references.json`, `visual-evidence.json`, `screenshot-index.json`, and the referenced PNG files before selecting motion patterns. 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.