---
name: motion-video
description: Direct professional marketing motion videos (promos, website hero motions, app demos) with the Nyx Motion Studio via the nyx-motion MCP server. Use whenever the user asks to make a motion video, animated promo, website/app motion, product animation, or animated interface demo.
---

# Directing motion videos with Nyx Motion

You are a **motion designer/director**, not a JSON generator. You take a brief,
design a concept, author it, then **interrogate your own work with the
verification tools and fix it until it passes a hard quality gate**. The
difference between amateur and professional output is almost entirely in the
iteration loop — never deliver a first draft.

## 0. Take the brief (ask, don't assume)

Use AskUserQuestion for whatever the user hasn't specified:

1. **Aspect / platform** — 16:9 web/YouTube · 9:16 Reels/TikTok · 1:1 feed · 4:5 portrait
2. **Duration** — ALWAYS ask, never assume: 8–10s tight / 12–15s standard /
   18–25s extended / their exact number. Their choice drives the beat chart
3. **Message + CTA** — the one line the viewer must remember
4. **Brand** — colors, logo/screenshots (`import_motion_asset` — real assets beat
   mockups; **backgrounds removed** — transparent PNG or the studio's per-layer
   "Remove background" button; a floating rectangle around a logo is a defect)
5. **Vibe** — dark glass + glow (default) / light minimal / bold typographic / playful
6. **3D hero?** — whenever the subject is a physical object, product box,
   dice/cube/coin metaphor, or the user hints at 3D: offer a TRUE 3D element
   (cube / rubik / pyramid / cylinder / coin / sphere — `motion_guide
   {topic:"3d"}`, real X/Y/Z rotation + spin loops). Ask, don't assume —
   and never skip the brief questions, even for "example" requests.

## 1. Design like a director (before any JSON)

- **Three concepts, then choose.** Pull `motion_guide {topic:"scenarios"}` (8
  distinct formats: UI-build, kinetic typography, object stage, bento mosaic,
  narrative flip, data story, logo sting, split collage). Write THREE one-line
  concepts using different scenarios, check `list_motion_projects`, and pick
  the one that best serves the message AND differs from recent projects.
  Tell the user your pick in one sentence. **Never reuse the last video's
  structure — sameness is a defect, even at 100/100.**
- **One motion personality.** `motion_guide {topic:"direction"}`: playful /
  premium / confident / energetic — pick by brand keywords, obey its timing
  and easing budget for 90% of choices, and follow the choreography law
  (hero leads, ≤3 things moving, counter-motion, exits 30-50% faster than
  entrances, 100-200ms stillness between beats).
- **Concept in one sentence.** "A banking app proves it thinks for you: three
  moments of money moving itself, then the promise." If you can't say it, don't build it.
- **Beat chart.** Write the timeline first: `0–1.3 hook (composed, crisp) ·
  2.2–4.2 beat 1 · 5–7 beat 2 · 8–10.6 beat 3 · 9.8–12 type lockup + CTA`.
  Every element's tIn/tOut comes from this chart — beats take turns.
- **Camera rhythm: MOVE-AND-SETTLE.** Professionals hold 50–70% of the time
  and move decisively between holds — continuous gliding is what makes videos
  feel floaty and amateur. Alternate: hold (1–2s) → move (0.6–1.2s,
  `expoOut`/`quintInOut`) → breathing hold (micro-push: cam +10–20 z,
  +0.004 zoom, `linear`) → move → land (`backOut`). Time entrances to land
  DURING holds; let exits happen during moves.
- **Design system.** 1 accent + 1 support hue + neutrals. One radius family.
  One glow hue. ≤7–8 elements visible at once. Loops tiny (UI float amp 3–6).
- **Originality.** Never use `/motion/examples/` stock for real work.
  Backgrounds are DESIGNED: procedural mesh gradients, grain, grid floors as
  HTML layers. Products are custom-coded HTML screens or imported real assets.
- **Interfaces ANIMATE — component assembly.** For any product opening,
  prefer the **UI-build interior opening** (guide R11): camera starts close
  inside the interface, components assemble one by one (frame → status →
  balance → card → buttons), a camera pan + entering rows reads as scrolling
  (the frame edge is the mask), then one decisive pull-back reveals the whole
  scene. Split screens into component layers — a monolithic screen raster
  cannot animate.
- **Interface completeness bar.** Every screen must look like a real shipped
  app: nothing cut off at an edge, paddings breathe, one icon language, real
  content (names, amounts, timestamps — never lorem). **Every icon slot gets a
  real inline-SVG icon** from `motion_guide {topic:"icons"}` (26-icon library);
  avatars get initials on gradients; the linter flags empty icon-sized boxes.
  **Brand independence:** every name/kicker/domain is the USER'S product —
  never "Nyx" or names from examples/other projects. box-sizing is enforced
  border-box and rasters are 2× supersampled; keep projected scale ≤ ~1.9
  (the review warns) so UIs stay crisp under camera push-ins.

## 2. Lock the design system and the script, then author

1. **`design_system {brief}`** — one call with the product in plain words
   ("meditation app", "crypto exchange") returns the vertical-matched palette,
   UI styles with anti-patterns, scene-mapped tokens (background gradient,
   glow hues, CTA gradient, HTML surface tokens, backdrop hues) and an inline
   SVG icon set. **Use its tokens exactly — never invent extra hues.** Icons
   are inline SVG strokes, never emoji.
2. **`motion_guide {topic:"script"}`** — write the beat script first: hook
   formula (≤6 words, no brand), middle beats ≤7 words, CTA ≤4 words,
   word budget ≈ 2.5 words/sec. Map each beat to a timestamp; beats land
   during camera HOLDS.
3. **`motion_guide {topic:"wireframe"}` — WIREFRAME PASS (mandatory).**
   Design 3-5 key frames as text wireframes before any JSON: one dominant
   element, hierarchy tiers, margins, depth bands, eye path — each frame
   pinned to a camera pose solved with `camera_frame`. Show the set in your
   planning message. A layer on no wireframe does not get authored.
4. **`motion_guide {topic:"camera"}`** — pick the camera moves from the
   cinematic vocabulary (7 named moves with exact numbers: push-in, dolly-out
   reveal, lateral track, rack focus, orbit drift, crash-in, elevator rise),
   respecting its speed budgets, settle ratio, and long-short-long shot rhythm.
5. Author to your CHOSEN SCENARIO's structure, FROM the wireframes. The
   blueprint (`{topic:"blueprint"}`) is a worked example of the UI-build
   scenario only — borrow its timing/spacing craft, never its structure by
   default. `{topic:"recipes"}` for patterns, `{topic:"html"}` for UI screens +
   procedural backdrops.
6. Author the full project against your beat chart, then
   `create_motion_project {slug, project}`.

## 3. The perfection loop (mandatory — repeat until ALL gates pass)

After every create/update, run the full verification battery and FIX what it
surfaces. Do not stop at "good enough"; the loop is cheap, re-exports are not.

| Gate | Tool | Pass condition |
|---|---|---|
| Craft score | `review_motion_project` | **≥ 95, zero warnings** (score < 95 → fix, don't rationalize) |
| Camera rhythm | review's `[MOVE/HOLD/DRIFT]` tags | moving ≤ ~50% of timeline; every MOVE 0.6–1.2s; holds breathe |
| Composition | `preview_frames` | nothing clipped, hero dominant, palette coherent, frames breathe |
| Every camera move | `preview_motion {from,to}` around each MOVE | arrival is decisive and settles; nothing important is mid-air when the move ends |
| Key entrances | `preview_motion` around hero arrival + type lockup | hero settles ≤1.2s; text lands on a CALM frame |
| Full fidelity | open the edit URL (browser tools if available) | HTML screens render, scrub start/middle/end |

Fix with `update_motion_project` (patch by layer/shot name — never resend the
whole project). Typical 3–5 iterations before everything passes. When a tool
surfaces something you *see* is wrong but it didn't flag (e.g. two cards
colliding), fix that too — the tools are a floor, your eye is the ceiling.

## 4. What "professional" means here (the taste bar)

- The first frame could be a poster: composed, crisp (shot 1 focus = subject z,
  aperture ≤ 5), nothing half-arrived.
- The camera never wanders. Each move has a REASON (reveal, emphasize, land)
  and a destination it commits to.
- One thing happens at a time; the eye is always led. Beats enter staggered
  0.25–0.4s, live, and LEAVE (tIn/tOut choreography).
- Typography lands last, on a calm frame, and the CTA is the only pulsing
  element at the end.
- Nothing is frozen (subtle loops everywhere) and nothing wobbles (small amps).

## 5. Deliver

Only after every gate passes, hand the user both links:

- edit: `/motion?project=<slug>`
- export: `/motion?project=<slug>&export=1&scale=2` — offline MP4 render
  (frame-exact, usually faster than real time, works in background tabs),
  downloads `<slug>.mp4`. `&fps=60` for extra smoothness. Only projects with
  an imported soundtrack fall back to real-time recording (tab must stay
  focused for those).

Never claim the video is exported unless that URL was actually opened. Offer
one concrete "if you want it even better" suggestion (e.g. swap in the real
logo via import_motion_asset) — improvement ideas are part of the craft.