Motion Editing Guide

How to use the SevIQ motion gallery as a visual learning and tuning tool. This is the how-to companion: the decision record explains why the system exists and what rules it follows; this page explains how to work with it without re-prompting every tiny visual change.

• Library: /assets/motion/motion.css
• Gallery: /assets/motion/index.html (every shipped primitive)
• Per-primitive demos: loader-globe, primer-flow

Core idea

Treat the gallery as a small visual lab. Work from the cheapest, safest change outward:

1. Pick an existing primitive close to the desired effect.
2. Tune the CSS variables (tokens) first.
3. Tune the primitive-specific classes second.
4. Edit keyframes only when the motion feel is wrong.
5. Edit SVG geometry last.

Most changes go through tokens and class-level knobs — not by rewriting SVG paths.

The editing ladder

Level 1 — Theme and speed (start here)

Safe, and they teach the fastest. Set them on the .motion-scope wrapper:

.motion-scope {
  --motion-speed: 0.85;       /* < 1 = slower/calmer, > 1 = faster/sharper */
  --motion-accent-1: #d9a441; /* primary       */
  --motion-accent-2: #ece5d8; /* secondary     */
  --motion-accent-3: #8ab86f; /* live/success  */
}

Level 2 — Timing scale

Durations are named tokens, so a whole class of motion retunes at once:

--motion-dur-fast:    0.9s;  /* spinner                    */
--motion-dur-base:    1.8s;  /* shimmer, ping ripple, dots */
--motion-dur-slow:    2.6s;  /* current flow, lamp glow    */
--motion-dur-breathe: 3.4s;  /* globe breathe, word pulse  */
--motion-dur-ambient: 7s;    /* slow orbit loops           */

Every animation is calc(<dur> / var(--motion-speed)) — --motion-speed scales them all together; the named tokens set the relative feel.

Level 3 — Per-primitive knobs

Level 4 — Keyframes (only when the feel is wrong)

Reach for @keyframes motion-* only when no token gets the motion right — the bounce too high, the ripple too large. Keep animating transform / opacity / stroke-dashoffset only.

Level 5 — SVG geometry (last resort)

Edit paths/shapes only when the thing being drawn must change (a different circuit, a new icon). The most expensive change to get right — exhaust the levels above first.

Suggested workflow

1. Clone, don't mutate. Copy the nearest demo first (loader-globe.html → loader-globe-test.html), hack until it feels right, then fold only the reusable parts back into motion.css. Delete the test file.

2. Temporary sandbox at the top of the test file:

/* Temporary tuning sandbox — do not ship as-is. */
.motion-scope { --motion-speed: 0.7; --motion-accent-1: #c9502e; }
.motion-globe .mg-orbit--cw { opacity: 0.35; }

3. Use DevTools as the interactive editor — often faster than another AI round: inspect the primitive, edit CSS variables live, toggle classes, disable individual animations, copy useful values back. You can also emulate prefers-reduced-motion and prefers-color-scheme there to check both states without changing the OS.

Prompting rules for an AI assistant

Use AI for structure, cleanup, and alternatives — not every visual pixel.

Tune an existing primitive:

Take this existing motion primitive and produce a small variant. Keep the token system, no JavaScript, no hardcoded colors outside tokens, and preserve the reduced-motion behavior. Change the minimum CSS/markup needed. Then tell me which knobs to tune visually afterward.

Create a new primitive:

Create a new SVG + CSS motion primitive for the SevIQ motion gallery. It must use .motion-scope tokens, external CSS classes, no JavaScript, no runtime dependency, and a prefers-reduced-motion stop state. Keep the markup small and class-driven. Include a short demo snippet, a gallery cell, and the safe tuning knobs.

Checklist for every primitive

• Works in dark theme
• Works in light theme (.motion--light)
• Stops under prefers-reduced-motion (motion stops, not slows)
• Uses only motion tokens for colour
• Uses named timing tokens (--motion-dur-*), not random durations
• Animates only transform, opacity, or stroke-dashoffset
• No inline JavaScript
• Inline SVG when CSS needs to target internals
• aria-hidden if decorative; role="img" + aria-label if meaningful
• Small enough to understand by reading it
• Has a cell in the gallery (index.html)

The editable source of this guide is the markdown at SevIQ/docs/motion-gallery-editing-guide.md; the decision record & full catalog live at SevIQ/docs/adr/0001-svg-css-motion-basics.md.