Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Claude
|
53388fe977 |
No files matched your search
@@ -0,0 +1,24 @@
|
||||
# Caption Animation
|
||||
|
||||
Turn a transcript or voiceover into word-timed, scroll-stopping captions: each word pops in on the syllable, the active word highlights, and the text stays glued to the narration. Build the kind of captions that drive watch-time on TikTok, Reels, and Shorts — readable, on-beat, and inside the safe area. For short-form creators burning open captions onto vertical video.
|
||||
|
||||
## When it activates
|
||||
|
||||
- "Add animated captions," "make TikTok captions," or "karaoke captions."
|
||||
- "Word-by-word subtitles," "auto subtitles," or "highlight the active word."
|
||||
- "Burn in captions to a video" or "sync captions to a voiceover/narration."
|
||||
- "Turn an SRT/transcript into animated text."
|
||||
|
||||
## Example prompts
|
||||
|
||||
- "Turn this Whisper transcript into karaoke captions with a per-word pop."
|
||||
- "Restyle these auto subtitles into a branded, Hormozi-style reveal."
|
||||
- "Burn word-level captions onto my voiceover and export a sidecar SRT."
|
||||
|
||||
## What's inside
|
||||
|
||||
- `SKILL.md` — the transcribe → normalize → page → animate → place → export pipeline.
|
||||
- `references/word-timed-captions.md` — deeper guidance on word-level timing and animation.
|
||||
|
||||
---
|
||||
Part of **[Short-Form Video Skills](../../)** · Built by **[iart.ai](https://iart.ai/?utm_source=github&utm_medium=readme&utm_campaign=tiktok-video-skills&utm_content=skill_footer&utm_term=caption-animation)** — the AI motion agent for editable, on-brand motion graphics.
|
||||
@@ -0,0 +1,177 @@
|
||||
---
|
||||
name: caption-animation
|
||||
description: This skill should be used when the user asks to "add animated captions", "make TikTok captions", "karaoke captions", "word-by-word subtitles", "auto subtitles", "highlight the active word", "burn in captions to a video", "sync captions to a voiceover/narration", or "turn an SRT/transcript into animated text". Covers word-level timing from Whisper, per-word pop/scale-in, active-word highlight, 9:16 safe-area placement, readable type, and burn-in vs sidecar SRT/VTT.
|
||||
version: 0.1.0
|
||||
---
|
||||
|
||||
# Caption Animation
|
||||
|
||||
Turn a transcript or voiceover into word-timed, scroll-stopping captions: each word pops in on the syllable, the active word highlights, and the text stays glued to the narration. Build the kind of captions that drive watch-time on TikTok, Reels, and Shorts — readable, on-beat, and inside the safe area.
|
||||
|
||||
## When to use
|
||||
|
||||
- Word-by-word or karaoke captions on short-form vertical video (9:16).
|
||||
- Burning open captions onto a voiceover/narration track from a transcript.
|
||||
- Turning a Whisper/SRT transcript into animated text in Remotion or on the web.
|
||||
- Restyling auto-generated subtitles into a branded, "Hormozi-style" reveal.
|
||||
|
||||
## The pipeline
|
||||
|
||||
| Stage | Job | Tool |
|
||||
|---|---|---|
|
||||
| Transcribe | Audio → word-level timestamps | Whisper (`@remotion/install-whisper-cpp`), AssemblyAI |
|
||||
| Normalize | → `{ text, startMs, endMs }[]` tokens | `@remotion/captions` `Caption` type |
|
||||
| Page | Group words into 1–4 word "pages" | `createTikTokStyleCaptions()` |
|
||||
| Animate | Per-word pop + active-word highlight | Remotion `spring()` / CSS |
|
||||
| Place | Safe-area, readable type | layout rules below |
|
||||
| Export | Burn-in (MP4) and/or sidecar SRT/VTT | Remotion render / file emit |
|
||||
|
||||
## Two non-negotiable rules
|
||||
|
||||
1. **Word-level timing, not line-level.** Karaoke reads as magic only when each word lands on the syllable. Always transcribe to word timestamps; never fake them by splitting a line evenly over its duration — drift is instantly visible.
|
||||
2. **Readability beats style.** Captions are read on a phone, in sunlight, muted. Bold sans-serif, heavy stroke or shadow, high contrast first; decoration second. A caption nobody can read is decoration, not a caption.
|
||||
|
||||
## Word timing from a transcript
|
||||
|
||||
Whisper emits word-level timestamps directly. Normalize every source into one flat token shape so the renderer never cares where the words came from:
|
||||
|
||||
```ts
|
||||
// Caption token — the one shape everything downstream consumes
|
||||
type Token = { text: string; startMs: number; endMs: number };
|
||||
|
||||
// Parse an SRT cue block "00:00:01,200 --> 00:00:01,640" into ms
|
||||
const toMs = (t: string) => {
|
||||
const [h, m, rest] = t.split(":");
|
||||
const [s, ms] = rest.split(",");
|
||||
return ((+h * 60 + +m) * 60 + +s) * 1000 + +ms;
|
||||
};
|
||||
```
|
||||
|
||||
If only sentence-level cues exist, re-transcribe for word timing — do not interpolate. Whisper's `medium.en` is ~2x faster than `large` and accurate enough for clean voice audio.
|
||||
|
||||
## Per-word pop-in (Remotion)
|
||||
|
||||
Drive each word's scale and opacity off a spring anchored to its own `startMs`. The micro-overshoot is what makes it feel "alive".
|
||||
|
||||
```tsx
|
||||
import { useCurrentFrame, useVideoConfig, spring, interpolate } from "remotion";
|
||||
|
||||
const Word: React.FC<{ token: Token; active: boolean }> = ({ token, active }) => {
|
||||
const frame = useCurrentFrame();
|
||||
const { fps } = useVideoConfig();
|
||||
const enter = (token.startMs / 1000) * fps; // word's own entrance frame
|
||||
const p = spring({ frame: frame - enter, fps, config: { damping: 12, mass: 0.6 } });
|
||||
const scale = interpolate(p, [0, 1], [0.6, 1]); // pop from 60% → 100% (overshoots)
|
||||
return (
|
||||
<span style={{
|
||||
display: "inline-block",
|
||||
transform: `scale(${scale})`,
|
||||
opacity: interpolate(p, [0, 1], [0, 1]),
|
||||
color: active ? "#FFE45E" : "#FFFFFF", // active-word highlight
|
||||
transition: "color 80ms linear",
|
||||
}}>{token.text} </span>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
Compute `active` by testing `frame` against each token's `[startMs, endMs]`. Keep the highlight a single accent color or a filled "box" behind the live word — never animate every word's color at once.
|
||||
|
||||
## Pages, not walls of text
|
||||
|
||||
Show 1–4 words at a time. Use Remotion's `createTikTokStyleCaptions()` (or group manually) and tune `combineTokensWithinMilliseconds`: ~200–500ms for true word-by-word, ~1000–1500ms for short readable phrases.
|
||||
|
||||
```ts
|
||||
import { createTikTokStyleCaptions } from "@remotion/captions";
|
||||
const { pages } = createTikTokStyleCaptions({
|
||||
captions, combineTokensWithinMilliseconds: 1200, // ~2–3 words per page
|
||||
});
|
||||
```
|
||||
|
||||
## Web/CSS pop (no Remotion)
|
||||
|
||||
For a DOM/live player, give each word its own `animation-delay` equal to `startMs`:
|
||||
|
||||
```css
|
||||
.word { display:inline-block; opacity:0; animation: pop .26s cubic-bezier(.34,1.56,.64,1) forwards; }
|
||||
@keyframes pop { from { opacity:0; transform:translateY(.18em) scale(.7) } to { opacity:1; transform:none } }
|
||||
.word.active { color:#FFE45E; }
|
||||
```
|
||||
```js
|
||||
words.forEach(w => { const el = mk(w.text); el.style.animationDelay = `${w.startMs}ms`; track.append(el); });
|
||||
```
|
||||
|
||||
## Readable type and safe-area placement (9:16, 1080×1920)
|
||||
|
||||
| Property | Value | Why |
|
||||
|---|---|---|
|
||||
| Font | Bold/ExtraBold sans (Montserrat, Inter, Helvetica) | Reads on small, busy screens |
|
||||
| Size | 56–80px (≈8% of frame height), min 45px | Legible muted on a phone |
|
||||
| Stroke | 2–6px solid black outline | Survives any background |
|
||||
| Shadow | Soft drop shadow as backup to stroke | Separation on bright frames |
|
||||
| Case | Uppercase or sentence; high contrast fill | Punch + scannability |
|
||||
| Vertical pos | Center band, ~62–70% down | Above the UI, below the action |
|
||||
| Bottom safe | Keep clear of bottom ~280px / 15% | Avoids caption/CTA/audio UI |
|
||||
| Side safe | Keep within center 80% width | Avoids right-rail icons |
|
||||
|
||||
Place captions in the center band — not pinned to the very bottom, where the platform UI (username, audio, buttons) lives. Pad text to a max of ~2 lines.
|
||||
|
||||
## Sync to a voiceover / narration
|
||||
|
||||
The transcript already carries the timing of the exact audio. Lay that same audio under the composition and keep timestamps in the audio's timebase — captions and voice stay locked with zero manual nudging. If the VO is re-recorded, re-transcribe; never hand-shift offsets.
|
||||
|
||||
## Burn-in vs sidecar SRT/VTT
|
||||
|
||||
| | Burn-in (open) | Sidecar SRT/VTT (closed) |
|
||||
|---|---|---|
|
||||
| Where | Pixels in the MP4 | Separate `.srt`/`.vtt` file |
|
||||
| Social (TikTok/Reels) | Required — guaranteed, styleable | Often ignored by the platform |
|
||||
| Accessibility (ADA/WCAG) | Does not satisfy alone | Required (toggleable) |
|
||||
| Best practice | Burn animated captions for social | Also ship a sidecar for the web/SEO |
|
||||
|
||||
Emit both: burn the animated captions for social, and write a plain SRT/VTT from the same tokens for accessible/SEO playback.
|
||||
|
||||
## Output checklist
|
||||
|
||||
- Word-level timestamps (real, from transcription) — no even-split fakery.
|
||||
- Per-word pop with micro-overshoot; one accent color for the active word.
|
||||
- 1–4 words per page; never a wall of text.
|
||||
- Bold sans, 56–80px, 2–6px stroke + shadow, high contrast.
|
||||
- Center band, clear of bottom ~280px and side rails.
|
||||
- Audio laid under composition; timestamps in the audio timebase.
|
||||
- Ship burn-in for social and a sidecar SRT/VTT for accessibility.
|
||||
|
||||
## 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`.
|
||||
|
||||
Captions ship as a Remotion composition (`<Composition>` + zod `schema` + `defaultProps`) — all word motion frame-driven off `useCurrentFrame()`, never `Date.now()` / `Math.random()` / timers. Deliverable = `out/*.mp4` (burned-in) + the project + the sidecar SRT/VTT. 9:16 vertical (1080×1920) is the default.
|
||||
|
||||
**Verify loop — render stills → inspect → encode.** Word timing is the thing that breaks; check it at exact frames before you spend an encode.
|
||||
|
||||
```bash
|
||||
# Stills at start / a sampled active-word frame / end — WITH SHIPPED PROPS (real tokens + audio)
|
||||
npx remotion still Captions out/f-start.png --frame=0 --props='{"captionsSrc":"vo.json"}'
|
||||
npx remotion still Captions out/f-mid.png --frame=90 --props='{"captionsSrc":"vo.json"}'
|
||||
npx remotion still Captions out/f-end.png --frame=N --props='{"captionsSrc":"vo.json"}' # N = durationInFrames-1
|
||||
|
||||
# Inspect each PNG:
|
||||
# - the word highlighted at frame 90 is the word whose [startMs,endMs] contains 90/fps (no drift)
|
||||
# - burn-in legible: bold sans, stroke+shadow holds, no clipping
|
||||
# - 9:16 safe area: caption sits in the center band, clear of top ~12% and bottom ~20-35% (captions/CTA/audio UI) and the right action rail
|
||||
|
||||
npx remotion render Captions out/captions.mp4 --props='{"captionsSrc":"vo.json"}' # encode once stills are right
|
||||
npx remotion render Captions out/demo.gif --codec=gif # README proof clip
|
||||
```
|
||||
|
||||
Use `npx remotion compositions` to read `durationInFrames`/`fps` and pick the active-word + end frames.
|
||||
|
||||
**Before you finish:**
|
||||
1. Stills render cleanly at frame 0, a mid active-word frame, and last — no missing font/audio.
|
||||
2. The correct word is highlighted at the sampled frame (frame/fps lands inside its token); no even-split fakery.
|
||||
3. Burn-in is legible (stroke+shadow) and the caption is fully inside the 9:16 safe area at every checked frame.
|
||||
4. Frame-driven only — no `Date.now()` / `Math.random()` / timers.
|
||||
5. Shipped props (real tokens, not just `defaultProps`) render correctly; MP4 + sidecar SRT/VTT emitted, GIF optional.
|
||||
|
||||
## Reference files
|
||||
|
||||
- `references/word-timed-captions.md` — end-to-end build: Whisper transcription and the `Caption` type, a full SRT parser, Remotion word-timed component with active-highlight, manual paging, an SRT/VTT emitter, per-platform safe-area maps, and a readable-type spec sheet.
|
||||
@@ -0,0 +1,254 @@
|
||||
# Word-Timed Captions — End-to-End Build
|
||||
|
||||
A complete, runnable path from audio/transcript to animated burn-in captions plus a sidecar SRT/VTT. Code targets Remotion for burn-in and plain JS for the web; the data shapes are framework-agnostic.
|
||||
|
||||
## 1. The one data shape
|
||||
|
||||
Everything normalizes to a flat array of word tokens. Get to this shape and the renderer never cares about the source.
|
||||
|
||||
```ts
|
||||
export type Token = { text: string; startMs: number; endMs: number };
|
||||
export type Page = { startMs: number; endMs: number; tokens: Token[] };
|
||||
```
|
||||
|
||||
Remotion's `@remotion/captions` uses a compatible `Caption` type:
|
||||
|
||||
```ts
|
||||
type Caption = { text: string; startMs: number; endMs: number; timestampMs: number | null; confidence: number | null };
|
||||
```
|
||||
|
||||
## 2. Transcribe to word-level timing (Whisper)
|
||||
|
||||
Word timestamps are non-negotiable for karaoke. Whisper produces them natively.
|
||||
|
||||
```bash
|
||||
npx @remotion/install-whisper-cpp # one-time: installs whisper.cpp + a model
|
||||
```
|
||||
|
||||
```ts
|
||||
import { transcribe, toCaptions } from "@remotion/install-whisper-cpp";
|
||||
|
||||
const { transcription } = await transcribe({
|
||||
inputPath: "voiceover.wav", // 16kHz mono WAV is ideal for whisper.cpp
|
||||
model: "medium.en", // medium.en ≈ 2x faster than large, accurate on clean voice
|
||||
tokenLevelTimestamps: true, // <-- the key flag: per-word, not per-line
|
||||
whisperPath: "./whisper.cpp",
|
||||
});
|
||||
const { captions } = toCaptions({ transcription }); // → Caption[]
|
||||
```
|
||||
|
||||
Tips:
|
||||
- Feed clean voice audio (denoise/normalize first). Background music wrecks word boundaries.
|
||||
- `large` is most accurate but 2–3x real-time on a laptop. Use `medium.en` unless accuracy is critical.
|
||||
- Cloud alternatives (AssemblyAI, Deepgram, OpenAI Whisper API) also return word timing — map their `words[]` into `Token` the same way.
|
||||
|
||||
Map any token shape into `Token`:
|
||||
|
||||
```ts
|
||||
const toTokens = (caps: Caption[]): Token[] =>
|
||||
caps.map(c => ({ text: c.text.trim(), startMs: c.startMs, endMs: c.endMs }));
|
||||
```
|
||||
|
||||
## 3. Parse an existing SRT into tokens
|
||||
|
||||
When handed an SRT, parse cues; if cues are sentence-level, re-transcribe for word timing rather than interpolating.
|
||||
|
||||
```ts
|
||||
const toMs = (t: string) => {
|
||||
const [h, m, rest] = t.trim().split(":");
|
||||
const [s, ms] = rest.split(",");
|
||||
return ((+h * 60 + +m) * 60 + +s) * 1000 + +ms;
|
||||
};
|
||||
|
||||
export function parseSrt(src: string): Token[] {
|
||||
return src.trim().split(/\n\s*\n/).map(block => {
|
||||
const lines = block.split("\n");
|
||||
const time = lines.find(l => l.includes("-->"))!;
|
||||
const [a, b] = time.split("-->");
|
||||
const text = lines.slice(lines.indexOf(time) + 1).join(" ").trim();
|
||||
return { text, startMs: toMs(a), endMs: toMs(b) };
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## 4. Page the tokens (1–4 words at a time)
|
||||
|
||||
Either use Remotion's helper or group manually. Manual grouping by gap + max-words keeps full control:
|
||||
|
||||
```ts
|
||||
export function paginate(tokens: Token[], maxWords = 3, maxGapMs = 1200): Page[] {
|
||||
const pages: Page[] = [];
|
||||
let cur: Token[] = [];
|
||||
for (const t of tokens) {
|
||||
const span = cur.length ? t.endMs - cur[0].startMs : 0;
|
||||
if (cur.length >= maxWords || span > maxGapMs) {
|
||||
if (cur.length) pages.push(pageOf(cur)); cur = [];
|
||||
}
|
||||
cur.push(t);
|
||||
}
|
||||
if (cur.length) pages.push(pageOf(cur));
|
||||
return pages;
|
||||
}
|
||||
const pageOf = (ts: Token[]): Page => ({ startMs: ts[0].startMs, endMs: ts.at(-1)!.endMs, tokens: ts });
|
||||
```
|
||||
|
||||
Remotion equivalent:
|
||||
|
||||
```ts
|
||||
import { createTikTokStyleCaptions } from "@remotion/captions";
|
||||
const { pages } = createTikTokStyleCaptions({ captions, combineTokensWithinMilliseconds: 1200 });
|
||||
// 200–500ms → word-by-word; 1000–1500ms → short readable phrases
|
||||
```
|
||||
|
||||
## 5. Remotion component: word-timed with active highlight
|
||||
|
||||
```tsx
|
||||
import { AbsoluteFill, Audio, Sequence, useCurrentFrame, useVideoConfig,
|
||||
spring, interpolate, staticFile } from "remotion";
|
||||
|
||||
const CAPTION_STYLE: React.CSSProperties = {
|
||||
fontFamily: "Montserrat, Inter, sans-serif",
|
||||
fontWeight: 800,
|
||||
fontSize: 72, // ~8% of 1920px height
|
||||
color: "#fff",
|
||||
textAlign: "center",
|
||||
textTransform: "uppercase",
|
||||
WebkitTextStroke: "5px #000", // heavy outline survives any background
|
||||
paintOrder: "stroke fill", // stroke behind fill, not clipping glyphs
|
||||
textShadow: "0 4px 16px rgba(0,0,0,.55)",
|
||||
lineHeight: 1.1,
|
||||
padding: "0 80px", // keep inside center 80% width
|
||||
};
|
||||
|
||||
const Word: React.FC<{ token: Token; active: boolean }> = ({ token, active }) => {
|
||||
const frame = useCurrentFrame();
|
||||
const { fps } = useVideoConfig();
|
||||
const enter = (token.startMs / 1000) * fps;
|
||||
const p = spring({ frame: frame - enter, fps, config: { damping: 12, mass: 0.6 } });
|
||||
return (
|
||||
<span style={{
|
||||
display: "inline-block",
|
||||
transform: `scale(${interpolate(p, [0, 1], [0.6, 1])})`,
|
||||
opacity: interpolate(p, [0, 1], [0, 1]),
|
||||
color: active ? "#FFE45E" : undefined,
|
||||
transition: "color 80ms linear",
|
||||
}}>{token.text} </span>
|
||||
);
|
||||
};
|
||||
|
||||
export const Captions: React.FC<{ pages: Page[]; audio: string }> = ({ pages, audio }) => {
|
||||
const { fps } = useVideoConfig();
|
||||
const f = (ms: number) => Math.round((ms / 1000) * fps);
|
||||
const frame = useCurrentFrame();
|
||||
return (
|
||||
<AbsoluteFill>
|
||||
<Audio src={staticFile(audio)} /> {/* same audio the transcript came from */}
|
||||
{pages.map((pg, i) => (
|
||||
<Sequence key={i} from={f(pg.startMs)} durationInFrames={Math.max(1, f(pg.endMs - pg.startMs))}>
|
||||
<AbsoluteFill style={{ justifyContent: "flex-start", alignItems: "center", paddingTop: "62%" }}>
|
||||
<div style={CAPTION_STYLE}>
|
||||
{pg.tokens.map((t, j) => {
|
||||
const now = (frame / fps) * 1000;
|
||||
return <Word key={j} token={t} active={now >= t.startMs && now < t.endMs} />;
|
||||
})}
|
||||
</div>
|
||||
</AbsoluteFill>
|
||||
</Sequence>
|
||||
))}
|
||||
</AbsoluteFill>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
Because the `<Audio>` and the timestamps share one timebase, voice and captions stay locked with no manual nudging. Re-record the VO → re-transcribe → done.
|
||||
|
||||
## 6. Web/CSS path (live DOM player)
|
||||
|
||||
```js
|
||||
function renderTrack(tokens, mountEl) {
|
||||
tokens.forEach(t => {
|
||||
const el = document.createElement("span");
|
||||
el.className = "word";
|
||||
el.textContent = t.text + " ";
|
||||
el.style.animationDelay = `${t.startMs}ms`; // each word pops on its own start
|
||||
mountEl.append(el);
|
||||
});
|
||||
}
|
||||
// drive .active off the media element's currentTime
|
||||
audio.addEventListener("timeupdate", () => {
|
||||
const ms = audio.currentTime * 1000;
|
||||
[...track.children].forEach((el, i) =>
|
||||
el.classList.toggle("active", ms >= tokens[i].startMs && ms < tokens[i].endMs));
|
||||
});
|
||||
```
|
||||
|
||||
```css
|
||||
.cap { font: 800 72px/1.1 Montserrat, sans-serif; text-transform: uppercase;
|
||||
color:#fff; -webkit-text-stroke:5px #000; paint-order:stroke fill;
|
||||
text-shadow:0 4px 16px rgba(0,0,0,.55); text-align:center; }
|
||||
.word { display:inline-block; opacity:0; animation: pop .26s cubic-bezier(.34,1.56,.64,1) forwards; }
|
||||
.word.active { color:#FFE45E; }
|
||||
@keyframes pop { from { opacity:0; transform:translateY(.18em) scale(.7) } to { opacity:1; transform:none } }
|
||||
```
|
||||
|
||||
## 7. Emit a sidecar SRT / VTT from the same tokens
|
||||
|
||||
Burn-in alone does not satisfy ADA/WCAG and many platforms ignore uploaded tracks — so ship both. Group tokens into readable cues and serialize:
|
||||
|
||||
```ts
|
||||
const pad = (n: number, w = 2) => String(n).padStart(w, "0");
|
||||
const stamp = (ms: number, sep: string) => {
|
||||
const h = Math.floor(ms / 3.6e6), m = Math.floor(ms % 3.6e6 / 6e4),
|
||||
s = Math.floor(ms % 6e4 / 1000), x = ms % 1000;
|
||||
return `${pad(h)}:${pad(m)}:${pad(s)}${sep}${pad(x, 3)}`;
|
||||
};
|
||||
|
||||
export const toSrt = (pages: Page[]) => pages.map((p, i) =>
|
||||
`${i + 1}\n${stamp(p.startMs, ",")} --> ${stamp(p.endMs, ",")}\n${p.tokens.map(t => t.text).join(" ")}`
|
||||
).join("\n\n") + "\n";
|
||||
|
||||
export const toVtt = (pages: Page[]) => "WEBVTT\n\n" + pages.map(p =>
|
||||
`${stamp(p.startMs, ".")} --> ${stamp(p.endMs, ".")}\n${p.tokens.map(t => t.text).join(" ")}`
|
||||
).join("\n\n") + "\n";
|
||||
```
|
||||
|
||||
Use SRT for the broadest platform support; VTT when styling/positioning cues or serving on the web.
|
||||
|
||||
## 8. Per-platform safe areas (1080×1920, 9:16)
|
||||
|
||||
| Platform | Bottom keep-clear | Top keep-clear | Side keep-clear | Notes |
|
||||
|---|---|---|---|---|
|
||||
| TikTok | ~340px | ~120px | ~110px right rail | Captions, audio title, action buttons crowd the bottom-right |
|
||||
| Instagram Reels | ~280px | ~130px | ~60px | Username/CTA bar at bottom |
|
||||
| YouTube Shorts | ~240px | ~100px | ~120px right rail | Title + channel at bottom-left |
|
||||
| Facebook Reels | ~300px | ~130px | ~80px | Similar to Reels |
|
||||
|
||||
Safe rule across all: place caption baseline at ~62–70% of frame height, keep text within the center 80% width, and never let it enter the bottom ~15%.
|
||||
|
||||
## 9. Readable-type spec sheet
|
||||
|
||||
| Property | Recommended | Floor |
|
||||
|---|---|---|
|
||||
| Weight | 800 (ExtraBold) | 700 |
|
||||
| Size @1080p | 56–80px | 45px |
|
||||
| Stroke | 4–6px solid #000 | 2px |
|
||||
| Shadow | `0 4px 16px rgba(0,0,0,.55)` | soft 1px |
|
||||
| Active accent | one color (e.g. #FFE45E) or filled box | — |
|
||||
| Lines on screen | 1–2 | 2 max |
|
||||
| Words per page | 1–4 | 5 max |
|
||||
|
||||
Set `paint-order: stroke fill` so a thick stroke sits behind the glyph instead of eating it. Test on a bright frame and a busy frame; if it survives both, it ships.
|
||||
|
||||
## 10. Render
|
||||
|
||||
```bash
|
||||
npx remotion render src/index.ts Captions out/captions.mp4 \
|
||||
--props='{"pages": ..., "audio": "voiceover.wav"}'
|
||||
```
|
||||
|
||||
A 10-minute video with animated captions can take 30–60 min to render locally; render long-form in segments, or render on Remotion Lambda for parallel speed.
|
||||
|
||||
---
|
||||
## 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 auto-time captions to a narration track and one-click burn them in from a template — change the text/audio and re-export. → [iart.ai](https://iart.ai/?utm_source=github&utm_medium=reference&utm_campaign=tiktok-video-skills&utm_content=ref_footer&utm_term=caption-animation)
|
||||
@@ -0,0 +1,25 @@
|
||||
# Countdown Video
|
||||
|
||||
Make a countdown that ends exactly when it should. The whole craft is one idea: derive the remaining time from the frame (or a monotonic timestamp), then format and animate that number — never count down with a `setInterval`. Covers livestream "starting soon" screens, launch and flash-sale countdowns, and looping backgrounds. For creators who need a timer that lands on zero on the exact frame.
|
||||
|
||||
## When it activates
|
||||
|
||||
- "Make a countdown timer video" or "create a countdown animation."
|
||||
- "Build a stream starting soon countdown" or "do an event/launch/sale countdown."
|
||||
- "Animate a mm:ss or dd:hh:mm:ss timer."
|
||||
- "Add digit roll/flip transitions to a counter" or "loop a countdown background."
|
||||
|
||||
## Example prompts
|
||||
|
||||
- "Build a 10-minute 'be right back' livestream countdown."
|
||||
- "Make a dd:hh:mm:ss launch countdown to a fixed target date."
|
||||
- "Add flip transitions to an mm:ss timer that hits zero on the exact frame."
|
||||
|
||||
## What's inside
|
||||
|
||||
- `SKILL.md` — frame-accurate (drift-free) timers, time formatting, and a configurable duration prop.
|
||||
- `references/countdown-cookbook.md` — recipes for common countdown scenarios.
|
||||
- `references/digit-flip.md` — digit flip/roll transition techniques.
|
||||
|
||||
---
|
||||
Part of **[Short-Form Video Skills](../../)** · Built by **[iart.ai](https://iart.ai/?utm_source=github&utm_medium=readme&utm_campaign=tiktok-video-skills&utm_content=skill_footer&utm_term=countdown-video)** — the AI motion agent for editable, on-brand motion graphics.
|
||||
@@ -0,0 +1,152 @@
|
||||
---
|
||||
name: countdown-video
|
||||
description: This skill should be used when the user asks to "make a countdown timer video", "create a countdown animation", "build a stream starting soon countdown", "do an event/launch/sale countdown", "animate a mm:ss or dd:hh:mm:ss timer", "add digit roll/flip transitions to a counter", or "loop a countdown background". Covers frame-accurate (drift-free) timers, digit flip/roll motion, time formatting, and a configurable duration prop.
|
||||
version: 0.1.0
|
||||
---
|
||||
|
||||
# Countdown Video
|
||||
|
||||
Make a countdown that ends exactly when it should. The whole craft is one idea: derive the remaining time from the frame (or a monotonic timestamp), then format and animate that number — never count down with a `setInterval`. Covers livestream "starting soon" screens, launch/sale countdowns, and looping backgrounds.
|
||||
|
||||
## When to use
|
||||
|
||||
- "Starting soon" / "be right back" livestream screens with a 5–10 min timer.
|
||||
- Launch and flash-sale countdowns (dd:hh:mm:ss down to a target date; mm:ss for urgency).
|
||||
- Any animated counter where the number must land on zero on the exact frame.
|
||||
|
||||
## The one rule: drive the number from the clock, never a tick
|
||||
|
||||
A `setInterval(fn, 1000)` countdown **drifts** — the callback fires *at least* 1000 ms later, never exactly, and stacks up when the tab is throttled or a render frame is slow. Reports of ~1 second lost per minute are common. The fix is the same for rendered video and live web: compute remaining time as a pure function of an authoritative clock, so a late frame self-corrects on the next frame instead of accumulating error.
|
||||
|
||||
| Context | Authoritative clock | Remaining time |
|
||||
|---|---|---|
|
||||
| Remotion render | `useCurrentFrame()` | `total − frame/fps` |
|
||||
| Web (live page) | `performance.now()` or `Date.now()` | `targetMs − now` |
|
||||
| To a fixed date | `Date.now()` | `targetTimestamp − Date.now()` |
|
||||
|
||||
Never store remaining time in state and decrement it. Recompute it every frame.
|
||||
|
||||
## Frame-accurate countdown (Remotion → MP4)
|
||||
|
||||
`useCurrentFrame()` is deterministic: frame N is always rendered at exactly `N/fps` seconds. Subtract from the total and the timer is drift-free by construction.
|
||||
|
||||
```tsx
|
||||
import { useCurrentFrame, useVideoConfig } from "remotion";
|
||||
|
||||
export const Countdown: React.FC<{ durationInSeconds: number }> = ({
|
||||
durationInSeconds,
|
||||
}) => {
|
||||
const frame = useCurrentFrame();
|
||||
const { fps } = useVideoConfig();
|
||||
|
||||
// remaining seconds, clamped at 0 — ceil so "1" shows for its full second
|
||||
const elapsed = frame / fps;
|
||||
const remaining = Math.max(0, Math.ceil(durationInSeconds - elapsed));
|
||||
|
||||
return <div style={{ fontVariantNumeric: "tabular-nums" }}>{formatMMSS(remaining)}</div>;
|
||||
};
|
||||
```
|
||||
|
||||
`durationInSeconds` is a **prop**, not a constant — the same composition renders a 5-minute stream timer or a 30-second sale timer by changing one input. Set the composition's `durationInFrames` to `durationInSeconds * fps` so the video is exactly as long as the countdown.
|
||||
|
||||
## Web timer (live page, requestAnimationFrame)
|
||||
|
||||
For a live page, drive an rAF loop from `performance.now()` and only repaint when the displayed second changes (no work 60×/sec for a 1 Hz number):
|
||||
|
||||
```js
|
||||
const start = performance.now();
|
||||
let lastShown = -1;
|
||||
function tick(now) {
|
||||
const remaining = Math.max(0, Math.ceil(duration - (now - start) / 1000));
|
||||
if (remaining !== lastShown) { render(remaining); lastShown = remaining; }
|
||||
if (remaining > 0) requestAnimationFrame(tick);
|
||||
}
|
||||
requestAnimationFrame(tick);
|
||||
```
|
||||
|
||||
Counting down to a fixed date is the same idea with `Date.now()`: `Math.max(0, target - Date.now())`. See `references/countdown-cookbook.md` for the full date-target version with timezone handling.
|
||||
|
||||
## Time formatting
|
||||
|
||||
Break a remaining-seconds integer into fields with division + modulo, then zero-pad. Pick the format to fit the duration — never show `00d 00h 05m` when minutes is all that matters.
|
||||
|
||||
```js
|
||||
const pad = (n) => String(n).padStart(2, "0");
|
||||
const formatMMSS = (s) => `${pad(Math.floor(s / 60))}:${pad(s % 60)}`;
|
||||
const formatDHMS = (s) => {
|
||||
const d = Math.floor(s / 86400), h = Math.floor((s % 86400) / 3600);
|
||||
const m = Math.floor((s % 3600) / 60), sec = s % 60;
|
||||
return `${pad(d)}:${pad(h)}:${pad(m)}:${pad(sec)}`;
|
||||
};
|
||||
```
|
||||
|
||||
| Format | Use | Drop fields when |
|
||||
|---|---|---|
|
||||
| `mm:ss` | stream "starting soon", short timers (<1h) | — |
|
||||
| `hh:mm:ss` | flash sale, same-day event | hide `dd` while 0 |
|
||||
| `dd:hh:mm:ss` | launch / multi-day countdown | hide leading 0 units for cleaner read |
|
||||
|
||||
Always set `font-variant-numeric: tabular-nums` (or a monospace digit font) so digits keep equal width and the layout does not jitter as numbers change.
|
||||
|
||||
## Digit roll / flip transitions
|
||||
|
||||
A flat number swap reads as cheap; the rolling "odometer" look sells the countdown. Render each digit as a vertical strip 0–9 and translate it by `-digit × digitHeight`. Animate the *position*, not the text content, so the change is a glide, not a pop.
|
||||
|
||||
```css
|
||||
.reel { height: 1em; overflow: hidden; }
|
||||
.reel .col { transition: transform .45s cubic-bezier(.22,1,.36,1); }
|
||||
/* col holds stacked 0..9; shift by -value em */
|
||||
```
|
||||
|
||||
In Remotion, drive the strip offset off the frame instead of a CSS transition (so it is deterministic). The flip-card style (top half folds down over the bottom) and the per-digit reel are both detailed, with runnable components, in `references/digit-flip.md`.
|
||||
|
||||
## Looping background
|
||||
|
||||
Stream screens hold for minutes, so the background must loop seamlessly. Build motion on a cycle that divides evenly into the timeline (e.g. a gradient or particle drift whose period is `loopFrames`), and read it as `frame % loopFrames` so there is no visible seam at the wrap. Keep it low-contrast and slow — the number is the subject; the background is ambience. Recipes in `references/countdown-cookbook.md`.
|
||||
|
||||
## Output checklist
|
||||
|
||||
- Remaining time recomputed from `useCurrentFrame()` / `performance.now()` every frame — no `setInterval` decrement.
|
||||
- Timer hits `00:00` on the exact intended frame; `durationInFrames === durationInSeconds × fps`.
|
||||
- Duration is an input prop, not a hardcoded constant.
|
||||
- Digits use `tabular-nums`; layout does not shift as numbers change.
|
||||
- Format matches the span (mm:ss vs dd:hh:mm:ss); leading zero units dropped when distracting.
|
||||
- Background loop period divides the timeline evenly; no seam at the wrap.
|
||||
|
||||
## 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`.
|
||||
|
||||
The countdown ships as a Remotion composition (`<Composition>` + zod `schema` + `defaultProps`, `durationInSeconds` a prop) — the timer is a pure function of `useCurrentFrame()`, never `setInterval` / `Date.now()` / `Math.random()`. Set `durationInFrames = durationInSeconds * fps`. Deliverable = `out/*.mp4` + the project. 9:16 vertical (1080×1920) is the default.
|
||||
|
||||
**Verify loop — render stills → inspect → encode.** The whole point is frame-accuracy, so check the *digit value* at exact frames before encoding.
|
||||
|
||||
```bash
|
||||
# Stills at start / mid / end — WITH SHIPPED PROPS (the real duration you'll render)
|
||||
npx remotion still Countdown out/f-start.png --frame=0 --props='{"durationInSeconds":300}'
|
||||
npx remotion still Countdown out/f-mid.png --frame=N --props='{"durationInSeconds":300}'
|
||||
npx remotion still Countdown out/f-end.png --frame=L --props='{"durationInSeconds":300}' # L = durationInFrames-1
|
||||
|
||||
# Inspect each PNG — the digits must read EXACTLY the frame/fps math:
|
||||
# - at frame N, displayed = ceil(durationInSeconds - N/fps) (e.g. 300s @ 30fps, frame 4500 → 150s → "02:30")
|
||||
# - last frame reads 00:00 (or the end-state hold); no drift, no off-by-one second
|
||||
# - tabular-nums: layout does not jitter between frames
|
||||
# - 9:16 safe area: the timer + brand block sit clear of top ~12% and bottom ~20-35% UI and the right action rail
|
||||
|
||||
npx remotion render Countdown out/countdown.mp4 --props='{"durationInSeconds":300}' # encode once digits verify
|
||||
npx remotion render Countdown out/demo.gif --codec=gif # README proof clip
|
||||
```
|
||||
|
||||
Use `npx remotion compositions` to confirm `durationInFrames`/`fps`, then compute the frame for any second you want to check.
|
||||
|
||||
**Before you finish:**
|
||||
1. Stills render cleanly at frame 0, mid, and last — no errors.
|
||||
2. The digit value at frame N equals `ceil(durationInSeconds - N/fps)` exactly; last frame hits 00:00 on the intended frame (no drift / off-by-one).
|
||||
3. Timer + brand stay inside the 9:16 safe area at every checked frame.
|
||||
4. Frame-driven only — no `setInterval` / `Date.now()` / timers; `tabular-nums` so layout holds.
|
||||
5. Shipped `durationInSeconds` (not just `defaultProps`) renders correctly; MP4 encoded, GIF optional.
|
||||
|
||||
## Reference files
|
||||
|
||||
- `references/countdown-cookbook.md` — complete runnable Remotion `<Countdown>` (configurable duration, mm:ss / dd:hh:mm:ss, end-state hold), the count-down-to-a-fixed-date web component with timezone handling, a "starting soon" stream-screen layout (brand block + social handles + looping gradient background), and the seamless-loop background pattern.
|
||||
- `references/digit-flip.md` — two deterministic digit-animation components: the odometer reel (vertical 0–9 strip driven by frame) and the flip-card (top-half fold) effect, plus when each suits launch vs sale vs stream.
|
||||
@@ -0,0 +1,205 @@
|
||||
# Countdown Cookbook
|
||||
|
||||
Complete, runnable recipes. Every value is derived from an authoritative clock (frame or timestamp) so nothing drifts.
|
||||
|
||||
## 1. Configurable Remotion countdown (mm:ss + dd:hh:mm:ss)
|
||||
|
||||
A single composition that handles any duration and either format. Drop into `src/Countdown.tsx`.
|
||||
|
||||
```tsx
|
||||
import React from "react";
|
||||
import { useCurrentFrame, useVideoConfig, AbsoluteFill } from "remotion";
|
||||
|
||||
const pad = (n: number) => String(n).padStart(2, "0");
|
||||
|
||||
const formatTime = (totalSeconds: number, mode: "mm:ss" | "dd:hh:mm:ss") => {
|
||||
const s = Math.max(0, totalSeconds);
|
||||
if (mode === "mm:ss") {
|
||||
return `${pad(Math.floor(s / 60))}:${pad(s % 60)}`;
|
||||
}
|
||||
const d = Math.floor(s / 86400);
|
||||
const h = Math.floor((s % 86400) / 3600);
|
||||
const m = Math.floor((s % 3600) / 60);
|
||||
const sec = s % 60;
|
||||
// drop leading day field once it is zero, for a cleaner read
|
||||
return d > 0
|
||||
? `${pad(d)}d ${pad(h)}:${pad(m)}:${pad(sec)}`
|
||||
: `${pad(h)}:${pad(m)}:${pad(sec)}`;
|
||||
};
|
||||
|
||||
export type CountdownProps = {
|
||||
durationInSeconds: number;
|
||||
format?: "mm:ss" | "dd:hh:mm:ss";
|
||||
label?: string;
|
||||
};
|
||||
|
||||
export const Countdown: React.FC<CountdownProps> = ({
|
||||
durationInSeconds,
|
||||
format = "mm:ss",
|
||||
label = "",
|
||||
}) => {
|
||||
const frame = useCurrentFrame();
|
||||
const { fps } = useVideoConfig();
|
||||
|
||||
// ceil so the last whole second ("1") is shown for its full duration,
|
||||
// and the display reaches "0" exactly on the final frame.
|
||||
const remaining = Math.max(0, Math.ceil(durationInSeconds - frame / fps));
|
||||
const ended = remaining === 0;
|
||||
|
||||
return (
|
||||
<AbsoluteFill
|
||||
style={{
|
||||
justifyContent: "center",
|
||||
alignItems: "center",
|
||||
background: "#0b0d17",
|
||||
color: "#fff",
|
||||
fontFamily: "Inter, system-ui, sans-serif",
|
||||
}}
|
||||
>
|
||||
{label && (
|
||||
<div style={{ fontSize: 36, opacity: 0.7, marginBottom: 16, letterSpacing: 4 }}>
|
||||
{label.toUpperCase()}
|
||||
</div>
|
||||
)}
|
||||
<div
|
||||
style={{
|
||||
fontSize: 180,
|
||||
fontWeight: 800,
|
||||
fontVariantNumeric: "tabular-nums", // equal-width digits → no jitter
|
||||
lineHeight: 1,
|
||||
color: ended ? "#ff4d4d" : "#fff",
|
||||
}}
|
||||
>
|
||||
{ended ? formatTime(0, format) : formatTime(remaining, format)}
|
||||
</div>
|
||||
</AbsoluteFill>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
Register it so `durationInFrames` matches the countdown exactly — the video ends when the timer does:
|
||||
|
||||
```tsx
|
||||
import { Composition } from "remotion";
|
||||
import { Countdown } from "./Countdown";
|
||||
|
||||
const FPS = 30;
|
||||
const DURATION_SECONDS = 300; // 5-minute "starting soon" timer
|
||||
|
||||
export const RemotionRoot = () => (
|
||||
<Composition
|
||||
id="Countdown"
|
||||
component={Countdown}
|
||||
durationInFrames={DURATION_SECONDS * FPS}
|
||||
fps={FPS}
|
||||
width={1920}
|
||||
height={1080}
|
||||
defaultProps={{ durationInSeconds: DURATION_SECONDS, format: "mm:ss", label: "Starting soon" }}
|
||||
/>
|
||||
);
|
||||
```
|
||||
|
||||
Render any duration/format without touching code — duration is a prop:
|
||||
|
||||
```bash
|
||||
npx remotion render Countdown out/sale.mp4 \
|
||||
--props='{"durationInSeconds":86400,"format":"dd:hh:mm:ss","label":"Sale ends in"}'
|
||||
```
|
||||
|
||||
To hold a final state (e.g. "WE'RE LIVE") instead of ending on `00:00`, extend `durationInFrames` past the countdown and branch on `ended`.
|
||||
|
||||
## 2. Count down to a fixed date (live web component)
|
||||
|
||||
For a real-time page that targets a calendar moment. Drift-free because remaining time is `target − Date.now()` recomputed each frame, never a decrement.
|
||||
|
||||
```js
|
||||
// targetISO must include an offset, e.g. "2026-07-01T09:00:00-07:00",
|
||||
// so the deadline is unambiguous regardless of the viewer's timezone.
|
||||
function startCountdown(targetISO, el) {
|
||||
const target = new Date(targetISO).getTime();
|
||||
const pad = (n) => String(n).padStart(2, "0");
|
||||
let lastShown = -1;
|
||||
|
||||
function tick() {
|
||||
const remainingMs = Math.max(0, target - Date.now());
|
||||
const s = Math.floor(remainingMs / 1000);
|
||||
if (s !== lastShown) {
|
||||
const d = Math.floor(s / 86400);
|
||||
const h = Math.floor((s % 86400) / 3600);
|
||||
const m = Math.floor((s % 3600) / 60);
|
||||
el.textContent = `${pad(d)}:${pad(h)}:${pad(m)}:${pad(s % 60)}`;
|
||||
lastShown = s;
|
||||
}
|
||||
if (remainingMs > 0) requestAnimationFrame(tick);
|
||||
else el.textContent = "00:00:00:00"; // or swap to an "It's live" state
|
||||
}
|
||||
requestAnimationFrame(tick);
|
||||
}
|
||||
```
|
||||
|
||||
Timezone notes:
|
||||
- Bake the offset into the target string (`-07:00`, `Z`). A bare `"2026-07-01T09:00:00"` is parsed as the viewer's *local* time and every viewer sees a different deadline.
|
||||
- To show "ends 9am in *your* timezone everywhere," instead pick the wall-clock time per locale and let each viewer's `Date` resolve it — but that is a different deadline per region. Decide which you want before building.
|
||||
|
||||
## 3. "Starting soon" stream screen
|
||||
|
||||
Livestream lead-in screens hold 5–10 minutes: a clean brand block, social handles, and a calm looping background, with the timer as the focal point. Keep it low-clutter — chat and music carry the wait; the screen just signals "we're about to start."
|
||||
|
||||
```tsx
|
||||
import { AbsoluteFill, useCurrentFrame, useVideoConfig, interpolate } from "remotion";
|
||||
|
||||
export const StartingSoon: React.FC<{ durationInSeconds: number; handle: string; brand: string }> = ({
|
||||
durationInSeconds,
|
||||
handle,
|
||||
brand,
|
||||
}) => {
|
||||
const frame = useCurrentFrame();
|
||||
const { fps, durationInFrames } = useVideoConfig();
|
||||
const remaining = Math.max(0, Math.ceil(durationInSeconds - frame / fps));
|
||||
const pad = (n: number) => String(n).padStart(2, "0");
|
||||
|
||||
// seamless looping gradient: angle cycles over loopFrames with no seam
|
||||
const loopFrames = fps * 8;
|
||||
const angle = interpolate(frame % loopFrames, [0, loopFrames], [0, 360]);
|
||||
|
||||
return (
|
||||
<AbsoluteFill
|
||||
style={{
|
||||
background: `linear-gradient(${angle}deg, #141a3a, #0b0d17 60%)`,
|
||||
color: "#fff",
|
||||
fontFamily: "Inter, system-ui, sans-serif",
|
||||
justifyContent: "center",
|
||||
alignItems: "center",
|
||||
}}
|
||||
>
|
||||
<div style={{ fontSize: 64, fontWeight: 800, marginBottom: 8 }}>{brand}</div>
|
||||
<div style={{ fontSize: 28, opacity: 0.6, letterSpacing: 6, marginBottom: 40 }}>
|
||||
STARTING SOON
|
||||
</div>
|
||||
<div style={{ fontSize: 200, fontWeight: 800, fontVariantNumeric: "tabular-nums", lineHeight: 1 }}>
|
||||
{pad(Math.floor(remaining / 60))}:{pad(remaining % 60)}
|
||||
</div>
|
||||
<div style={{ position: "absolute", bottom: 60, fontSize: 30, opacity: 0.7 }}>{handle}</div>
|
||||
</AbsoluteFill>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
Export as MP4 and add it as a Media/Video source in OBS, or use a looping playout for a browser source. Common durations: 300s (5 min) or 600s (10 min) at 1920×1080.
|
||||
|
||||
## 4. Seamless looping background
|
||||
|
||||
Any motion whose period divides the timeline evenly wraps without a seam. Read animation phase as `frame % loopFrames` so the value at the wrap equals the value at frame 0.
|
||||
|
||||
```tsx
|
||||
const loopFrames = fps * 6; // one full cycle every 6 seconds
|
||||
const phase = (frame % loopFrames) / loopFrames; // 0 → 1, repeats
|
||||
const driftY = Math.sin(phase * Math.PI * 2) * 40; // returns to start each cycle
|
||||
```
|
||||
|
||||
Use sine/cosine (inherently periodic) or `interpolate(frame % loopFrames, [0, loopFrames], [a, a])` with matching start/end so there is no jump. Keep contrast low and motion slow — the number is the subject.
|
||||
|
||||
---
|
||||
## 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 render countdown videos from a template with a set time and brand — change the text/data and re-export. → [iart.ai](https://iart.ai/?utm_source=github&utm_medium=reference&utm_campaign=tiktok-video-skills&utm_content=ref_footer&utm_term=countdown-video)
|
||||
@@ -0,0 +1,146 @@
|
||||
# Digit Flip & Roll Transitions
|
||||
|
||||
Two ways to animate a digit changing. Both are driven by the frame (deterministic) so they render identically every time — no CSS transition clock that the renderer can disagree with.
|
||||
|
||||
Pick by tone:
|
||||
|
||||
| Effect | Feel | Best for |
|
||||
|---|---|---|
|
||||
| Odometer reel | smooth, continuous glide | launch countdowns, premium/minimal timers |
|
||||
| Flip card | mechanical "snap", split-flap board | sale urgency, retro/airport-board style |
|
||||
|
||||
## Shared idea
|
||||
|
||||
A single displayed digit is a stack of glyphs `0..9` laid out vertically. Showing digit `d` means translating the stack so glyph `d` sits in the window: `translateY(-d × digitHeight)`. Animate the *offset*, not the text, and you get a roll. The trick for a countdown is that the offset is continuous: between whole seconds the digit eases from its old value toward its new one.
|
||||
|
||||
## Odometer reel (Remotion, frame-driven)
|
||||
|
||||
```tsx
|
||||
import React from "react";
|
||||
import { useCurrentFrame, useVideoConfig, interpolate, Easing } from "remotion";
|
||||
|
||||
const DIGIT_H = 160; // px per glyph
|
||||
const ROLL_FRAMES = 12; // how long a single digit roll takes
|
||||
|
||||
// Animated single digit: rolls from `prev` to `value` over the last ROLL_FRAMES
|
||||
// of the current second.
|
||||
const Reel: React.FC<{ value: number; prev: number; secondProgress: number }> = ({
|
||||
value,
|
||||
prev,
|
||||
secondProgress,
|
||||
}) => {
|
||||
// secondProgress: 0→1 across the current whole second.
|
||||
// Start the roll near the end of the second so the number "settles" on change.
|
||||
const t = interpolate(secondProgress, [0.7, 1], [0, 1], {
|
||||
extrapolateLeft: "clamp",
|
||||
extrapolateRight: "clamp",
|
||||
easing: Easing.bezier(0.22, 1, 0.36, 1),
|
||||
});
|
||||
// continuous position between prev and value
|
||||
const shown = prev + (value - prev) * t;
|
||||
const offset = -shown * DIGIT_H;
|
||||
|
||||
return (
|
||||
<div style={{ height: DIGIT_H, width: 110, overflow: "hidden", position: "relative" }}>
|
||||
<div style={{ transform: `translateY(${offset}px)` }}>
|
||||
{[0, 1, 2, 3, 4, 5, 6, 7, 8, 9].map((n) => (
|
||||
<div
|
||||
key={n}
|
||||
style={{
|
||||
height: DIGIT_H,
|
||||
lineHeight: `${DIGIT_H}px`,
|
||||
textAlign: "center",
|
||||
fontSize: 140,
|
||||
fontWeight: 800,
|
||||
fontVariantNumeric: "tabular-nums",
|
||||
}}
|
||||
>
|
||||
{n}
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
// Renders an mm:ss reel where each digit rolls.
|
||||
export const ReelClock: React.FC<{ durationInSeconds: number }> = ({ durationInSeconds }) => {
|
||||
const frame = useCurrentFrame();
|
||||
const { fps } = useVideoConfig();
|
||||
|
||||
const elapsed = frame / fps;
|
||||
const remaining = Math.max(0, Math.ceil(durationInSeconds - elapsed));
|
||||
const prevRemaining = Math.max(0, remaining + 1); // value one second ago
|
||||
const secondProgress = elapsed % 1; // 0→1 within the current second
|
||||
|
||||
const digits = (s: number) =>
|
||||
[Math.floor(s / 600) % 10, Math.floor(s / 60) % 10, Math.floor(s / 10) % 10, s % 10];
|
||||
|
||||
const cur = digits(remaining);
|
||||
const prev = digits(prevRemaining);
|
||||
|
||||
return (
|
||||
<div style={{ display: "flex", gap: 8, color: "#fff", background: "#0b0d17", padding: 40 }}>
|
||||
{cur.map((d, i) => (
|
||||
<React.Fragment key={i}>
|
||||
{i === 2 && <div style={{ fontSize: 140, fontWeight: 800 }}>:</div>}
|
||||
<Reel value={d} prev={prev[i]} secondProgress={secondProgress} />
|
||||
</React.Fragment>
|
||||
))}
|
||||
</div>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
Notes:
|
||||
- Each digit only rolls when it actually changes; a digit whose `prev === value` sits still because `shown` stays constant.
|
||||
- A `9 → 0` rollover rolls *backward* through the strip (the cheap-looking part). To make tens/units roll the natural way on a carry, render an extra `0` glyph below the `9` and clamp — covered as an exercise; for most timers the backward roll at the tens boundary is unnoticeable at speed.
|
||||
- `ROLL_FRAMES` is unused above because the roll is tied to `secondProgress`; expose it instead if a fixed-length roll is preferred.
|
||||
|
||||
## Flip card (split-flap)
|
||||
|
||||
The top half of the old digit folds down over a static bottom half, revealing the new digit. Pure CSS keyframe version — fine for a live web page; for Remotion, drive the `rotateX` off `secondProgress` the same way as the reel so it stays deterministic.
|
||||
|
||||
```css
|
||||
.flip { position: relative; width: 110px; height: 160px; perspective: 600px; }
|
||||
.flip .card {
|
||||
position: absolute; inset: 0;
|
||||
display: flex; align-items: center; justify-content: center;
|
||||
font-size: 140px; font-weight: 800; font-variant-numeric: tabular-nums;
|
||||
backface-visibility: hidden;
|
||||
}
|
||||
.flip .top { clip-path: inset(0 0 50% 0); transform-origin: bottom; }
|
||||
.flip .bottom { clip-path: inset(50% 0 0 0); }
|
||||
/* on change, animate the leaf folding down */
|
||||
.flip .leaf {
|
||||
position: absolute; inset: 0; transform-origin: bottom;
|
||||
animation: fold .45s cubic-bezier(.36,0,.66,-0.2) forwards;
|
||||
}
|
||||
@keyframes fold {
|
||||
0% { transform: rotateX(0deg); }
|
||||
100% { transform: rotateX(-90deg); }
|
||||
}
|
||||
```
|
||||
|
||||
```js
|
||||
// swap the digit and replay the fold whenever the value changes
|
||||
function setFlip(el, newDigit) {
|
||||
if (el.dataset.v === String(newDigit)) return; // no change → no flip
|
||||
el.dataset.v = String(newDigit);
|
||||
el.querySelector(".top").textContent = newDigit;
|
||||
el.querySelector(".bottom").textContent = newDigit;
|
||||
const leaf = el.querySelector(".leaf");
|
||||
leaf.textContent = newDigit;
|
||||
leaf.style.animation = "none";
|
||||
void leaf.offsetWidth; // reflow → restart the animation
|
||||
leaf.style.animation = "";
|
||||
}
|
||||
```
|
||||
|
||||
Drive `setFlip` from the same `requestAnimationFrame` + `performance.now()` loop in the cookbook (only call it when the displayed second changes), so the flips fire on real time and never drift.
|
||||
|
||||
## Choosing
|
||||
|
||||
- **Launch / premium:** odometer reel, slow ease, large tabular digits, muted palette.
|
||||
- **Flash sale:** flip card for the mechanical urgency, or reel with a faster roll and a hot accent color on `mm:ss`.
|
||||
- **Stream "starting soon":** either works, but keep it calm — a single reel on `mm:ss` reads better than a busy split-flap for a 5–10 minute hold.
|
||||
@@ -0,0 +1,24 @@
|
||||
# Lower Thirds
|
||||
|
||||
Build a clean, branded lower third — the name/role caption that lives in the bottom band of the frame — that animates in, holds long enough to read, and exits without stealing the shot. The craft is restraint: a crisp reveal, a strong type hierarchy, correct safe-area placement, and one template that drives a whole roster of speakers. For creators producing interviews, panels, podcasts, and broadcast-style titles.
|
||||
|
||||
## When it activates
|
||||
|
||||
- "Make an animated lower third" or "add lower thirds."
|
||||
- "Create a name tag/name lower third" or "do a speaker name overlay."
|
||||
- "Build broadcast titles" or "animate a title/name/role caption."
|
||||
- "Template lower thirds across a list of names."
|
||||
|
||||
## Example prompts
|
||||
|
||||
- "Add a lower third with the speaker's name and role, branded to my colors."
|
||||
- "Build a staggered slide-in name plate for a podcast guest."
|
||||
- "Template one lower-third design across a roster of 12 panelists."
|
||||
|
||||
## What's inside
|
||||
|
||||
- `SKILL.md` — enter/exit animation, in/out timing and dwell, safe-area conventions, and brand styling.
|
||||
- `references/lower-third-component.md` — a reusable lower-third component.
|
||||
|
||||
---
|
||||
Part of **[Short-Form Video Skills](../../)** · Built by **[iart.ai](https://iart.ai/?utm_source=github&utm_medium=readme&utm_campaign=tiktok-video-skills&utm_content=skill_footer&utm_term=lower-thirds)** — the AI motion agent for editable, on-brand motion graphics.
|
||||
@@ -0,0 +1,146 @@
|
||||
---
|
||||
name: lower-thirds
|
||||
description: This skill should be used when the user asks to "make an animated lower third", "add lower thirds", "create a name tag/name lower third", "build broadcast titles", "animate a title/name/role caption", "do a speaker name overlay", or "template lower thirds across a list of names". Covers enter/exit animation (slide/wipe/mask reveal), in/out timing & dwell, safe-area & broadcast conventions, name-vs-role type hierarchy, brand styling, and rendering one design across many names.
|
||||
version: 0.1.0
|
||||
---
|
||||
|
||||
# Lower Thirds
|
||||
|
||||
Build a clean, branded lower third — the name/role caption that lives in the bottom band of the frame — that animates in, holds long enough to read, and exits without stealing the shot. The craft is restraint: a crisp reveal, a strong type hierarchy, correct safe-area placement, and one template that drives a whole roster of speakers.
|
||||
|
||||
## When to use
|
||||
|
||||
- Speaker/interview name tags, panel rosters, talking-head captions.
|
||||
- Broadcast-style titles, news straps, podcast/webinar name plates.
|
||||
- Templating one design across a list of names/titles → many clips (the payoff).
|
||||
|
||||
## Anatomy
|
||||
|
||||
A lower third is two text lines plus a graphic bed, placed in the lower band:
|
||||
|
||||
| Element | Role | Type treatment |
|
||||
|---|---|---|
|
||||
| **Name** (primary) | Who | Largest, heaviest, tightest tracking |
|
||||
| **Role/title** (secondary) | What/where | ~45–60% of name size, lighter weight, often a brand accent color |
|
||||
| **Bar / panel / accent** | Reads against any background | Solid or 70–85% opacity; an accent rule ties to brand |
|
||||
|
||||
Keep it to two lines. A name line + role line is the whole job — extra lines erode the hierarchy and crowd the safe area.
|
||||
|
||||
## Three rules that prevent cheap-looking titles
|
||||
|
||||
1. **Never hard-cut a title on or off.** A bare appear/disappear reads as a mistake. Even a 12-frame fade or slide makes it feel produced.
|
||||
2. **Stagger, don't slam.** Animate the bar first, then the name, then the role, each offset by 3–6 frames. Everything arriving at once feels flat; a short cascade feels designed.
|
||||
3. **Hold long enough to read twice.** Roughly 3–5s on screen (read it aloud twice). Too short and it's missed; too long and it nags. Animate in/out, never mid-segment.
|
||||
|
||||
## Enter & exit animations
|
||||
|
||||
Pick one motion language and reuse it. The most reliable, premium-reading reveals:
|
||||
|
||||
| Reveal | Feel | How |
|
||||
|---|---|---|
|
||||
| **Slide + fade** | Clean, default | Translate in ~24–40px while fading; ease-out on enter |
|
||||
| **Wipe bar** | Broadcast | A bar scales/sweeps in (`scaleX`/clip), text fades behind it |
|
||||
| **Mask reveal** | Premium | Clip text to a moving rectangle so letters "wipe on" |
|
||||
|
||||
Use asymmetric easing: a snappy `ease-out` (`cubic-bezier(.22,1,.36,1)`) on enter, a quicker `ease-in` on exit. Exit faster than you entered (~⅔ the duration) so the title gets out of the way.
|
||||
|
||||
```css
|
||||
/* Mask reveal: text wipes on left→right, no plugin needed */
|
||||
.lt-name { clip-path: inset(0 100% 0 0); animation: wipe .5s cubic-bezier(.22,1,.36,1) forwards; }
|
||||
@keyframes wipe { to { clip-path: inset(0 0 0 0); } }
|
||||
```
|
||||
|
||||
## In/out timing & dwell
|
||||
|
||||
Think in three phases. Budget frames, not vibes (at 30fps):
|
||||
|
||||
| Phase | Budget | Note |
|
||||
|---|---|---|
|
||||
| Enter | 12–18f (0.4–0.6s) | Staggered: bar → name → role |
|
||||
| Hold | 90–150f (3–5s) | The readable dwell; scale with line length |
|
||||
| Exit | 8–12f (0.27–0.4s) | Faster than enter |
|
||||
|
||||
In code, drive every state from the current frame (or a paused timeline), not wall-clock time — a video renderer demands deterministic frames. Express enter/hold/exit as a single progress curve so the same component works live in a browser and frame-by-frame in a renderer.
|
||||
|
||||
## Safe area & broadcast conventions
|
||||
|
||||
The lower third must survive every screen and platform UI. Compose inside the **title-safe area** (inner ~90% / margin 5%) and respect platform chrome:
|
||||
|
||||
| Frame | Anchor | Avoid |
|
||||
|---|---|---|
|
||||
| 16:9 (1920×1080) | Left edge at ~5% margin; baseline ~80–85% down | Outer 5% (title-safe), action-safe outer 10% |
|
||||
| 9:16 (1080×1920) | Same left margin; **lift the band up** | Bottom ~18% (captions/UI), top ~12% |
|
||||
| 1:1 (1080×1080) | Lower band, center-left | Outer 5% |
|
||||
|
||||
Anchor to the **left** and grow rightward so names of different lengths stay pinned and never re-center awkwardly. Keep the role line within the same left margin as the name. For 9:16, do not park the title at the very bottom — platform captions and buttons sit there.
|
||||
|
||||
## Type hierarchy & brand styling
|
||||
|
||||
Hierarchy is the whole design. Make the name unmistakably dominant:
|
||||
|
||||
- **Size contrast** ≥ 1.6× (name vs role). If unsure, push the name bigger, not the role.
|
||||
- **Weight + color**: name in bold/near-white; role in a lighter weight and a **brand accent** color (one accent, used consistently).
|
||||
- **Contrast for legibility**: text rides over unknown footage. Use a solid/semi-opaque bar, a subtle scrim, or a soft text shadow so it reads over both bright and dark plates.
|
||||
- **Brand lock**: pin font, accent color, bar style, and corner radius in one theme object so every title across a series matches.
|
||||
|
||||
## Templating one design across a list
|
||||
|
||||
The reason to build this in code: change the text/data, re-export — no re-animating. Make name/role/theme **props**, never hardcoded, then map a roster to instances.
|
||||
|
||||
```jsx
|
||||
const ROSTER = [
|
||||
{ name: "Ada Lovelace", role: "Founder, Analytical Engines" },
|
||||
{ name: "Grace Hopper", role: "Rear Admiral, US Navy" },
|
||||
{ name: "Alan Turing", role: "Mathematician" },
|
||||
];
|
||||
// One <LowerThird> design; map the list → many instances (sequence them in a renderer)
|
||||
{ROSTER.map((p, i) => <LowerThird key={p.name} {...p} theme={BRAND} startFrame={i * 150} />)}
|
||||
```
|
||||
|
||||
In a renderer, make the roster an input prop and render once per row (`--props`) to emit one branded clip per person — same animation, same brand, only the text changes. See `references/lower-third-component.md` for the full runnable component and batch script.
|
||||
|
||||
## Output checklist
|
||||
|
||||
- Two lines only: dominant name, secondary role (≥1.6× size contrast).
|
||||
- Animated in and out (no hard cut); enter staggered bar→name→role; exit faster.
|
||||
- Hold 3–5s (readable twice); motion only at the ends, never mid-segment.
|
||||
- Left-anchored inside title-safe; 9:16 band lifted above the bottom-18% UI zone.
|
||||
- Text legible over any plate (bar/scrim/shadow); one brand accent throughout.
|
||||
- Name/role/theme are props — one template renders the whole roster.
|
||||
|
||||
## 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`.
|
||||
|
||||
The lower third ships as a Remotion composition (`<Composition>` + zod `schema` + `defaultProps`, name/role/theme as props) — enter/dwell/exit all driven by `useCurrentFrame()`, never `Date.now()` / `Math.random()` / timers. Deliverable = `out/*.mp4` + the project (re-render per roster row). 9:16 vertical (1080×1920) is the default.
|
||||
|
||||
**Verify loop — render stills → inspect → encode.** Sample the three phases so you catch a stagger or safe-area bug before encoding (or batching the whole roster).
|
||||
|
||||
```bash
|
||||
# Stills at enter / dwell / exit — WITH SHIPPED PROPS (a real roster row, not defaults)
|
||||
npx remotion still LowerThird out/f-enter.png --frame=10 --props='{"name":"Ada Lovelace","role":"Founder, Analytical Engines"}'
|
||||
npx remotion still LowerThird out/f-dwell.png --frame=75 --props='{"name":"Ada Lovelace","role":"Founder, Analytical Engines"}'
|
||||
npx remotion still LowerThird out/f-exit.png --frame=N --props='{"name":"Ada Lovelace","role":"Founder, Analytical Engines"}'
|
||||
|
||||
# Inspect each PNG — focus the DWELL frame (fully on screen):
|
||||
# - hierarchy holds: name dominant (>=1.6x role), role in brand accent; both fully revealed, not mid-wipe
|
||||
# - brand lock: font, accent color, bar/scrim correct; legible over the plate
|
||||
# - 9:16 safe area: band LIFTED above the bottom ~20-35% UI zone, clear of top ~12% and the right action rail; left-anchored inside title-safe
|
||||
# - enter/exit frames show partial reveal (animation actually runs), not a hard cut
|
||||
|
||||
npx remotion render LowerThird out/lower-third.mp4 --props='{"name":"Ada Lovelace","role":"Founder, Analytical Engines"}'
|
||||
npx remotion render LowerThird out/demo.gif --codec=gif # README proof clip
|
||||
```
|
||||
|
||||
**Batch roster**: verify ONE row via stills *before* rendering all names — catch a layout/overflow bug once, not N times. Use `npx remotion compositions` for `durationInFrames`/`fps` to pick the dwell + exit frames.
|
||||
|
||||
**Before you finish:**
|
||||
1. Stills render cleanly at enter, dwell, and exit — no missing font/brand assets.
|
||||
2. At the dwell frame: name dominant over role, brand accent + bar correct, fully (not partly) revealed.
|
||||
3. The band is inside the 9:16 safe area — lifted above the bottom UI zone, clear of top and right rail — at every checked frame.
|
||||
4. Frame-driven only — no `Date.now()` / `Math.random()` / timers; enter/exit show motion, never a hard cut.
|
||||
5. A real roster row (not `defaultProps`) renders correctly; MP4 encoded, GIF optional.
|
||||
|
||||
## Reference files
|
||||
|
||||
- `references/lower-third-component.md` — a complete runnable lower-third: a Remotion component with staggered spring enter, readable hold, and faster exit driven purely by frame; a typed theme object for brand lock; the list→many-instances sequencing pattern; a per-row batch render script; plus a dependency-free CSS/HTML version of the same design with mask-reveal and wipe-bar variants.
|
||||
@@ -0,0 +1,268 @@
|
||||
# Lower-Third Component — runnable code
|
||||
|
||||
A complete, production-grade lower third you can drop in. Two paths:
|
||||
|
||||
1. **Remotion** (frame-deterministic, renders to MP4, batches over a roster).
|
||||
2. **CSS/HTML** (no dependencies, for the web or a quick preview) with mask-reveal and wipe-bar variants.
|
||||
|
||||
Both share the same design language: a left-anchored bar, a dominant name, a brand-accent role line, a staggered enter, a readable hold, and a faster exit.
|
||||
|
||||
---
|
||||
|
||||
## 1. Remotion component (props-driven, frame-deterministic)
|
||||
|
||||
The animation is a pure function of `frame`, so it renders identically every time and stays in sync with the renderer. Enter staggers the bar, name, then role; exit is computed from the end of the clip so the title leaves faster than it arrived.
|
||||
|
||||
```tsx
|
||||
// LowerThird.tsx
|
||||
import {
|
||||
AbsoluteFill, Sequence, interpolate, spring,
|
||||
useCurrentFrame, useVideoConfig,
|
||||
} from "remotion";
|
||||
|
||||
// --- Brand lock: change once, every title matches -------------------------
|
||||
export type Theme = {
|
||||
font: string;
|
||||
bar: string; // panel/bar color
|
||||
name: string; // primary text color
|
||||
role: string; // accent color for the role line
|
||||
radius: number;
|
||||
marginPct: number; // left/safe margin as % of width
|
||||
};
|
||||
export const BRAND: Theme = {
|
||||
font: "Inter, system-ui, sans-serif",
|
||||
bar: "rgba(12,14,22,0.86)",
|
||||
name: "#FFFFFF",
|
||||
role: "#6EE7F0", // single brand accent
|
||||
radius: 10,
|
||||
marginPct: 5,
|
||||
};
|
||||
|
||||
export type LowerThirdProps = {
|
||||
name: string;
|
||||
role: string;
|
||||
theme?: Theme;
|
||||
holdSeconds?: number; // readable dwell, default 4s
|
||||
};
|
||||
|
||||
// Staggered enter via spring; exit via a quick fade/slide near the end.
|
||||
const useEnterExit = (delayFrames: number, holdSeconds: number) => {
|
||||
const frame = useCurrentFrame();
|
||||
const { fps, durationInFrames } = useVideoConfig();
|
||||
|
||||
// ENTER: spring 0→1, offset by delayFrames (the cascade)
|
||||
const enter = spring({
|
||||
frame: frame - delayFrames,
|
||||
fps,
|
||||
config: { damping: 200, stiffness: 180, mass: 0.6 },
|
||||
});
|
||||
|
||||
// EXIT: faster than enter — last 10 frames of the clip
|
||||
const exitStart = durationInFrames - 10;
|
||||
const exit = interpolate(frame, [exitStart, durationInFrames], [1, 0], {
|
||||
extrapolateLeft: "clamp",
|
||||
extrapolateRight: "clamp",
|
||||
});
|
||||
|
||||
const opacity = enter * exit;
|
||||
const x = interpolate(enter, [0, 1], [-32, 0]); // slide in from left
|
||||
return { opacity, x };
|
||||
};
|
||||
|
||||
const Line: React.FC<{
|
||||
delay: number; holdSeconds: number; children: React.ReactNode;
|
||||
size: number; weight: number; color: string; tracking?: number;
|
||||
}> = ({ delay, holdSeconds, children, size, weight, color, tracking = 0 }) => {
|
||||
const { opacity, x } = useEnterExit(delay, holdSeconds);
|
||||
return (
|
||||
<div style={{
|
||||
opacity,
|
||||
transform: `translateX(${x}px)`,
|
||||
fontSize: size, fontWeight: weight, color,
|
||||
letterSpacing: tracking, lineHeight: 1.15, whiteSpace: "nowrap",
|
||||
}}>
|
||||
{children}
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
export const LowerThird: React.FC<LowerThirdProps> = ({
|
||||
name, role, theme = BRAND, holdSeconds = 4,
|
||||
}) => {
|
||||
const { width, height } = useVideoConfig();
|
||||
const bar = useEnterExit(0, holdSeconds); // bar leads the cascade
|
||||
|
||||
const left = (width * theme.marginPct) / 100;
|
||||
const baseline = height * 0.80; // sit ~80% down, inside title-safe
|
||||
|
||||
return (
|
||||
<AbsoluteFill style={{ fontFamily: theme.font }}>
|
||||
<div style={{
|
||||
position: "absolute", left, top: baseline,
|
||||
opacity: bar.opacity,
|
||||
transform: `translateX(${bar.x}px)`,
|
||||
}}>
|
||||
{/* panel behind text guarantees legibility over any plate */}
|
||||
<div style={{
|
||||
background: theme.bar, borderRadius: theme.radius,
|
||||
padding: "14px 22px 16px",
|
||||
borderLeft: `4px solid ${theme.role}`, // accent rule ties to brand
|
||||
backdropFilter: "blur(6px)",
|
||||
}}>
|
||||
<Line delay={4} holdSeconds={holdSeconds} size={46} weight={800} color={theme.name} tracking={-0.5}>
|
||||
{name}
|
||||
</Line>
|
||||
<Line delay={8} holdSeconds={holdSeconds} size={26} weight={500} color={theme.role}>
|
||||
{role}
|
||||
</Line>
|
||||
</div>
|
||||
</div>
|
||||
</AbsoluteFill>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
Why each choice matters:
|
||||
- **`spring` per line, offset by `delay`** gives the bar→name→role cascade. Same offsets everywhere keep titles consistent.
|
||||
- **Exit derived from `durationInFrames`** means any clip length exits cleanly without per-instance tuning, and it's quicker than the enter (10f vs the spring's settle).
|
||||
- **`whiteSpace: nowrap` + left anchor** keeps long and short names pinned to the same edge — no awkward re-centering across a roster.
|
||||
- **`borderLeft` accent + semi-opaque panel** is the brand tie plus the legibility guarantee over unknown footage.
|
||||
|
||||
### Roster → many instances (one design, a whole panel)
|
||||
|
||||
Sequence the same component down a list. Each person gets a slot; only the text changes.
|
||||
|
||||
```tsx
|
||||
// Roster.tsx
|
||||
import { Series } from "remotion";
|
||||
import { LowerThird, BRAND } from "./LowerThird";
|
||||
|
||||
const ROSTER = [
|
||||
{ name: "Ada Lovelace", role: "Founder, Analytical Engines" },
|
||||
{ name: "Grace Hopper", role: "Rear Admiral, US Navy" },
|
||||
{ name: "Alan Turing", role: "Mathematician" },
|
||||
];
|
||||
|
||||
export const Roster: React.FC = () => (
|
||||
<Series>
|
||||
{ROSTER.map((p) => (
|
||||
<Series.Sequence key={p.name} durationInFrames={150 /* ~5s @30fps */}>
|
||||
<LowerThird name={p.name} role={p.role} theme={BRAND} />
|
||||
</Series.Sequence>
|
||||
))}
|
||||
</Series>
|
||||
);
|
||||
```
|
||||
|
||||
### Batch: one branded clip per person
|
||||
|
||||
Make the roster an input prop and render once per row, so each speaker becomes a standalone overlay clip — identical animation and brand, only the text differs.
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# render one transparent-friendly lower-third clip per person in roster.json
|
||||
# roster.json: [{"name":"Ada Lovelace","role":"Founder, Analytical Engines"}, ...]
|
||||
set -euo pipefail
|
||||
mkdir -p out
|
||||
jq -c '.[]' roster.json | while read -r row; do
|
||||
slug=$(echo "$row" | jq -r '.name' | tr '[:upper:] ' '[:lower:]-')
|
||||
npx remotion render LowerThird "out/${slug}.mp4" --props="$row"
|
||||
done
|
||||
```
|
||||
|
||||
For overlay-ready output with transparency, render the `LowerThird` composition (transparent background) to a codec that keeps alpha, e.g. `--codec=prores --prores-profile=4444`, or `--image-format=png` for a PNG sequence.
|
||||
|
||||
---
|
||||
|
||||
## 2. CSS / HTML version (no dependencies)
|
||||
|
||||
The same design without a framework — for the web, OBS browser sources, or a fast look-test. Includes both a **slide+fade** default and a **mask-reveal** name, plus a **wipe-bar** variant.
|
||||
|
||||
```html
|
||||
<div class="lt" style="--accent:#6EE7F0">
|
||||
<div class="lt-bar">
|
||||
<div class="lt-name">Ada Lovelace</div>
|
||||
<div class="lt-role">Founder, Analytical Engines</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<style>
|
||||
:root { font-family: Inter, system-ui, sans-serif; }
|
||||
|
||||
.lt {
|
||||
position: absolute; left: 5%; top: 80%; /* title-safe, left-anchored */
|
||||
}
|
||||
.lt-bar {
|
||||
display: inline-block;
|
||||
background: rgba(12,14,22,0.86);
|
||||
backdrop-filter: blur(6px);
|
||||
border-left: 4px solid var(--accent);
|
||||
border-radius: 10px;
|
||||
padding: 14px 22px 16px;
|
||||
/* bar leads the cascade: slide + fade in, then a faster fade out */
|
||||
animation: lt-in .5s cubic-bezier(.22,1,.36,1) both,
|
||||
lt-out .3s ease-in 4.5s forwards; /* hold ~4s, exit faster */
|
||||
}
|
||||
.lt-name {
|
||||
font-size: 46px; font-weight: 800; color: #fff; letter-spacing: -.5px;
|
||||
line-height: 1.15; white-space: nowrap;
|
||||
/* MASK REVEAL: letters wipe on left→right, staggered after the bar */
|
||||
clip-path: inset(0 100% 0 0);
|
||||
animation: lt-wipe .5s cubic-bezier(.22,1,.36,1) .12s forwards;
|
||||
}
|
||||
.lt-role {
|
||||
font-size: 26px; font-weight: 500; color: var(--accent);
|
||||
line-height: 1.15; white-space: nowrap;
|
||||
opacity: 0;
|
||||
animation: lt-fade .4s ease-out .22s forwards; /* role arrives last */
|
||||
}
|
||||
|
||||
@keyframes lt-in { from { opacity: 0; transform: translateX(-32px); }
|
||||
to { opacity: 1; transform: none; } }
|
||||
@keyframes lt-out { to { opacity: 0; transform: translateX(-16px); } }
|
||||
@keyframes lt-wipe { to { clip-path: inset(0 0 0 0); } }
|
||||
@keyframes lt-fade { to { opacity: 1; } }
|
||||
|
||||
/* Mobile/9:16: lift the band above the bottom UI/caption zone */
|
||||
@media (max-aspect-ratio: 1/1) { .lt { top: 70%; } }
|
||||
</style>
|
||||
```
|
||||
|
||||
### Wipe-bar variant (broadcast feel)
|
||||
|
||||
Swap the bar animation so a colored bar sweeps in and the text rides behind it:
|
||||
|
||||
```css
|
||||
.lt-bar.wipe {
|
||||
position: relative; overflow: hidden;
|
||||
animation: lt-in .45s cubic-bezier(.22,1,.36,1) both,
|
||||
lt-out .3s ease-in 4.5s forwards;
|
||||
}
|
||||
.lt-bar.wipe::before {
|
||||
content: ""; position: absolute; inset: 0;
|
||||
background: var(--accent);
|
||||
transform-origin: left;
|
||||
animation: lt-sweep .55s cubic-bezier(.76,0,.24,1) both; /* sweep across, then reveal */
|
||||
}
|
||||
@keyframes lt-sweep { 0% { transform: scaleX(0); } 60% { transform: scaleX(1); }
|
||||
100% { transform: scaleX(0); transform-origin: right; } }
|
||||
```
|
||||
|
||||
The CSS clock (`animation`) is fine for live/web playback. For a deterministic MP4, prefer the Remotion path above — a frame renderer and CSS timers disagree, which causes flicker or desync at export.
|
||||
|
||||
---
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Need | Knob |
|
||||
|---|---|
|
||||
| Slower/faster reveal | enter duration 12–18f / `.5s` |
|
||||
| Longer dwell | `holdSeconds` / the `4.5s` exit delay |
|
||||
| Bigger name dominance | name `fontSize` (keep ≥1.6× the role) |
|
||||
| Rebrand everything | the `BRAND` theme object / `--accent` |
|
||||
| 9:16 placement | `baseline 0.80→0.70` / the media query |
|
||||
|
||||
---
|
||||
## 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 generate branded lower-thirds from a list of names/titles, one-click — change the text/data and re-export. → [iart.ai](https://iart.ai/?utm_source=github&utm_medium=reference&utm_campaign=tiktok-video-skills&utm_content=ref_footer&utm_term=lower-thirds)
|
||||
@@ -1,315 +0,0 @@
|
||||
---
|
||||
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
|
||||
@@ -1,93 +0,0 @@
|
||||
# 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%)
|
||||
@@ -1,83 +0,0 @@
|
||||
# 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
|
||||
@@ -1,53 +0,0 @@
|
||||
# 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
|
||||
@@ -1,91 +0,0 @@
|
||||
# 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? |
|
||||
@@ -1,102 +0,0 @@
|
||||
# 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 |
|
||||
@@ -1,71 +0,0 @@
|
||||
# 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) |
|
||||
@@ -1,89 +0,0 @@
|
||||
# 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
|
||||
@@ -1,62 +0,0 @@
|
||||
# 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
|
||||
@@ -1,81 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,82 +0,0 @@
|
||||
# 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)
|
||||
@@ -1,69 +0,0 @@
|
||||
# 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 |
|
||||
@@ -1,96 +0,0 @@
|
||||
# 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
|
||||
@@ -1,95 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,67 +0,0 @@
|
||||
# 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
|
||||
@@ -1,106 +0,0 @@
|
||||
# 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% |
|
||||
@@ -1,73 +0,0 @@
|
||||
# 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
|
||||
@@ -0,0 +1,24 @@
|
||||
# Short-Form Video
|
||||
|
||||
Engineer a 9:16 video that survives the swipe. Short-form is a retention machine, not a small launch film: a hook that earns the first second, pattern interrupts that reset attention every few seconds, and often a loop that buys watch-time past 100%. The craft is timing, not polish. For creators making Reels, TikToks, and YouTube Shorts (7–60s, vertical).
|
||||
|
||||
## When it activates
|
||||
|
||||
- "Make a Reels/TikTok/YouTube Shorts video" or "build a short-form video template."
|
||||
- "Write a hook for a short" or "fix the first 3 seconds."
|
||||
- "Edit for retention," "add pattern interrupts," or "pace cuts for a vertical video."
|
||||
- "Make a video loop" or "set up 9:16 safe areas."
|
||||
|
||||
## Example prompts
|
||||
|
||||
- "Build a reusable 9:16 short-form template — one design, many topics."
|
||||
- "Fix the drop-off in this Reel: tighten pacing and add pattern interrupts."
|
||||
- "Write three hook options for a 30-second educational short."
|
||||
|
||||
## What's inside
|
||||
|
||||
- `SKILL.md` — the retention arc, hook grammar, and pacing rules.
|
||||
- `references/retention-pacing.md` — deeper guidance on retention editing and pacing.
|
||||
|
||||
---
|
||||
Part of **[Short-Form Video Skills](../../)** · Built by **[iart.ai](https://iart.ai/?utm_source=github&utm_medium=readme&utm_campaign=tiktok-video-skills&utm_content=skill_footer&utm_term=short-form-video)** — the AI motion agent for editable, on-brand motion graphics.
|
||||
@@ -0,0 +1,155 @@
|
||||
---
|
||||
name: short-form-video
|
||||
description: This skill should be used when the user asks to "make a Reels/TikTok/YouTube Shorts video", "build a short-form video template", "write a hook for a short", "edit for retention", "add pattern interrupts", "make a video loop", "fix the first 3 seconds", "pace cuts for a vertical video", or "set up 9:16 safe areas". Covers the hook→retention→loop grammar of vertical short-form (distinct from a launch hype film).
|
||||
version: 0.1.0
|
||||
---
|
||||
|
||||
# Short-Form Video
|
||||
|
||||
Engineer a 9:16 video that survives the swipe. Short-form is not a small launch film — it is a retention machine: a hook that earns the first second, pattern interrupts that reset attention every few seconds, and often a loop that buys watch-time past 100%. The craft is timing, not polish.
|
||||
|
||||
## When to use
|
||||
|
||||
- Reels / TikTok / YouTube Shorts (7–60s, vertical 9:16).
|
||||
- Retention editing: fixing drop-off, adding pattern interrupts, tightening pacing.
|
||||
- Hooks, seamless loops, repeatable short-form templates (one design, many topics).
|
||||
|
||||
## Story structure (the retention contract)
|
||||
|
||||
Short-form storytelling is a contract with the viewer's thumb: every second must re-earn the next one. The narrative is shaped *backwards from the retention curve*, not forwards from an intro. Lock these before touching the timeline.
|
||||
|
||||
- **One idea per video.** A short carries exactly one payoff. A second idea splits attention and the curve sags in the middle — make it a second video instead. If you can't name the single takeaway in a sentence, you don't have a short yet.
|
||||
- **Open a loop in the first ~3s, close it last.** The hook poses a question or gap (the open loop); the payoff answers it. The viewer stays because the loop is open — so never answer it early, and never bury the payoff under setup.
|
||||
- **No dead air.** Every beat either advances the idea or resets attention. Cut anything that does neither. Silence, slow ramps, throat-clearing intros ("hey guys, in this video…") are where viewers swipe.
|
||||
- **Why the curve, not the cut, is the unit of work.** The algorithm distributes whatever holds the per-second retention curve flat; a "good" edit that flattens the curve loses to an ugly one that keeps it up. You are editing the *curve*, and the hook gates everything after it — fix it first.
|
||||
|
||||
The narrative spine (the `Hook → Setup → Body → Payoff/loop` arc is budgeted in the table below):
|
||||
|
||||
| Move | Story job | Failure if missed |
|
||||
|---|---|---|
|
||||
| Hook | Open the loop; promise the payoff | Swipe in first 3s |
|
||||
| Tension hold | Keep the gap open through the body | Flat middle, mid-drop |
|
||||
| Payoff | Close the loop — the one idea, delivered | "Wasted my time," no share |
|
||||
| Loop / CTA | Feed back to frame 0, or one clear ask | No re-watch, no action |
|
||||
|
||||
(`The retention arc` table below assigns seconds to each move; this section is the narrative logic and ordering behind it. `Hook grammar` lists the hook archetypes.)
|
||||
|
||||
## The one metric that drives everything
|
||||
|
||||
**Retention, not production value.** The algorithm distributes whatever holds viewers; ~87% decide to stay or swipe inside 3 seconds, and the threshold for distribution sits near **70%+ average view-through** (Shorts ~73%, TikTok ~78%, Reels ~65%). Every decision below trades against that curve. A flawless shot that bores at 0:04 loses to an ugly one that holds.
|
||||
|
||||
## The retention arc
|
||||
|
||||
| Beat | Job | Budget (of a 20s short) |
|
||||
|---|---|---|
|
||||
| Hook (0–1s) | One frame + one line that creates an open loop | 0–1s |
|
||||
| Setup | Pay off *why watch* — promise, stakes, or the gap | 1–4s |
|
||||
| Body | Deliver value in beats; one idea per beat | 4–17s |
|
||||
| Payoff / loop | Close the loop — or feed it back to frame 0 | 17–20s |
|
||||
|
||||
Scale the *body*, never the hook. A 60s short has a longer body and more beats — the same 1-second hook.
|
||||
|
||||
## Hook grammar (first ~1s)
|
||||
|
||||
The hook is a sentence + a visual that opens a curiosity gap the brain needs closed. Pick one pattern and commit:
|
||||
|
||||
| Hook type | Shape | Best for |
|
||||
|---|---|---|
|
||||
| Open loop | "The reason your X keeps Y…" (answer delayed) | most content |
|
||||
| Direct promise | "3 ways to ___ in 30 seconds" | educational / listicle |
|
||||
| Pattern interrupt | snap-zoom / whip-pan / visual mismatch in frame 1 | entertainment |
|
||||
| Negation | "Stop doing ___" / "You're ___ wrong" | strong opinions |
|
||||
|
||||
Two rules: the hook line is **on-screen as text by frame 1** (85% watch muted), and the most striking *visual* is also the first frame — never a slow ramp-in. Hold a strong opening frame; do not fade up from black.
|
||||
|
||||
## Pattern interrupts & cut rhythm
|
||||
|
||||
A pattern interrupt is any change that resets attention: a hard cut, zoom punch, b-roll insert, sound effect, caption pop, or angle change. In short-form, density is high — a *visual change every ~2–4 seconds*; videos with an interrupt roughly every 4s hold ~58% vs ~41% for a static talking head. The killer is a flat middle: TikTok throttles distribution when the watch-through curve flattens, so never stitch the body from low-energy takes.
|
||||
|
||||
```js
|
||||
// Drive every interrupt off the FRAME, not wall-clock — renders deterministically.
|
||||
import { useCurrentFrame } from "remotion";
|
||||
const fps = 30;
|
||||
const cuts = [0, 1.2, 3.0, 5.4, 8.0, 11.2, 14.0]; // seconds — uneven on purpose
|
||||
const frame = useCurrentFrame();
|
||||
const shot = cuts.findIndex((t, i) => frame < (cuts[i + 1] ?? Infinity) * fps);
|
||||
```
|
||||
|
||||
Vary the interval — a metronome reads as boredom; uneven cuts read as momentum. A punch-in zoom is the cheapest interrupt that needs no new footage:
|
||||
|
||||
```jsx
|
||||
import { useCurrentFrame, interpolate, spring, useVideoConfig } from "remotion";
|
||||
const PunchIn = ({ at, children }) => {
|
||||
const frame = useCurrentFrame(); const { fps } = useVideoConfig();
|
||||
const s = spring({ frame: frame - at * fps, fps, config: { damping: 12, stiffness: 200 } });
|
||||
const scale = interpolate(s, [0, 1], [1, 1.12]); // snap to 112% on the beat
|
||||
return <div style={{ transform: `scale(${scale})`, transformOrigin: "50% 45%" }}>{children}</div>;
|
||||
};
|
||||
```
|
||||
|
||||
## Captions
|
||||
|
||||
Most viewers watch muted, so on-screen captions are not optional — they carry the content and double as a pattern interrupt when each phrase pops in. Keep 4–7 words per line, high contrast, inside the safe area. **Do not re-implement caption animation here** — use the `caption-animation` skill for word-by-word timing, karaoke highlight, and styling; this skill only places captions on the retention timeline and inside the 9:16 safe zone.
|
||||
|
||||
## Loops & re-watch
|
||||
|
||||
A seamless loop counts each re-watch as fresh watch-time — a clean 8s loop watched 3× is 300% view-through, the strongest possible signal. Two techniques: match the **last frame to the first** (same composition, position, color) so the cut is invisible, and write a **sentence loop** — phrase the hook so the payoff feeds back into frame 0 ("…and that's why I never — " → loops to the start). Best length for re-watch is ~7–15s.
|
||||
|
||||
## 9:16 safe areas
|
||||
|
||||
Compose inside the universal safe zone so platform UI never covers text or faces.
|
||||
|
||||
| Zone | Pixels (1080×1920) | Avoid |
|
||||
|---|---|---|
|
||||
| Universal safe (all platforms) | center **900×1400** | anything critical outside it |
|
||||
| Top | keep clear ~120px | profile / sound UI |
|
||||
| Bottom | keep clear ~320px | captions, CTA, hashtags, audio bar |
|
||||
| Right | keep clear ~120px | like / comment / share rail |
|
||||
|
||||
Put the hook text and key subject in the center 900×1400 box. Reserve the bottom ~320px even if it looks empty in the editor — that is where the platform paints its own captions and buttons.
|
||||
|
||||
## Output checklist
|
||||
|
||||
- Hook line is on-screen text by frame 1; strongest visual is the first frame (no fade-up).
|
||||
- One open loop / promise set in the first ~4s.
|
||||
- A visual pattern interrupt every ~2–4s; intervals uneven; no flat middle.
|
||||
- Captions present (via `caption-animation`), 4–7 words, inside safe area.
|
||||
- Loop closed — matched first/last frame or a sentence that feeds frame 0.
|
||||
- Composed inside the 900×1400 center box; bottom 320px / top 120px / right 120px kept clear.
|
||||
- Every animated value derived from `useCurrentFrame()` — no CSS/library timers.
|
||||
|
||||
## 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`.
|
||||
|
||||
The short ships as a Remotion composition (`<Composition>` + zod `schema` + `defaultProps`) — every cut, punch-in, and interrupt driven by `useCurrentFrame()`, never `Date.now()` / `Math.random()` / timers. Deliverable = `out/*.mp4` + the project (re-render per topic). 9:16 vertical (1080×1920) is the default.
|
||||
|
||||
**Verify loop — render stills → inspect → encode.** Three frames test the three things that make or break retention: the hook, the pacing, and the loop seam.
|
||||
|
||||
```bash
|
||||
# Stills at hook / mid-body / last frame — WITH SHIPPED PROPS (the real topic, not defaults)
|
||||
npx remotion still Short out/f-hook.png --frame=10 --props='{"topic":"...","hook":"..."}' # ~first 3s reads instantly
|
||||
npx remotion still Short out/f-mid.png --frame=N --props='{"topic":"...","hook":"..."}'
|
||||
npx remotion still Short out/f-end.png --frame=L --props='{"topic":"...","hook":"..."}' # L = durationInFrames-1
|
||||
|
||||
# Inspect each PNG:
|
||||
# - HOOK frame (~frame 0-ish / first 3s): hook line is on-screen text and reads instantly; strongest visual already up (no fade-up)
|
||||
# - LOOP seam: compare f-hook(frame 0) vs f-end(last frame) — same composition/position/color for an invisible loop cut
|
||||
# - 9:16 safe area: hook + key subject inside the center 900x1400 box; clear of top ~12%, bottom ~20-35% (captions/CTA/audio), right action rail
|
||||
|
||||
npx remotion render Short out/short.mp4 --props='{"topic":"...","hook":"..."}' # encode once stills verify
|
||||
npx remotion render Short out/demo.gif --codec=gif # README proof clip
|
||||
```
|
||||
|
||||
**Per topic / batch**: verify ONE topic via stills *before* rendering all of them. Use `npx remotion compositions` for `durationInFrames`/`fps` to pick the mid + last frames.
|
||||
|
||||
**Before you finish:**
|
||||
1. Stills render cleanly at the hook, mid, and last frame — no errors.
|
||||
2. The hook frame reads instantly (on-screen text + strongest visual up front, no fade-up); first vs last frame match for a clean loop seam.
|
||||
3. Hook + subject + captions sit inside the 9:16 center 900×1400 safe box at every checked frame.
|
||||
4. Frame-driven only — no `Date.now()` / `Math.random()` / timers; cuts uneven, no flat middle.
|
||||
5. A real topic's shipped props (not `defaultProps`) render correctly; MP4 encoded, GIF optional.
|
||||
|
||||
## Reference files
|
||||
|
||||
- `references/retention-pacing.md` — a complete runnable Remotion `<Short>` composition: a frame-driven shot scheduler with uneven cuts, the PunchIn pattern interrupt, an on-screen hook, a 9:16 safe-area overlay, and a seamless first/last-frame loop. Plus a hook-pattern library, a retention-curve debugging method, per-platform safe-zone maps, and the template×topic batch-render pattern.
|
||||
@@ -0,0 +1,209 @@
|
||||
# Retention Pacing — Short-Form Video Reference
|
||||
|
||||
Deep reference for the `short-form-video` skill: a full runnable Remotion short, a hook library, a retention-debugging method, per-platform safe zones, and batch output. All timing is frame-driven so renders are deterministic.
|
||||
|
||||
## 1. A complete `<Short>` composition
|
||||
|
||||
One self-contained vertical short: frame-driven shot scheduler with uneven cuts, a punch-in pattern interrupt, an on-screen hook, a 9:16 safe-area overlay (dev only), and a seamless loop. Topic content is a prop, so the same file renders many shorts.
|
||||
|
||||
```tsx
|
||||
// Short.tsx — 1080×1920, 30fps. Register at 600 frames (20s) for a clean loop.
|
||||
import {
|
||||
AbsoluteFill, useCurrentFrame, useVideoConfig,
|
||||
interpolate, spring, Sequence, Img,
|
||||
} from "remotion";
|
||||
|
||||
type Beat = { at: number; text: string; src?: string }; // at = seconds
|
||||
export type ShortProps = {
|
||||
hook: string; // on-screen by frame 1
|
||||
beats: Beat[]; // body, one idea each
|
||||
loopText: string; // sentence that feeds back to frame 0
|
||||
};
|
||||
|
||||
// --- frame-driven shot scheduler: uneven cuts read as momentum ---
|
||||
const useShot = (cuts: number[]) => {
|
||||
const { fps } = useVideoConfig();
|
||||
const frame = useCurrentFrame();
|
||||
let i = 0;
|
||||
for (let k = 0; k < cuts.length; k++) if (frame >= cuts[k] * fps) i = k;
|
||||
const startF = cuts[i] * fps;
|
||||
const endF = (cuts[i + 1] ?? cuts[i] + 2) * fps;
|
||||
const local = (frame - startF) / (endF - startF); // 0→1 within shot
|
||||
return { index: i, local, startF };
|
||||
};
|
||||
|
||||
// --- punch-in: the cheapest pattern interrupt, snaps on the cut ---
|
||||
const PunchIn: React.FC<{ startF: number; to?: number; children: React.ReactNode }> = ({
|
||||
startF, to = 1.1, children,
|
||||
}) => {
|
||||
const frame = useCurrentFrame();
|
||||
const { fps } = useVideoConfig();
|
||||
const s = spring({ frame: frame - startF, fps, config: { damping: 13, stiffness: 220 } });
|
||||
const scale = interpolate(s, [0, 1], [1, to]);
|
||||
return <AbsoluteFill style={{ transform: `scale(${scale})`, transformOrigin: "50% 45%" }}>{children}</AbsoluteFill>;
|
||||
};
|
||||
|
||||
// --- hook: text present from frame 0, micro-overshoot, no fade-up ---
|
||||
const Hook: React.FC<{ text: string }> = ({ text }) => {
|
||||
const frame = useCurrentFrame();
|
||||
const { fps } = useVideoConfig();
|
||||
const pop = spring({ frame, fps, config: { damping: 9, stiffness: 260 } });
|
||||
const scale = interpolate(pop, [0, 1], [0.9, 1]);
|
||||
return (
|
||||
<div style={{
|
||||
position: "absolute", top: 360, left: 90, right: 90, // inside 900-wide safe box
|
||||
transform: `scale(${scale})`, transformOrigin: "0 0",
|
||||
fontFamily: "Inter, sans-serif", fontWeight: 800, fontSize: 76, lineHeight: 1.05,
|
||||
color: "#fff", textShadow: "0 4px 24px rgba(0,0,0,.55)",
|
||||
}}>{text}</div>
|
||||
);
|
||||
};
|
||||
|
||||
export const Short: React.FC<ShortProps> = ({ hook, beats, loopText }) => {
|
||||
const { fps, durationInFrames } = useVideoConfig();
|
||||
const frame = useCurrentFrame();
|
||||
const cuts = [0, ...beats.map((b) => b.at)]; // hook shot + one per beat
|
||||
const { index, startF } = useShot(cuts);
|
||||
const current = index === 0 ? null : beats[index - 1];
|
||||
|
||||
// seamless loop: match the LAST 0.5s back toward the opening frame
|
||||
const tailF = durationInFrames - frame;
|
||||
const loopFade = interpolate(tailF, [0, fps * 0.5], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
|
||||
|
||||
return (
|
||||
<AbsoluteFill style={{ backgroundColor: "#0b0b0f" }}>
|
||||
<PunchIn startF={startF}>
|
||||
{current?.src && <Img src={current.src} style={{ width: "100%", height: "100%", objectFit: "cover" }} />}
|
||||
</PunchIn>
|
||||
|
||||
{index === 0 && <Hook text={hook} />}
|
||||
|
||||
{/* body caption — placement only; styling/word-timing belongs to caption-animation */}
|
||||
{current && (
|
||||
<div style={{
|
||||
position: "absolute", left: 90, right: 90, bottom: 380, // above the 320px bottom UI band
|
||||
fontFamily: "Inter, sans-serif", fontWeight: 700, fontSize: 60, color: "#fff",
|
||||
textAlign: "center", textShadow: "0 3px 18px rgba(0,0,0,.6)",
|
||||
}}>{current.text}</div>
|
||||
)}
|
||||
|
||||
{/* loop sentence rises as the clip ends, easing the eye back to frame 0 */}
|
||||
<div style={{
|
||||
position: "absolute", left: 90, right: 90, bottom: 380, opacity: 1 - loopFade,
|
||||
fontFamily: "Inter, sans-serif", fontWeight: 800, fontSize: 64, color: "#fff", textAlign: "center",
|
||||
}}>{loopText}</div>
|
||||
|
||||
<SafeZone />{/* remove for final render */}
|
||||
</AbsoluteFill>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
Register it with a duration that *is* the loop length:
|
||||
|
||||
```ts
|
||||
// Root.tsx
|
||||
import { Composition } from "remotion";
|
||||
import { Short } from "./Short";
|
||||
export const Root = () => (
|
||||
<Composition
|
||||
id="Short" component={Short}
|
||||
durationInFrames={600} fps={30} width={1080} height={1920}
|
||||
defaultProps={{
|
||||
hook: "You're editing Shorts wrong —",
|
||||
beats: [
|
||||
{ at: 1.2, text: "Cut every 2–4 seconds", src: "b1.jpg" },
|
||||
{ at: 4.0, text: "Never on a fixed grid", src: "b2.jpg" },
|
||||
{ at: 7.5, text: "Kill the flat middle", src: "b3.jpg" },
|
||||
{ at: 11.0, text: "Match last frame to first", src: "b4.jpg" },
|
||||
],
|
||||
loopText: "…and that's why mine loop forever",
|
||||
}}
|
||||
/>
|
||||
);
|
||||
```
|
||||
|
||||
## 2. The 9:16 safe-area overlay (dev-only)
|
||||
|
||||
Render this on top while editing; delete it before the final export.
|
||||
|
||||
```tsx
|
||||
import { AbsoluteFill } from "remotion";
|
||||
export const SafeZone: React.FC = () => (
|
||||
<AbsoluteFill style={{ pointerEvents: "none" }}>
|
||||
{/* universal safe box: center 900×1400 in 1080×1920 */}
|
||||
<div style={{ position: "absolute", left: 90, top: 260, width: 900, height: 1400, outline: "2px dashed #39d", opacity: .6 }} />
|
||||
{/* platform UI bands to keep clear */}
|
||||
<div style={{ position: "absolute", top: 0, left: 0, right: 0, height: 120, background: "rgba(255,0,0,.12)" }} />
|
||||
<div style={{ position: "absolute", bottom: 0, left: 0, right: 0, height: 320, background: "rgba(255,0,0,.12)" }} />
|
||||
<div style={{ position: "absolute", bottom: 320, top: 120, right: 0, width: 120, background: "rgba(255,128,0,.10)" }} />
|
||||
</AbsoluteFill>
|
||||
);
|
||||
```
|
||||
|
||||
## 3. Hook pattern library
|
||||
|
||||
The hook is a sentence that opens a gap the brain must close, plus the most striking frame as frame 0. Copyable shapes:
|
||||
|
||||
| Pattern | Template | Note |
|
||||
|---|---|---|
|
||||
| Open loop | "The real reason your ___ keeps ___ …" | answer withheld until payoff |
|
||||
| Direct promise | "___ in 30 seconds, no ___ needed" | name the payoff + the timebox |
|
||||
| Negation | "Stop ___. You're doing it backwards." | strong-opinion content |
|
||||
| Pattern interrupt | snap-zoom / whip / hard visual mismatch | entertainment, no text needed |
|
||||
| Stakes | "This ___ cost me $___ — don't repeat it" | story / case-study |
|
||||
| Listicle | "3 ___ that ___ (the 3rd one ___ )" | tees up a forward reference |
|
||||
|
||||
Rules that matter more than the wording: (1) the hook text is on-screen by frame 1 — most viewers are muted; (2) frame 0 is the best frame, never a fade-up from black; (3) one gap only — stacking two hooks closes neither.
|
||||
|
||||
## 4. Retention-curve debugging
|
||||
|
||||
Treat the per-second retention graph (TikTok Analytics, YT Studio "Audience retention", Reels) as a profiler.
|
||||
|
||||
| Symptom on the curve | Likely cause | Fix |
|
||||
|---|---|---|
|
||||
| Cliff at 0:00–0:02 | weak hook / slow first frame | new hook line; cut the ramp-in; lead with the best frame |
|
||||
| Steady gentle decline | normal — leave it | — |
|
||||
| Flat-then-drop in the middle | low-energy body, cuts too sparse | add interrupts; tighten cut spacing to 2–4s |
|
||||
| Bump back up near the end | viewers are looping | lean in — tighten the loop, shorten total length |
|
||||
| Spike at one timestamp | a re-watched moment | front-load that beat or make it the hook |
|
||||
|
||||
Target ≥70% average view-through. Iterate the hook first — it moves the curve more than any other edit because it gates everything after it.
|
||||
|
||||
## 5. Per-platform safe zones
|
||||
|
||||
All on a 1080×1920 canvas. The universal box (center 900×1400) is the intersection; design inside it and one master fits every platform.
|
||||
|
||||
| Platform | Top clear | Bottom clear | Right clear | Notes |
|
||||
|---|---|---|---|---|
|
||||
| Universal (use this) | ~120px | ~320px | ~120px | center 900×1400 holds on all |
|
||||
| TikTok | ~108px | ~320px | ~120px | caption + button rail at bottom-right |
|
||||
| Instagram Reels | ~120px | ~310px | ~84px | audio bar + caption bottom |
|
||||
| YouTube Shorts | ~120px | ~300px | ~60px | channel + subscribe bottom band |
|
||||
| TikTok Ads | ~108px | ~370px | ~120px | extra room for the CTA button |
|
||||
|
||||
When unsure, design to the *largest* margin (TikTok Ads bottom 370px) and nothing ever clips.
|
||||
|
||||
## 6. Template × topic — batch output
|
||||
|
||||
The payoff of code-driven shorts: lock the design once, swap only the props, render N videos. Make topic content a prop (already done above), keep one theme object, and loop over JSON files.
|
||||
|
||||
```jsx
|
||||
// theme.ts — one source of truth so 50 shorts stay on-brand
|
||||
export const theme = { font: "Inter", hookSize: 76, bodySize: 60, bg: "#0b0b0f", fg: "#fff", accent: "#39d" };
|
||||
```
|
||||
|
||||
```bash
|
||||
# render the same Short template for every topic file in /topics
|
||||
for f in topics/*.json; do
|
||||
name=$(basename "$f" .json)
|
||||
npx remotion render Short "out/$name.mp4" --props="$f"
|
||||
done
|
||||
```
|
||||
|
||||
Each `topics/*.json` is one `ShortProps` object (`hook`, `beats`, `loopText`). Keep the hook line, cut points, and loop sentence per-topic; everything else stays fixed so the series reads as one brand.
|
||||
|
||||
---
|
||||
## 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 batch-produce short-form videos from one template × data — change the text/data and re-export. → [iart.ai](https://iart.ai/?utm_source=github&utm_medium=reference&utm_campaign=tiktok-video-skills&utm_content=ref_footer&utm_term=short-form-video)
|
||||
Symlink
+1
@@ -0,0 +1 @@
|
||||
../../.agents/skills/caption-animation
|
||||
Symlink
+1
@@ -0,0 +1 @@
|
||||
../../.agents/skills/countdown-video
|
||||
Symlink
+1
@@ -0,0 +1 @@
|
||||
../../.agents/skills/lower-thirds
|
||||
@@ -1 +0,0 @@
|
||||
../../.agents/skills/motion-design
|
||||
Symlink
+1
@@ -0,0 +1 @@
|
||||
../../.agents/skills/short-form-video
|
||||
+22
-4
@@ -1,11 +1,29 @@
|
||||
{
|
||||
"version": 1,
|
||||
"skills": {
|
||||
"motion-design": {
|
||||
"source": "LottieFiles/motion-design-skill",
|
||||
"caption-animation": {
|
||||
"source": "iart-ai/tiktok-video-skills",
|
||||
"sourceType": "github",
|
||||
"skillPath": "skills/motion-design/SKILL.md",
|
||||
"computedHash": "9fcf9130cc46ee8fd1d8e09a9263347a9d76efbcbfa46591cc4cefaf19bbb453"
|
||||
"skillPath": "skills/caption-animation/SKILL.md",
|
||||
"computedHash": "e42c4828d3c6115dfb4d8fd3c3fd485b8e6a89c35a8835eee6dae39fb83210a4"
|
||||
},
|
||||
"countdown-video": {
|
||||
"source": "iart-ai/tiktok-video-skills",
|
||||
"sourceType": "github",
|
||||
"skillPath": "skills/countdown-video/SKILL.md",
|
||||
"computedHash": "dafb9127ededa76d0df08be73adc46e18d6ec3955153f6ecfd0f928984ce95b2"
|
||||
},
|
||||
"lower-thirds": {
|
||||
"source": "iart-ai/tiktok-video-skills",
|
||||
"sourceType": "github",
|
||||
"skillPath": "skills/lower-thirds/SKILL.md",
|
||||
"computedHash": "502c1a8a491e477dd855eb1a45469c09f6ff46a72ea841838d358d0a6a9fd790"
|
||||
},
|
||||
"short-form-video": {
|
||||
"source": "iart-ai/tiktok-video-skills",
|
||||
"sourceType": "github",
|
||||
"skillPath": "skills/short-form-video/SKILL.md",
|
||||
"computedHash": "893ea19615f3199159b9fe94f05e37a5e538e7e0c3af7f77f9f9bed7ff933423"
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user