refactor(embedded-captions): merge motion-vocabulary + direction-catalog into live homes

14->12 reference files. Both advertised a retired "10 looks / 10 motion primitives"
model that contradicts the live 48-identity catalog, and neither is read by any
compiler.

Kernels migrated first (verified no-successor):
- direction-catalog's tone x shot x platform CLASSIFICATION MATRIX -> CATALOG.md as a
  shortlisting crosswalk (verbatim table + a usage header tying direction labels to
  current identities + the anchor-fallback). The 10 per-direction specs map ~1:1 onto
  shipped identities and drop with the file.
- motion-vocabulary's "palette not a cage / pick by content tone / invent
  deterministically" permission -> _motion.md intro. Its 10 move definitions are
  redundant with _motion.md's richer mood->entrance catalog (type/fade-up/pop/whip/
  glitch/blur-in + 50 moves) and drop; its 60% exit rule was DROPPED, not carried, as
  it conflicts with _motion.md's canonical "exit ~= 75% of entry".

Repointed all 5 inbound links: SKILL:211 (matrix cross-ref -> CATALOG), the two SKILL
table rows (removed), SKILL:240 prose ("and direction catalog" dropped), and
typographic-moves.md:203 (the dead direction-catalog §1 parenthetical dropped; it
already names the `documentary` identity).

Verified: zero residual refs, no dangling file/anchor links, kernels present in their
new homes, CJK-free, oxfmt clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
jieling-jenson
2026-06-19 21:09:20 +08:00
co-authored by Claude Opus 4.8
parent 26321ac2ce
commit 311cd32725
6 changed files with 19 additions and 291 deletions
+14
View File
@@ -14,6 +14,20 @@ Routing procedure (replaces any mode decision):
4. Author the identity's file (last column), then render with its engine's
pipeline. Done — no category question ever surfaced.
### Tone × shot × platform — direction crosswalk (shortlisting aid)
A pre-shortlist input for step 2: intersect the clip's register with the delivery platform to get a **direction**, then pick the CATALOG identity of that register from the table below (documentary → `documentary` / `anchor`; keynote → `keynote`; poetic → `cream`; conversational → a cinematic column-flow or a rail theme; energetic → a loud theme). The cells are direction labels, not identity names; when none fits cleanly → **`anchor`**.
| Tone ↓ / Platform → | 9:16 portrait | 16:9 landscape | 1:1 square |
| ------------------- | ---------------------------------------- | ------------------------ | ------------------------ |
| **Documentary** | documentary-dignified (vertical variant) | documentary-dignified | broadcast-dignified |
| **Conversational** | portrait-header + default | memory-wall OR champion | broadcast-dignified |
| **Energetic** | high-energy-vlog | high-energy-vlog-wide | high-energy-vlog-sq |
| **Poetic** | lyrical-poem-on-wall (portrait) | lyrical-poem-on-wall | chapter-card |
| **Keynote/tech** | — (9:16 not ideal) | tech-keynote-confident | tech-keynote-confident |
| **Investigative** | — | investigative-typewriter | investigative-typewriter |
| **Music video** | k-pop-lyric | k-pop-lyric | k-pop-lyric |
## Identities
| Identity | Reading surface | Voice (one line) | Recommend for | Scene needs | Author → engine |
+2 -4
View File
@@ -208,7 +208,7 @@ Classify the clip on 3 axes and feed the result into CATALOG.md's shortlisting
- 9:16 portrait (TikTok/IG/Shorts) | 16:9 landscape (YouTube/web) | 1:1 square | broadcast export
Cross-reference in [references/direction-catalog.md § Classification matrix](references/direction-catalog.md) for direction language — then return to [CATALOG.md](CATALOG.md) to shortlist identities (this matrix informs the shortlist; the catalog is the only routing surface).
Cross-reference the **tone × shot × platform crosswalk** in [CATALOG.md](CATALOG.md) for direction language — it informs the shortlist; the catalog is the only routing surface.
## Composition craft (embed track) — read before embedding
@@ -230,8 +230,6 @@ track has its own, much simpler spec → **[references/rail.md](references/rail.
| [dna/README.md](dna/README.md) | **The DNA registry** — ten scene-parameterized visual languages; how to pick. |
| [references/reference-bar.md](references/reference-bar.md) | **The taste bar** — per-register world-class references + the 5 positive checks. |
| [references/aesthetic-principles.md](references/aesthetic-principles.md) | **The 18 rules.** Beat Veed AI on taste. Read first. |
| [references/motion-vocabulary.md](references/motion-vocabulary.md) | 10 named motion primitives + tone→timing lookup |
| [references/direction-catalog.md](references/direction-catalog.md) | 10 ship-ready aesthetics + tone×shot×platform matrix |
| [references/anti-patterns.md](references/anti-patterns.md) | Bugs already locked out (CoreML, letter-spacing reflow, etc.) |
| [references/layout-heuristics.md](references/layout-heuristics.md) | Step 0 embed-viability gate (is a surface usable — 4 conditions); plane positioning, clean-zone selection, crown 3 conditions, pillarbox math |
| [references/typography-presets.md](references/typography-presets.md) | Font-size × column-width matrix (starting points) |
@@ -239,7 +237,7 @@ track has its own, much simpler spec → **[references/rail.md](references/rail.
| [references/failure-modes.md](references/failure-modes.md) | Long tail of dev gotchas |
| [references/bespoke-vs-presets.md](references/bespoke-vs-presets.md) | Why presets fail sometimes; clone-and-tweak pattern |
**Read the aesthetic principles and direction catalog FIRST.** Everything else is implementation detail.
**Read the aesthetic principles FIRST.** Everything else is implementation detail.
---
@@ -9,6 +9,8 @@ metadata:
`_anatomy.md` wires four hooks onto one paused timeline: `FLOW_IN`, `FLOW_OUT`, `CLIMAX_IN`, `CLIMAX_OUT`. This file is the catalog each template picks from. Each recipe is a GSAP tween on the climax `span` (or a flow `.w`); placed at an absolute time it is fully **seek-safe**. Multi-stage looks use GSAP `keyframes:{}` (still seek-safe) — never CSS keyframes.
**A palette, not a cage.** Pick the entry by mood (the mood→entrance table below) and **by content tone — never default every group to one move**. When a scene genuinely demands a move this catalog lacks, invent one — as long as it stays deterministic + seek-safe and animates transform/opacity only (the reflow rule, [\_anatomy.md](_anatomy.md)).
## Numerics (shared)
**Ease palette** (sanctioned — reads clean on video, stays distinct):
@@ -1,138 +0,0 @@
# Direction catalog
10 distinct aesthetic directions the skill can express. Each is a complete look: font, motion, color, placement, rhetorical defaults. The agent picks by **content tone × shot type × platform**, not preset name.
**Superseded for routing by [CATALOG.md](../CATALOG.md) → [dna/](../dna/README.md) (the 10 column-flow voices) + [themes/](../themes/README.md) (38 themed)** — the per-direction specs below map ~1:1 onto shipped identities. Kept for the **classification matrix** (tone × shot × platform), which the live registries don't restate; the rest are future ship-ready aesthetics.
Classification matrix — pick direction by intersection:
| Tone ↓ / Platform → | 9:16 portrait | 16:9 landscape | 1:1 square |
| ------------------- | ---------------------------------------- | ------------------------ | ------------------------ |
| **Documentary** | documentary-dignified (vertical variant) | documentary-dignified | broadcast-dignified |
| **Conversational** | portrait-header + default | memory-wall OR champion | broadcast-dignified |
| **Energetic** | high-energy-vlog | high-energy-vlog-wide | high-energy-vlog-sq |
| **Poetic** | lyrical-poem-on-wall (portrait) | lyrical-poem-on-wall | chapter-card |
| **Keynote/tech** | — (9:16 not ideal) | tech-keynote-confident | tech-keynote-confident |
| **Investigative** | — | investigative-typewriter | investigative-typewriter |
| **Music video** | k-pop-lyric | k-pop-lyric | k-pop-lyric |
---
## Direction specs
### 1. documentary-dignified _(Errol Morris / PBS Frontline)_ — rail-surface direction (use the `documentary` / `anchor` identities)
- **Family**: Söhne Mono OR GT Sectra for name cards; Inter for body
- **Weights**: 500 body, 700 name card
- **Color**: bone `#F5EFE6` on charcoal, OR charcoal `#1A1A1A` on bone. No accent.
- **Motion**: burn-in (no animation). Held 0.5s past last word.
- **Placement**: bottom-left block, 10% margin, locked position for whole interview.
- **Rules**: 2-line max. Speaker name card once at first utterance + after each cut. No emphasis styling — gravitas IS the style.
- **Rhetorical**: aggressive filler suppression. Every word is chosen.
### 2. cinematic-noir _(Kyle Cooper / Se7en)_
- **Family**: Distressed serif (Hoefler Text) + tight mono for detail
- **Weights**: 700 mostly; thin italic ONLY for whispers
- **Color**: off-white `#E8E0D0` with deep red `#8B0000` single-word accent for menace
- **Motion**: typewriter with 10% chance of 1px jitter on entry; scratched etch for chapter beats
- **Placement**: off-axis — avoid dead-center, slightly high-left or low-right
- **Rules**: no emoji, no rounded corners, everything hand-feeling
### 3. tech-keynote-confident _(Apple / Jony Ive ad)_
- **Family**: SF Pro Display OR Inter, nothing else
- **Weights**: 800 headline keyword, 400 context
- **Color**: pure white on any bg; `mix-blend-mode: difference` fallback for bright scenes
- **Motion**: swipe-reveal from bottom via clip-path (400ms); exit fades 400ms
- **Placement**: dead center, large. NOT lower-third.
- **Rules**: one caption on screen at a time. 2–5 words per caption. Long held silences between. Feels like slides.
### 4. lyrical-poem-on-wall _(extends current memory-wall template)_
- **Family**: Serif with personality — EB Garamond / GT Sectra / Caslon Italic
- **Weights**: 400–500 only. **This direction rejects bold.**
- **Color**: picks up wall via `mix-blend-mode: overlay`, opacity 0.85, no stroke
- **Motion**: etch in 600ms, hold 1.5–3s, etch out
- **Placement**: always on a surface in the scene (back wall, foam, whiteboard). Uses matte pipeline.
- **Rules**: captions are **fewer** than spoken text — 40–60%. Intentional silences. No other tool does this; strong differentiation.
### 5. high-energy-vlog _(controlled Hormozi)_
- **Family**: Inter ExtraBold, uppercase
- **Weights**: 900 always
- **Color**: white body + ONE accent (`#FFD600` or `#00E676`) + narrow 2px dark stroke
- **Motion**: word-pop with elastic, 60ms stagger; active word scales 1.15× on speech onset
- **Placement**: center-frame, ~35% from top
- **Rules**: max 3 words per frame. Hard break at breath pauses. Accent color on ~15% of words. **One full silence every 10s** (what Hormozi imitators miss).
### 6. chapter-card _(Wes Anderson / Grand Budapest)_
- **Family**: Futura Bold (modern) / Archer (warm) / Bodoni (formal)
- **Weights**: 700 chapter title, 400 attribution
- **Color**: pastel hue sampled from scene
- **Motion**: full-frame static card between interview segments
- **Placement**: centered card for chapters; lower-left name card during speech
- **Rules**: chapter cards get their own beat (0.8s silence before, 0.4s after). Feels authored.
### 7. investigative-typewriter _(Frontline / 60 Minutes / Morris Interrotron)_
- **Family**: IBM Plex Mono OR JetBrains Mono
- **Weights**: 500
- **Color**: white with 3px shadow, no stroke
- **Motion**: typewriter char-by-char 25ms/char; cursor blink 600ms after last char
- **Placement**: bottom band with 40% opacity gradient up — **NOT a hard box**
- **Rules**: one line only, two-line max. Every caption ends with 1-frame cursor-hold before next enters.
### 8. k-pop-lyric _(music video typographic flex)_
- **Family**: oversized display serif (Playfair Display / GT Super) + tiny mono detail line
- **Weights**: display 900, mono 400
- **Color**: deep saturated single hue per song/segment
- **Motion**: cascade entries alternating sides; words cross subject with mix-blend
- **Placement**: intentionally LARGE — sometimes bigger than the face
- **Rules**: emotional/musical moments only. Never informational content. **Breaks rule #1 (subject wins) on purpose** — that's the whole point.
### 9. broadcast-dignified _(BBC / NYT documentary standard)_
- **Family**: Helvetica Now / Neue Haas Grotesk
- **Weights**: 500 body, 700 name
- **Color**: white on 40% black gradient pill (not hard box, not plain shadow — gradient is the signature)
- **Motion**: 200ms fade-up, 150ms fade-down
- **Placement**: bottom-center, 10% margin, title-safe locked
- **Rules**: strict BBC — 160–180wpm, 32–34 chars/line, 2 lines max, 1.5s min gap. "Export to broadcast" mode. Boring on purpose. Never wrong.
### 10. conference-lower-third-killer _(B2B but not lame)_
- **Family**: GT America / Aktiv Grotesk
- **Weights**: dual-weight name card — role 400, name 700, same size
- **Color**: scene-sampled accent on name, white on role
- **Motion**: name card swipes in from left 400ms on first appearance only; subsequent static
- **Placement**: lower-left card + active-word highlight inline in dialogue above
- **Rules**: mode for podcast clips, founder interviews, keynote pulls. Sophisticated without being arty.
---
## Which to ship next
Current templates: `memory-wall` (roughly direction #4), `champion` (roughly a mix of #5 and #9), `portrait-header` (default vertical).
Priority ship order based on competitive gap:
1. **documentary-dignified** — no one else does this well; Errol Morris aesthetic is an unserved niche
2. **lyrical-poem-on-wall** (as distinct template) — the one that most uses our matte-embed moat
3. **high-energy-vlog** — matches but out-designs Hormozi/Submagic presets
4. **tech-keynote-confident** — big for product launch videos
5. **investigative-typewriter** — niche but highly distinctive
---
## How the agent picks
1. Classify the clip: `tone × shot × platform` (see matrix above)
2. Look up direction in matrix
3. Read that direction's spec in this file
4. Translate spec into plan.json parameters OR clone the canonical HTML from `examples/`
5. Tune layout per scene (agent judgment, see `aesthetic-principles.md §1–18`)
If no direction fits cleanly → the **`anchor` theme** (the conservative verbatim default). Don't fake-fit an ill-matched direction.
@@ -1,148 +0,0 @@
# Motion Vocabulary — named word-entry moves
10 motion primitives the skill uses. Each has a specific timing + easing + situational fit. Agent picks by **content tone**, not default to one.
**Easing philosophy:** `cubic-bezier(.2,.7,.2,1)` is the "considered confident" default. `linear` is almost always wrong. Back-easing (elastic) is for playful content only — never documentary.
**Exit rules:** Default exit is the same tween reversed at 60% duration. Never exit with a different motion than entry unless doing a rhetorical pivot. Never fade out during speech — only during the gap between phrases.
---
## The 10 moves
### 1. typewriter
Char-by-char reveal, 25–35ms/char, linear easing. Documentary / data-heavy / tense / interrogative.
```js
// GSAP
words.forEach((w, i) => {
const chars = w.textContent.split("");
w.textContent = "";
chars.forEach((c, j) => {
const span = document.createElement("span");
span.textContent = c;
span.style.opacity = 0;
w.appendChild(span);
tl.to(span, { opacity: 1, duration: 0 }, wordStart + j * 0.028);
});
});
```
### 2. word-fade-up (DEFAULT)
Per-word, 80ms stagger, `opacity 0→1 + translateY 8→0`, `cubic-bezier(.2,.7,.2,1)` (ease-out). Default for conversational content.
```js
tl.fromTo(
word,
{ opacity: 0, y: 8 },
{ opacity: 1, y: 0, duration: 0.45, ease: "power2.out" },
wordStart,
);
```
### 3. word-pop
Per-word, 60ms stagger, `scale 0.85→1 + opacity 0→1`, elastic-light `cubic-bezier(.34,1.56,.64,1)`. Energetic / YouTube-vlog / high-tempo. **Never for documentary.**
### 4. swipe-reveal
Whole phrase at once, 400ms, `clip-path inset 0 100% 0 0 → 0 0 0 0`, expo `cubic-bezier(.77,0,.175,1)`. Keynote / tech product / announcement.
```css
.cap {
clip-path: inset(0 100% 0 0);
}
/* animate to inset(0 0 0 0) */
```
### 5. drop-and-settle
Per-word, 120ms stagger, `y: -30→0` with back-bounce `cubic-bezier(.68,-.55,.27,1.55)`. Playful but controlled. **Not for documentary.**
### 6. etch
Whole word at once, 600ms, opacity ramp `0→1` with slight blur→sharp transition. Ease-in-out. Poetic / lyrical / "quote on wall" direction.
### 7. crosshair
Per-word, 200ms total: two 1px lines converge on word center (linear 150ms), then word snaps in (expo-out 50ms). Thriller / investigative doc.
### 8. breathing-hold
**Static but alive.** No entry animation. Once visible, micro-scale loop `1.00↔1.008` over 2s, sine ease. Used on climax lines held 1.5s+.
### 9. cascade
Each word from alternating direction: L, R, L, R. `translateX: ±40→0`, ease-out 300ms. **Rhythm-break move** — use sparingly, once per 30s max.
### 10. burn-in
**Zero animation.** Sudden 1-frame opacity 1. No fade, no transform. Interview-doc style. Use for every 6–8th phrase in a documentary direction for variety (see direction-catalog §1).
---
## Tone → timing lookup table
| Tone | Stagger | Hold | Entry move |
| -------------- | ------------------------- | ----------- | ---------------------------------- |
| documentary | 150ms | 600ms | burn-in (70%) + word-fade-up (30%) |
| conversational | 80ms | 400ms | word-fade-up |
| energetic | 50ms | 300ms | word-pop |
| poetic | 250ms | 1200ms | etch |
| broadcast | 0 (burn-in) | BBC timings | burn-in |
| investigative | 25ms/char | 500ms | typewriter |
| keynote | 0 per-word (phrase swipe) | 600ms | swipe-reveal |
Agent picks tone → this table → GSAP parameters. Data, not guesswork.
---
## Per-word vs per-phrase animation axis
Orthogonal to the 10 moves above.
- **Per-word animation** (default): each word enters at its `w.start` timestamp. Tight sync with speech.
- **Per-phrase animation**: whole group enters/exits at `g.in`/`g.out`. Words appear together. Used for:
- swipe-reveal moves
- burn-in (no animation, but the "reveal" is a group event)
- title cards / chapter breaks
Rule: per-word for content that tracks speech; per-phrase for moments that step outside the speech flow.
---
## Stagger breakdown by context
Fine-tune stagger within a tone:
- **Documentary dialog**: 150ms (measured)
- **Documentary punchline**: 250ms (weighted)
- **Vlog opener**: 50ms (fast hook)
- **Vlog narration**: 70ms (conversational but snappy)
- **Poem / lyric**: 250–400ms per word, with 500–1000ms gaps between phrases
- **Keynote hero**: per-phrase only (stagger = N/A)
- **Interview name card**: 0 stagger (static)
---
## Anti-patterns (motion pacing)
The animation-property bans — never animate `letter-spacing` / `filter:blur` / font-size (inline-block reflow) — live in [failure-modes.md § Animation](failure-modes.md). Motion-pacing-specific:
- `Math.random()` / `Date.now()` in timeline → non-deterministic render
- Entries under 100ms total → frantic, unreadable
- Same motion for every group for 30s+ → eye adapts, stops registering
---
## When to break the vocabulary
The 10 moves are a comfortable coverage, not a ceiling. Invent new moves when the scene demands it:
- Kyle Cooper's scratched typewriter for noir
- K-pop lyric's directional word-from-side
- Film-title flash-cut burn-in with chromatic aberration
When inventing: stay deterministic, stay transform+opacity only, state the motion in terms of the 4 axes (entry, hold, exit, stagger).
@@ -200,7 +200,7 @@ This DNA assumes mid-to-dark backgrounds (the cream/`screen` luma band — see t
- Bright white studios → cinematic-cream's cream + `screen` washes out, and the DNA is
**locked** (no recolour — see [../SKILL.md](../SKILL.md) § Non-negotiables) → use the **`anchor` theme** or **`ink`** (opaque rail / letterpress) instead
- Documentary formal → the **`documentary`** column-flow identity (see references/direction-catalog.md §1)
- Documentary formal → the **`documentary`** column-flow identity
- Energetic vlog hooks → future `kinetic-vlog` DNA (not yet shipped)
## Example: memory-wall original, expressed in freeform