Pixel2Motion Documentation

Pixel2Motion is a specialized skill designed to transform raster logos (PNG, JPG, WebP, or screenshots) into high-quality, animated SVG/HTML assets. The process follows a three-phase pipeline:

1. Phase 1 — PIXEL: Analysis of the source image and creation of a motion brief.
2. Phase 2 — VECTOR: Converting the raster into minimal, smooth, and motion-ready SVG geometry.
3. Phase 3 — MOTION: Choreographing the geometry using Disney's 12 Principles of Animation.

The core philosophy is that minimal smooth geometry IS animatable geometry. A professional result requires a 'Final Frame Contract' where the animation lands exactly on a QA-verified static vector.

A complete Pixel2Motion project produces the following artifacts:

• logo.svg: The final structured static vector.
• motion.css: The choreographed CSS targeting semantic SVG IDs.
• logo_motion.html: A dependency-free HTML showcase with replay, speed control, and QA hooks.
• motion_spec.md: The motion brief containing principles, easing tokens, and QA notes.
• outputs/fit_iterations/*.png: Visual evidence of geometry fitting.
• outputs/motion_frames/*.png & outputs/motion_strip.png: Deterministic motion QA frames.
• outputs/final_render.png & outputs/html_render.png: Static render verification files.

To achieve professional-grade motion, structure your animation timeline using the following ratio for Anticipation, Action, and Follow-through:

Anticipation : Action : Follow-through = 20% : 50% : 30%

Example for a 1500ms reveal:

• Anticipation: ~300ms
• Main Action: ~750ms
• Settle (Follow-through): ~450ms

Staggering Rule: Stagger overlapping parts by 10–20% of the part's own duration. Never allow all parts to start or stop on the same frame to avoid a mechanical look. Follow the drag hierarchy: root → primary → secondary → tertiary detail.

When animating a draw-on stroke that crosses itself (like an infinity symbol or monogram), a standard mask will cause the 'other' branch to pop in prematurely at the intersection. Use the split-fill recipe from references/reveal-patterns.md §1b:

1. Cut the fill: Divide the fill into pieces between crossing passes, each with its own mask spine.
2. Use Butt Caps: Use a dash pattern of 1 1. Avoid round caps, as they cause the visible tip to lead the pen by half the stroke width, creating a 'stall and pop' effect.
3. Subdivide Easing: Use de Casteljau subdivision so the combined pace of the pieces equals the intended design.
4. Bridge the Gap: Use a 'tip glint' riding an offset-path to bridge the visual dead window where the pen is painting under existing ink.

Use scripts/fit_ribbon_centerline.py to get the required cut fractions (arc fractions) for the split.

Follow these rules to ensure high-quality, performant logo animations:

Composition Rules:

1. Limit Noise: Use exactly one reveal + at most one idle loop + at most one hover behavior.
2. Context: Reveal plays once per session/page-load; do not trigger on every route change.
3. Consistency: All variants must share the same personality tokens.
4. Accessibility: Wrap all animations in @media (prefers-reduced-motion: no-preference). The fallback for reduced motion is the finished static logo.

Performance Rules:

• Animate only: transform, opacity, clip-path, stroke-dashoffset, and filter (sparingly).
• Avoid: Never animate layout properties.
• Optimization: Use at most one will-change per animated part, and remove it after the reveal is complete.

A high IoU (Intersection over Union) score does not excuse poor vector craft. The Smoothness Gate is a hard requirement. A vector fails if it exhibits:

• Visible stair-stepping or pixel-grid orthogonal runs.
• Noisy trace knots or 'chatter'.
• Looking like a bitmap mask when zoomed (200-400%).
• A path made mostly of 1px horizontal/vertical segments for curves or rounded shapes.

Decision Rule: If a smoother curve results in a slightly lower IoU but preserves the silhouette, width profile, and extrema, prefer the smooth version.

Linear motion looks mechanical. Use easing for all durations except continuous rotation in a spinner-style loop.

Easing Selection Guide:

• Duration < 150ms: Use ease-out only (no time for ease-in).
• 150–400ms: Use ease-out or custom curves.
• 400ms+: Full ease-in-out is available.
• Entrances: Use cubic-bezier(0, 0, 0.2, 1) or the stronger cubic-bezier(0.16, 1, 0.3, 1).
• Narrative arcs: Use cubic-bezier(0.34, 0, 0.14, 1) for sharp interest and soft resolution.

A complete Pixel2Motion run produces the following artifacts:

• logo.svg: The final static vector with a motion-ready structure.
• logo_motion.html: A standalone HTML showcase featuring the main animation, atomic motion studies, playback controls (replay/slow/speed), and QA hooks.
• motion_spec.md: Documentation containing personality words, applied principles, a timeline table, easing tokens, and atomic motions.
• outputs/fit_iterations/*.png & overlay_progress_strip.png: Visual evidence for geometry QA.
• outputs/motion_frames/*.png & motion_strip.png: Visual evidence for motion QA.
• final_render.png & html_render.png: Static renders and path audit artifacts.

Logo motion should be pose-to-pose rather than straight-ahead. Define key poses and let easing interpolate between them.

Key Pose Workflow:

1. Hidden
2. Anticipation pose
3. Peak
4. Overshoot
5. Final Pose (The Final Frame Contract: must be the QA-verified static vector).

Pose Counts by Duration:

• 300ms header reveal: 2–3 key poses.
• 1200–2000ms sequence: 6–10 key poses.

Note: Straight-ahead thinking is only suitable for continuous idle loops (drift, shimmer) with no destination.

Staging ensures one clear focus at a time. A logo reveal should be treated like a tiny film with a specific reading order (e.g., Mark → Wordmark → Tagline).

Best practices:

• Verify via frame strip: Check where the eye lands at specific timestamps (e.g., t=300, t=800).
• Amplitude control: Background or secondary elements must have smaller amplitude or lower opacity deltas than the focal element.
• Negative space: Use mask wipes to reveal the counter-form of a mark to stage the silhouette.

Failure mode: Simultaneous equal-amplitude motion across all elements prevents the eye from landing.