Motion quality gate

Motion Quality Gate

Review web animation and interaction motion without turning taste heuristics into universal laws. Prefer observed behavior, measurements and current platform documentation over stylistic absolutes.

Outcome

Produce a decision that answers four questions:

1. Does the motion serve the interaction?
2. Does it preserve control, continuity and accessibility?
3. Does it remain smooth under realistic conditions?
4. What is the smallest change that improves it?

Review only unless the user also asks for implementation.

Evidence hierarchy

Use evidence in this order:

1. Rendered behavior observed in the target browser or device.
2. Performance traces, frame evidence or reproducible interaction results.
3. Source code at exact file and line.
4. Current framework and platform documentation.
5. Calibrated craft heuristics.

Never present a heuristic as measured fact. Never infer GPU acceleration, main-thread behavior or accessibility compliance from syntax alone.

Read references/calibrated-motion-standards.md when exact timing, easing, performance, accessibility or framework guidance is needed.

Workflow

1. Establish the interaction contract

Identify:

• the user action and intended feedback
• how often the interaction occurs
• input modes: pointer, touch, keyboard or assistive technology
• target browsers and devices
• component personality and product context
• whether motion conveys essential information
• the files, route or rendered page in scope

If these are unknown, state the assumption that affects the verdict.

2. Inspect the implementation

Find the motion entry points:

• CSS transitions, keyframes and starting styles
• Web Animations API
• Motion, Framer Motion or another animation library
• spring and gesture handlers
• pointer capture, drag thresholds and velocity handoff
• focus, keyboard and reduced-motion behavior
• hover behavior on touch-capable devices
• animated layout, paint and composite properties
• cancellation, interruption and rapid re-trigger behavior

Search narrowly and cite exact file and line locations. Ignore unrelated code.

3. Exercise rendered behavior

When the project can run safely, inspect the actual interaction:

• normal speed
• slowed playback or frame-by-frame inspection
• rapid repeated activation
• interruption and reversal mid-animation
• keyboard, pointer and touch paths when relevant
• reduced-motion preference
• mobile and desktop layouts
• realistic load or CPU pressure when performance is material

Capture the test route, viewport, browser, input path and result. If rendered testing is unavailable, mark behavioral and performance conclusions as unverified.

4. Review across seven dimensions

1. Purpose and frequency: motion earns its attention cost.
2. Response and timing: feedback begins when the user expects it and does not delay control.
3. Spatial continuity: origin, direction and state changes preserve orientation.
4. Input and interruptibility: the user can reverse, repeat or cancel without jumps or locks.
5. Performance: the implementation avoids observed jank and unnecessary rendering work.
6. Accessibility: reduced motion, focus, pointer diversity and essential information are handled.
7. Cohesion: motion fits the component, product and interaction rather than displaying generic flourish.

5. Calibrate each finding

Use these levels:

• Blocker: loss of control, inaccessible essential interaction, severe reproducible jank, unsafe flashing or motion, or a broken primary path.
• Major: observed degradation or a high-confidence defect with meaningful user impact.
• Minor: localized polish or maintainability issue with limited impact.
• Suggestion: a taste improvement or experiment, not a defect.

Label every finding as Observed, Measured, Code-inferred or Heuristic. Include confidence as high, medium or low.

Do not automatically block:

• ease-in
• scale from zero
• animation over 300 milliseconds
• keyboard-triggered motion
• width or height animation
• Motion x, y or scale props
• clip-path, filter or JavaScript animation

These are review prompts. Severity depends on purpose, frequency, actual behavior and evidence.

6. Recommend the smallest effective remedy

Prefer this order:

1. Remove motion that has no job.
2. Reduce distance, duration, repetition or affected area.
3. Correct timing, easing, origin or direction.
4. Preserve interruption, cancellation and velocity continuity.
5. Replace expensive work only after profiling identifies it.
6. Add reduced-motion and input-mode handling.
7. Add decorative polish last.

Do not rewrite the motion system when a local correction is sufficient.

Required output

Lead with one verdict:

• Approve
• Approve with changes
• Block
• Unverified

Then provide:

Findings

For each finding:

• Severity and evidence type
• Location
• Observed or expected behavior
• Why it matters
• Smallest recommended change
• Confidence

Use exact file and line references. Include reproduction steps for Blocker and Major findings.

Validation record

List:

• routes or components inspected
• browser, viewport and input modes
• reduced-motion result
• rapid-trigger or interruption result
• performance evidence gathered
• important checks not performed

Good decisions preserved

Name motion choices that should remain. A quality gate should protect good work, not only produce criticism.

Guardrails

• Do not promote a course, author or tool.
• Do not force an Apple-like aesthetic onto every product.
• Do not treat one designer's preference as a platform requirement.
• Do not claim browser or library behavior without version-aware evidence.
• Do not approve rendered motion that was materially in scope but never exercised; use Unverified.
• Do not modify code, dependencies or live systems unless the user asks.