Agent-Skills.md

Agent Skills: Design Motion Audit

Audits a repo, route, screen, or 3D scene for motion quality, covering design-token consistency, frame-rate and draw-call risk, reduced-motion coverage, and accessibility. Use to audit, critique, or find motion gaps. Returns a prioritized punch list rather than implementing fixes.

UncategorizedID: bjornmelin/dev-skills/design-motion-audit

Repository

bjornmelin/dev-skills
BjornMelin
8

Install this agent skill to your local

pnpm dlx add-skill https://github.com/BjornMelin/dev-skills/tree/HEAD/plugins/design-motion/skills/design-motion-audit

Skill Files

Browse the full folder contents for design-motion-audit.

Download Skill

Loading file tree…

plugins/design-motion/skills/design-motion-audit/SKILL.md

Skill Metadata

Name
design-motion-audit
Description
"Audits a repo, route, screen, or 3D scene for motion quality, covering design-token consistency, frame-rate and draw-call risk, reduced-motion coverage, and accessibility. Use to audit, critique, or find motion gaps. Returns a prioritized punch list rather than implementing fixes."

Design Motion Audit

Audit the target surface (a repo, route, screen, component, or 3D scene) for motion quality and implementation safety, and return a prioritized punch list with exact files, severity, reasoning, and concrete fixes. This skill diagnoses; it routes implementation to the owning skill (expo-motion, web-three-r3f for R3F setup and correctness, r3f-scene-polish for look-dev, or gsap). Token and motion-system work is handled here via references/design-system-tokens.md and scripts/scaffold_motion_tokens.py.

How to run

  1. Optionally run the static analyzers to gather leads (treat findings as leads, verify each against the real code before reporting):

    python3 scripts/detect_motion_stack.py <project-root> --pretty   # what stacks/files exist
python3 scripts/audit_motion_system.py <project-root> --pretty    # heuristic motion-quality scan

  2. Read the flagged files and judge against the dimensions below.

  3. Return the punch list, most-severe first.

Optional analyzers

These Rust CLIs are optional static-lead generators. Install only the analyzers needed for the target stack, run doctor to capture the exact catalog/version, and verify every result in the source before reporting it.

| Tool | Use for | Catalog | | --- | --- | --- | | motion-token-audit | Cross-stack token drift and orphans | rules | | expo-motion-audit | Reanimated/Worklets source and Expo config | rules | | gsap-audit | GSAP/ScrollTrigger and React source | rules |

# From a dev-skills checkout only. Standalone skill installs lack the
# crates tree, so these commands fail there: skip this section and work
# from the audit dimensions below (static-only mode).
cargo install --path crates/motion-token-audit --locked --force
cargo install --path crates/expo-motion-audit --locked --force
cargo install --path crates/gsap-audit --locked --force

# Record the exact installed version and catalog before scanning.
motion-token-audit doctor --format json
expo-motion-audit doctor --format json
gsap-audit doctor --format json

# Omit --categories for a full scan; otherwise record the CSV used in the report.
motion-token-audit scan --root <project-root> --format json
expo-motion-audit scan --root <project-root> --format json
gsap-audit scan --root <project-root> --format json

Audit dimensions

  1. Design tokens & consistency — hardcoded durations/easings/springs vs tokenized values; naming by intent. (references/motion-vocabulary.md)
  2. R3F / three.js / WebGL — setState in useFrame, missing delta-time, per-frame allocations, disposal, DPR, shadows, postprocessing budget.
  3. Reanimated / Expo / gestures — JS-thread per-frame work, deprecated runOnJS/runOnUI, worklet misuse, interruptibility, layout-vs-transform.
  4. Interaction physicality — velocity-aware release, cancellation-safety.
  5. Performance risk — frame budget, draw calls, texture/asset weight, blur. (references/performance-accessibility.md)
  6. Reduced-motion coverage — every camera move, parallax, loop, and bounce has a reduced-motion branch that preserves functional feedback.
  7. Accessibility & readability — text legibility during motion.
  8. Missing hallmark opportunities — where a signature motion would add value.

Score against references/quality-gates.md, and shape the output with references/report-template.md. For any change with a visible motion surface, add runtime proof (references/runtime-verification.md) — static findings alone do not prove a scene renders or holds its frame budget; the motion-runtime-verifier subagent (design-motion plugin) drives that when the browser tools are available. For deep implementation fixes, hand each finding to the skill that owns its stack.