Introducing a new way to review your PRs.

Read the announcement

pbakaus / impeccable

The design vocabulary for your coding agent. Steer with polish and bolder, review with critique and audit, catch AI slop before it ships.

View on GitHub

32 documents · Updated Nov 20, 2026

docs / motion-capture-analysis

Motion capture analysis

Motion capture analysis records a browser interaction as a small set of time-based page snapshots. It turns visible motion into reviewable evidence and named findings so design-quality workflows can inspect continuity, content changes, layering, and reduced-motion behavior without relying on a live animation.

Analysis role

Motion capture is a focused browser workflow next to the main quality detector. The detector checks a page state; this workflow checks how that state changes after an interaction. Its findings are evidence for design review, not a complete proof that an animation is smooth.

The workflow supports common interaction entry points:

  • a click on one selector;
  • a JSON sequence of clicks, hovers, key presses, and short waits;
  • an optional setup sequence that reaches the state before the motion under review; and
  • an optional reduced-motion pass compared with a normal-motion baseline.

For the wider detector model, see UI quality detection system. The browser runtime that supplies the page session is described in Browser analysis runtime.

Motion findings remain part of the wider rule and review model. See Detection engines and antipattern rules for rule ownership and Design system profiling for the project context used by the detector's other quality checks.

Capture boundaries

The capture uses a fixed 1000 by 760 viewport and records either the full viewport or a selected region. The target must use http, https, or file, and the capture must name an output directory and an interaction sequence. Selectors identify interaction targets and regions; a numeric region uses [x,y,width,height] coordinates.

The capture accepts three to fifteen sampled frames. It limits each setup or interaction sequence to twenty steps and limits waits to two seconds. These limits keep evidence bounded and make a failed capture easier to diagnose.

References: crates/…/motion.rs• L14-18 crates/…/motion.rs• L23-31 crates/…/motion.rs• L42-83

Capture lifecycle

The capture lifecycle separates page preparation from motion sampling. It first loads and settles the page, then applies setup actions, records the settled starting state, applies the interaction, and seeks through the captured animation timeline.

When the workflow processes a request, it follows this sequence:

  1. Launch a Chromium-based browser and create a page at the fixed viewport.
  2. Load the URL and wait for fonts and two animation frames so the starting page is stable.
  3. Apply setup steps, if present, and wait for the page's current animations to reach rest.
  4. Install motion tracking and freeze the animation playback rate.
  5. Record the before frame.
  6. Apply the requested interaction and collect its animations.
  7. Record the first, middle, and last timeline samples, plus any additional requested samples.
  8. Release the animation debugger, finish the animations, and record the settled frame.
  9. Analyze the frames and write the report and evidence files.

This order matters for exit states. For example, setup can open a panel first, so the before frame shows the open panel and the requested click captures its exit rather than its entrance.

The flow below shows the relationship between preparation, evidence, and analysis.

flowchart LR
    A[URL and actions] --> B[Load and settle]
    B --> C[Optional setup]
    C --> D[Resting before frame]
    D --> E[Interaction]
    E --> F[Timeline samples]
    F --> G[Settled frame]
    G --> H[Findings and evidence]

References: crates/…/motion.rs• L172-268 crates/…/motion.rs• L213-245

Interaction model

Each step contains one action. Click and hover actions resolve the target's center point and reject missing, empty, or out-of-viewport targets. Press actions support Enter, Space, Tab, Escape, and arrow keys. Wait actions pause for at most 2000 milliseconds.

Setup uses the same action model as the captured interaction. It is not part of the reported motion; it establishes the state from which the reported interaction starts. This distinction lets a reviewer assess an exit, collapse, or replacement state without mixing it with the setup animation.

References: crates/…/motion.rs• L85-163 crates/…/motion.rs• L189-197

Animation evidence

The page-side recorder tracks CSS animations, CSS transitions, Web Animations API effects, and View Transition effects. It freezes each discovered animation at its current position, computes a wall-clock duration from playback rate and current time, then seeks all tracked effects to shared sample times.

The evidence describes visible elements and the relationships that can change during motion:

  • element boxes, opacity, clipping, content, and ancestry;
  • generated ::before and ::after content;
  • open shadow-root elements with host-qualified selectors;
  • overlapping paint order;
  • View Transition groups, old/new opacity, geometry timing, and transition paint order; and
  • animation properties and duration metadata.

The recorder also produces a screenshot for each sample. The report links each frame to its image, while the filmstrip and HTML viewer make the time sequence easy to inspect.

Finding categories

The analyzer compares adjacent boundary frames, interior samples, and layer evidence. The main finding categories are:

CategoryWhat it signals
start-jump, end-jumpA visible element appears, disappears, changes geometry, opacity, content, or shadow abruptly at a motion boundary.
mid-stepAn interior sample moves as a spike against the motion on both sides.
clipped-midwayAn element is clipped during motion but is visible at the start and end.
content-swapVisible content changes while the element or an ancestor is moving outside a View Transition.
paint-order-flipOverlapping ordinary elements change which element paints on top.
entrance-replayA finished entrance animation runs again when the interaction starts.
crossfade-dipView Transition old and new layers do not keep a near-complete combined opacity.
orphan-lingerA View Transition layer remains after related geometry motion has ended.
end-paint-swapView Transition paint order changes at settlement.
reduced-motion-ignoredA moving element keeps nearly the same distance and duration when reduced motion is requested.

The analyzer avoids some false positives by ignoring pseudo-elements for ordinary presence checks, accepting strong ease-out motion, tolerating tiny shadow interpolation differences, and treating complementary crossfades as clean. A short animation under one millisecond is treated as instant rather than sampled as visible motion.

References: crates/…/motion.rs• L299-447 crates/…/motion.rs• L449-565 crates/…/motion.js• L39-69 crates/…/motion.js• L104-218

Reduced-motion comparison

The reduced-motion option runs a normal baseline first, then captures the same interaction with reduced motion enabled. The comparison reports only when the element still moves almost the same distance and keeps almost the same relevant duration. It checks the target and its moving ancestors, so a grid gap or other container change can be attributed to the affected child.

This pass is a review aid rather than a claim that every animation must disappear. It focuses on motion that remains substantial after the page receives the reduced-motion preference.

References: crates/…/motion.rs• L656-683 crates/…/motion.rs• L743-757 crates/…/motion.js• L220-247

Evidence outputs

Each successful capture writes a report and visual evidence to the requested directory. The report records the schema version, viewport, region, setup and interaction steps, duration, animation metadata, frame metadata, findings, reduced-motion baseline duration when used, and known limitations. The visual output includes one PNG per frame, a combined filmstrip.png, and an index.html viewer with a frame scrubber.

The manifest is written last. A failed replacement therefore does not leave a report that appears valid while its images are incomplete.

References: crates/…/motion.rs• L685-729 crates/…/motion.rs• L749-767

CLI access

The motion-capture verb is a direct CLI entry point. It is routed by the main command router rather than through the normal detect target-selection path, so engineers invoke it as a dedicated browser evidence command.

Typical forms are:

impeccable motion-capture https://example.test --click "#toggle" --out-dir motion
impeccable motion-capture file:///path/page.html --steps steps.json --region "#card" --frames 9 --out-dir motion
impeccable motion-capture https://example.test --click "#close" --setup setup.json --reduced-motion --out-dir motion

The command prints the report as JSON on standard output and a short evidence summary on standard error. --help prints the usage contract. Invalid options, unsupported URL schemes, missing targets, invalid regions, and animation readiness failures return a non-zero exit code.

For the broader command and configuration surface, see Detector commands and configuration. The normal detector pipeline is described in Detector analysis pipeline; motion capture is a separate evidence command, although both use the browser runtime.

References: crates/…/router.rs• L62-69 crates/…/router.rs• L350-369 crates/…/motion.rs• L731-777 tests/…/motion.mjs• L1-7

Motion validation fixtures

The browser integration fixtures exercise one motion shape per small HTML page. The test harness runs the CLI against a file URL, limits the capture to #region, checks the expected finding kind, and confirms that report, filmstrip, viewer, and every referenced frame image exist.

The fixture set covers these behavior groups:

Fixture groupRepresentative fixturesExpected contract
Continuity and contentswap-while-growing, late-hover-lift, smoothDetect content replacement or a late boundary change while keeping smooth control motion clean.
Visibility and stackingclipped-container, sibling-over, paint-order-swap, shadow-toggleDetect transient clipping, ordinary paint-order changes, View Transition paint changes, and abrupt shadow changes.
View Transition layerscrossfade-dip, crossfade-overexposure, orphan-linger, entrance-replayCheck complementary fades, opacity loss or excess, lingering layers, and replayed entrances.
Timing and preferencesplayback-rate, playback-reverse, grid-gapCheck forward and reverse playback timing, container-driven movement, and reduced-motion comparison.
DOM boundariespseudo-twins, web-componentKeep generated-content identities distinct and capture animations inside open shadow roots.
Starting stateexit-panelConfirm setup reaches the open state before the captured exit begins.

The fixture assertions also verify that the capture phases remain ordered as before, first, last, and settled. This protects the meaning of the report as well as the finding rules.

References: crates/…/motion.rs• L11-65 crates/…/motion.rs• L66-170 crates/…/motion.rs• L174-245

Motion anti-pattern fixture

The general browser detector has a separate motion fixture at tests/…/motion.html. Its two-column page separates cases that should flag from cases that should pass, including elastic easing, good ease-out curves, safe transform and opacity changes, color and shadow transitions, layout transitions, and restrained image zoom. It validates detector rules over rendered examples; it is not a timeline-evidence fixture.

This distinction matters when a change affects both systems. A static or browser rule can judge the declared motion pattern, while motion-capture can judge the observed transition between states.

References: tests/…/motion.html• L8-13 tests/…/motion.html• L22-63 tests/…/motion.html• L68-183

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the CLI option contract, URL validation, and oracle goldens aligned.
  • Keep report frame phases and image names aligned with the filmstrip and HTML viewer.
  • When a finding kind or evidence field changes, update the analyzer tests and the fixture expectation that proves it.
  • When selector identity or shadow-root traversal changes, check both web-component and pseudo-element fixtures.
  • When reduced-motion timing changes, verify both baseline duration reporting and the moving-ancestor comparison.
  • When View Transition evidence changes, check complementary fades, orphan layers, paint swaps, and shadow-layer checks together.
  • When capture setup or viewport rules change, preserve the distinction between setup state and the captured interaction.

Important failure modes

TriggerConsequenceGuard
The interaction selector is missing, has no box, or falls outside the fixed viewportThe capture stops before producing motion evidenceUse a visible target inside the 1000 by 760 capture viewport
A new animation starts after capture readinessThe timeline can no longer represent one stable interactionCapture that interaction separately or start all related motion from the requested action
Animation timing is infinite or exceeds ten secondsThe recorder cannot create a bounded timelineUse finite animation timing within the capture limit
Motion continues after the final sampleThe page does not reach the required settled stateRemove chained or newly created motion, or capture the later interaction separately
A region contains more than 2000 elementsSnapshot collection fails rather than producing incomplete evidenceSelect a smaller region
Closed shadow roots, canvas, masks, clip paths, cross-origin frames, or unsynchronized timers carry the motionThe report may miss or estimate part of the visible effectInspect the filmstrip and treat the stated limitation as a need for human review

Key files

FileWhy to read it
crates/…/motion.rsDefines the capture contract, lifecycle, report, evidence writer, and deterministic finding analysis.
crates/…/motion.jsDefines the page-side animation recorder, element snapshots, shadow-root coverage, and View Transition evidence.
crates/…/router.rsShows how the dedicated motion-capture verb enters the CLI.
crates/…/motion.rsShows the browser contract and the expected finding and artifact checks for each fixture.
tests/fixtures/motion/Provides focused pages for continuity, layers, timing, reduced motion, DOM boundaries, and setup-state checks.
tests/…/motion.htmlProvides rendered pass and fail examples for the detector's general motion rules.
tests/…/motion.mjsDefines browser-free CLI contract cases for help, usage errors, and URL validation.