gstack/design-motion/SKILL.md.tmpl

---
name: design-motion
preamble-tier: 2
version: 1.0.0
description: |
  Design motion: animate an approved design into a seamless MP4 and GIF loop.
  Sources: a /design-shotgun PNG, a /design-html finalized.html, or a URL. Rebuilds the exact frame,
  loads it from empty, gives each visual one story, records deterministic
  frames, and exports an MP4 for X, a website GIF and an 800x500 GIF after
  seam, rest and overflow checks. Use when: "animate this design", "make a
  showcase video", "GIF of this UI", "motion mockup". (gstack)
triggers:
  - animate this design
  - make a showcase loop
  - turn the design into a video
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - AskUserQuestion
---

{{PREAMBLE}}

# /design-motion: Showcase Loops from an Approved Design

You turn a finished design into a loop that proves it is alive. The viewer must
see the exact design working: the frame loads from empty, each
visual acts out what it does, and the loop returns to the design and repeats
without a seam.

**exact frame → empty state → smooth load → one story per visual → seamless repeat.**

---

{{SECTION_INDEX:design-motion}}

---

## Motion doctrine (gstack rules that win over the motion values)

- **Showcase or website decides the motion budget.** A showcase is an artifact: the motion is the content, so every visual gets its story. On a website gstack's rule holds: **one authored motion moment per page.** Animate the one section whose visual most needs explaining; ask before animating a second.
- **Content never hides behind animation timing.** On a website the section renders complete with no script, under reduced motion, and before the intro fires. The intro is an enhancement that starts on an IntersectionObserver, never an opacity-0 block waiting for scroll.
- **Only what the design has moves.** No added loading lines, glows, gradients or gradient text, no new copy (showcase accents excepted). Helpers a story needs (a cursor, a duplicate row) match the design and are absent from the still.
- **No bounce.** Curves never pass 1 (the catalog's bounce-easing tell). Never `scale(0)` an object; only lines and bars grow from zero.
- **Pulses, marquees and blinking carets are showcase-only accents** on elements that are live indicators, inputs or logo rows in the design. A shipped website keeps none of them running (catalog: pulsing-dot, marquee, blinking-cursor).
- **Animate `transform`, `opacity`, `filter` and `clip-path` only** (plus a mask angle or `stroke-dashoffset` for sweeps). Blur stays at 14 px or less. Website transitions stay in gstack's 50 to 700 ms range; showcase timing is slower on purpose.

## Step 0: Setup and source detection

```bash
SLUG=$(~/.claude/skills/gstack/bin/gstack-slug --get SLUG 2>/dev/null)
GSTACK_STATE_ROOT=$(~/.claude/skills/gstack/bin/gstack-paths --get GSTACK_STATE_ROOT); : "${GSTACK_STATE_ROOT:?gstack-paths failed; reinstall with ./setup or /gstack-upgrade}"
setopt +o nomatch 2>/dev/null || true
_APPROVED=$(ls -t "$GSTACK_STATE_ROOT/projects/$SLUG/designs/"*/approved.json 2>/dev/null | head -1)
[ -n "$_APPROVED" ] && echo "APPROVED: $_APPROVED" || echo "NO_APPROVED"
_FINALIZED=$(ls -t "$GSTACK_STATE_ROOT/projects/$SLUG/designs/"*/finalized.html 2>/dev/null | head -1)
[ -n "$_FINALIZED" ] && echo "FINALIZED: $_FINALIZED" || echo "NO_FINALIZED"
[ -f DESIGN.md ] && echo "DESIGN_MD: exists" || echo "NO_DESIGN_MD"
[ -n "${FIGMA_TOKEN:-}${FIGMA_ACCESS_TOKEN:-}" ] && echo "FIGMA_TOKEN: set" || echo "NO_FIGMA_TOKEN"
[ -e "${GSTACK_FFMPEG:-$(command -v ffmpeg)}" ] && echo "FFMPEG: ready" || echo "NO_FFMPEG"
{{BIN_DIR}}/gstack-browser-ensure --quiet
```

**Pick the source** (the user's explicit choice wins):

1. **An approved /design-shotgun PNG.** Resolve it with `{{BIN_DIR}}/gstack-design-approved "<APPROVED path>"`; on "approved image ... is missing", say so and offer /design-shotgun. Never substitute another image.
2. **A /design-html `finalized.html`.** The design already exists as live HTML.
3. **A URL** the user names. A page behind a login: ask for a screenshot and treat it as a PNG.
4. **A Figma link**, only when `FIGMA_TOKEN: set`. Without the token, ask for an export PNG instead.

Nothing found and nothing named: ask once which design to animate, offering /design-shotgun or /design-html to make one.

`BROWSER_UNAVAILABLE` or native Windows (capture needs WSL, macOS, Linux): nothing renders; give the fix, build `page.html` and stop before the first capture call. `NO_FFMPEG`: say ffmpeg is needed for the checks and exports (macOS `brew install ffmpeg`, Debian/Ubuntu `sudo apt-get install -y ffmpeg`), build the page, render its Step 3 still for a visual check, and stop.

Set up the run directory:

```bash
SLUG=$(~/.claude/skills/gstack/bin/gstack-slug --get SLUG 2>/dev/null)
GSTACK_STATE_ROOT=$(~/.claude/skills/gstack/bin/gstack-paths --get GSTACK_STATE_ROOT); : "${GSTACK_STATE_ROOT:?gstack-paths failed; reinstall with ./setup or /gstack-upgrade}"
_MOTION_DIR="$GSTACK_STATE_ROOT/projects/$SLUG/designs/<name>-motion-$(date +%Y%m%d)"
mkdir -p "$_MOTION_DIR"
echo "MOTION_DIR: $_MOTION_DIR"
```

Replace `<name>` with a kebab-case name for the design. Later blocks write that printed path for `<motion-dir>`. Everything this run writes goes there: `page.html`, `reference.png`, the capture in `cap/`, and the exports.

## Step 1: Intake and the motion plan

Decide the **context** first: inside a site's codebase, or when the request names a page, it is a **website**; a design with no site is a **showcase**. Unclear: ask once.

Gather in one AskUserQuestion, only what the source does not settle: the context, which visuals should act out a story, the deliverables (showcase default: all three exports; website: the animated section in the site's code, exports only when asked), and whether a camera move is wanted (default none). Anything left: assume it and say so in one line.

Then state the plan before building:

1. **Context**: showcase, or website with each section and what it gets (intro and story, intro only, nothing). Text-only sections get nothing.
2. **Layout**: app frame (which joined surfaces stay static) or separate cards (which cards rise in), and each clip shape.
3. **Background**: kept exactly, or what cannot be reproduced.
4. **Choreography**: load order and the entrance kind per element group.
5. **Stories**: one sentence per visual saying what it acts out.
6. **Cycle**: length and phases (default 12 s: build 0-2.4, stories 2.4-11.0, dissolve 11.0-11.6, empty 11.6-12.0).

## Step 2: Rebuild the exact frame

{{SECTION:fidelity}}

With `FIGMA_TOKEN: set` and a Figma source:

{{SECTION:figma}}

## Step 3: Verify the still

Render the rebuilt page's still and the reference at 2x, then compare:

```bash
{{BIN_DIR}}/gstack-motion-capture.ts "<motion-dir>/page.html" --size <frame-size> --still "<motion-dir>/still-2x.png" --scale 2
{{BIN_DIR}}/gstack-motion-encode compare "<motion-dir>/reference.png" "<motion-dir>/still-2x.png" --blur 1.2
```

Aim above 35 dB for the frame (`--crop w:h:x:y` per container: above 30 dB; text-heavy containers retest at `--blur 2.5`). Read both images for structure: a glow too high, wrong stacking, a missing stroke. Fix structure, never sub-pixel offsets. A flat PNG source gets a visual comparison and a plainly stated limit instead of a dB target.

## Step 4: Motion

{{SECTION:motion}}

## Step 5: Capture

The page must expose the capture contract (fidelity section): `?capture` stops `requestAnimationFrame`, exposes `window.__start()`, `window.__tick(dt)` and `window.__lt`, and sets `window.__mark` on state changes.

```bash
{{BIN_DIR}}/gstack-motion-capture.ts "<motion-dir>/page.html" --size <frame-size> --cycle <cycle-seconds> --out "<motion-dir>/cap" --mask '[data-motion-clip]'
```

It steps a fake clock in whole milliseconds averaging 1000/60, records 15 PRE frames before `__start`, one full cycle from frame PRE − 1 (the empty state), and 10 frames past it. It writes `cap/frames/`, `cap/still.png`, `cap/mask.png` and `cap/capture.json`, and prints `CAPTURE_OK`. The mask paints every element marked `data-motion-clip` (each clip container, per the fidelity section). `MOTION_CONTRACT_MISSING`: add the capture mode and rerun.

## Step 6: Motion checks (before any export)

```bash
{{BIN_DIR}}/gstack-motion-encode check "<motion-dir>/cap" --layout <app|cards>
```

The phase defaults follow the cycle: dissolve at cycle − 1.0 s, empty beat from cycle − 0.4 s, intro landed at 2.4 s. When your plan's phases differ, add `--dissolve-at`, `--empty-from` and `--intro-end` in seconds. One `MOTION_CHECK:` line each, then `MOTION_RESULT: clean` or `<n> failed`:

- **seam**: the window's first frame equals the frame one cycle later.
- **empty-beat**: every empty-beat frame equals the frame before `__start`; catches JS state the reset missed, which the seam cannot see.
- **rest**: the last frame before the dissolve equals `still.png`: every story came back to the design. A story that leaves an inline `translate(0)` on an element fails this; clear the inline style at rest.
- **overflow**: outside the mask, nothing moves. App frame: every frame equals the empty first frame. Cards: every story frame equals the still. `--mask-grow <px>` covers shadows.

Read `cap/contact-sheet.png` for ghosting, pops, content moving ahead of its card, and stories too timid to see. Fix, recapture and recheck, at most three rounds; then report what still fails, unexported. `FFMPEG_MISSING`: relay its install line and stop.

## Step 7: Export and report

On a session's first design, show the contact sheet before exporting so the direction is cheap to correct.

```bash
{{BIN_DIR}}/gstack-motion-encode export "<motion-dir>/cap" --name <name> --pad '<hex-color>'
```

It writes `<name>-x.mp4` (H.264, 60 fps, CRF 15, long side up to 1920), `<name>-loop.gif` (960 px wide, 20 fps) and `<name>-800x500.gif`. For the 800×500, frames with wide empty borders (most card and bento frames) crop to the content with about 40 px of margin at exactly 1.6:1 (add `--crop w:h:x:y` in capture pixels); a frame its content fills is fitted and padded with `--pad`; a photo background always crops. A heavy GIF lowers `--gif-fps` or `--small-fps` (12) before its size.

Report: still fidelity (frame and worst container PSNR), each check's result, the three files with size, dimensions, frame rate and duration, and anything not reproduced exactly, named plainly. Offer to copy the exports into the project.

## Important Rules

1. **The design is the brief.** Stories start and end on the exact design; the still equals the reference.
2. **Never encode before Steps 3 and 6 pass**, or before the user accepted a named exception.
3. **Use the configured state root.** All motion artifacts go to `$GSTACK_STATE_ROOT/projects/$SLUG/designs/`.
4. **Never record in real time.** Only the capture contract and the fake clock produce frames.
5. **The background never moves**, blurs, fades or recolours.
6. **Never print, echo or commit a Figma token.**