conductor-motion

# Conductor Motion Generate the mid-layer animation patterns that make product marketing sites feel alive — typewriter simulations, progress bar choreography, staggered content reveals, Lottie sequencing, and scroll-driven animation compositions. These patterns simulate live software through animation alone. Deconstructed from [ConductorAI.com](https://www.conductorai.com/) (Webflow, GSAP 3.15, Lottie, vanilla JS). ## Quick Start ```bash # Typewriter hero with word cycling python3 scripts/conductor_motion_generator.py --mode typewriter \ --base-text "Accelerating" \ --words "complex approvals,investigations,e-discovery,FOIA review" \ --output typewriter.html # Progress bar simulation python3 scripts/conductor_motion_generator.py --mode progress \ --title "search initialization" --doc-count 1324 \ --rows "QUERY_RECEIVED,INPUT,ELECTRONIC SIGNATURE,JURISDICTION" \ --output progress.html # File review state machine python3 scripts/conductor_motion_generator.py --mode file-review \ --files "Report_Q4.xlsx,Contract_Draft.pdf,Audit_Log.csv" \ --output file-review.html # Full landing page with all patterns python3 scripts/conductor_motion_generator.py --mode full-page \ --output landing.html # Effects catalog (all modes demonstrated) python3 scripts/conductor_motion_generator.py --mode catalog --output catalog.html ``` Or let Claude generate directly from the templates and references. ## Motion Interview When invoked without `--mode`, the skill runs a brief motion interview: 1. **Content type** — What are you animating? (hero section, product demo, status dashboard, landing page) 2. **Pacing** — What tempo? (slow/deliberate, medium/professional, fast/urgent) 3. **Patterns** — Which effects? (typewriter, progress, file-review, stagger, terminal, lottie, or all) 4. **Color scheme** — Dark or light background? 5. **Design tokens** — Use existing `DESIGN.md` / `.design-context.md`, or defaults? Output: `.motion-context.md` consumed by generation phase. If `.design-context.md` exists with MOTION_INTENSITY dial set, skip the pacing question and derive from that value: - MOTION_INTENSITY 1-3 → slow - MOTION_INTENSITY 4-6 → medium - MOTION_INTENSITY 7-10 → fast ## Modes | Mode | Template | Patterns Composed | |------|----------|-------------------| | `typewriter` | `assets/templates/typewriter.html` | Hero rotator + type-on + blinking cursor | | `progress` | `assets/templates/progress.html` | Progress bar + counter + dot-leaders + processing dots + staggered rows | | `file-review` | `assets/templates/file-review.html` | File list + state machine (unreviewed→processing→reviewed) + status indicators | | `stagger-reveal` | `assets/templates/stagger-reveal.html` | Hero cascade + section reveals + IntersectionObserver scroll triggers | | `terminal` | `assets/templates/terminal.html` | Timestamps + status typing + search result counters + progress sync | | `lottie-compose` | `assets/templates/lottie-compose.html` | Lottie player (via `--lottie-src`) + responsive variants + scroll-synced playback; SVG slot placeholders when no source is set | | `streaming-text` | `assets/templates/streaming-text.html` | AI-response streaming: chunk-buffered text + scroll anchoring + stop/regenerate + polite announcements | | `top-layer` | `assets/templates/top-layer.html` | Popover + dialog + toast lifecycles via @starting-style, allow-discrete, and overlay transitions | | `full-page` | `assets/templates/full-page.html` | Typewriter hero + progress + stagger reveals + file review composed into a landing section | | `catalog` | `assets/templates/catalog.html` | Visual reference: live demos of typewriter, progress, file review, stagger, terminal, and Lottie slots | ## Color System All effects read from `--cm-*` CSS custom properties. Override at `:root` to re-theme. Default: dark scheme with `#4F7BF7` brand accent. Light scheme swaps bg/text polarity. Full token reference (dark, light, easing, timing): `references/design-tokens.md` ## Composition Parameters | Parameter | Range | Default | Effect | |-----------|-------|---------|--------| | `--pacing` | `slow \| medium \| fast` | `medium` | Speed multiplier: slow=1.5x duration, fast=0.6x | | `--stagger` | `100–400` | `200` | Milliseconds between sequential reveals | | `--typing-speed` | `20–80` | `45` | Base ms per character typed | | `--typing-variance` | `0–40` | `18` | Random variance added to typing speed | | `--easing` | `cubic \| quart \| linear` | `cubic` | Swaps the rAF `ease` alias: easeOutCubic, easeOutQuart, or linear | | `--hold-duration` | `500–3000` | `1100` | Ms to hold typed word before deleting (typewriter/terminal) | | `--color-scheme` | `dark \| light` | `dark` | Background/foreground polarity | | `--font` | font name | `Geist` | Primary font (loaded via Google Fonts CDN) | | `--accent` | hex color | `#4F7BF7` | Override `--cm-brand` | | `--lottie-cdn` | `boolean` | `false` | Include lottie-web CDN script in `<head>` | ### Content Parameters (per mode) **typewriter**: `--base-text`, `--words` (comma-separated), `--cursor` (char, default `|`), `--no-loop` (type the list once, settle on the last word) **progress**: `--title`, `--doc-count`, `--rows` (comma-separated labels), `--progress-duration` (total ms, default 6000), `--start-percent` (default 5) **file-review**: `--files` (comma-separated filenames with extensions), `--review-speed` (ms per file) **terminal**: `--status-items` (comma-separated), `--result-count`, `--result-label`, `--no-timestamps` (hide the timestamp column) **lottie-compose**: `--lottie-src` (URL to .json, loaded into `data-lottie-slot` containers), `--no-lottie-loop`, `--no-lottie-autoplay` **streaming-text**: `--prompt` (user message), `--response` (response text; `||` separates paragraphs) **top-layer**: `--toast-messages` (comma-separated) Every flag above is implemented in the generator and covered by the eval suite — a flag that doesn't change output is a bug, not a placeholder. Stagger-reveal content (items, directions) is authored directly in the template rather than injected via CLI; direction variants are documented in `references/stagger-reveal-patterns.md`. ## Architecture ``` ┌──────────────────────┐ │ .design-context.md │ ← from /shape (optional) │ DESIGN.md tokens │ ← from /design-md (optional) └──────────┬───────────┘ │ ┌──────────▼───────────┐ │ Motion Interview │ ← asks pacing, patterns, content │ (skip if --mode set) │ └──────────┬───────────┘ │ ┌──────────▼───────────┐ │ .motion-context.md │ ← pacing, patterns, content data └──────────┬───────────┘ │ ┌─────────────────┼─────────────────┐ ▼ ▼ ▼ ┌────────────┐ ┌────────────┐ ┌────────────────┐ │ Template │ │ Token │ │ Content │ │ Selection │ │ Application│ │ Injection │ │ (mode→html) │ │ (--cm-*) │ │ (user data) │ └──────┬─────┘ └─────┬──────┘ └───────┬────────┘ │ │ │ └────────────────┼────────────────────┘ ▼ ┌──────────────────────┐ │ Single-file HTML │ │ (inline CSS + JS) │ │ CDN: fonts only │ │ (+ Lottie if needed)│ └──────────────────────┘ ``` ## Animation Engine Internals Easing functions, timing constants per mode, and pacing multiplier tables: `references/design-tokens.md` Key: `easeOutCubic` (`t => 1 - Math.pow(1-t, 3)`) is the default. Pacing multiplier scales all durations — slow=1.5×, medium=1.0×, fast=0.6×. Stagger delays scale at 0.8× the multiplier. ## Gotchas (What Claude Gets Wrong Without This Skill) 1. **Reaches for GSAP or Framer Motion.** These patterns are vanilla JS — no framework needed. GSAP adds 30KB for effects achievable with `requestAnimationFrame` and CSS transitions. 2. **Uses `transition: all` for reveals.** Triggers layout on every property. Explicitly list `opacity` and `transform` only. 3. **Forgets `prefers-reduced-motion`.** Every single effect must show its final state immediately under reduced motion. Claude skips this ~60% of the time. 4. **Uses `Date.now()` in animation loops.** Not monotonic, drifts on clock sync. Must use `performance.now()`. 5. **Hardcodes colors instead of CSS custom properties.** Makes re-theming impossible. All colors must go through `--cm-*` tokens. 6. **Leaves `will-change` on permanently.** Reserves GPU memory for the life of the element. Add before animation, remove after. 7. **Generates typing effects without a cursor.** The blinking cursor is what sells the illusion of a human typing. Without it, it looks like a broken render. 8. **Animates `width` for progress bars.** The fill is a full-width element scaled with `transform: scaleX()` from `transform-origin: left` — compositor-only, no reflow per frame. Sync `aria-valuenow` in the same tick. 9. **Puts stagger delays in JS `setTimeout` chains.** Use CSS `transition-delay: calc(N * var(--cm-stagger))` so pacing changes propagate from one token. 10. **Builds file review UI with `innerHTML`.** XSS vector when filenames come from user input. Use `textContent` + DOM construction. ## Implementation Rules 1. **Vanilla only.** No React, Vue, Svelte, Angular. Plain HTML + CSS + JS. These are marketing page embeds — a framework adds 30-100KB for effects that need <2KB of JS. 2. **Single-file output.** Everything in one HTML file. CDN imports for fonts only (+ Lottie when needed). Single-file means drag-and-drop into any CMS or Webflow embed block. 3. **`requestAnimationFrame` only.** Never `setInterval` for visual animation loops. `setInterval` permitted only for non-visual state cycling (e.g., "PROCESSING..." dot count). 4. **`performance.now()` for timing.** Never `Date.now()` in animation tick functions. 5. **`prefers-reduced-motion` required.** Every animated effect shows its final state immediately when reduced motion is preferred. No motion, no transitions. 6. **Visibility API integration.** Pause all animation loops when `document.hidden === true`. Resume on visibility change. 7. **`will-change` lifecycle.** Add `will-change: opacity, transform` before animation starts, remove after completion. Never leave it permanent. 8. **`--cm-*` tokens everywhere.** Never hardcode colors, timing, or typography — always reference custom properties. 9. **Guard double-initialization.** Every init function checks `dataset.{name}Init === "true"` before proceeding. Without this, hot-reload in dev tools or Webflow's live preview runs init twice, doubling all animations. 10. **Viewport meta required.** `<meta name="viewport" content="width=device-width, initial-scale=1">`. Without it, mobile browsers zoom to 980px default, breaking all clamp() sizing. 11. **Touch and resize handlers.** Responsive recalculation on `resize` (debounced 80ms). Touch-friendly interaction targets. 12. **Accessible by default.** `aria-hidden="true"` on decorative elements (cursors, spinners). `role="progressbar"` with `aria-valuenow` synced on every visual update. All content readable without JS: templates ship `<html class="no-js">`, JS swaps it for `is-loaded`, and initial-hidden styles apply only under the loaded class — JS-built sections carry static final-state markup that init clears. 13. **Font: Geist + Geist Mono.** Via Google Fonts CDN. `-webkit-font-smoothing: antialiased`. Geist's monospace numerals and tight letter-spacing match the ConductorAI source. The mono variant is essential for terminal displays and dot-leader alignment. ## Anti-Patterns - Never use `transition: all` — explicitly list each property and duration - Never animate `width`, `height`, `top`, `left`, `margin`, `padding` — use `transform` and `opacity` only - Never hardcode stagger delays in ms — use CSS custom property `--cm-stagger` multiplied by index - Never omit `prefers-reduced-motion` — every effect needs it, no exceptions - Never animate off-screen elements — guard with IntersectionObserver or page-load class toggle - Never use `Date.now()` in rAF loops — `performance.now()` is monotonic and sub-ms accurate - Never leave `will-change` on permanently — it reserves GPU memory; add before, remove after - Never assume typing text is single-line — handle `white-space: nowrap` on the typing container, not the parent - Never use pure white `#FFFFFF` as text in dark mode — use `--cm-text` (`#E8ECF4`) for less eye strain - Never play Lottie animations eagerly on mobile if they're below the fold — use IntersectionObserver - Never create typing effects without cursor — the cursor sells the illusion - Never hardcode file extensions in the file-review pattern — parse from filename See `references/anti-patterns.md` for expanded explanations with code examples. ## Generator Script ```bash python3 scripts/conductor_motion_generator.py \ --mode typewriter|progress|file-review|stagger-reveal|terminal|lottie-compose|full-page|catalog \ --pacing slow|medium|fast \ --stagger 200 \ --typing-speed 45 \ --easing cubic \ --color-scheme dark|light \ --accent "#4F7BF7" \ --output output.html ``` Mode-specific content flags documented under Composition Parameters. ## Validation ```bash python3 scripts/validate_conductor_motion.py output.html ``` Checks: viewport meta, `--cm-*` properties, no framework imports, `requestAnimationFrame` present, `prefers-reduced-motion` media query, `performance.now()` in animation code, font-smoothing, `aria-hidden` on cursors, `document.hidden` visibility check, no `transition: all`, no `setInterval` for animation, no layout-triggering property animation, no `.style.width` assignment in JS, `aria-valuenow` synced when a progress fill animates, visibility pause flags actually consulted by their loops, and no-js/is-loaded gating wherever content starts at `opacity: 0`. ## References Load on-demand when implementing specific patterns: | Reference | Covers | |-----------|--------| | `references/design-tokens.md` | Full `--cm-*` token system: dark/light schemes, easing functions, timing constants per mode, pacing multiplier | | `references/typewriter-patterns.md` | Hero rotator + type-on variants, timing constants, cursor styles, visibility API, word cycling state machine | | `references/progress-simulation-patterns.md` | Progress bar, easeOutCubic tick, counters, dot-leaders, staggered rows, processing dots | | `references/stagger-reveal-patterns.md` | Hero cascade, section reveals, IntersectionObserver, scroll-triggered, double-rAF technique | | `references/file-review-patterns.md` | State machine (unreviewed→processing→reviewed), template cloning, status indicators, SVG icons | | `references/terminal-display-patterns.md` | Status typing, timestamps, dot-leaders, search result counters, progress sync |