Add LottieFiles motion-design skill

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0119deVM65AKpJiLTLhEdDg9
2026-10-18 21:44:48 +00:00
33 changed files with 1633 additions and 1399 deletions
@@ -1,163 +0,0 @@
---
-name: ad-creative-video
-description: This skill should be used when the user asks to "make a video ad", "create an animated ad", "build a performance/UGC-style ad", "batch-produce ad creative variations", "generate ad variants for A/B testing", "swap headline/offer/CTA across many ad versions", or "export one ad in multiple aspect ratios for Meta/TikTok/Reels". Covers ad hook structures, hook→CTA message-match, data-driven variant generation (1 template × CSV = N ads), multi-aspect export, and platform specs.
-version: 0.1.0
---
-
-# Ad Creative Video
-
-Build ONE motion-graphics ad template, then mass-produce variants from a data table — different hooks, offers, CTAs, and products — so a performance marketer can A/B test dozens of versions across placements and aspect ratios. The craft is making the template fully data-driven and message-matched, so 40 variants stay on-brand and only the tested variable changes.
-
-## When to use
-
- Performance/UGC-style video ads where the first 1.5–3s must stop the scroll.
- Batch variant generation: one template rendered against many rows (headline/offer/CTA/product swaps) for A/B testing.
- Multi-aspect export of the same ad for Meta Feed, Reels/Stories, TikTok, YouTube.
-
-Not for sale/discount countdown promos, and not for testimonial/review-driven ads — those are different structures. Stay on the batch-variation, test-everything angle.
-
-## The two rules that make variants worth running
-
-1. **Isolate one variable per variant.** A test only teaches something if exactly one thing changes. Hold layout, motion, colors, and timing constant; swap *only* the field under test (hook, or offer, or CTA). Mixing two changes makes the winner uninterpretable.
-2. **Message-match the hook to the CTA.** The promise made in the first 3 seconds must be the promise the button pays off. A "stop wasting 2 hours a day" hook ends on "Save 2 hours — try free," not a generic "Shop now." The hook and CTA are a matched pair in every row of the data table.
-
-## Ad anatomy (15–30s)
-
-| Beat | Job | Budget |
-|---|---|---|
-| Hook (0–3s) | Stop the scroll; state the problem or pattern-interrupt | 0–3s |
-| Context | Make the viewer feel the problem / agitate | 3–8s |
-| Payoff | Show the product as the solution, one clear benefit | 8–18s |
-| Proof | One concrete number, demo, or result | 18–25s |
-| CTA (last 3s) | Single action, message-matched to the hook | hold ≥2s |
-
-Land the hook's emotional trigger before the 2-second mark — judgment forms in ~1.7s and scroll speed keeps rising. Test the hook FIRST; it moves CPA more than any other element.
-
-## Hook taxonomy (the field you vary most)
-
-| Hook type | Template | When it wins |
-|---|---|---|
-| Problem-first | "I didn't realize how much X was costing me until…" | pain is felt but unnamed |
-| Pattern interrupt | "This is going to sound controversial, but…" | crowded feed, generic category |
-| Curiosity gap | "Nobody talks about the one thing that…" | educated, skeptical audience |
-| Immediate benefit | "Cut your X in half in 7 days" | clear, quantifiable outcome |
-| Direct callout | "If you do X every morning, stop." | sharp audience segment |
-
-Keep a column of 5–10 hook strings and let the batch render produce one ad per hook against the same body — that is the cleanest hook test possible.
-
-## Data-driven template (everything is a prop)
-
-Hardcode nothing the marketer might A/B test. The composition reads a single `variant` object; the renderer never edits the component. Make every animated value a pure function of `useCurrentFrame()` so each frame renders deterministically (no CSS transitions, no library timers — they desync the render).
-
-```tsx
-import {useCurrentFrame, interpolate, AbsoluteFill, useVideoConfig} from "remotion";
-
-type Variant = {hook: string; benefit: string; proof: string; cta: string; bg: string; accent: string};
-
-export const AdTemplate: React.FC<{v: Variant}> = ({v}) => {
-  const frame = useCurrentFrame(); const {fps} = useVideoConfig();
-  const hookIn = interpolate(frame, [0, 8], [40, 0], {extrapolateRight: "clamp"});
-  const ctaIn  = interpolate(frame, [fps * 22, fps * 23], [0, 1], {extrapolateLeft: "clamp", extrapolateRight: "clamp"});
-  return (
-    <AbsoluteFill style={{background: v.bg, fontFamily: "Inter, sans-serif"}}>
-      <h1 style={{transform: `translateY(${hookIn}px)`, opacity: interpolate(frame,[0,8],[0,1])}}>{v.hook}</h1>
-      {frame > fps * 8  && <p>{v.benefit}</p>}
-      {frame > fps * 18 && <strong>{v.proof}</strong>}
-      <button style={{opacity: ctaIn, background: v.accent}}>{v.cta}</button>
-    </AbsoluteFill>
-  );
-};
-```
-
-See `references/batch-ad-pipeline.md` for the complete template, the CSV→props parser with validation, and the brand-lock theme object.
-
-## 1 template × CSV = N variants
-
-The payoff: author the ad once, then let a CSV drive the matrix. Each row is one fully-formed, message-matched variant. Render once per row.
-
-```bash
-# variants.csv: id,hook,benefit,proof,cta,bg,accent  → one MP4 per row
-node csv-to-props.js variants.csv ./props        # writes props/<id>.json per row
-for f in props/*.json; do
-  id=$(basename "$f" .json)
-  npx remotion render AdTemplate "out/${id}.mp4" --props="$f"
-done
-```
-
-To build a clean test matrix, hold every column constant and vary one: 5 hooks × 1 body = 5 ads (hook test); then take the winning hook × 3 CTAs (CTA test). `references/batch-ad-pipeline.md` has a matrix generator that expands variable lists into the CSV so combinatorial tests stay one-variable-at-a-time.
-
-## Multi-aspect export
-
-Each placement wants a native aspect. Compose against a center safe zone so one master reframes cleanly to all of them — don't letterbox, re-center.
-
-| Aspect | Placements | Resolution | Keep-clear safe zone |
-|---|---|---|---|
-| 9:16 | Reels, Stories, TikTok In-Feed | 1080×1920 | top ~14%, bottom ~20–35% (UI/caption), sides ~6% |
-| 4:5 | Meta Feed (best feed real estate) | 1080×1350 | center 90%; CTA out of bottom 10% |
-| 1:1 | Feed, broad reach | 1080×1080 | center square survives every crop |
-| 16:9 | YouTube, in-stream | 1920×1080 | center 90% |
-
-Design the hook text, product, and CTA inside the **1:1 center square** so they survive every crop. Drive aspect from a prop and render each per variant:
-
-```bash
-for ar in 9x16 4x5 1x1; do
-  npx remotion render AdTemplate "out/${id}-${ar}.mp4" --props="props/${id}.json" \
-    --props-merge="{\"aspect\":\"${ar}\"}"
-done
-```
-
-Keep critical content out of the 9:16 bottom third — that is where the platform stacks captions, the CTA button, and the username. `references/platform-specs.md` has exact pixel safe zones and per-platform duration/format limits.
-
-## Output checklist
-
- One variable per variant; layout/motion/timing identical across a test.
- Hook lands its trigger before 2s; hook and CTA are message-matched in every row.
- Every animated value is a pure function of `useCurrentFrame()` — no CSS/library timers.
- Dataset is a prop; nothing testable is hardcoded; one template renders the whole CSV.
- Each variant exported 9:16 + 4:5 + 1:1 (+16:9 if needed), key content in the center square.
- Brand stays locked across all variants via a single theme object.
-
-## Deliver & verify (rendered stills → MP4)
-
-> **Packaged helper** (`scripts/`): tile your stills with `scripts/contact-sheet.sh sheet.png f-hook.png f-mid.png f-end.png`, then assert the encode with `scripts/probe-mp4.sh out.mp4 [WxH] [fps]`. See `scripts/README.md`.
-
-**Output contract:**
- A Remotion ad template registered as `<Composition>` (+ zod `schema` + `defaultProps`), every animated value frame-driven (no CSS transitions / library timers / `Date.now()` / `Math.random()`).
- Deliverable = the rendered `out/*.mp4` per variant per aspect (plus the project + CSV, so the marketer re-renders on new rows).
-
-**Verify loop — render stills → inspect → encode.** Cheap PNGs first, full encode only once they're clean. Render with the **shipped** props (the real row), not just `defaultProps`.
-
-```bash
-# Frame-exact stills across the hook→CTA arc, with a real variant's props
-npx remotion still AdTemplate out/f-hook.png --frame=12  --props=props/v1.json   # hook readable < 2s
-npx remotion still AdTemplate out/f-mid.png  --frame=300 --props=props/v1.json   # benefit/proof
-npx remotion still AdTemplate out/f-cta.png  --frame=689 --props=props/v1.json   # CTA, message-matched
-# inspect each: fidelity (hook / offer / proof / CTA text exact, brand bg+accent right)
-#   AND artifacts (text overflow, off-canvas, CTA inside the 9:16 bottom third, missing font, wrong row binding)
-```
-
-**Multi-aspect / batch — verify one variant in EACH aspect before batch-rendering the matrix.** A layout bug repeats across every row × aspect; catch it once.
-
-```bash
-for ar in 9x16 4x5 1x1; do                                  # one representative variant, every target aspect
-  npx remotion still AdTemplate "out/v1-${ar}.png" --frame=300 \
-    --props=props/v1.json --props-merge="{\"aspect\":\"${ar}\"}"
-done
-# stills clean in all aspects? → then batch-render every row × aspect:
-for f in props/*.json; do id=$(basename "$f" .json); for ar in 9x16 4x5 1x1; do
-  npx remotion render AdTemplate "out/${id}-${ar}.mp4" --props="$f" --props-merge="{\"aspect\":\"${ar}\"}"
-done; done
-npx remotion render AdTemplate out/demo.gif --codec=gif --props=props/v1.json   # README demo
-```
-
-**Before you finish:**
-1. `npx remotion still` renders cleanly at hook / mid / CTA — no errors, no missing fonts/assets.
-2. Hook/offer/proof/CTA text exact and brand colors right; nothing in the 9:16 bottom third or outside the center safe zone.
-3. Frame-driven only — no CSS/library timers, `Date.now()`, or `Math.random()`.
-4. Shipped row's props render correctly (not just `defaultProps`); one variable per variant holds.
-5. One variant verified in 9:16 + 4:5 + 1:1 before the batch; MP4s play; (optional) GIF for the README.
-
-## Reference files
-
- `references/batch-ad-pipeline.md` — the full runnable Remotion ad template, the CSV→typed-props parser with validation, a one-variable test-matrix generator, the brand-lock theme object, and the complete batch + multi-aspect render script.
- `references/platform-specs.md` — exact 2025/2026 pixel safe zones, durations, aspect ratios, and format limits for Meta Feed/Reels/Stories, TikTok In-Feed, and YouTube, plus a hook→CTA message-match worksheet.
@@ -1,289 +0,0 @@
-# Batch Ad Pipeline — full template, parser, matrix, render
-
-This is the complete, runnable implementation behind the SKILL.md overview: a data-driven Remotion ad template, a CSV→props parser with validation, a one-variable test-matrix generator, a brand-lock theme, and the batch + multi-aspect render scripts. Hardcode nothing a marketer might want to A/B test.
-
-## 1. The brand-lock theme
-
-Keep every brand-controlled value in one object so 40 variants stay consistent and only the *tested* fields change per row. The variant data supplies copy and per-campaign accents; the theme supplies the locked look.
-
-```ts
-// theme.ts
-export const theme = {
-  fontFamily: "Inter, system-ui, sans-serif",
-  ink: "#0B0B0F",
-  paper: "#FFFFFF",
-  radius: 20,
-  hookSize: 76,    // px, on the 1080-wide master
-  bodySize: 44,
-  proofSize: 52,
-  ctaSize: 40,
-  pad: 80,         // outer padding; also the side safe margin
-  durationInSeconds: 25,
-} as const;
-```
-
-## 2. Aspect config
-
-Drive layout from a single aspect prop so one composition reframes to every placement. Dimensions and the keep-clear bottom band differ per aspect.
-
-```ts
-// aspects.ts
-export type Aspect = "9x16" | "4x5" | "1x1" | "16x9";
-export const ASPECTS: Record<Aspect, {w: number; h: number; bottomSafe: number}> = {
-  "9x16": {w: 1080, h: 1920, bottomSafe: 540}, // captions + CTA + username stack here
-  "4x5":  {w: 1080, h: 1350, bottomSafe: 135},
-  "1x1":  {w: 1080, h: 1080, bottomSafe: 110},
-  "16x9": {w: 1920, h: 1080, bottomSafe: 110},
-};
-```
-
-## 3. The data-driven template
-
-Every animated value is a pure function of `useCurrentFrame()` — no CSS transitions, no GSAP/library timers (they desync deterministic rendering and flicker in the export). The component reads one `variant` plus an `aspect`; the renderer never edits this file.
-
-```tsx
-// AdTemplate.tsx
-import {
-  AbsoluteFill, useCurrentFrame, useVideoConfig, interpolate, spring, Sequence,
-} from "remotion";
-import {theme} from "./theme";
-import {ASPECTS, Aspect} from "./aspects";
-
-export type Variant = {
-  id: string;
-  hook: string;      // 0–3s scroll-stopper
-  benefit: string;   // the single payoff claim
-  proof: string;     // one concrete number / result
-  cta: string;       // message-matched to the hook
-  accent: string;    // per-campaign accent color
-  bg: string;        // background color
-};
-
-export const AdTemplate: React.FC<{v: Variant; aspect: Aspect}> = ({v, aspect}) => {
-  const frame = useCurrentFrame();
-  const {fps} = useVideoConfig();
-  const {bottomSafe} = ASPECTS[aspect];
-
-  // Hook rises + fades in over the first 8 frames, holds, then eases up and out at 8s.
-  const hookY = interpolate(frame, [0, 8], [48, 0], {extrapolateRight: "clamp"});
-  const hookOpacity =
-    interpolate(frame, [0, 8], [0, 1], {extrapolateRight: "clamp"}) *
-    interpolate(frame, [fps * 7, fps * 8], [1, 0], {extrapolateLeft: "clamp", extrapolateRight: "clamp"});
-
-  // CTA springs in for impact in the last 3s and holds.
-  const ctaProgress = spring({frame: frame - fps * 22, fps, config: {damping: 14, stiffness: 120}});
-
-  return (
-    <AbsoluteFill style={{backgroundColor: v.bg, fontFamily: theme.fontFamily, color: theme.ink}}>
-      <AbsoluteFill style={{padding: theme.pad, paddingBottom: bottomSafe, justifyContent: "center"}}>
-
-        {/* HOOK 0–8s */}
-        <Sequence durationInFrames={fps * 8}>
-          <h1 style={{fontSize: theme.hookSize, fontWeight: 800, lineHeight: 1.05,
-                      transform: `translateY(${hookY}px)`, opacity: hookOpacity}}>
-            {v.hook}
-          </h1>
-        </Sequence>
-
-        {/* BENEFIT 8–18s */}
-        <Sequence from={fps * 8} durationInFrames={fps * 10}>
-          <FadeUp delay={0}>
-            <p style={{fontSize: theme.bodySize, fontWeight: 600}}>{v.benefit}</p>
-          </FadeUp>
-        </Sequence>
-
-        {/* PROOF 18–22s */}
-        <Sequence from={fps * 18} durationInFrames={fps * 4}>
-          <FadeUp delay={0}>
-            <strong style={{fontSize: theme.proofSize, color: v.accent,
-                            fontVariantNumeric: "tabular-nums"}}>{v.proof}</strong>
-          </FadeUp>
-        </Sequence>
-
-        {/* CTA last 3s, message-matched to the hook */}
-        <Sequence from={fps * 22}>
-          <button style={{
-            alignSelf: "flex-start", marginTop: 40, padding: "22px 44px",
-            fontSize: theme.ctaSize, fontWeight: 700, border: "none",
-            borderRadius: theme.radius, color: theme.paper, backgroundColor: v.accent,
-            transform: `scale(${interpolate(ctaProgress, [0, 1], [0.85, 1])})`,
-            opacity: ctaProgress,
-          }}>
-            {v.cta}
-          </button>
-        </Sequence>
-      </AbsoluteFill>
-    </AbsoluteFill>
-  );
-};
-
-const FadeUp: React.FC<{children: React.ReactNode; delay: number}> = ({children, delay}) => {
-  const frame = useCurrentFrame();
-  const o = interpolate(frame - delay, [0, 10], [0, 1], {extrapolateLeft: "clamp", extrapolateRight: "clamp"});
-  const y = interpolate(frame - delay, [0, 10], [24, 0], {extrapolateLeft: "clamp", extrapolateRight: "clamp"});
-  return <div style={{opacity: o, transform: `translateY(${y}px)`}}>{children}</div>;
-};
-```
-
-## 4. Register the composition (aspect + variant as props)
-
-```tsx
-// Root.tsx
-import {Composition} from "remotion";
-import {AdTemplate} from "./AdTemplate";
-import {ASPECTS} from "./aspects";
-import {theme} from "./theme";
-
-const defaultVariant = {
-  id: "demo", hook: "Spending 2 hrs/day on reports?", benefit: "Auto-build them in one click.",
-  proof: "Teams save 11 hrs a week.", cta: "Save 2 hours — try free", accent: "#4F46E5", bg: "#FFFFFF",
-};
-
-export const RemotionRoot = () => {
-  const aspect = "9x16" as const; // overridden per-render via --props
-  const {w, h} = ASPECTS[aspect];
-  return (
-    <Composition
-      id="AdTemplate"
-      component={AdTemplate}
-      durationInFrames={theme.durationInSeconds * 30}
-      fps={30}
-      width={w}
-      height={h}
-      defaultProps={{v: defaultVariant, aspect}}
-      // Resolve real dimensions from the incoming aspect prop at render time:
-      calculateMetadata={({props}) => {
-        const a = ASPECTS[(props as any).aspect ?? "9x16"];
-        return {width: a.w, height: a.h};
-      }}
-    />
-  );
-};
-```
-
-`calculateMetadata` lets a single composition output any aspect from the `aspect` prop — no separate composition per ratio.
-
-## 5. CSV → typed props, with validation
-
-The dataset is the input. Parse, validate every row (a bad hex or empty CTA must fail loudly, not render a broken ad), and write one props file per variant.
-
-```js
-// csv-to-props.js   usage: node csv-to-props.js variants.csv ./props [aspect]
-const fs = require("fs");
-const path = require("path");
-
-const [, , csvPath, outDir, aspect = "9x16"] = process.argv;
-const REQUIRED = ["id", "hook", "benefit", "proof", "cta", "accent", "bg"];
-const isHex = (s) => /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(s);
-
-const parseCSV = (text) => {
-  const [head, ...lines] = text.trim().split(/\r?\n/);
-  const cols = head.split(",").map((c) => c.trim());
-  return lines.filter(Boolean).map((line) => {
-    // simple split; wrap fields containing commas in double quotes in the CSV
-    const cells = line.match(/("([^"]|"")*"|[^,]*)/g).filter((_, i, a) => i < a.length - 1);
-    const row = {};
-    cols.forEach((c, i) => (row[c] = (cells[i] ?? "").replace(/^"|"$/g, "").replace(/""/g, '"').trim()));
-    return row;
-  });
-};
-
-const rows = parseCSV(fs.readFileSync(csvPath, "utf8"));
-fs.mkdirSync(outDir, {recursive: true});
-
-const seen = new Set();
-let errors = 0;
-rows.forEach((row, n) => {
-  const where = `row ${n + 2} (${row.id || "no-id"})`;
-  REQUIRED.forEach((k) => { if (!row[k]) { console.error(`✗ ${where}: missing "${k}"`); errors++; } });
-  if (seen.has(row.id)) { console.error(`✗ ${where}: duplicate id`); errors++; }
-  seen.add(row.id);
-  if (row.hook && row.hook.length > 60) console.warn(`⚠ ${where}: hook >60 chars may clip in 9:16`);
-  ["accent", "bg"].forEach((k) => { if (row[k] && !isHex(row[k])) { console.error(`✗ ${where}: "${k}" not a hex color`); errors++; } });
-  if (errors) return;
-  fs.writeFileSync(path.join(outDir, `${row.id}.json`), JSON.stringify({v: row, aspect}, null, 2));
-});
-
-if (errors) { console.error(`\n${errors} error(s) — no broken ads written.`); process.exit(1); }
-console.log(`✓ ${rows.length} variant prop files written to ${outDir}`);
-```
-
-Example `variants.csv` (one fully message-matched ad per row):
-
-```csv
-id,hook,benefit,proof,cta,accent,bg
-v01_problem,Spending 2 hrs/day on reports?,Auto-build them in one click.,Teams save 11 hrs a week.,Save 2 hours — try free,#4F46E5,#FFFFFF
-v02_interrupt,Your reporting tool is lying to you.,See the real numbers instantly.,Teams save 11 hrs a week.,See the real numbers — free,#DC2626,#0B0B0F
-v03_curiosity,Nobody talks about this reporting trick.,One click builds the whole report.,Teams save 11 hrs a week.,Try the trick — free,#059669,#FFFFFF
-```
-
-Note the CTA mirrors the hook in every row — that is the message-match discipline encoded into the data.
-
-## 6. Test-matrix generator — one variable at a time
-
-A test only teaches something if exactly one field changes. This expands a base variant plus a list of values for ONE field into a CSV, so a hook test or a CTA test stays clean and combinatorial mistakes are impossible.
-
-```js
-// make-matrix.js   usage: node make-matrix.js > variants.csv
-const base = {benefit: "Auto-build them in one click.", proof: "Teams save 11 hrs a week.",
-              cta: "Save 2 hours — try free", accent: "#4F46E5", bg: "#FFFFFF"};
-
-// Vary ONLY this field; everything else is held identical across the test.
-const FIELD = "hook";
-const values = [
-  "Spending 2 hrs/day on reports?",
-  "Your reporting tool is lying to you.",
-  "Nobody talks about this reporting trick.",
-  "Cut report time in half this week.",
-  "If you build reports by hand, stop.",
-];
-
-const esc = (s) => (/[",]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s);
-const cols = ["id", "hook", "benefit", "proof", "cta", "accent", "bg"];
-console.log(cols.join(","));
-values.forEach((val, i) => {
-  const row = {...base, [FIELD]: val, id: `${FIELD}_${String(i + 1).padStart(2, "0")}`};
-  console.log(cols.map((c) => esc(row[c])).join(","));
-});
-```
-
-To run a CTA test next, set `FIELD = "cta"`, paste the *winning* hook into `base.hook`, and list CTA variants. Same one-variable rule, next stage of the funnel.
-
-## 7. Batch + multi-aspect render
-
-Render every variant in every aspect a campaign needs. Concurrency keeps large batches fast.
-
-```bash
-#!/usr/bin/env bash
-# render-all.sh   one MP4 per (variant × aspect)
-set -euo pipefail
-
-node make-matrix.js > variants.csv          # 1) build the one-variable test matrix
-ASPECTS=("9x16" "4x5" "1x1")                 # placements this campaign needs
-
-for ar in "${ASPECTS[@]}"; do
-  node csv-to-props.js variants.csv "props/$ar" "$ar"   # 2) typed, validated props per aspect
-  for f in "props/$ar"/*.json; do
-    id=$(basename "$f" .json)
-    npx remotion render AdTemplate "out/${id}_${ar}.mp4" \
-      --props="$f" --concurrency=4 --log=error              # 3) render
-  done
-done
-
-echo "Done. $(ls out/*.mp4 | wc -l) ad variants in ./out"
-```
-
-5 hooks × 3 aspects = 15 MP4s from one template and one command. Add a CTA stage and the same template produces the next test wave with zero new component code.
-
-## Common pitfalls
-
- **Two variables changed at once** — the winner is uninterpretable. The matrix generator prevents this; keep using it.
- **Hook clips in 9:16** — long hooks overflow; the parser warns past 60 chars. Keep hooks short and high in the frame.
- **CTA hidden behind platform UI** — anything in the 9:16 bottom third gets covered by captions and the CTA button. The `bottomSafe` padding reserves that band.
- **Drift across variants** — accent/copy live in the data, everything else in `theme`. If a variant looks off-brand, the fix is the theme, not the row.
- **Animation flicker in export** — caused by CSS transitions or library timers. Every value must derive from `useCurrentFrame()`.
-
---
-## Built by the team behind iart.ai
-
-This skill is part of an open motion-graphics collection from iart.ai — the AI motion agent that turns data, scripts, and designs into editable motion graphics (Remotion → MP4). If you'd rather not hand-build this, iart.ai can mass-produce ad-creative variants from one template × a data table — change the text/data and re-export. → [iart.ai](https://iart.ai/?utm_source=github&utm_medium=reference&utm_campaign=ad-video-skills&utm_content=ref_footer&utm_term=ad-creative-video)
@@ -1,72 +0,0 @@
-# Platform Specs & Message-Match Worksheet
-
-Exact pixel safe zones, durations, aspect ratios, and format limits per placement (2025/2026), plus a worksheet for building message-matched hook→CTA pairs before they go into the CSV. Verify against each platform's current Ads Manager docs before a big spend — placements and safe zones shift.
-
-## Aspect ratio → placement map
-
-| Aspect | Resolution | Native placements |
-|---|---|---|
-| 9:16 | 1080×1920 | TikTok In-Feed, Instagram/Facebook Reels, Stories, YouTube Shorts |
-| 4:5 | 1080×1350 | Meta Feed (largest feed real estate, recommended for Feed video) |
-| 1:1 | 1080×1080 | Meta Feed, broad/automatic placements, X |
-| 16:9 | 1920×1080 | YouTube in-stream, landscape feed, in-article |
-
-Master rule: design the hook, product, and CTA inside the **1:1 center square** so a single composition reframes to every aspect by re-centering, not letterboxing. Black bars on a vertical feed read as "ad" and underperform.
-
-## Safe zones (keep-clear bands)
-
-Platform UI — captions, CTA chips, usernames, profile icons, progress bars — overlaps the frame. Keep all critical content out of these bands.
-
-| Aspect / placement | Top keep-clear | Bottom keep-clear | Sides |
-|---|---|---|---|
-| 9:16 Reels/Stories (Meta) | ~14% (~270px on 1920h) | ~20–35% (~384–672px) | ~6% (~65px) |
-| 9:16 TikTok In-Feed | ~130px | ~484px (right-side icon rail + caption) | right ~140px |
-| 4:5 Meta Feed | ~5% | ~10% (keep CTA above it) | ~5% |
-| 1:1 / 16:9 | center 90% safe | center 90% safe | center 90% safe |
-
-The 9:16 bottom third is the single most violated zone — captions, the CTA button, and the handle stack there. The `bottomSafe` padding in `batch-ad-pipeline.md` reserves it.
-
-## Duration & format limits
-
-| Placement | Sweet spot | Hard limits | Format |
-|---|---|---|---|
-| Meta Feed (4:5/1:1) | 6–15s | up to 240 min, ≤4GB | MP4/MOV, H.264 |
-| Meta Reels/Stories (9:16) | 8–15s | Reels ≤90s, Stories ≤2 min | MP4/MOV |
-| TikTok In-Feed (9:16) | 15–30s (TikTok cites 21–34s) | up to 10 min (non-Spark) | MP4/MOV, ≥540×960 |
-| YouTube in-stream (16:9) | 15–30s | skippable after 5s | MP4 |
-
-Practical default for performance video: **15–30s, with the hook trigger landing before 2s.** Most ad-account data shows attention falls off a cliff after ~15s, so front-load everything that matters.
-
-## Hook → CTA message-match worksheet
-
-Fill one row per ad *before* writing the CSV. The CTA must pay off the exact promise the hook made; if it doesn't, the click is wasted and the test is noisy. Each completed row becomes one record in `variants.csv`.
-
-| Hook (0–3s promise) | Hook type | Single benefit | Proof point | CTA (pays off the hook) |
-|---|---|---|---|---|
-| "Spending 2 hrs/day on reports?" | problem-first | one-click report build | "save 11 hrs/week" | "Save 2 hours — try free" |
-| "Your reporting tool is lying to you." | pattern interrupt | shows real numbers instantly | "save 11 hrs/week" | "See the real numbers — free" |
-| "Nobody talks about this reporting trick." | curiosity gap | one click builds it | "save 11 hrs/week" | "Try the trick — free" |
-| "Cut report time in half this week." | immediate benefit | auto-built reports | "save 11 hrs/week" | "Cut it in half — free" |
-| "If you build reports by hand, stop." | direct callout | automate it now | "save 11 hrs/week" | "Automate yours — free" |
-
-Bad pairing to avoid: a "stop wasting 2 hours" hook ending on a generic "Shop now" — the promise and the payoff don't connect, so even a great hook converts poorly.
-
-## Testing order (which field to vary first)
-
-Run tests in funnel order; isolate one field per wave using the matrix generator:
-
-1. **Hook** — biggest lever on CPA; test 5–8 hooks against one identical body.
-2. **Offer / benefit** — take the winning hook, vary the core promise.
-3. **CTA** — winning hook + offer, vary the closing action.
-4. **Format / aspect** — same winning ad, compare placements.
-
-Budget guide many teams use: ~60% to proven winners, ~30% to variations of winners, ~10% to fresh concepts. Run each test long enough for a real sample (commonly several hundred impressions per variant, ~1 week to smooth daily swings) before declaring a winner.
-
-## Pre-flight checklist per variant
-
- Hook trigger lands before 2s and fits the frame (≤~60 chars in 9:16).
- CTA visibly pays off the hook's specific promise.
- Critical content inside the center square and outside every keep-clear band.
- Duration within the placement's sweet spot.
- Exported in every aspect the campaign's placements require.
- Exactly one field differs from the other variants in this test wave.
@@ -1,137 +0,0 @@
---
-name: launch-video
-description: This skill should be used when the user asks to "make a launch video", "create a product hype/sizzle film", "build a teaser/trailer for a drop", "do a reveal montage with an end-card CTA", "cut a hero video to the beat", or "export a launch film in 16:9/9:16/1:1". Covers the hook→tease→reveal→feature-montage→end-card arc and multi-aspect export.
-version: 0.1.0
---
-
-# Launch Video
-
-Make a premium, high-energy 15–60s launch film that stops the scroll and converts. Build the classic arc — hook → tease → reveal → feature montage → end-card CTA — cut to the music, and export for every platform aspect.
-
-## When to use
-
- Product drops, feature announcements, trailers, hype reels (15–60s).
- "Sizzle" hero videos for a landing page.
- Beat-synced reveals where the brand moment lands on the drop.
-
-## The arc
-
-| Beat | Job | Typical share (of 30s) |
-|---|---|---|
-| Hook (0–3s) | A striking frame/motion that stops the scroll | 0–3s |
-| Tease | Hint the product; build curiosity, beat-synced | 3–9s |
-| Reveal | Product/logo hits on the music drop | 9–13s |
-| Feature montage | Fast, kinetic, one benefit per shot | 13–25s |
-| End card | Logo + tagline + CTA, clean hold | 25–30s |
-
-Scale the same proportions for 15s (tighter) or 60s (longer montage, never a longer hook).
-
-## Two non-negotiable rules
-
-1. **Sound design leads picture.** Lock the track first, mark the beats and the drop, then cut visuals to those marks. Never score a finished cut — the reveal lands on the drop, not near it.
-2. **Quality over quantity.** A few flawless shots beat many mediocre ones. Cut any shot that isn't premium.
-
-## Beat-synced reveal on the drop
-
-Find the drop's exact timecode in the audio, then time the reveal so the brand mark snaps to full at that frame, with a micro-overshoot for impact.
-
-```js
-import gsap from "gsap";
-const DROP = 9.0; // seconds, measured from the track
-const tl = gsap.timeline({ paused: true });
-// tease builds tension up to the drop
-tl.to(".tease", { opacity: 1, scale: 1.05, duration: DROP, ease: "power1.in" })
-// reveal SNAPS on the drop frame
-  .set(".logo", { opacity: 1 }, DROP)
-  .fromTo(".logo", { scale: 1.18 }, { scale: 1.0, duration: .18, ease: "power3.out" }, DROP)
-  .fromTo(".flash", { opacity: .9 }, { opacity: 0, duration: .25 }, DROP); // white hit
-audio.addEventListener("play", () => tl.play());
-```
-
-Cut on transients, not on a fixed grid: the hardest cuts go on kick/snare hits; ramp speed (time-remap) into the drop, then hard-cut out of it.
-
-## Kinetic feature montage
-
-One benefit per shot, ~0.6–1.0s each, hard cuts on the beat. Each shot = a bold keyword + a single supporting visual.
-
-```css
-.feature { opacity:0; }
-.feature.in .kw   { animation: pop .35s cubic-bezier(.22,1,.36,1) forwards; }
-.feature.in .word { display:inline-block; }
-@keyframes pop { from { opacity:0; transform:translateY(24px) } to { opacity:1; transform:none } }
-```
-
-```js
-// drive shots off beat marks measured from the track
-const beats = [13.0, 13.8, 14.6, 15.4, 16.2]; // seconds
-beats.forEach((t, i) => scheduleAt(t, () => showFeature(i)));
-```
-
-Keep one motion language across the montage (same enter curve, same exit) so speed reads as confidence, not chaos.
-
-## End card
-
-Hold the logo + tagline + CTA still and clean for ≥2s. No busy motion competing with the CTA; let the brand settle. Land the brand moment on the strongest remaining beat, then a crisp button/URL.
-
-## Multi-aspect export
-
-Compose with a center safe zone so one master crops cleanly to all aspects.
-
-| Aspect | Use | Resolution | Safe zone |
-|---|---|---|---|
-| 16:9 | YouTube, landing hero, X | 1920×1080 | keep key content within center 90% |
-| 9:16 | Reels, TikTok, Shorts, Stories | 1080×1920 | text within center 80% h; avoid top 12% / bottom 18% (UI) |
-| 1:1 | Feed posts | 1080×1080 | center square of the 16:9 frame |
-
-Design the hero/logo/CTA inside the **1:1 center square** so it survives every crop. Render the 16:9 master, then reframe (don't just letterbox) 9:16 and 1:1 from the same project.
-
-## Output checklist
-
- Track locked first; reveal lands exactly on the drop.
- Hook earns the first 3 seconds.
- Montage: one benefit per shot, hard cuts on beats, consistent motion language.
- End card holds ≥2s with one clear CTA.
- 16:9 + 9:16 + 1:1 exports, key content in the center safe zone.
- Premium-only shots — nothing mediocre survives the cut.
-
-## Deliver & verify (rendered stills → MP4)
-
-> **Packaged helper** (`scripts/`): tile your stills with `scripts/contact-sheet.sh sheet.png f-hook.png f-mid.png f-end.png`, then assert the encode with `scripts/probe-mp4.sh out.mp4 [WxH] [fps]`. See `scripts/README.md`.
-
-If the launch film is built/rendered in Remotion, treat it as the heavy tier: register a `<Composition>` (+ zod `schema` + `defaultProps`), drive every value off `useCurrentFrame()` — no GSAP timelines / audio-event callbacks / `Date.now()` / `Math.random()` at render time (bake beat + drop timecodes into props). Deliverable = the rendered `out/*.mp4` per aspect (plus the project).
-
-**Verify loop — render stills → inspect → encode.** Sample the arc, with the **shipped** props (real headline/tagline/CTA), not just `defaultProps`.
-
-```bash
-# Frame-exact stills across hook → reveal → end-card
-npx remotion still Launch out/f-hook.png   --frame=24  --props=props/launch.json   # hook earns first 3s
-npx remotion still Launch out/f-reveal.png --frame=270 --props=props/launch.json   # logo SNAPS on the drop frame
-npx remotion still Launch out/f-end.png    --frame=899 --props=props/launch.json   # end card: logo+tagline+CTA, clean hold
-# inspect each: fidelity (product/logo, tagline, CTA text exact, brand colors right, reveal at the drop frame)
-#   AND artifacts (text overflow, off-canvas, CTA in the 9:16 bottom third, missing font, flash frame stuck on)
-```
-
-**Multi-aspect — verify the master in EACH aspect before encoding all of them.** A reframe bug (hero pushed off the safe zone) repeats across every aspect; catch it once.
-
-```bash
-for ar in 16x9 9x16 1x1; do                                 # check reveal + end card per aspect
-  npx remotion still Launch "out/reveal-${ar}.png" --frame=270 \
-    --props=props/launch.json --props-merge="{\"aspect\":\"${ar}\"}"
-done
-# stills clean in all aspects? → then encode each:
-for ar in 16x9 9x16 1x1; do
-  npx remotion render Launch "out/launch-${ar}.mp4" --props=props/launch.json --props-merge="{\"aspect\":\"${ar}\"}"
-done
-npx remotion render Launch out/demo.gif --codec=gif --props=props/launch.json   # README demo
-```
-
-**Before you finish:**
-1. `npx remotion still` renders cleanly at hook / reveal / end card — no errors, no missing fonts/assets.
-2. Logo/tagline/CTA text exact, brand colors right; reveal lands on the drop frame; key content inside the center safe zone, clear of the 9:16 bottom third.
-3. Frame-driven only — no GSAP/audio-callback timing, `Date.now()`, or `Math.random()` (beats/drop baked into props).
-4. Shipped props render correctly (not just `defaultProps`); the end card holds ≥2s with one CTA.
-5. Master verified in 16:9 + 9:16 + 1:1 before encoding; MP4s play; (optional) GIF for the README.
-
-## Reference files
-
- `references/launch-structure.md` — a full shot-by-shot template with timecodes for a 30s film (scalable to 15–60s), beat-synced reveal timing, kinetic-montage shot recipes, the sound-design-leads-picture workflow, and detailed multi-aspect safe-area maps for 16:9 / 9:16 / 1:1.
@@ -1,142 +0,0 @@
-# Launch Video Structure — Cookbook
-
-Shot-by-shot template, beat-sync timing, montage recipes, and multi-aspect maps for a premium 15–60s launch film.
-
-## Sound-design-leads-picture workflow
-
-1. **Pick/commission the track first.** The track defines the film's length and energy.
-2. **Mark the structure in the audio**: intro, build, the **drop** (the single biggest moment), and the kick/snare transients through the montage. Note exact timecodes.
-3. **Map beats → cuts.** Hard cuts land on transients; the reveal lands on the drop frame.
-4. **Build picture to the marks.** Never finish a cut and then look for music. Score-first guarantees the reveal hits.
-5. **Mix last**: add risers into the drop, an impact/whoosh on the reveal, and let the end-card breathe (drop music low, or a clean tag).
-
-## Shot-by-shot template — 30s film (scalable)
-
-```
-00:00–00:03  HOOK
-  Visual : single striking frame — extreme close detail / impossible motion
-  Motion : slow push-in or a fast whip that resolves; NO logo yet
-  Audio  : sub-bass swell begins, sparse
-  Cut    : on first audible beat at ~03s
-
-00:03–00:09  TEASE
-  Visual : fragments/silhouettes of the product, never the full thing
-  Motion : light leaks, partial reveals, parallax; tension rising
-  Audio  : riser building toward the drop
-  Cut    : quick cuts accelerating into the drop
-
-00:09–00:13  REVEAL  ← THE DROP at 00:09
-  Visual : product/logo SNAPS to full on the drop frame
-  Motion : scale 1.18→1.0 over 0.18s + white flash-out; settle clean
-  Audio  : drop hits + impact stinger on the exact frame
-  Hold   : let it sit ~1.2s before moving
-
-00:13–00:25  FEATURE MONTAGE
-  Visual : one benefit per shot, ~0.6–1.0s each (≈8–10 shots)
-  Motion : bold keyword pop + one supporting visual; consistent enter/exit
-  Audio  : hard cuts on kick/snare; energy sustained
-  Pattern: KEYWORD + UI/product moment, repeat with rhythm
-
-00:25–00:30  END CARD
-  Visual : logo + tagline + CTA, centered, still
-  Motion : minimal — a soft settle, then hold ≥2s
-  Audio  : music resolves; clean sonic tag
-  CTA    : one action (URL or button), nothing competing
-```
-
-### Re-proportioning
-
- **15s**: Hook 0–2s · Tease 2–5s · Reveal 5–7s · Montage 7–12s (4–5 shots) · End card 12–15s.
- **60s**: same hook (still ≤3s) · longer tease and a richer montage (14–16 shots, grouped in waves) · end card ≥3s.
-
-The hook never gets longer — only the montage scales.
-
-## Beat-synced reveal (timing detail)
-
-```js
-import gsap from "gsap";
-const DROP = 9.0;                 // measured drop timecode (s)
-const tl = gsap.timeline({ paused: true });
-
-// build tension toward the drop
-tl.fromTo(".tease", { scale: 1.0, opacity: .6 },
-                    { scale: 1.08, opacity: 1, duration: DROP, ease: "power1.in" });
-
-// REVEAL exactly on the drop
-tl.set(".logo",  { opacity: 1 }, DROP);
-tl.fromTo(".logo",  { scale: 1.18 }, { scale: 1.0, duration: .18, ease: "power3.out" }, DROP);
-tl.fromTo(".flash", { opacity: .9 },  { opacity: 0, duration: .25, ease: "power2.out" }, DROP);
-tl.to(".tease", { opacity: 0, duration: .12 }, DROP);
-
-// hold the reveal
-tl.to(".logo", { scale: 1.0, duration: 1.2 }); // dwell
-
-audio.addEventListener("play", () => tl.play());
-```
-
-Speed-ramp into the drop (Remotion time-remap idea): play the last ~0.5s of the tease faster, then hard-cut to the reveal on the drop frame for a snap.
-
-## Kinetic montage shot recipe
-
-Each shot: a bold keyword + one product/UI visual, ~0.6–1.0s, hard cut on the beat.
-
-```css
-.feature { position:absolute; inset:0; opacity:0; }
-.feature.in { opacity:1; }
-.feature .word { display:inline-block; opacity:0; transform:translateY(26px); }
-.feature.in .word { animation: pop .32s cubic-bezier(.22,1,.36,1) forwards; }
-.feature.in .word:nth-child(2){ animation-delay:.04s }
-.feature.in .word:nth-child(3){ animation-delay:.08s }
-@keyframes pop { to { opacity:1; transform:none; } }
-```
-
-```js
-// schedule shots on measured beat marks
-const beats = [13.0, 13.8, 14.6, 15.4, 16.2, 17.0, 17.8, 18.6]; // seconds
-let i = 0;
-function loop(now){
-  const t = (now - start) / 1000;
-  if (i < beats.length && t >= beats[i]) { showFeature(i); i++; }
-  if (i < beats.length) requestAnimationFrame(loop);
-}
-```
-
-Montage discipline: keep ONE enter curve and ONE exit across all shots; vary content, never grammar. Alternate visual rhythm (full-frame ↔ detail) but keep cut cadence locked to the beat.
-
-## Multi-aspect safe-area maps
-
-Compose so a single master reframes to every aspect. Place hero/logo/CTA inside the smallest common safe zone — the 1:1 center square.
-
-```
-16:9  1920×1080
-  Safe: center 90% (96px H / 54px V margins)
-  Use : YouTube, landing hero, X timeline
-
-9:16  1080×1920
-  Safe: text within center 80% height
-  Avoid: top 12% (status/clock area), bottom 18% (caption + UI buttons)
-  Use : Reels, TikTok, Shorts, Stories
-
-1:1   1080×1080
-  Safe: this square == the design anchor; put logo/CTA here
-  Use : feed posts
-```
-
-Export workflow:
-
-1. Build the 16:9 master with all key content inside the 1:1 center square.
-2. For 9:16, **reframe** (pan/scale per shot to keep the subject centered) — do not letterbox.
-3. For 1:1, crop the center square; verify text isn't clipped.
-4. Re-check captions/CTA against each platform's UI overlay zones before export.
-
-## Final QA checklist
-
- [ ] Reveal lands on the exact drop frame, with overshoot + flash.
- [ ] Hook holds attention in the first 3s without showing the product.
- [ ] Every montage shot is one benefit, premium quality, on a beat.
- [ ] End card holds ≥2s, single CTA, nothing competing.
- [ ] 16:9 / 9:16 / 1:1 each pass safe-area and caption checks.
- [ ] Audio mixed: riser → impact on drop → clean tag on end card.
-
---
-Nail the reveal beat and the sound-leads-picture cut, and a launch film lands. Built by **[iart.ai](https://iart.ai/?utm_source=github&utm_medium=readme&utm_campaign=ad-video-skills&utm_content=skill_footer&utm_term=launch-video)** — the AI motion agent for editable, on-brand motion graphics.
@@ -0,0 +1,315 @@
+---
+name: motion-design
+description: >
+  Applies motion design principles to create emotionally-driven, technically sound animations and transitions.
+  Provides timing, easing, choreography, and Disney animation principles adapted for UI.
+  Use when creating animations, transitions, micro-interactions, loading states, page transitions,
+  scroll-triggered effects, or any motion work. Works with CSS, Framer Motion, GSAP, Lottie, Spring,
+  or any animation system.
+license: MIT
+metadata:
+  author: LottieFiles
+  version: "1.0.0"
+---
+
+# Motion Design Skill
+
+## When to Apply
+
+Use this skill when:
+- Creating UI animations (buttons, cards, modals, page transitions)
+- Designing micro-interactions and feedback animations
+- Building loading, success, or error states
+- Animating illustrations or decorative elements
+- Planning scroll-triggered or progress-based animations
+- Establishing brand motion identity
+- Choreographing multi-element sequences
+
+**Decision tree:**
+1. Does it serve a functional purpose (feedback, guidance)? → Timing rules for responsiveness
+2. Does it express brand personality? → Motion Personality archetypes
+3. Does it tell a story or guide attention? → Disney principles + choreography
+4. Is this a complex multi-element scene? → 1/3 Rule + stagger patterns
+
+---
+
+## Quick Reference: 8-Step Checklist
+
+Before creating any animation:
+
+1. **Emotional target?** — joy, calm, urgency, elegance
+2. **Motion Personality?** — Playful, Premium, Corporate, Energetic
+3. **Primary property?** — position, scale, rotation, opacity
+4. **Duration?** — see duration table below
+5. **Easing family?** — entrance=decelerate, exit=accelerate
+6. **Hero element?** — apply staging principles
+7. **Secondary + ambient layers?** — add richness
+8. **1/3 rules?** — motion distance, simultaneous elements
+
+---
+
+## Three Pillars (CRITICAL)
+
+Every animation must satisfy three pillars before any technical decisions:
+
+| Pillar | Question | Drives |
+|--------|----------|--------|
+| **Emotional Intent** | What should the viewer FEEL? | Easing, timing, amplitude |
+| **Visual Narrative** | What's the micro-story? | Setup → Action → Resolution |
+| **Motion Craft** | How do we make it believable? | Physics, secondary motion, paths |
+
+**Three motion layers** (flat animation = missing layers):
+- **Primary**: Main action the viewer follows
+- **Secondary**: Supporting richness (shadows, icons shifting)
+- **Ambient**: Background life (gradients, subtle pulses)
+
+> Deep dive: [director/core-philosophy.md](director/core-philosophy.md)
+
+---
+
+## Motion Personality
+
+Select ONE archetype per project. Apply consistently.
+
+| Archetype | Duration | Easing | Overshoot | Keywords |
+|-----------|----------|--------|-----------|----------|
+| **Playful** | 150-300ms | ease-out-back | 10-20% | fun, whimsical, bouncy, cute |
+| **Premium** | 350-600ms | cubic-bezier(0.4,0,0.2,1) | 0% | elegant, minimal, luxury, sophisticated |
+| **Corporate** | 200-400ms | cubic-bezier(0.2,0,0,1) | 0-3% | clean, professional, business, dashboard |
+| **Energetic** | 100-250ms | ease-out-expo | 15-30% | dynamic, energetic, bold, exciting |
+
+**Default**: Corporate for UI, Playful for illustrations.
+
+**Brand Motion Identity** — define three constants:
+1. **Signature easing**: One curve for 80% of animations
+2. **Duration palette**: 3 durations (quick / standard / slow)
+3. **Entrance pattern**: One consistent entry style
+
+> Deep dive: [director/motion-personality.md](director/motion-personality.md)
+
+---
+
+## Property Selection
+
+| Effect Goal | Primary Property | Secondary Properties |
+|-------------|------------------|---------------------|
+| Entrance/Exit | position | opacity, scale |
+| Emphasis/Attention | scale | rotation (subtle), opacity pulse |
+| State Change | opacity, color | scale (press feedback) |
+| Direction/Flow | position | rotation (follow path) |
+| Depth/3D Feel | scale + shadow | position (parallax) |
+| Loading/Progress | rotation (spinner) | scale, opacity pulse |
+| Success | scale (pop) | color, rotation (checkmark draw) |
+| Error/Alert | position (shake) | color, rotation (wobble) |
+
+**Simplicity threshold**: Use the minimum properties needed. One = direct. Two = polished. Three+ = potentially overwhelming.
+
+> Deep dive: [reference/property-selection.md](reference/property-selection.md)
+
+---
+
+## Duration Table
+
+| Element Type | Duration | Rationale |
+|-------------|----------|-----------|
+| Tooltip / micro-feedback | 80-120ms | Must feel instant |
+| Button press / toggle | 120-180ms | Responsive feedback |
+| Icon transition | 150-250ms | Clear state change |
+| Card enter / exit | 200-350ms | Spatial awareness |
+| Modal / dialog | 300-400ms | Focus shift |
+| Page transition | 400-600ms | Context switch |
+| Dramatic reveal | 600-1200ms | Theatrical build |
+
+**Distance scales duration**: 100px = base. 200px = 1.3x. 400px = 1.6x.
+
+**Enter > Exit**: Entrances 30-50% longer than exits. Users care about what appears.
+
+**Interactive feedback**:
+- Hover: <100ms
+- Press: <150ms
+- Release/settle: 200-300ms
+- Error shake: 300-400ms (2-3 oscillations)
+
+> Deep dive: [reference/timing-easing-tables.md](reference/timing-easing-tables.md)
+
+---
+
+## Easing Selection
+
+**Directional rules**:
+- **Entrance** → decelerate (fast start, gentle landing): ease-out family
+- **Exit** → accelerate (gentle start, fast departure): ease-in family
+- **On-screen** → smooth both ends: ease-in-out family
+- **Looping ambient** → seamless: sine-based ease-in-out
+
+**Industry standards**:
+
+| Standard | Cubic Bezier | Use For |
+|----------|-------------|---------|
+| Material Design 3 | (0.2, 0, 0, 1) | Default on-screen |
+| MD3 Emphasized | (0.05, 0.7, 0.1, 1) | Entrances, attention |
+| MD3 Accelerate | (0.3, 0, 1, 1) | Exits, dismissals |
+| Apple HIG | (0.25, 0.1, 0.25, 1) | Standard iOS |
+| Snappy UI | (0.2, 0, 0, 1) | Fast, decisive |
+| Gentle float | (0.4, 0, 0.2, 1) | Ambient, background |
+| Bounce settle | (0.175, 0.885, 0.32, 1.275) | Overshoot, playful |
+
+**Material-based easing**:
+
+| Material | Duration Scale | Overshoot |
+|----------|---------------|-----------|
+| Rigid (metal, stone) | 1.2x | 0% |
+| Elastic (rubber, gel) | 0.8x | 15-25% |
+| Fluid (water, paint) | 1.5x | 5% |
+| Paper (cards, sheets) | 1.0x | 3-5% |
+| Gas (smoke, fog) | 2.0x | 0% |
+| Glass (brittle) | 0.9x | 0% |
+
+> Deep dive: [reference/timing-easing-tables.md](reference/timing-easing-tables.md)
+
+---
+
+## Common Patterns
+
+### Button Press (Playful)
+1. **Anticipation**: Scale to 0.97 (50ms, ease-out)
+2. **Squash**: Scale to [1.04, 0.96] (100ms, ease-in)
+3. **Follow through**: Overshoots to 1.02, settles to 1.0 (spring, 200ms)
+4. **Secondary**: Shadow shrinks during press, icon shifts down 2px
+5. **Total**: ~150ms press + 200ms settle
+
+### Card Entrance (Premium)
+1. **Start**: 20px below target, opacity 0
+2. **Path**: Slight curve (10px X offset at midpoint)
+3. **Easing**: ease-out-cubic deceleration
+4. **Follow through**: Shadow arrives 50ms after card
+5. **Secondary**: Content fades in 100ms after card lands
+6. **Staging**: Other cards dim to 80%
+
+### Success State (Playful)
+1. **Primary**: Scale pop with ease-out-back
+2. **Secondary**: Checkmark draws in
+3. **Ambient**: Subtle particle burst
+4. **Color**: Green fill
+5. **Total**: 300-400ms
+
+### Error Shake (Corporate)
+1. **Primary**: Position oscillates 2-3 times, ±10-15px horizontal
+2. **Easing**: ease-in-out for sharp stops
+3. **Color**: Red tint
+4. **Total**: 300-400ms
+5. **No overshoot**: Errors feel firm
+
+> More patterns: [patterns/entrance-exit.md](patterns/entrance-exit.md) | [patterns/state-feedback.md](patterns/state-feedback.md)
+
+---
+
+## Choreography Essentials
+
+**Coordinated entry**:
+- Lead with the hero — primary element enters first or most prominently
+- Spatial consistency — all elements enter from same direction
+- Counter-motion — hero moves right → ambient moves left at 20-30% speed
+
+**1/3 Rule (distance)**: No motion travels more than 1/3 of screen without a keyframe change.
+
+**1/3 Rule (elements)**: With 3+ elements, no more than 1/3 in active motion simultaneously.
+
+**Stagger budgets**:
+
+| Pattern | Delay | Total Budget | Use Case |
+|---------|-------|-------------|----------|
+| Micro cascade | 20-40ms | <200ms | List items, grid cells |
+| Standard | 50-100ms | <400ms | Cards, panels, nav |
+| Dramatic | 100-200ms | <600ms | Hero sections |
+| Wave | 30-60ms | <500ms | Data visualizations |
+
+**Critical**: Total stagger must stay under 500ms.
+
+> Deep dive: [director/choreography.md](director/choreography.md)
+
+---
+
+## Emotion-to-Motion Map
+
+| Emotion | Character | Path | Easing | Duration |
+|---------|-----------|------|--------|----------|
+| Joy | Bouncy, arcs | Curved, upward | ease-out-back | 200-400ms |
+| Calm | Smooth, flowing | Gentle curves | sine ease-in-out | 500-1000ms |
+| Urgency | Sharp, fast | Straight lines | ease-out | 100-200ms |
+| Sadness | Slow, downward | Drooping curves | cubic ease-in-out | 600-1200ms |
+| Surprise | Sudden, expanding | Radial outward | ease-out-expo | 150-300ms |
+| Elegance | Slow, controlled | Long arcs | (0.4,0,0.2,1) | 400-700ms |
+| Playfulness | Bouncy, irregular | Arcs, squiggly | ease-out-back | 200-350ms |
+
+**Path as language**: Angular = tense. Curved = friendly. Spiral = whimsical. Diagonal = purposeful. Vertical = growth/weight. Horizontal = progress.
+
+> Deep dive: [director/emotion-mapping.md](director/emotion-mapping.md)
+
+---
+
+## Weight Classification
+
+| Weight | Examples | Duration | Overshoot | Easing |
+|--------|----------|----------|-----------|--------|
+| Heavy | Modals, overlays | 300-500ms | 0% | Gentle, high damping |
+| Medium | Cards, panels | 200-350ms | 3-5% | Moderate |
+| Light | Tooltips, badges, icons | 80-200ms | 5-15% | Responsive |
+
+---
+
+## Quality Rules
+
+### CRITICAL — never break
+1. **Never linear for spatial movement** — always use easing curves (linear only for spinners, progress bars)
+2. **Never opacity-only** for important state changes — combine with position or scale
+3. **Never exceed 1/3 screen** without intermediate keyframe
+4. **Always three motion layers** — primary + secondary + ambient
+
+### HIGH — strongly follow
+1. Match duration to element type (see tables)
+2. Use directional easing (ease-out entrance, ease-in exit)
+3. Apply Disney principles (especially anticipation, follow-through)
+4. Maintain consistent personality across scene
+
+> Full checklist: [reference/quality-checklist.md](reference/quality-checklist.md)
+
+---
+
+## Troubleshooting Quick Reference
+
+| Problem | Likely Cause | Fix |
+|---------|-------------|-----|
+| Looks robotic | Linear easing or no arcs | Add easing curves + arc paths |
+| Feels too slow | Duration too long for element type | Check duration table, use ease-out |
+| Feels cheap/flat | Missing secondary + ambient | Add shadow motion + background life |
+| Too distracting | Too many elements moving | Apply 1/3 rule, reduce amplitude |
+| No personality | Generic easing everywhere | Apply personality archetype consistently |
+
+> Deep dive: [reference/troubleshooting.md](reference/troubleshooting.md)
+
+---
+
+## File Reference
+
+**Philosophy** (director/):
+- [core-philosophy.md](director/core-philosophy.md) — Three Pillars deep dive
+- [decision-framework.md](director/decision-framework.md) — Full decision pipeline
+- [disney-principles.md](director/disney-principles.md) — 12 principles, UI-adapted
+- [motion-personality.md](director/motion-personality.md) — 4 archetypes + brand identity
+- [emotion-mapping.md](director/emotion-mapping.md) — Emotion → motion + color psychology
+- [choreography.md](director/choreography.md) — Multi-element coordination
+- [narrative-structure.md](director/narrative-structure.md) — Micro-story framework
+- [context-adaptation.md](director/context-adaptation.md) — Platform, a11y, performance
+
+**Reference** (reference/):
+- [timing-easing-tables.md](reference/timing-easing-tables.md) — Duration + easing lookups
+- [property-selection.md](reference/property-selection.md) — Property communication guide
+- [troubleshooting.md](reference/troubleshooting.md) — Animation smells + fixes
+- [quality-checklist.md](reference/quality-checklist.md) — Evaluation criteria
+
+**Patterns** (patterns/):
+- [entrance-exit.md](patterns/entrance-exit.md) — Entrance/exit recipes
+- [state-feedback.md](patterns/state-feedback.md) — Success, error, loading, hover
+- [ambient-continuous.md](patterns/ambient-continuous.md) — Looping, breathing, parallax
+- [multi-element.md](patterns/multi-element.md) — Stagger + choreography recipes
@@ -0,0 +1,93 @@
+# Choreography
+
+## Coordinated Entry Rules
+
+### 1. Lead with the Hero
+- Hero gets largest displacement and most attention-grabbing easing
+- Supporting elements are subtler in every dimension
+
+### 2. Spatial Origin Consistency
+All elements enter from same direction or shared origin. Mixed directions = chaos.
+
+### 3. Counter-Motion
+
+| Hero Motion | Counter-Motion | Speed Ratio |
+|-------------|---------------|-------------|
+| Enters left | Background shifts right | 20-30% |
+| Scales up | Shadow scales down | 10-20% |
+| Rotates CW | Ambient drifts CCW | 15-25% |
+| Lifts (Y up) | Shadow spreads + softens | 20-30% |
+
+## Sequence Structure
+
+| Phase | Duration Share | What Happens |
+|-------|--------------|-------------|
+| Setup | 20-30% | Elements enter, scene establishes |
+| Action | 30-40% | Primary motion, hero moment |
+| Resolution | 30-40% | Settle, secondary reactions, breathing |
+
+Leave 100-200ms stillness after resolution before new motion.
+
+## The 1/3 Rules
+
+**Distance**: No motion travels >1/3 screen without intermediate keyframe. Break with direction changes, speed variations, or arc adjustments.
+
+**Elements**: With 3+ animated elements, max 1/3 active simultaneously. Stagger so element 1 settles as element 3 starts.
+
+## Stagger Patterns
+
+| Pattern | Description | Best For |
+|---------|------------|----------|
+| Sequential | Reading order | Lists, grids |
+| Center-out | Radiating from center | Hero content, ripples |
+| Random | Varied timing | Organic, particle-like |
+| Wave | Sine-based | Data bars, continuous |
+| Reverse | Bottom-to-top | Exits, backward nav |
+
+- All staggered elements use same easing family
+- Vary only start time, not curve
+- Optional: last element gets slight overshoot (punctuation)
+
+## Shared Motion Events
+
+When multiple elements react to one trigger:
+- All start within 50ms of each other
+- Can arrive at different times (staggered landing)
+- Same easing family; motion originates from trigger point
+
+## Attention Direction
+
+| Technique | Implementation |
+|-----------|---------------|
+| Leading motion | Animate target before context |
+| Following motion | Settle on focal point |
+| Ambient motion | Subtle continuous in periphery |
+| Pointing motion | Directional toward CTA |
+
+### Depth Through Speed
+
+| Layer | Displacement | Speed |
+|-------|-------------|-------|
+| Foreground | 1.0x | Fastest |
+| Midground | 0.5x | Medium |
+| Background | 0.2x | Slowest |
+
+## Common Recipes
+
+### Dashboard Load
+1. Skeletons fade in (100ms)
+2. Hero metric (250ms, ease-out, 100ms delay)
+3. Supporting cards stagger (50ms between, 200ms each)
+4. Chart data draws in (300ms, starts with cards)
+5. Ambient pulse on primary metric
+
+### Modal Open
+1. Background dims (200ms)
+2. Modal scales 95%→100% + fades (300ms, 50ms delay)
+3. Content fades in (200ms, 100ms after modal)
+4. Close button last (150ms)
+
+### List Update (item added)
+1. Existing items shift down (200ms, ease-in-out)
+2. New item fades+slides from top (250ms, ease-out, 50ms delay)
+3. Subtle scale overshoot on land (3-5%)
@@ -0,0 +1,83 @@
+# Context Adaptation
+
+## Platform Scaling
+
+| Platform | Duration Modifier | Complexity | Physics |
+|----------|------------------|------------|---------|
+| Desktop | 1.0x (baseline) | Full | All types |
+| Tablet | 0.9x | Standard | Most types |
+| Mobile | 0.8x | Reduced (1-2 properties) | Snappy only |
+| Watch | 0.6x | Minimal (1 property) | None |
+| TV/Kiosk | 1.3x | Full | All types |
+
+**Mobile rules**: prefer opacity + transform; touch feedback <100ms; reduce stagger budgets by 30%; avoid parallax
+**Desktop opportunities**: hover states, cursor tracking, multi-column stagger, spatial choreography
+
+## Accessibility
+
+### prefers-reduced-motion
+
+| Original Motion | Reduced Alternative |
+|----------------|-------------------|
+| Slide entrance | Opacity fade only |
+| Bounce/spring | Instant or simple ease-out |
+| Parallax | Static positioning |
+| Auto-playing | Paused, user-initiated |
+| Complex choreography | Single fade |
+| Continuous ambient | Static or subtle opacity pulse |
+
+Reduced motion means: remove spatial movement, keep opacity, remove spring easing, reduce duration 50%+, never auto-play loops.
+
+### Vestibular Triggers (avoid or provide alternatives)
+- Large-scale zoom, full-screen position transitions
+- Spinning elements >100px, parallax >2 layers, rapid direction changes
+
+### Cognitive Accessibility
+- Same interaction = same animation every time
+- Pause controls for animations >5 seconds
+- Don't convey critical info through motion alone
+
+## Performance Budgets
+
+| Tier | Properties | Max Elements |
+|------|-----------|-------------|
+| Optimal | transform, opacity | Unlimited (GPU) |
+| Good | + color, clip-path | 10-15 |
+| Acceptable | + width, height, margin | 5-8 |
+| Avoid | box-shadow, border-radius, filter | 1-3 |
+
+- Target 60fps (16.67ms/frame); animation logic <10ms/frame
+- will-change sparingly; keep animated elements <20 per viewport
+- Stagger reduces peak load vs simultaneous
+- Fallback: 30fps acceptable for ambient
+
+## Content Type Adaptation
+
+| Content Type | Personality | Duration | Motion Density |
+|-------------|-------------|----------|---------------|
+| Financial | Corporate/Premium | 250-500ms | Low |
+| Social media | Playful | 150-300ms | Medium |
+| Enterprise SaaS | Corporate | 200-400ms | Low |
+| Gaming | Energetic | 100-250ms | High |
+| Healthcare | Corporate/Calm | 300-600ms | Very low |
+| E-commerce | Varies | 200-400ms | Medium |
+| Editorial | Premium | 350-600ms | Low |
+| Children's apps | Playful | 150-300ms | High |
+
+## Responsive Motion
+
+| Container Width | Max Displacement | Duration |
+|----------------|-----------------|----------|
+| <400px | 20% of width | 0.8x |
+| 400-800px | 25% of width | 1.0x |
+| 800-1200px | 20% of width | 1.0x |
+| >1200px | 15% of width | 1.1x |
+
+- Small viewport: sequential, one element at a time
+- Medium: standard stagger, 2-3 columns
+- Large: full choreography, center-out stagger, parallax
+
+## Dark Mode
+- Reduce motion intensity 10-20% (bright on dark = more impact)
+- Subtler ambient motion; careful with opacity values
+- Avoid pure white flashes
@@ -0,0 +1,53 @@
+# Core Philosophy
+
+## Three Pillars
+
+### Pillar 1: Emotional Intent
+Define target emotion before choosing any property.
+
+| Emotion | Character | Timing | Easing |
+|---------|----------|--------|--------|
+| Trust | Smooth, predictable | 300-400ms | Gentle curves |
+| Delight | Bouncy, surprising | 200-300ms | Overshoot |
+| Urgency | Sharp, direct | 100-200ms | Snappy ease-out |
+| Calm | Slow, flowing | 500-1000ms | Sine curves |
+| Surprise | Sudden, explosive | 150-300ms | Exponential |
+| Confidence | Direct, decisive | 200-400ms | Strong ease-out |
+
+### Pillar 2: Visual Narrative
+
+| Phase | Duration Share | Purpose |
+|-------|--------------|---------|
+| Setup | 20-30% | Establish context, prepare viewer |
+| Action | 30-40% | Primary motion, hero moment |
+| Resolution | 30-40% | Settle, breathe, confirm |
+
+Even a 200ms tooltip fade has implicit setup→action→resolution.
+
+### Pillar 3: Motion Craft
+- Easing curves match emotional intent
+- Duration proportional to element size and distance
+- Arcs for organic, straight for mechanical
+- Secondary motion (shadows, related elements)
+- Nothing starts and stops all at once
+
+## Three Motion Layers
+
+| Layer | Role | Amplitude |
+|-------|------|-----------|
+| Primary | Main action viewer follows | 100% |
+| Secondary | Supporting richness | 30-50% |
+| Ambient | Background life | 10-20% |
+
+- Secondary offset 50-100ms from primary, different easing
+- Ambient is continuous/slow, never demands attention
+- Primary-only animation feels flat; always add secondary + ambient
+
+## The 1/3 Screen Rule
+No motion travels >1/3 screen without intermediate keyframe. Break with direction changes, speed shifts, or arc adjustments.
+
+## The Attention Budget
+- One hero motion per scene moment
+- Max 2-3 elements in active motion simultaneously
+- Ambient doesn't count against budget
+- Stagger rather than synchronize
@@ -0,0 +1,91 @@
+# Decision Framework
+
+## The First Questions
+
+### 1. Purpose?
+
+| Purpose | Approach | Priority |
+|---------|----------|----------|
+| Draw attention | Scale, color, pulse | Responsiveness |
+| Guide sequence | Stagger, directional flow | Clarity |
+| Provide feedback | Immediate response | Speed |
+| Create atmosphere | Subtle, continuous | Subtlety |
+| Explain relationship | Position, connection | Legibility |
+| Celebrate/reward | Overshoot, particles | Delight |
+
+### 2. Audience?
+- Stressed → calm motion; Browsing → richer motion
+- Task-focused → fast, minimal; Exploring → can be dramatic
+- Seen 100x/day → fast, subtle; Seen once → can be dramatic
+
+### 3. Context?
+- Busy layout → simpler motion; Empty → can be dramatic
+- Other animations active → coordinate or stagger
+- Small container → small motion
+
+## 4-Level Decision Hierarchy
+
+### Level 1: Motion Category
+
+| Category | When |
+|----------|------|
+| Revealing | Content appearing |
+| Concealing | Content disappearing |
+| Transitioning | Between states/views |
+| Emphasizing | Drawing attention |
+| Responding | Reacting to interaction |
+| Ambient | Background atmosphere |
+
+### Level 2: Motion Personality
+Match to brand. See [motion-personality.md](motion-personality.md).
+
+### Level 3: Motion Direction
+
+| Direction | Communicates |
+|-----------|-------------|
+| Upward | Growth, aspiration |
+| Downward | Settling, completion |
+| Leftward | Regression, departure |
+| Rightward | Progression, arrival |
+| Outward (scale up) | Importance, emergence |
+| Inward (scale down) | Dismissal, removal |
+| Center-seeking | Focus, convergence |
+| Center-fleeing | Distribution, release |
+
+### Level 4: Implementation Properties
+Choose animated properties. See [property-selection.md](../reference/property-selection.md).
+
+## Decision Quick-Path
+
+```
+1. PURPOSE → What does this motion DO?
+   ├── Feedback → short, ease-out, minimal
+   ├── Entrance → ease-out, personality-matched
+   ├── Exit → ease-in, 70% of entrance
+   ├── Emphasis → scale or color pulse
+   └── Ambient → slow, continuous, sine
+
+2. PERSONALITY → Match keywords
+   ├── Fun/bouncy → Playful
+   ├── Elegant/luxury → Premium
+   ├── Clean/professional → Corporate
+   └── Bold/dynamic → Energetic
+
+3. PROPERTIES → Minimum needed (two = sweet spot)
+
+4. TIMING → Check duration table, adjust for distance/weight
+
+5. EASING → Entering=ease-out, Leaving=ease-in, On-screen=ease-in-out, Looping=sine
+```
+
+## Evaluation Before Delivery
+
+| Check | Question |
+|-------|----------|
+| Purpose | Clear function? |
+| Personality | Matches brand/context? |
+| Repetition | Fine on 100th viewing? |
+| Attention | Respects viewer's focus? |
+| Hierarchy | Reinforces importance? |
+| Layers | Primary + secondary + ambient? |
+| Timing | Duration appropriate? |
@@ -0,0 +1,102 @@
+# Disney's 12 Principles — UI Adapted
+
+## 1. Squash and Stretch
+
+- Squash: scale ~[1.2, 0.8]; Stretch: ~[0.85, 1.15]
+- Impact: 2-4 frames (30-65ms); Recovery: 4-8 frames (65-130ms)
+- Preserve volume: width +20% → height decreases proportionally
+- Skip for premium/luxury brands
+
+## 2. Anticipation
+
+- Small motion opposite to main direction before action
+- Duration: 100-200ms, magnitude: 10-20% of main action
+- Button: scale down 3% before expanding; Card: shift 5-10px away first
+- Skip for micro-feedback (<150ms)
+
+## 3. Staging
+
+- Dim non-hero elements to 40-60% opacity; optional 2-4px blur
+- Hero enters 100-200ms after supporting elements
+- One primary action per timing beat
+
+## 4. Straight Ahead vs. Pose to Pose
+
+| Approach | Feel | Best For |
+|----------|------|----------|
+| Straight Ahead | Fluid, spontaneous | Particles, ambient, generative art |
+| Pose to Pose | Planned, controlled | UI transitions, state changes |
+
+## 5. Follow Through and Overlapping Action
+
+- Child delay: 50-150ms behind parent
+- Trailing elements: offset stop times by 100-200ms
+- Use spring easing for trailing parts (lower stiffness = more trailing)
+
+## 6. Slow In and Slow Out
+
+| Context | Easing | Why |
+|---------|--------|-----|
+| Entrance | ease-out | Arrives smoothly |
+| Exit | ease-in | Departs quickly |
+| On-screen | ease-in-out | Smooth journey |
+| Ambient loop | sine ease-in-out | Seamless |
+
+**NEVER** linear for spatial movement. Linear only for: rotation, progress bars, timers.
+
+## 7. Arcs
+
+- Add 10-20px perpendicular offset at path midpoint
+- Subtle (5px) for corporate, pronounced (20px+) for playful
+- Mechanical UIs can use straight paths intentionally
+
+## 8. Secondary Action
+
+- Amplitude: 30-50% of primary; timing: 50-100ms after primary
+- Different easing than primary
+- Examples: card enters → shadow grows; button presses → ripple expands
+
+## 9. Timing
+
+| Weight/Mood | Duration |
+|-------------|----------|
+| Heavy (modals, pages) | 400-800ms |
+| Light (tooltips, toggles) | 100-250ms |
+| Sad/serious | 600ms+ |
+| Happy/light | 200-400ms |
+| Urgent | 100-200ms |
+
+Enter-exit asymmetry: entrances 30-50% longer than exits.
+
+## 10. Exaggeration
+
+| Personality | Exaggeration |
+|-------------|-------------|
+| Playful | 15-25% |
+| Energetic | 20-30% |
+| Corporate | 0-5% |
+| Premium | 0% |
+
+- Scale overshoot: 10-30% beyond target; rotation: ±5-15°
+
+## 11. Solid Drawing
+
+- Maintain consistent proportions across keyframes
+- Use scale + rotation together for depth
+- Shadow behavior matches implied light source
+
+## 12. Appeal
+
+- Smooth curves over sharp angles; satisfying timing
+- Personality consistency across all elements
+- Appeal killers: jerky motion, inconsistent timing, abrupt stops, uniform animation
+
+## Combining Principles
+
+| Recipe | Principles Used |
+|--------|----------------|
+| Button press | Anticipation + Squash/Stretch + Follow-Through + Secondary + Timing |
+| Card entrance | Anticipation + Arcs + Slow In/Out + Follow-Through + Staging |
+| Success celebration | Exaggeration + Secondary + Timing + Squash/Stretch + Appeal |
+| Error shake | Timing + Slow In/Out + Staging (no exaggeration) |
+| Loading spinner | Timing + Slow In/Out + Appeal |
@@ -0,0 +1,71 @@
+# Emotion-to-Motion Mapping
+
+## Core Table
+
+| Emotion | Character | Path | Easing | Duration |
+|---------|----------|------|--------|----------|
+| Joy/Delight | Bouncy, arcs, overshoot | Curved, upward | ease-out-back | 200-400ms |
+| Calm/Serenity | Smooth, flowing | Gentle curves | sine ease-in-out | 500-1000ms |
+| Urgency/Alert | Sharp, fast, direct | Straight lines | ease-out | 100-200ms |
+| Sadness/Weight | Slow, downward | Drooping curves | cubic ease-in-out | 600-1200ms |
+| Surprise/Impact | Sudden, expanding | Radial outward | ease-out-expo | 150-300ms |
+| Elegance/Grace | Slow, controlled | Long smooth arcs | (0.4, 0, 0.2, 1) | 400-700ms |
+| Playfulness | Bouncy, irregular | Arcs, squiggly | ease-out-back | 200-350ms |
+| Confidence | Direct, decisive | Straight, horizontal | ease-out | 200-400ms |
+| Curiosity | Exploratory, varied | Mixed, circular | varied | 300-500ms |
+| Tenderness | Soft, gentle | Very subtle curves | soft ease-in-out | 600-1000ms |
+
+## Path as Emotional Language
+
+| Path Type | Connotation |
+|-----------|------------|
+| Angular/sharp | Tense, urgent, mechanical |
+| Curved/smooth | Relaxed, friendly, organic |
+| Spiral | Playful, whimsical |
+| Straight diagonal | Dynamic, purposeful |
+| Vertical up | Growth, achievement |
+| Vertical down | Settling, gravity |
+| Horizontal | Journey, progress |
+| Radial outward | Explosion, release |
+| Radial inward | Focus, convergence |
+
+## Emotional Intensity
+
+| Intensity | Characteristics | When |
+|-----------|----------------|------|
+| Low | Subtle opacity, tiny shifts | Ambient, routine |
+| Medium | Visible but not demanding | Most UI interactions |
+| High | Demands attention, large displacement | Errors, celebrations, onboarding |
+
+## Color Psychology
+
+| Color | Emotion | Animation Pairing |
+|-------|---------|------------------|
+| Blue | Trust, calm | Smooth, medium transitions |
+| Green | Success, growth | Upward, expansion, gentle overshoot |
+| Red | Alert, urgency | Sharp, fast, horizontal shakes |
+| Orange | Energy, warmth | Bouncy, diagonal paths |
+| Purple | Premium, mystery | Slow reveals, elegant easing |
+| Yellow | Optimism, caution | Quick pulses |
+| Teal | Modern, clarity | Clean, snappy transitions |
+
+### Color Transition Rules
+- Success: transition TO green (don't start with it)
+- Error: flash red then settle (don't sustain)
+- Warning: pulse yellow/amber for urgency
+- Neutral: use opacity rather than color change
+
+## Context-Based Emotion Defaults
+
+| Context | Default Emotion |
+|---------|----------------|
+| Form success | Joy + Confidence |
+| Validation error | Mild urgency |
+| Page load | Calm + Confidence |
+| Navigation | Confidence |
+| Notification | Mild surprise |
+| Loading | Calm |
+| Onboarding | Curiosity + Delight |
+| Dashboard | Calm + Confidence |
+| Purchase complete | Joy + Confidence |
+| Delete/remove | Calm (respectful departure) |
@@ -0,0 +1,89 @@
+# Motion Personality
+
+## Four Archetypes
+
+### Playful
+
+| Parameter | Value |
+|-----------|-------|
+| Duration | 150-300ms |
+| Easing | ease-out-back / bouncy springs |
+| Overshoot | 10-20% |
+| Paths | Arcs and curves, never straight |
+| Squash-stretch | Yes, on impacts |
+
+Signature: bounce settle, squash-stretch on press, rotation wobble, bright color pops, varied stagger timing.
+Use for: children's apps, casual games, social media, celebrations, onboarding, creative tools.
+
+### Premium / Luxury
+
+| Parameter | Value |
+|-----------|-------|
+| Duration | 350-600ms |
+| Easing | cubic-bezier(0.4, 0, 0.2, 1) |
+| Overshoot | 0% |
+| Paths | Smooth curves, subtle parallax |
+| Squash-stretch | Never |
+
+Signature: slow fades, subtle scale (98%→100%), generous pauses, minimal properties (opacity+one), ultra-smooth.
+Use for: fashion, finance, luxury brands, premium SaaS, portfolios, editorial.
+
+### Corporate / Professional
+
+| Parameter | Value |
+|-----------|-------|
+| Duration | 200-400ms |
+| Easing | cubic-bezier(0.2, 0, 0, 1) |
+| Overshoot | 0-3% |
+| Paths | Mostly straight, small arcs for emphasis |
+| Squash-stretch | No |
+
+Signature: consistent timing, clear state transitions, functional motion, predictable patterns, uniform stagger.
+Use for: enterprise, dashboards, business tools, admin, healthcare, banking.
+
+### Energetic / Dynamic
+
+| Parameter | Value |
+|-----------|-------|
+| Duration | 100-250ms |
+| Easing | ease-out-expo / elastic |
+| Overshoot | 15-30% |
+| Paths | Dramatic arcs, large displacement, diagonal |
+| Squash-stretch | Yes, exaggerated |
+
+Signature: large scale changes (50-150%), fast color transitions, particle bursts, accelerating stagger, bold edge entrances.
+Use for: gaming, sports, music, events, marketing, fitness apps.
+
+## Keyword Matching
+
+| Keywords | Archetype |
+|----------|-----------|
+| fun, whimsical, bouncy, cute, friendly | Playful |
+| elegant, minimal, luxury, sophisticated | Premium |
+| clean, professional, business, dashboard | Corporate |
+| dynamic, energetic, bold, exciting | Energetic |
+| (unspecified) + UI | Corporate (default) |
+| (unspecified) + illustration | Playful (default) |
+
+## Brand Motion Identity
+
+Define three constants for recognizable motion:
+
+### 1. Signature Easing (80% of animations)
+Playful: ease-out-back | Premium: (0.4,0,0.2,1) | Corporate: (0.2,0,0,1) | Energetic: ease-out-expo
+
+### 2. Duration Palette
+
+| Tier | Playful | Premium | Corporate | Energetic |
+|------|---------|---------|-----------|-----------|
+| Quick | 150ms | 350ms | 200ms | 100ms |
+| Standard | 250ms | 500ms | 300ms | 180ms |
+| Slow | 400ms | 800ms | 450ms | 300ms |
+
+### 3. Entrance Pattern
+Playful: bounce up from below | Premium: slow fade + scale 98%→100% | Corporate: slide right + opacity | Energetic: snap from edge + overshoot
+
+## Mixing Archetypes
+- 90% primary archetype; specific moments can borrow another
+- Ease into personality shifts, don't snap
+- Example: corporate dashboard borrows Playful for success state only
@@ -0,0 +1,62 @@
+# Narrative Structure
+
+## Four-Act Structure
+
+### Act 1: Anticipation (10-20%)
+- Wind-up: small motion opposite to main direction
+- Gathering: elements pull together before dispersing
+- Dimming: context fades for focus; Tension: hold compressed ~50ms
+- Skip for <150ms interactions and hover states
+
+### Act 2: Action (30-50%)
+Peak energy. The primary communicative motion.
+- Fast+direct (sharp easing) → alerts
+- Smooth+flowing (gentle easing, curves) → transitions
+- Explosive+expanding (expo, radial) → celebrations
+- Controlled+precise (linear-ish) → data charts
+
+### Act 3: Reaction (10-20%)
+- Shadows adjust: 50-100ms after primary
+- Siblings shift: 50-150ms after primary
+- Environment ripples: 100-200ms after primary
+- Counter-motion: simultaneous with action
+- Skip for simple toggles/checkboxes
+
+### Act 4: Resolution (20-30%)
+- Overshoot settle (spring/back-easing); opacity reaches final (ease-out)
+- 100-200ms breathing room before next motion
+- Even 50ms of settling transforms the feel
+
+## Scaling to Duration
+
+| Total | Anticipation | Action | Reaction | Resolution |
+|-------|-------------|--------|----------|------------|
+| 100-200ms | skip | 60-70% | skip | 30-40% |
+| 200-400ms | 10-15% | 40-50% | 10-15% | 25-30% |
+| 400-800ms | 15-20% | 30-40% | 15-20% | 20-25% |
+| 800ms+ | 20% | 30-35% | 15-20% | 25-30% |
+
+## Multi-Beat Narratives
+
+Transitions: overlap (fluid) | sequential (clear) | simultaneous (parallel)
+
+Progressions:
+- **Build-Up**: low → rising → peak → settling
+- **Cycle**: depart → peak → return → repeat
+- **Impact**: sudden action → ripple → slow settle
+
+## By Personality
+
+| Personality | Anticipation | Action | Resolution |
+|------------|-------------|--------|------------|
+| Playful | Exaggerated wind-up | Bouncy, overshoot | Wobble settle |
+| Premium | Subtle tension | Smooth, controlled | Elegant ease |
+| Corporate | Minimal/none | Direct, efficient | Clean stop |
+| Energetic | Quick gather | Explosive | Fast snap |
+
+## Common Patterns
+
+- **Reveal**: tension (dim, scale 95%) → emerge (100%, full opacity) → surroundings adjust → settled
+- **Departure**: gather (scale 98%) → exit → close gap → layout settles
+- **Transformation**: destabilize (vibration) → morph → secondary appears → new state breathing
+- **Celebration**: compress (50-100ms) → burst (scale, particles) → settle → calm with positive state
@@ -0,0 +1,81 @@
+# Ambient & Continuous Patterns
+
+Ambient amplitude: 10-20% of primary motion. Never compete for attention.
+
+## Breathing / Pulse
+
+- Scale oscillation 0.98-1.02, sine ease-in-out, 2000-4000ms/cycle
+- Alt: opacity oscillation 0.7-1.0
+
+| Context | Scale Range | Duration | Opacity Range |
+|---------|-----------|----------|--------------|
+| Active indicator | 0.95-1.05 | 2000ms | 0.6-1.0 |
+| Waiting/idle | 0.98-1.02 | 3000ms | 0.8-1.0 |
+| Background element | 0.99-1.01 | 4000ms | 0.9-1.0 |
+| CTA attention | 0.97-1.03 | 2500ms | 0.7-1.0 |
+
+Pulsing >±5% scale becomes attention-demanding.
+
+## Floating / Hovering
+
+- Y position ±5-15px, sine ease-in-out, 3000-5000ms/cycle
+- Optional: slight rotation ±2-3°, offset 30% of position cycle
+
+**Layered floating** (multiple elements — different durations prevent sync):
+- Element 1: 4000ms, ±10px
+- Element 2: 5500ms, ±8px (offset 30%)
+- Element 3: 3500ms, ±12px (offset 60%)
+
+## Gradient Shift
+
+- Background-position or gradient angle shift
+- Duration: 8000-20000ms/cycle; range: ±10-20% position or ±15° angle
+- Easing: linear or sine; should be imperceptible at a glance
+
+## Parallax
+
+| Layer | Speed Ratio | Content |
+|-------|------------|---------|
+| Foreground | 1.0x | Interactive, text |
+| Midground | 0.5x | Decorative, cards |
+| Background | 0.2x | Patterns, scenery |
+| Deep background | 0.1x | Texture, atmospheric |
+
+**Scroll-driven**: total displacement <100px; avoid on mobile; never parallax text
+**Mouse-driven**: foreground 10-20px max, background 5-10px opposite direction, 100-200ms interpolation
+
+## Continuous Rotation
+
+- Spinners: linear easing, 1000-2000ms/revolution
+
+| Variant | Speed | Use Case |
+|---------|-------|----------|
+| Slow spin | 10-30s/rev | Background decoration |
+| Gear-like | 3-5s/rev | Technical/mechanical |
+| Orbital | 5-15s/rev | Space/science theme |
+| Wobble | 2-4s/cycle, sine | Playful idle |
+
+## Shimmer / Gleam
+
+- Gradient sweep left-to-right, 1500-2500ms/sweep
+- Pause 2000-5000ms between sweeps
+- Opacity gradient: 0%→30%→0%
+- Use for: skeleton loading, premium accents, "new" badges
+
+## Particle Ambient
+
+### Snow/Falling: 10-20 elements, 20-60px/s down, ±10-20px drift, 3-8px, 30-70% opacity
+### Dust/Motes: 5-10 elements, 10-30px/s mixed, 2-5px, 20-50% opacity
+### Sparkle/Stars: 8-15 elements, opacity pulse 0→100%→0, 500-1500ms/sparkle, random stagger
+
+**Performance**: <20 ambient elements, transform+opacity only, larger/fewer over small/numerous
+
+## Combining Ambient Layers
+
+| Layer | Type | Example |
+|-------|------|---------|
+| Background | Gradient shift or parallax | Slow color temperature change |
+| Midground | Floating or particles | Gentle floating elements |
+| Foreground | Breathing or shimmer | Subtle pulse on content |
+
+Total ambient: max 20% of primary motion's visual energy.
@@ -0,0 +1,82 @@
+# Entrance & Exit Patterns
+
+## Entrance Strategies
+
+### 1. Direct Entrance (Slide In)
+- Position + opacity; offset 20-40px + opacity 0 → final position + opacity 1
+- Easing: ease-out; duration 200-350ms
+
+| Personality | Offset | Easing | Overshoot |
+|------------|--------|--------|-----------|
+| Playful | 30-50px | ease-out-back | 10-15% |
+| Premium | 15-25px | (0.4, 0, 0.2, 1) | 0% |
+| Corporate | 20-30px | (0.2, 0, 0, 1) | 0-3% |
+| Energetic | 40-80px | ease-out-expo | 15-25% |
+
+Direction: below=arrival, right=forward, left=back, above=dropdown/authority.
+
+### 2. Emergent Entrance (Scale In)
+- Scale + opacity; start 85-95% + opacity 0 → 100% + opacity 1
+- Duration 250-400ms
+
+| Personality | Start Scale | Easing | Overshoot |
+|------------|------------|--------|-----------|
+| Playful | 70-80% | ease-out-back | 10-20% |
+| Premium | 95-98% | (0.4, 0, 0.2, 1) | 0% |
+| Corporate | 90-95% | (0.2, 0, 0, 1) | 0-3% |
+| Energetic | 50-70% | ease-out-expo | 15-30% |
+
+Best for: modals, dialogs, notifications, popovers, tooltips.
+
+### 3. Reveal Entrance (Clip/Mask)
+- clip-path or mask + opacity; 300-500ms, ease-out
+- Directions: top-to-bottom (dramatic), L-to-R (reading order), center-out (focus), edge-in (contained)
+
+### 4. Assembled Entrance (Multi-Part)
+- Parts arrive from different positions; stagger 50-100ms; total 300-600ms
+- Best for: icon assembly, logo builds, data viz construction
+
+## Exit Strategies
+
+**Rule**: Exits = 65-75% of entrance duration.
+
+### 1. Direct Exit (Slide Out)
+- Offset 20-40px + opacity 0; ease-in; 150-250ms
+
+### 2. Dissolve Exit (Fade Out)
+- Opacity (+ optional scale to 98%); ease-in; 150-250ms
+- Best for: gentle departures, backgrounding, crossfades
+
+### 3. Collapse Exit (Shrink Out)
+- Scale 85-95% + opacity 0; ease-in; 150-250ms
+- Best for: deletion, closing modals, dismissal
+
+### 4. Transfer Exit (Move Away)
+- Position toward destination + scale shrink; ease-in-out; 250-400ms
+- Best for: add-to-cart, save-to-collection, move-to-folder
+
+## Entrance-Exit Continuity
+- Eye follows naturally from exit to entrance
+- Exit point near entry point when possible
+- 100-150ms timing overlap between exit and entrance
+- Same easing family for paired entrance-exit
+
+## Common Recipes
+
+### Notification Slide-In
+1. Slide from right + opacity (250ms, ease-out)
+2. Overshoot 3-5% (corporate) or 10-15% (playful)
+3. Icon appears (100ms, 50ms delay)
+
+### Toast Dismiss
+1. Slide toward edge + opacity (180ms, ease-in)
+2. Remaining toasts shift up (200ms, ease-in-out)
+
+### Dropdown Open
+1. Scale Y 0→100% (200ms, ease-out)
+2. Items stagger fade in (30ms apart, 50ms after container)
+
+### Page Transition (Forward)
+1. Current page slides left + fades (300ms, ease-in)
+2. New page from right + fades in (400ms, ease-out, 100ms delay)
+3. Shared elements morph (400ms, ease-in-out)
@@ -0,0 +1,69 @@
+# Multi-Element Patterns
+
+## Stagger Recipes
+
+### List Items
+- Slide up 20px + fade (200ms, ease-out); stagger 40-60ms; total <400ms for 8 items
+
+| Personality | Duration | Stagger | Easing |
+|------------|---------|---------|--------|
+| Playful | 250ms | 60ms | ease-out-back |
+| Premium | 350ms | 80ms | (0.4, 0, 0.2, 1) |
+| Corporate | 200ms | 50ms | (0.2, 0, 0, 1) |
+| Energetic | 150ms | 30ms | ease-out-expo |
+
+### Grid Cards
+- Scale from 95% + fade (250ms, ease-out); stagger 50-80ms reading order; +20ms per new row
+- Shadow 50ms after card. Alt patterns: center-out, column-first, random
+
+### Navigation Items
+- Slide from side + fade (180ms, ease-out); stagger 30-50ms; total <300ms
+
+### Dashboard Widgets
+```
+0ms   — Skeletons visible
+100ms — Hero metric (250ms, ease-out)
+200ms — Widgets begin (200ms each, 60ms stagger)
+350ms — Hero complete, chart draws (300ms)
+500ms — All landed
+650ms — Ambient pulse begins
+```
+
+## Coordinated Sequences
+
+### Modal with Content
+0ms: backdrop dims (200ms) → 50ms: modal scales 95%→100% (300ms) → 200ms: title → 280ms: body → 350ms: buttons → 400ms: close button. Content in reading order.
+
+### Tab Switch
+0ms: indicator slides (250ms, ease-in-out) + old fades (150ms) → 100ms: new content from tab direction (200ms) → 150ms: elements stagger (40ms)
+
+### Accordion
+Expand: arrow rotates (150ms) + height expands (250ms) + content fades at 50ms (200ms); siblings shift (200ms). Collapse: reverse, ease-in.
+
+### Page Transition
+Current slides left+fades (300ms, ease-in) → new from right (400ms, ease-out, 100ms delay) → hero scales in → content staggers (50ms). Optional shared element morph (400ms).
+
+### Drag and Drop
+Drag: lift (scale 1.03, 150ms); others shift (200ms). Drop: settle (scale 1.0, 200ms); gaps close.
+
+## Choreography Rules
+
+### Timing Overlap
+0%=methodical | 25%=brisk (standard) | 50%=fluid | 75%=rapid (energetic)
+
+### Group Rules
+- Same easing family; different durations/delays fine
+- Exception: secondary/ambient can differ
+
+### Shared Origin
+Motion from trigger point; closer=first; farther=more delay
+
+### Counter-Motion
+
+| Hero Does | Counter-Motion |
+|-----------|---------------|
+| Slides right | Background left (20-30%) |
+| Scales up | Shadow spreads |
+| Lifts up | Shadow drops+softens |
+| Rotates CW | Ambient CCW |
+| Expands | Siblings compress |
@@ -0,0 +1,96 @@
+# State & Feedback Patterns
+
+## Button Press
+
+### Playful
+- Press: scale 0.95 (60ms, ease-out); Release: overshoot 1.05 (80ms); Settle: 1.0 (120ms, spring)
+- Secondary: shadow shrinks/grows; color darkens/brightens. Total ~260ms
+
+### Premium
+- Press: scale 0.98 (80ms); Release: 1.0 (150ms, no overshoot)
+- Opacity dims to 90% on press. Total ~230ms
+
+### Corporate
+- Press: scale 0.97 (60ms); Release: 1.0 (100ms); overshoot 0-2%
+- Background darkens 10%. Total ~160ms
+
+## Hover States
+
+| Element | Effect | Duration |
+|---------|--------|----------|
+| Button | Scale 1.02-1.05 | <100ms |
+| Card | Scale 1.01-1.02 + shadow lift | <100ms |
+| Link | Color change + underline | <100ms |
+| Icon | Scale 1.1 + rotation 2-5° | <100ms |
+| Image | Scale 1.03 (overflow hidden) | 150ms |
+
+Hover enter <100ms; hover exit 150-200ms (slower = polished).
+
+## Toggle / Switch
+- Thumb slides (120-180ms, ease-in-out); track color transitions simultaneously
+- Slight squash in movement direction
+- Playful: bounce at destination; Premium: smooth, no overshoot
+
+## Success State
+
+### Checkmark Success
+1. Container: scale 0.9→1.0 (200ms, ease-out-back, 5-10% overshoot)
+2. Checkmark: stroke draw (150ms, ease-out, 100ms delay)
+3. Color: to green (200ms); ambient glow/particles (300ms)
+4. Total: 400-500ms
+
+### Confirmation Badge
+1. Badge scales from 0 (200ms, ease-out-back)
+2. Text fades in (150ms, 50ms delay)
+3. Background pulse (300ms, sine)
+
+### Payment Success
+1. Spinner → checkmark crossfade (200ms)
+2. Checkmark draws (200ms); container → success color (200ms)
+3. Text fades in (200ms, 100ms delay); optional confetti (300-500ms)
+
+## Error State
+
+### Error Shake
+- Horizontal oscillation ±10-15px, 2-3 cycles decreasing amplitude
+- ease-in-out, 300-400ms total; red tint; no overshoot; settles at origin
+
+### Inline Validation
+1. Error text slides down + fades in (200ms)
+2. Border → red (150ms); icon scales in (150ms, 50ms delay)
+3. Optional single shake (200ms)
+
+### Form Submission Error
+1. Button returns to normal (200ms)
+2. Error message slides in (250ms)
+3. Affected fields highlight red (150ms, staggered 30ms)
+4. Smooth scroll to first error (300ms, ease-in-out)
+
+## Loading States
+
+### Spinner
+- Continuous 360°, linear, 1000-1500ms/rev; optional breathing pulse (2-3s)
+
+### Skeleton
+- Gradient sweep L→R, 1500-2000ms; base 10-20% opacity, peak 30-40%
+
+### Progress Bar
+- Width/transform, ease-in-out; optional color milestones + shimmer
+
+### Indeterminate
+- Oscillating position/width, 1500-2500ms, ease-in-out; continuous, never frantic
+
+## Warning State
+1. Yellow/amber border (150ms)
+2. Warning icon scales in (150ms, subtle overshoot)
+3. Optional icon pulse (2-3s, sine); text fades in (200ms, 50ms delay)
+
+## Disabled / Enabled
+
+- **Disabling**: opacity to 50-60% (200ms); optional scale to 98%
+- **Enabling**: opacity to 100% (200ms); optional scale pulse 98%→100%
+
+## Focus States
+- Focus ring: scale 95%→100% + opacity (150ms)
+- Card focus: scale 1.01, shadow increase (150ms)
+- Tab nav focus: <100ms; must work with reduced-motion
@@ -0,0 +1,95 @@
+# Property Selection
+
+## Position
+
+| Direction | Meaning |
+|-----------|---------|
+| Upward | Growth, improvement, aspiration |
+| Downward | Settling, completion, grounding |
+| Leftward | Regression, backward, departure |
+| Rightward | Progression, forward, arrival |
+| Toward center | Focus, convergence |
+| Away from center | Distribution, expansion |
+
+## Scale
+
+| Direction | Meaning |
+|-----------|---------|
+| Scale up | Importance, activation, proximity |
+| Scale down | Deprioritization, distance |
+| Pulse | Attention, heartbeat, life |
+| Breathing | Presence, waiting |
+
+## Rotation
+
+| Range | Meaning |
+|-------|---------|
+| Small (5-15°) | Subtle adjustment |
+| Medium (45-90°) | Transformation |
+| Full (360°) | Completion, processing |
+| Continuous | Ongoing activity |
+
+## Opacity
+
+| Direction | Meaning |
+|-----------|---------|
+| Fade in | Arrival, enablement |
+| Fade out | Departure, disablement |
+| Partial | Secondary, disabled state |
+
+**Rule**: NEVER opacity alone for important state changes. Combine with position or scale.
+
+## Color
+
+| Transition | Meaning |
+|-----------|---------|
+| To green | Success, go |
+| To red | Error, stop |
+| To blue | Trust, active |
+| To gray | Disabled, inactive |
+| Brightening | Activation, focus |
+| Dimming | Deactivation, background |
+
+## Combined Properties
+
+| Combination | Best For |
+|-------------|----------|
+| Position + Opacity | Content appearing/disappearing |
+| Scale + Opacity | Cards, modals, notifications |
+| Position + Scale | Selected items, focused content |
+| Rotation + Scale | Celebrations, playful activation |
+| Position + Rotation | Organic transitions |
+| Color + Scale | State emphasis |
+
+Primary property carries meaning; secondary adds polish. Two properties is the sweet spot.
+
+## Property Selection by Goal
+
+| Goal | Primary | Secondary | Avoid |
+|------|---------|-----------|-------|
+| Entrance | position | opacity | rotation |
+| Exit | position | opacity | scale up |
+| Button press | scale | color | position |
+| Hover | scale or color | opacity | position |
+| Success | scale | color + opacity | position |
+| Error | position (shake) | color | scale |
+| Loading | rotation | opacity | position |
+| Toggle | position | color | rotation |
+| Notification | position + scale | opacity | rotation |
+| Delete | scale + opacity | position | grow |
+| Selection | scale | color, opacity | rotation |
+| Progress | position or scale | color | opacity |
+
+## Performance
+
+| Property | Performance |
+|----------|-------------|
+| transform (translate, scale, rotate) | Excellent — GPU-accelerated |
+| opacity | Excellent — GPU-accelerated |
+| color / background-color | Good — triggers paint |
+| clip-path | Good — GPU on modern browsers |
+| width / height | Poor — triggers layout |
+| margin / padding | Poor — triggers layout |
+| box-shadow | Poor — expensive paint |
+
+**Rule**: Prefer transform + opacity for all motion.
@@ -0,0 +1,67 @@
+# Quality Checklist
+
+## Visual Quality
+- [ ] Elements >40px for motion, >100px for detail
+- [ ] Readable at full speed without slow-motion
+- [ ] Clear primary, secondary, ambient layers
+- [ ] Counter-motion for balance where needed
+- [ ] Natural arcs (unless intentionally mechanical)
+- [ ] 1/3 rule (distance): no unbroken motion >1/3 container
+- [ ] 1/3 rule (density): max 1/3 elements active simultaneously
+
+## Technical Quality
+- [ ] No linear easing on spatial movement
+- [ ] Duration matches element type table
+- [ ] Ease-out entrances, ease-in exits
+- [ ] Duration proportional to distance
+- [ ] Entrance duration >= exit duration
+- [ ] Not opacity-only for important state changes
+- [ ] Stagger total <500ms
+- [ ] Follow-through: child elements offset 50-150ms
+
+## Emotional Quality
+- [ ] Target emotion identified before properties
+- [ ] Personality archetype matches brand
+- [ ] Setup → action → resolution structure
+- [ ] Intensity matches interaction importance
+- [ ] Consistent: same interaction = same motion
+- [ ] Appropriate on 100th viewing
+
+## Performance Quality
+- [ ] Primary motion uses transform + opacity
+- [ ] <20 animated elements per viewport
+- [ ] No layout-triggering properties animated
+- [ ] Elements staggered, not simultaneous
+- [ ] Maintains 60fps (30fps acceptable for ambient)
+
+## Accessibility Quality
+- [ ] prefers-reduced-motion alternative provided
+- [ ] No vestibular triggers without alternative
+- [ ] Same interaction = same animation
+- [ ] Critical info not motion-only
+- [ ] Animations >5s are pausable
+
+## Severity Tiers
+
+### CRITICAL
+- Linear easing on spatial movement
+- Opacity-only for important states
+- Exceeds 1/3 screen rule
+- Missing primary layer
+- Stagger >500ms
+- Layout property animation causing jank
+
+### HIGH
+- Missing secondary layer
+- Duration mismatch with element type
+- Wrong directional easing
+- Inconsistent personality
+- No follow-through
+- Missing reduced-motion alternative
+
+### MEDIUM
+- Missing ambient layer
+- No anticipation phase
+- Overshoot mismatch
+- Could use better arcs
+- Missing counter-motion
@@ -0,0 +1,106 @@
+# Timing & Easing Tables
+
+## Duration by Element Type
+
+| Element | Duration |
+|---------|----------|
+| Tooltip / micro-feedback | 80-120ms |
+| Button / toggle | 120-180ms |
+| Icon transition | 150-250ms |
+| Card enter/exit | 200-350ms |
+| Modal / dialog | 300-400ms |
+| Page transition | 400-600ms |
+| Dramatic reveal | 600-1200ms |
+| Ambient | 2000-20000ms |
+
+## Distance-Duration Scaling
+
+50px=0.8x | 100px=1.0x | 200px=1.3x | 300px=1.5x | 400px=1.6x | Full screen=1.8-2.0x
+
+## Enter vs. Exit
+Entrance = base (100%). Exit = 65-75% of entrance.
+
+## Interactive Feedback
+
+| Interaction | Max Latency |
+|------------|-------------|
+| Hover | <100ms |
+| Press/tap | <150ms |
+| Release/settle | 200-300ms |
+| Error shake | 300-400ms |
+| Long press | 500-800ms |
+| Drag start | <50ms |
+
+## Duration by Personality
+
+| Personality | Quick | Standard | Slow |
+|------------|-------|----------|------|
+| Playful | 150ms | 250ms | 400ms |
+| Premium | 350ms | 500ms | 800ms |
+| Corporate | 200ms | 300ms | 450ms |
+| Energetic | 100ms | 180ms | 300ms |
+
+## Easing: Directional Rules
+
+Entrance=ease-out | Exit=ease-in | On-screen=ease-in-out | Looping=sine | Rotation/progress=linear
+
+## Easing: Industry Standards
+
+| Name | Cubic Bezier | Use |
+|------|-------------|-----|
+| MD3 Standard | (0.2, 0, 0, 1) | Default on-screen |
+| MD3 Emphasized | (0.05, 0.7, 0.1, 1) | Entrances |
+| MD3 Accelerate | (0.3, 0, 1, 1) | Exits |
+| MD3 Decelerate | (0, 0, 0, 1) | Entering |
+| Apple HIG | (0.25, 0.1, 0.25, 1) | iOS default |
+| Apple Spring | stiffness:300 damping:20 | Interactive |
+| Snappy UI | (0.2, 0, 0, 1) | Fast, decisive |
+| Gentle float | (0.4, 0, 0.2, 1) | Ambient |
+| Bounce settle | (0.175, 0.885, 0.32, 1.275) | Playful |
+| Elastic snap | (0.68, -0.55, 0.265, 1.55) | Dramatic |
+
+## Material-Based Easing
+
+| Material | Duration Scale | Overshoot |
+|----------|---------------|-----------|
+| Rigid (metal) | 1.2x | 0% |
+| Elastic (rubber) | 0.8x | 15-25% |
+| Fluid (water) | 1.5x | 5% |
+| Paper (cards) | 1.0x | 3-5% |
+| Gas (smoke) | 2.0x | 0% |
+| Glass | 0.9x | 0% |
+
+## Spring Parameters
+
+| Feel | Stiffness | Damping |
+|------|-----------|---------|
+| Very stiff | 400+ | 25-30 |
+| Standard | 250-350 | 18-24 |
+| Bouncy | 150-250 | 10-15 |
+| Very bouncy | 100-200 | 5-10 |
+| Gentle | 100-150 | 20-25 |
+
+Damping: <1.0=oscillates, 1.0=fastest no-oscillation, >1.0=slow settle.
+
+## Stagger Patterns
+
+| Pattern | Delay | Budget |
+|---------|------|--------|
+| Micro cascade | 20-40ms | <200ms |
+| Standard | 50-100ms | <400ms |
+| Dramatic | 100-200ms | <600ms |
+| Wave | 30-60ms | <500ms |
+
+Direction: top-to-bottom (lists) | L-to-R (horizontal) | center-out (hero) | random (organic) | reverse (exits)
+
+Total stagger MUST stay <500ms.
+
+## Overshoot Budget
+
+| Context | Overshoot |
+|---------|-----------|
+| Success | 5-10% |
+| Error | 0% |
+| Feedback | 2-5% |
+| Celebration | 15-25% |
+| Premium | 0% |
@@ -0,0 +1,73 @@
+# Troubleshooting
+
+## Looks Robotic
+- Linear easing → use ease-out (entrance) or ease-in-out
+- Straight paths → add 10-20px arc at midpoint
+- Uniform timing → stagger 50-100ms between elements
+- Everything synced → offset start/stop 50-150ms
+- No secondary → add shadow, icon reaction, ambient
+
+## Feels Too Slow
+- Duration exceeds type budget → check duration table
+- ease-in-out when ease-out works → ease-out feels faster
+- Too much anticipation → reduce to 10% or remove
+- Stagger exceeded → total <500ms
+- Overshoot settle too long → increase damping
+
+## Feels Too Fast / Jarring
+- Duration below minimum → modals 300ms+, pages 400ms+
+- No easing → add ease-out minimum
+- Missing resolution → add 50-100ms settle
+- No anticipation on large motion → add 100-200ms wind-up
+
+## Feels Cheap / Flat
+- Only primary motion → add secondary + ambient
+- Opacity-only → combine with position or scale
+- Same easing everywhere → vary primary vs secondary
+- No follow-through → child elements trail 50-150ms
+- No overshoot → add 3-10%
+
+## Too Distracting
+- Too many moving → 1/3 rule
+- Amplitude too large → reduce to minimum
+- Competing heroes → one per moment, dim rest
+- Ambient too prominent → 10-20% amplitude, slower
+- No breathing room → 100-200ms pause between beats
+
+## No Personality
+- Default easing → apply archetype's signature
+- Same duration for all → use personality palette
+- No consistent entrance → define one for project
+- Mixed archetypes → pick one for 90%+
+
+## Inconsistent Feel
+- Different easing same-type → standardize per motion type
+- Duration varies same type → use palette consistently
+- Entry direction changes → one origin everywhere
+- Overshoot inconsistent → apply rules consistently
+
+## Performance (Dropped Frames)
+- Animating width/height/margin → use transform
+- Too many elements → <20 per viewport
+- Complex shadows/filters → simplify or pre-render
+- No GPU acceleration → transform + opacity
+- All simultaneous → stagger to spread load
+
+## Quick Diagnostic
+
+1. No linear on spatial movement
+2. Duration matches element type
+3. Primary + secondary layers
+4. Consistent personality
+5. Directional easing correct
+6. 1/3 screen rule
+7. 1/3 element rule
+8. Follow-through present
+9. Every motion has purpose
+10. Fine on 100th viewing
+
+## Personality Mistakes
+- **Playful**: overshoot >25% = broken; not everything bounces; short+bounce = glitchy
+- **Premium**: too subtle = invisible; too slow = waiting; zero = broken
+- **Corporate**: too conservative = boring; playful easing breaks trust; identical = monotonous
+- **Energetic**: max everywhere = nothing stands out; too many particles; no settle = chaos
@@ -1,196 +0,0 @@
---
-name: testimonial-video
-description: This skill should be used when the user asks to "make an animated testimonial", "create a quote video", "build a review video", "turn a customer testimonial into a graphic", "animate a customer review", "make a social proof video", "add an animated star rating", or "turn a list of reviews into videos". Covers quote typography, staggered line reveals, kinetic emphasis on key phrases, animated star ratings, the author block (name/role/avatar/company), and templating one card across many quotes.
-version: 0.1.0
---
-
-# Testimonial Video
-
-Animate a written quote, review, or testimonial into a short, trustworthy social-proof clip. The craft is typographic, not flashy: a clean quote card where the words land in reading order, the key phrase gets emphasis exactly when it should, the stars fill to the real score, and the author signs off. One card design, driven by props, becomes a video for every review on the list.
-
-## When to use
-
- Customer review → a 6–12s vertical/feed clip (the headline use case).
- A pull-quote or testimonial graphic with author name, role, avatar, company.
- An animated star rating (including half/fractional scores like 4.5).
- A batch: a list/CSV of reviews → one video each, same template.
-
-Do **not** reach here for sale/discount promos or generic ad creative — this skill is strictly the quote / social-proof angle.
-
-## The one rule: trust before motion
-
-A testimonial earns its job by feeling *real*, not produced. Restraint reads as credibility; over-animation reads as an ad people skip.
-
-1. **Reveal in reading order.** The eye must finish a line before the next arrives. Stagger lines (or clauses), never all words at once, and never reorder for visual flair.
-2. **Quote the words exactly.** Do not paraphrase, trim mid-sentence, or invent a rating. If you emphasize a phrase, it must be the customer's phrase.
-3. **The author is the proof.** A quote with no attributable human is just a slogan. Name + role + company (and avatar if real) is non-negotiable.
-
-## The anatomy of a quote card
-
-| Element | Job | Timing |
-|---|---|---|
-| Quote mark motif | Signals "this is a quote" before words read | Frame 0, scales/fades in first |
-| Quote body | The testimonial, revealed line-by-line | Staggered, ~6–10 frames apart |
-| Emphasis span | The one phrase that sells | Lands *after* its line settles |
-| Star rating | The score, filled to the real value | Fills left→right after the quote |
-| Author block | Name / role / company / avatar | Signs off last, slides up |
-
-Build in that order; reveal in that order. The viewer reads the quote, believes it, sees the score, then learns who said it.
-
-## Staggered line reveal
-
-Split the quote into lines (or clauses), then offset each one's entrance. In Remotion, drive every line off `useCurrentFrame()` so it renders deterministically — never a CSS transition or a JS timer, which desync from the frame renderer.
-
-```jsx
-import { useCurrentFrame, spring, useVideoConfig } from "remotion";
-
-const QuoteBody = ({ lines, startAt = 8, stagger = 6 }) => {
-  const frame = useCurrentFrame();
-  const { fps } = useVideoConfig();
-  return (
-    <blockquote>
-      {lines.map((line, i) => {
-        const enter = spring({ frame: frame - startAt - i * stagger, fps,
-          config: { damping: 200 } });           // 0→1, no overshoot
-        return (
-          <span key={i} style={{ display: "block",
-            opacity: enter,
-            transform: `translateY(${(1 - enter) * 14}px)` }}>
-            {line}
-          </span>
-        );
-      })}
-    </blockquote>
-  );
-};
-```
-
-Keep one motion language: same easing, same 14px rise, every line. Speed reads as confidence only when it's consistent. See `references/quote-card.md` for the full composition.
-
-## Kinetic emphasis on the key phrase
-
-Pick the single phrase that carries the testimonial ("saved us 10 hours a week") and let it arrive *after* its line has settled — a highlight sweep, a weight shift, or a color pop. Emphasis competing with the reveal cancels both.
-
-```jsx
-const sweep = interpolate(frame, [hlStart, hlStart + 10], [0, 100],
-  { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
-// a highlighter wiping in behind the phrase, left→right
-<mark style={{ background:
-  `linear-gradient(90deg, var(--accent) ${sweep}%, transparent ${sweep}%)`,
-  color: "inherit", padding: "0 .08em" }}>{phrase}</mark>
-```
-
-Emphasize at most one span per quote. Two highlights is no highlight.
-
-## Animated star rating (fractional)
-
-Render the real score, including halves. Use one full row of star glyphs as a mask, then wipe a filled layer to `rating / max` width — this handles 4.5 as cleanly as 5.0, with no half-star sprite.
-
-```jsx
-const StarRating = ({ rating, max = 5, fillStart = 30, fillDur = 14 }) => {
-  const frame = useCurrentFrame();
-  const target = (rating / max) * 100;
-  const w = interpolate(frame, [fillStart, fillStart + fillDur], [0, target],
-    { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
-  return (
-    <div className="stars" role="img" aria-label={`${rating} out of ${max} stars`}>
-      <div className="track">★★★★★</div>
-      <div className="fill" style={{ width: `${w}%` }}>★★★★★</div>
-    </div>
-  );
-};
-```
-
-```css
-.stars { position: relative; display: inline-block; font-size: 40px; letter-spacing: 4px; }
-.track { color: rgba(255,255,255,.22); }
-.fill  { position: absolute; inset: 0; overflow: hidden; white-space: nowrap;
-         color: var(--accent); }   /* clipped by width → fractional fill */
-```
-
-Fill left→right after the quote reads. Never animate stars before the words — the score must feel earned, not pre-loaded. Always set `aria-label` to the real value.
-
-## The author block
-
-Sign off last. The block slides up under the stars and holds still — stillness is what makes attribution read as fact.
-
-```jsx
-<figcaption className="author">
-  {avatar && <img src={avatar} alt="" className="avatar" />}
-  <div>
-    <span className="name">{name}</span>
-    <span className="role">{role}{company && `, ${company}`}</span>
-  </div>
-</figcaption>
-```
-
-Use a real avatar or none — a generic placeholder face actively destroys trust. Name is the loudest line in the block; role/company is secondary weight.
-
-## Template × reviews — one video per quote
-
-The payoff: make every field a prop, hardcode nothing, then render once per review.
-
-```jsx
-export const Testimonial = ({ quote, highlight, rating, name, role, company, avatar }) => { /* … */ };
-```
-```bash
-for f in reviews/*.json; do
-  npx remotion render Testimonial "out/$(basename "$f" .json).mp4" --props="$f"
-done
-```
-
-Keep colors/fonts/quote-mark/layout in one theme object so 50 testimonials stay brand-locked and only the words and score change. See `references/batch-and-typography.md` for the review schema, CSV→props parsing, quote-typography craft (smart quotes, hanging punctuation, line-splitting, orphans), and the batch script.
-
-## Output checklist
-
- Lines reveal in reading order; one consistent enter motion, ~6–10 frame stagger.
- The quote is verbatim; exactly one emphasized span, landing after its line settles.
- Stars fill to the *real* score (halves supported) after the quote, with a correct `aria-label`.
- Author block (name + role + company, real avatar or none) signs off last and holds still.
- Every animated value derives from `useCurrentFrame()` — no CSS/JS timers.
- Every field is a prop; one template renders every review in the folder.
-
-## Deliver & verify (rendered stills → MP4)
-
-> **Packaged helper** (`scripts/`): tile your stills with `scripts/contact-sheet.sh sheet.png f-hook.png f-mid.png f-end.png`, then assert the encode with `scripts/probe-mp4.sh out.mp4 [WxH] [fps]`. See `scripts/README.md`.
-
-**Output contract:**
- A Remotion `Testimonial` registered as `<Composition>` (+ zod `schema` + `defaultProps`), every value frame-driven (no CSS transitions / JS timers / `Date.now()` / `Math.random()`).
- Deliverable = the rendered `out/*.mp4` per review per aspect (plus the project + review data, so the user re-renders on new quotes).
-
-**Verify loop — render stills → inspect → encode.** Cheap PNGs first; render with the **shipped** review's props, not just `defaultProps`.
-
-```bash
-# Frame-exact stills across the reveal order: quote → stars → author
-npx remotion still Testimonial out/f-quote.png  --frame=30  --props=reviews/r1.json  # lines in reading order, emphasis span
-npx remotion still Testimonial out/f-stars.png  --frame=48  --props=reviews/r1.json  # stars filled to the REAL score (e.g. 4.5)
-npx remotion still Testimonial out/f-author.png --frame=215 --props=reviews/r1.json  # author block signed off, holding still
-# inspect each: fidelity (quote VERBATIM, exactly one emphasized span, star fill matches rating, name/role/company exact)
-#   AND artifacts (text overflow/orphans, off-canvas, author in the 9:16 bottom third, missing font, broken avatar)
-```
-
-**Multi-aspect / batch — verify one review in EACH target aspect before batch-rendering the list.** A layout bug (overflowing quote, clipped author) repeats across every review × aspect; catch it once.
-
-```bash
-for ar in 9x16 1x1 16x9; do                                  # one representative review, every aspect
-  npx remotion still Testimonial "out/r1-${ar}.png" --frame=215 \
-    --props=reviews/r1.json --props-merge="{\"aspect\":\"${ar}\"}"
-done
-# stills clean in all aspects? → then batch-render the list:
-for f in reviews/*.json; do id=$(basename "$f" .json); for ar in 9x16 1x1 16x9; do
-  npx remotion render Testimonial "out/${id}-${ar}.mp4" --props="$f" --props-merge="{\"aspect\":\"${ar}\"}"
-done; done
-npx remotion render Testimonial out/demo.gif --codec=gif --props=reviews/r1.json   # README demo
-```
-
-**Before you finish:**
-1. `npx remotion still` renders cleanly at quote / stars / author — no errors, no missing fonts/avatar.
-2. Quote is verbatim with one emphasized span; stars fill to the real score; name/role/company exact and inside the safe zone (clear of the 9:16 bottom third).
-3. Frame-driven only — no CSS/JS timers, `Date.now()`, or `Math.random()`.
-4. Shipped review's props render correctly (not just `defaultProps`); `aria-label` carries the real rating.
-5. One review verified in 9:16 + 1:1 + 16:9 before the batch; MP4s play; (optional) GIF for the README.
-
-## Reference files
-
- `references/quote-card.md` — a complete runnable Remotion `Testimonial` composition: staggered line reveal, key-phrase highlight sweep, fractional star fill, author block, theme object, and the timing map for a 9:16 card. Plus a dependency-free HTML/CSS variant.
- `references/batch-and-typography.md` — the review prop schema, CSV/JSON→props parsing and validation, quote typography craft (smart quotes, hanging quotation marks, line/clause splitting, orphan control, legibility in motion), star-rating accessibility, and the template×reviews batch render script for N videos.
@@ -1,140 +0,0 @@
-# Batch & Typography
-
-How to feed many reviews into one card design, plus the quote-typography craft that separates a credible testimonial from a sloppy one.
-
-## Review prop schema
-
-One object per testimonial. Keep it flat so a CSV row maps to it directly.
-
-```ts
-type Review = {
-  quote: string;        // verbatim — never paraphrased or trimmed mid-sentence
-  highlight?: string;   // EXACT substring of `quote`; one phrase only
-  rating: number;       // 0–max, halves allowed (4.5)
-  max?: number;         // default 5
-  name: string;         // required — a quote with no name is not social proof
-  role?: string;
-  company?: string;
-  avatar?: string;      // real photo URL, or omit (never a stock face)
-};
-```
-
-### Validation (fail loud, before rendering 50 videos)
-
-```ts
-function validate(r: Review): string[] {
-  const errs: string[] = [];
-  if (!r.quote?.trim()) errs.push("quote is empty");
-  if (!r.name?.trim()) errs.push("name is required (no anonymous testimonials)");
-  const max = r.max ?? 5;
-  if (r.rating < 0 || r.rating > max) errs.push(`rating ${r.rating} out of 0–${max}`);
-  if (r.highlight && !r.quote.includes(r.highlight))
-    errs.push(`highlight "${r.highlight}" is not a substring of the quote`);
-  return errs;
-}
-```
-
-The `highlight ⊂ quote` check is the important one: it guarantees you only ever emphasize words the customer actually wrote. If the highlight isn't an exact substring, the emphasis silently disappears in the card — so block the render instead.
-
-## CSV → props
-
-Reviews usually arrive as a spreadsheet export. Map columns to the schema and coerce the rating.
-
-```js
-import { parse } from "csv-parse/sync";
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
-
-// CSV columns: quote,highlight,rating,name,role,company,avatar
-const rows = parse(readFileSync("reviews.csv"), { columns: true, trim: true });
-mkdirSync("reviews", { recursive: true });
-
-rows.forEach((row, i) => {
-  const r = {
-    quote: row.quote,
-    highlight: row.highlight || undefined,
-    rating: Number(row.rating),
-    name: row.name,
-    role: row.role || undefined,
-    company: row.company || undefined,
-    avatar: row.avatar || undefined,
-  };
-  const errs = validate(r);
-  if (errs.length) { console.error(`Row ${i + 1} (${r.name}):`, errs); process.exit(1); }
-  writeFileSync(`reviews/${String(i).padStart(3, "0")}-${slug(r.name)}.json`,
-    JSON.stringify(r, null, 2));
-});
-
-const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-```
-
-## Batch render — one video per review
-
-```bash
-mkdir -p out
-for f in reviews/*.json; do
-  name=$(basename "$f" .json)
-  npx remotion render Testimonial "out/$name.mp4" --props="$f"
-done
-```
-
-Everything visual lives in the single `theme` object in the composition (colors, fonts, quote-mark glyph, spacing). Because only the props change per render, 50 testimonials stay pixel-for-pixel brand-locked while the words and score vary. To re-theme the whole set, edit one object and re-run the loop.
-
-For multi-aspect (9:16 feed + 1:1 post + 16:9 site), register the composition at each size with a shared center-safe layout and loop over both `reviews/*.json` and the aspect list.
-
-## Quote typography craft
-
-Motion is the easy part; legible, well-set type is what makes the quote trustworthy.
-
-### Smart quotes, always
-
-Straight quotes (`"`) read as un-proofed. Convert to typographic quotes before rendering.
-
-```js
-const smarten = (s) => s
-  .replace(/(^|[\s([{])"/g, "$1“").replace(/"/g, "”")   // “ ”
-  .replace(/(^|[\s([{])'/g, "$1‘").replace(/'/g, "’")   // ‘ ’
-  .replace(/--/g, "—");                                       // em dash
-```
-
-### Hanging quotation marks
-
-A leading quote glyph indents the first line and breaks the flush-left edge. Hang it into the margin so the text block stays optically aligned — the gold standard for set quotes.
-
-```css
-blockquote { hanging-punctuation: first; }            /* Safari/WebKit */
-/* Cross-engine fallback: pull the opening mark left by its own width */
-blockquote::before { content: "\201C"; margin-left: -0.55em; color: var(--muted); }
-```
-
-When the card uses a large decorative quote mark (as in `quote-card.md`), drop the inline opening glyph so the mark isn't doubled.
-
-### Splitting into lines / clauses
-
-Reveal in reading order means splitting on meaning, not on a fixed character count. Prefer clause boundaries (`. ! ? , ; —`), then pack to a comfortable measure (~32–40 chars at card size). The `toLines` helper in `quote-card.md` does exactly this. Never split a short quote into one-word-per-line — that reads as a ransom note, not a testimonial.
-
-### Orphans & widows
-
-A single dangling word on the last line looks broken. Bind the last two words with a non-breaking space so they wrap together.
-
-```js
-const noOrphan = (s) => s.replace(/ ([^ ]+)\s*$/, " $1");
-```
-
-### Legibility in motion
-
- Use a font that stays readable while moving — avoid thin weights and tight tracking; a serif or a humanist sans at 500–600 weight holds up best on a rising line.
- Animate **opacity + a small translate** only. Blur, rotation, and scale on body text hurt readability mid-reveal.
- Contrast: body text ≥ 4.5:1 against the card; the highlight accent should pass against both the card and the ink it sits behind.
- One emphasized span per quote. A second highlight halves the weight of the first.
-
-## Star-rating accessibility & correctness
-
- The visual stars are decorative; expose the value to assistive tech with `role="img"` and `aria-label="4.5 out of 5 stars"` on the container (already in `quote-card.md`).
- For fractional scores, the width-clip method (`rating / max * 100%`) is exact for any decimal — no rounding to the nearest half-star, so 4.3 renders as 4.3.
- Never animate the stars before the quote is read, and never show more filled stars than the data supports. A faked rating is the fastest way to lose the trust the testimonial was meant to build.
- If a review has no rating, omit the star row entirely rather than defaulting to 5 — an invented score is worse than none.
-
-## Pacing notes
-
- Hold the finished card still for the back half of the clip (≥3s) so it's screenshot-able and re-shareable — shares are the whole point of social proof.
- For a sequence of testimonials in one video, give each card a full read (~3–4s) and hard-cut between them; cross-dissolving quotes makes both unreadable.
@@ -1,241 +0,0 @@
-# Quote Card — complete runnable component
-
-A full testimonial card you can drop into a Remotion project, plus a zero-dependency HTML/CSS variant for non-Remotion pipelines. Both reveal in reading order, emphasize one phrase, fill stars to the real score, and sign off with the author.
-
-## Timing map (9:16, 30fps, ~10s)
-
-| Frame | Beat |
-|---|---|
-| 0–8 | Quote mark scales in; card settles |
-| 8–48 | Quote body, line-by-line (8 + i×6) |
-| 44–54 | Key-phrase highlight sweep (after its line settles) |
-| 56–70 | Stars fill left→right to `rating/max` |
-| 72–88 | Author block slides up, holds |
-| 88–300 | Everything holds still (screenshot-able) |
-
-The card holds motionless for the back half — stillness is what makes a testimonial read as a fact rather than an ad.
-
-## Remotion composition
-
-```tsx
-import {
-  AbsoluteFill, useCurrentFrame, useVideoConfig, spring, interpolate, Img,
-} from "remotion";
-
-export type Review = {
-  quote: string;          // verbatim testimonial
-  highlight?: string;     // exact substring of `quote` to emphasize
-  rating: number;         // e.g. 4.5
-  max?: number;           // default 5
-  name: string;
-  role?: string;
-  company?: string;
-  avatar?: string;        // real photo URL, or omit
-};
-
-const theme = {
-  bg: "#0E1116",
-  ink: "#F5F7FA",
-  muted: "rgba(245,247,250,.55)",
-  accent: "#FFC24B",
-  font: "Inter, system-ui, sans-serif",
-  quoteFont: "'Newsreader', Georgia, serif",
-  quoteMark: "“",     // left double quotation mark
-};
-
-// Split a quote into clauses for reading-order reveal.
-// Prefer sentence/clause boundaries; fall back to ~32-char wraps.
-const toLines = (q: string): string[] => {
-  const parts = q.match(/[^.!?,;]+[.!?,;]?\s*/g) ?? [q];
-  const lines: string[] = [];
-  let buf = "";
-  for (const p of parts) {
-    if ((buf + p).length > 34 && buf) { lines.push(buf.trim()); buf = p; }
-    else buf += p;
-  }
-  if (buf.trim()) lines.push(buf.trim());
-  return lines;
-};
-
-// Render a line, wrapping the highlight substring in <mark> if present.
-const Line: React.FC<{ text: string; highlight?: string; sweep: number }> = ({
-  text, highlight, sweep,
-}) => {
-  if (!highlight || !text.includes(highlight)) return <>{text}</>;
-  const [before, after] = text.split(highlight);
-  return (
-    <>
-      {before}
-      <mark
-        style={{
-          background: `linear-gradient(90deg, ${theme.accent} ${sweep}%, transparent ${sweep}%)`,
-          color: "inherit",
-          padding: "0 .08em",
-          borderRadius: 3,
-          WebkitBoxDecorationBreak: "clone",
-        }}
-      >
-        {highlight}
-      </mark>
-      {after}
-    </>
-  );
-};
-
-export const Testimonial: React.FC<Review> = ({
-  quote, highlight, rating, max = 5, name, role, company, avatar,
-}) => {
-  const frame = useCurrentFrame();
-  const { fps } = useVideoConfig();
-  const lines = toLines(quote);
-
-  // Quote mark
-  const markIn = spring({ frame, fps, config: { damping: 14 } });
-
-  // Highlight sweep, after the body has revealed
-  const hlStart = 8 + lines.length * 6 + 4;
-  const sweep = interpolate(frame, [hlStart, hlStart + 10], [0, 100], {
-    extrapolateLeft: "clamp", extrapolateRight: "clamp",
-  });
-
-  // Stars fill, after the quote
-  const fillStart = hlStart + 14;
-  const target = (rating / max) * 100;
-  const starW = interpolate(frame, [fillStart, fillStart + 14], [0, target], {
-    extrapolateLeft: "clamp", extrapolateRight: "clamp",
-  });
-
-  // Author block slides up last
-  const authStart = fillStart + 16;
-  const auth = spring({ frame: frame - authStart, fps, config: { damping: 200 } });
-
-  return (
-    <AbsoluteFill style={{ background: theme.bg, fontFamily: theme.font,
-      padding: 120, justifyContent: "center", color: theme.ink }}>
-      <div
-        aria-hidden
-        style={{ fontFamily: theme.quoteFont, fontSize: 200, lineHeight: .6,
-          color: theme.accent, opacity: markIn, transform: `scale(${markIn})`,
-          transformOrigin: "left top" }}
-      >
-        {theme.quoteMark}
-      </div>
-
-      <blockquote style={{ fontFamily: theme.quoteFont, fontSize: 64,
-        lineHeight: 1.25, margin: "24px 0 48px", fontWeight: 500 }}>
-        {lines.map((line, i) => {
-          const enter = spring({ frame: frame - (8 + i * 6), fps,
-            config: { damping: 200 } });
-          return (
-            <span key={i} style={{ display: "block", opacity: enter,
-              transform: `translateY(${(1 - enter) * 14}px)` }}>
-              <Line text={line} highlight={highlight} sweep={sweep} />
-            </span>
-          );
-        })}
-      </blockquote>
-
-      {/* Stars */}
-      <div role="img" aria-label={`${rating} out of ${max} stars`}
-        style={{ position: "relative", display: "inline-block", fontSize: 52,
-          letterSpacing: 6, marginBottom: 56 }}>
-        <div style={{ color: "rgba(245,247,250,.20)" }}>{"★".repeat(max)}</div>
-        <div style={{ position: "absolute", inset: 0, overflow: "hidden",
-          whiteSpace: "nowrap", width: `${starW}%`, color: theme.accent }}>
-          {"★".repeat(max)}
-        </div>
-      </div>
-
-      {/* Author */}
-      <figcaption style={{ display: "flex", alignItems: "center", gap: 20,
-        opacity: auth, transform: `translateY(${(1 - auth) * 16}px)` }}>
-        {avatar && (
-          <Img src={avatar} alt=""
-            style={{ width: 88, height: 88, borderRadius: "50%", objectFit: "cover" }} />
-        )}
-        <div style={{ display: "flex", flexDirection: "column" }}>
-          <span style={{ fontSize: 38, fontWeight: 700 }}>{name}</span>
-          <span style={{ fontSize: 30, color: theme.muted }}>
-            {[role, company].filter(Boolean).join(", ")}
-          </span>
-        </div>
-      </figcaption>
-    </AbsoluteFill>
-  );
-};
-```
-
-Register it with a duration long enough for the back-half hold:
-
-```tsx
-<Composition id="Testimonial" component={Testimonial}
-  durationInFrames={300} fps={30} width={1080} height={1920}
-  defaultProps={{
-    quote: "We shipped in days, not months. Onboarding saved us 10 hours a week.",
-    highlight: "saved us 10 hours a week",
-    rating: 4.5, name: "Dana Reyes", role: "Head of Ops", company: "Northwind",
-  }} />
-```
-
-## Why these choices
-
- **`spring` with `damping: 200`** gives a clean rise with no overshoot — testimonials should feel composed, not bouncy. The quote mark uses lighter damping (14) for a touch of life on the one decorative element.
- **Highlight as a gradient `<mark>`** wipes a real highlighter behind the phrase without a second element or a mask, and survives line wraps via `box-decoration-break: clone`.
- **Stars as two stacked glyph rows clipped by width** render any fractional score (4.5, 4.3) with no half-star asset, and the filled row inherits the brand accent.
- **Author after stars** matches reading psychology: claim → proof → who. Reordering weakens trust.
-
-## Zero-dependency HTML/CSS variant
-
-For pipelines that capture a headless-browser timeline (or just a web embed). Animations are CSS `@keyframes` with per-line `animation-delay`; if rendering frame-exact video, prefer the Remotion version above so frames stay deterministic.
-
-```html
-<figure class="card" style="--accent:#FFC24B; --rating:4.5; --max:5">
-  <div class="qmark" aria-hidden="true">&ldquo;</div>
-  <blockquote>
-    <span style="--i:0">We shipped in days, not months.</span>
-    <span style="--i:1">Onboarding <mark>saved us 10 hours a week.</mark></span>
-  </blockquote>
-  <div class="stars" role="img" aria-label="4.5 out of 5 stars">
-    <div class="track">★★★★★</div><div class="fill">★★★★★</div>
-  </div>
-  <figcaption>
-    <img src="dana.jpg" alt="" class="avatar">
-    <div><b>Dana Reyes</b><small>Head of Ops, Northwind</small></div>
-  </figcaption>
-</figure>
-```
-
-```css
-.card { --bg:#0E1116; --ink:#F5F7FA; background:var(--bg); color:var(--ink);
-  font-family:Inter,system-ui,sans-serif; padding:120px; max-width:1080px; }
-.qmark { font:200px/.6 'Newsreader',Georgia,serif; color:var(--accent);
-  animation:pop .4s cubic-bezier(.22,1,.36,1) both; }
-blockquote { font:500 64px/1.25 'Newsreader',Georgia,serif; margin:24px 0 48px; }
-blockquote span { display:block; opacity:0;
-  animation:rise .5s cubic-bezier(.22,1,.36,1) both;
-  animation-delay:calc(.27s + var(--i) * .2s); }
-mark { background:linear-gradient(90deg,var(--accent) 100%,transparent 100%);
-  color:inherit; padding:0 .08em; border-radius:3px;
-  -webkit-box-decoration-break:clone; box-decoration-break:clone;
-  animation:sweep .35s ease-out both; animation-delay:1s; }
-@keyframes sweep { from { background-size:0 100% } to { background-size:100% 100% } }
-.stars { position:relative; display:inline-block; font-size:52px; letter-spacing:6px; }
-.track { color:rgba(245,247,250,.20); }
-.fill { position:absolute; inset:0; overflow:hidden; white-space:nowrap;
-  color:var(--accent); width:0; animation:fill .5s ease-out 1.3s forwards; }
-@keyframes fill { to { width:calc(var(--rating) / var(--max) * 100%) } }
-figcaption { display:flex; align-items:center; gap:20px; margin-top:56px;
-  opacity:0; animation:rise .5s ease-out 1.8s both; }
-.avatar { width:88px; height:88px; border-radius:50%; object-fit:cover; }
-figcaption b { font-size:38px; } figcaption small { display:block; font-size:30px;
-  color:rgba(245,247,250,.55); }
-@keyframes pop  { from { opacity:0; transform:scale(.7) } to { opacity:1; transform:none } }
-@keyframes rise { from { opacity:0; transform:translateY(14px) } to { opacity:1; transform:none } }
-```
-
-The CSS `mark` sweep uses `background-size` (animatable) rather than a gradient color-stop, since color-stop percentages don't animate in CSS. The star `--rating/--max` math is the same fractional fill as the Remotion version.
-
---
-## Built by the team behind iart.ai
-
-This skill is part of an open motion-graphics collection from iart.ai — the AI motion agent that turns data, scripts, and designs into editable motion graphics (Remotion → MP4). If you'd rather not hand-build this, iart.ai can turn a list of reviews/quotes into testimonial videos, swap text, and re-export. → [iart.ai](https://iart.ai/?utm_source=github&utm_medium=reference&utm_campaign=ad-video-skills&utm_content=ref_footer&utm_term=testimonial-video)
@@ -1 +0,0 @@
-../../.agents/skills/ad-creative-video
@@ -1 +0,0 @@
-../../.agents/skills/launch-video
@@ -0,0 +1 @@
+../../.agents/skills/motion-design
@@ -1 +0,0 @@
-../../.agents/skills/testimonial-video
@@ -1,23 +1,11 @@
 {
  "version": 1,
  "skills": {
-    "ad-creative-video": {
-      "source": "iart-ai/ad-video-skills",
+    "motion-design": {
+      "source": "LottieFiles/motion-design-skill",
      "sourceType": "github",
-      "skillPath": "skills/ad-creative-video/SKILL.md",
-      "computedHash": "94c33e3435abd802773c4b7e6058f3d47456bc56354d87b1e6fc2b689757735d"
-    },
-    "launch-video": {
-      "source": "iart-ai/ad-video-skills",
-      "sourceType": "github",
-      "skillPath": "skills/launch-video/SKILL.md",
-      "computedHash": "a55b82d2ca76de5bb80a1217594b11d1bf1ae4485b487bcad7ab256e2f116790"
-    },
-    "testimonial-video": {
-      "source": "iart-ai/ad-video-skills",
-      "sourceType": "github",
-      "skillPath": "skills/testimonial-video/SKILL.md",
-      "computedHash": "0d71fa501ffc13fc979d4d93865785c16741c6b4041ccbb3926eaf0da0f486da"
+      "skillPath": "skills/motion-design/SKILL.md",
+      "computedHash": "9fcf9130cc46ee8fd1d8e09a9263347a9d76efbcbfa46591cc4cefaf19bbb453"
    }
  }
 }