creator-editing-studio 1.3.5 → 1.3.6

package/template/src/compositions/BeatTest.tsx

@@ -3,7 +3,8 @@ import {AbsoluteFill, Sequence} from 'remotion';
 import {DataLine} from '../components/DataLine';
 import {MorphState} from '../components/MorphState';
 import {TypeAhead} from '../components/TypeAhead';
-import {FONT, PALETTE, SHADOW, WEIGHT} from '../design/tokens';
+import {withAlpha} from '../design/color';
+import {COLOR, FONT, SHADOW, WEIGHT} from '../design/tokens';
 
 /**
  * The three beats added from the UI-motion reference, side by side so they can be judged before
@@ -13,10 +14,10 @@ import {FONT, PALETTE, SHADOW, WEIGHT} from '../design/tokens';
  * Render stills with:  node scripts/stills.mjs BeatTest --frames=14,30,46,70
  */
 
-const LIME = PALETTE.lime400;
+const ACCENT = COLOR.accent;
 
 const Label: React.FC<{children: React.ReactNode}> = ({children}) => (
-  <div style={{fontFamily: FONT.sans, fontSize: 24, fontWeight: WEIGHT.semibold, letterSpacing: '0.06em', color: '#8a8880', textTransform: 'uppercase'}}>
+  <div style={{fontFamily: FONT.sans, fontSize: 24, fontWeight: WEIGHT.semibold, letterSpacing: '0.06em', color: COLOR.fgSecondary, textTransform: 'uppercase'}}>
     {children}
   </div>
 );
@@ -24,7 +25,7 @@ const Label: React.FC<{children: React.ReactNode}> = ({children}) => (
 export const BEAT_TEST_FRAMES = 90;
 
 export const BeatTest: React.FC = () => (
-  <AbsoluteFill style={{backgroundColor: PALETTE.cream, fontFamily: FONT.sans, padding: 80, gap: 56, display: 'flex', flexDirection: 'column'}}>
+  <AbsoluteFill style={{backgroundColor: COLOR.surfaceAlt, fontFamily: FONT.sans, padding: 80, gap: 56, display: 'flex', flexDirection: 'column'}}>
     {/* 1. Morph into state — a payment row becoming its own confirmation. */}
     <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
       <Label>Morph into state</Label>
@@ -35,8 +36,8 @@ export const BeatTest: React.FC = () => (
           width: 620,
           height: 104,
           radius: 999,
-          background: PALETTE.white,
-          colour: PALETTE.ink900,
+          background: COLOR.surface,
+          colour: COLOR.fg,
           children: (
             <span style={{fontSize: 34, fontWeight: WEIGHT.medium, padding: '0 36px'}}>
               Send ₹2,000 to Wise account
@@ -47,8 +48,8 @@ export const BeatTest: React.FC = () => (
           width: 340,
           height: 104,
           radius: 999,
-          background: LIME,
-          colour: PALETTE.ink900,
+          background: ACCENT,
+          colour: COLOR.onAccent,
           children: <span style={{fontSize: 36, fontWeight: WEIGHT.bold}}>Received ✓</span>,
         }}
       />
@@ -57,7 +58,7 @@ export const BeatTest: React.FC = () => (
     {/* 2. Live data morph — the panel holds still, only the line changes. */}
     <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
       <Label>Live data morph</Label>
-      <div style={{width: 820, height: 260, borderRadius: 24, backgroundColor: PALETTE.white, border: '1px solid rgba(18,18,16,0.10)', padding: 32, boxShadow: SHADOW.pop}}>
+      <div style={{width: 820, height: 260, borderRadius: 24, backgroundColor: COLOR.surface, border: `1px solid ${COLOR.borderSubtle}`, padding: 32, boxShadow: SHADOW.pop}}>
         <DataLine
           width={756}
           height={196}
@@ -67,9 +68,9 @@ export const BeatTest: React.FC = () => (
           frames={20}
           from={[0.22, 0.44, 0.3, 0.58, 0.41, 0.69, 0.52, 0.78, 0.6, 0.72]}
           to={[0.3, 0.26, 0.52, 0.38, 0.72, 0.5, 0.86, 0.62, 0.9, 0.84]}
-          colour="#3b82f6"
-          toColour="#e5484d"
-          fill="rgba(229,72,77,0.07)"
+          colour={COLOR.fgSecondary}
+          toColour={ACCENT}
+          fill={withAlpha(ACCENT, 0.1)}
         />
       </div>
     </div>
@@ -82,9 +83,9 @@ export const BeatTest: React.FC = () => (
           text="cut the gaps and add captions"
           at={8}
           speed={1.3}
-          colour={PALETTE.ink900}
-          ghost="rgba(18,18,16,0.22)"
-          background={LIME}
+          colour={COLOR.onAccent}
+          ghost={withAlpha(COLOR.fg, 0.22)}
+          background={ACCENT}
           fontSize={42}
           fontFamily={FONT.sans}
           fontWeight={WEIGHT.semibold}

package/template/templates/BRIEF.md

@@ -1,97 +1,97 @@
-# Brief: {{name}}
-
-Fill in what you can. Plain words are fine. Leave a line blank if you don't care.
-When done: drop your files in this folder's `footage/` (and `screenshots/`), then run
-`npm run prep -- {{name}}` and start the session with "start {{name}}".
-
-## Basics
-Format: 16:9            <!-- 16:9, 9:16, or both -->
-Language: en            <!-- en, hi, ar ... the language you speak in the video -->
-Talking head file:      <!-- file name in footage/, e.g. —.mp4. Leave blank if there's only one clip. -->
-Background-free copy:   <!-- Optional. Leave blank. Only fill this in if you already export a
-                             version with the background removed or replaced by flat green; the
-                             cutout is built automatically from your normal footage otherwise. -->
-Length target:          <!-- e.g. 25s, 90s -->
-
-## Script
-<!-- Paste the script exactly as you read it. Numbers as digits: $99, 11 minutes, 3 days. -->
-
-
-## The one thing viewers must remember
-<!-- One sentence. Everything in the edit serves this. -->
-
-
-## Must-have moments
-<!-- By the words you say, not by time. Plain words are fine.
-- When I say "look at this" → my clip shrinks and other creators' clips appear
-- "millions of views" → a counter racing up to 1M+ -->
-
-
-## Moments from references
-<!-- READ FIRST, BEFORE ANY DESIGN DECISION. These, and the ones saved in references/references.md,
-     beat the house defaults wherever the two disagree. -->
-<!-- You DON'T need the name of the effect. Clip + time + what you like about it.
-     Format: - clip-file.mp4 mm:ss-mm:ss — what you like (feel words are fine: snappy, floaty, punchy)
-- a-reel-you-like.mp4 00:02-00:04 — the colour screens flipping with each phrase, feels punchy -->
-
-
-## Effects from the library
-<!-- Optional: pick any by name (see the list at the bottom), and say where.
-- colour flip → "different person, different story" -->
-
-
-## B-roll
-<!-- Which clip where, by the words you say. Mark clips you DON'T want used.
-- creators' clips → "all of these people"  -->
-
-
-## Screenshots / things to blur
-<!-- Names, emails, prices, logos that must not be readable. -->
-
-
-## CTA / ending
-<!-- What the viewer should do, and what the last frame shows. -->
-
-
-## Sound
-SFX library: audio/     <!-- put sound effects in this folder's audio/, or say "none" -->
-Music: added by me in Premiere / Instagram     <!-- or a file name in audio/ -->
-
-## Don't want
-<!-- Anything you dislike: e.g. boxes over my footage, huge text, bouncy motion. -->
-
-
----
-
-### Effects library (names you can use)
-| Name | What it looks like |
-|---|---|
-| Text behind me | Big headline sits behind your head (works from normal footage) |
-| Card swap | You shrink into a rounded card, turn into another clip mid-shrink, a row of cards slides in and drifts |
-| Colour flip | Hard cuts to solid accent / ink screens on each phrase; a word rolls into the next and the colours swap |
-| Counter race | A number races up from 0 and lands on a value (e.g. 1,000,000+) |
-| Zoom-through cut | A jump cut hidden by a quick push-in that eases back — used on every cut by default |
-| Gradient CTA | Dark gradient rises from the bottom, small label + big word typed on the VO, then ticked pointers |
-| Browser mockup | Screenshots inside a clean browser window that pans and zooms to the detail |
-| Pointer click | An arrow glides to a spot and clicks, with a ripple |
-| Rolling number | Digits roll from one value to another (e.g. $26.50 → $48.94) |
-| Highlight marker | Accent marker wipes behind a key phrase |
-| Side card | You move into a card beside the graphics (16:9) or below them (9:16) |
-| Headline to pill | A big headline shrinks into a small corner tag that stays on screen |
-| Word-by-word captions | On by default (looks: clean, block, highlight, pop) |
-| Whip pan | Fast blurred pan between two unrelated shots |
-| Push | The next scene pushes the last one out |
-| Mask wipe | A soft-edged wipe reveals the next scene |
-| Match cut | Cut hidden inside a shared shape or movement |
-| Dip | Quick dip through the background colour |
-| Speed ramp | Glide into slow-mo (or speed-up) and back out |
-| Beat cut | Cuts land on the beat of your music |
-| Tighten it | Silence and filler words removed, every join hidden as a punch-in |
-| Cut to the music | Whole edit built off the track: slow intro, faster build, hardest on the drop |
-| Film look | Grain, halation, light leak, gate weave (looks: clean, film, super8, cinema) |
-| Sound pass | Whooshes, impacts and risers placed off the cut list, ducked under the voice |
-| Morph into state | An element becomes its next state in place — the row you click turns into the confirmation, instead of one thing fading out and another in |
-| Directional blur | Anything moving fast smears and only resolves as it slows, including rolling digits and redrawing lines |
-| Overshoot and settle | Arrivals come in slightly too big, or just past the mark, and ease back |
-| Live data morph | A chart or list updates in place: only the data moves, the panel never re-enters |
-| Ghosted type-ahead | Text types itself into a pill that grows with it, the words still to come already there in pale grey |
+# Brief: {{name}}
+
+Fill in what you can. Plain words are fine. Leave a line blank if you don't care.
+When done: drop your files in this folder's `footage/` (and `screenshots/`), then run
+`npm run prep -- {{name}}` and start the session with "start {{name}}".
+
+## Basics
+Format: 16:9            <!-- 16:9, 9:16, or both -->
+Language: en            <!-- en, hi, ar ... the language you speak in the video -->
+Talking head file:      <!-- file name in footage/, e.g. —.mp4. Leave blank if there's only one clip. -->
+Background-free copy:   <!-- Optional. Leave blank. Only fill this in if you already export a
+                             version with the background removed or replaced by flat green; the
+                             cutout is built automatically from your normal footage otherwise. -->
+Length target:          <!-- e.g. 25s, 90s -->
+
+## Script
+<!-- Paste the script exactly as you read it. Numbers as digits: $99, 11 minutes, 3 days. -->
+
+
+## The one thing viewers must remember
+<!-- One sentence. Everything in the edit serves this. -->
+
+
+## Must-have moments
+<!-- By the words you say, not by time. Plain words are fine.
+- When I say "look at this" → my clip shrinks and other creators' clips appear
+- "millions of views" → a counter racing up to 1M+ -->
+
+
+## Moments from references
+<!-- READ FIRST, BEFORE ANY DESIGN DECISION. These, and the ones saved in references/references.md,
+     beat the house defaults wherever the two disagree. -->
+<!-- You DON'T need the name of the effect. Clip + time + what you like about it.
+     Format: - clip-file.mp4 mm:ss-mm:ss — what you like (feel words are fine: snappy, floaty, punchy)
+- a-reel-you-like.mp4 00:02-00:04 — the colour screens flipping with each phrase, feels punchy -->
+
+
+## Effects from the library
+<!-- Optional: pick any by name (see the list at the bottom), and say where.
+- colour flip → "different person, different story" -->
+
+
+## B-roll
+<!-- Which clip where, by the words you say. Mark clips you DON'T want used.
+- creators' clips → "all of these people"  -->
+
+
+## Screenshots / things to blur
+<!-- Names, emails, prices, logos that must not be readable. -->
+
+
+## CTA / ending
+<!-- What the viewer should do, and what the last frame shows. -->
+
+
+## Sound
+SFX library: audio/     <!-- put sound effects in this folder's audio/, or say "none" -->
+Music: added by me in Premiere / Instagram     <!-- or a file name in audio/ -->
+
+## Don't want
+<!-- Anything you dislike: e.g. boxes over my footage, huge text, bouncy motion. -->
+
+
+---
+
+### Effects library (names you can use)
+| Name | What it looks like |
+|---|---|
+| Text behind me | Big headline sits behind your head (works from normal footage) |
+| Card swap | You shrink into a rounded card, turn into another clip mid-shrink, a row of cards slides in and drifts |
+| Colour flip | Hard cuts to solid accent / ink screens on each phrase; a word rolls into the next and the colours swap |
+| Counter race | A number races up from 0 and lands on a value (e.g. 1,000,000+) |
+| Zoom-through cut | A jump cut hidden by a quick push-in that eases back — used on every cut by default |
+| Gradient CTA | Dark gradient rises from the bottom, small label + big word typed on the VO, then ticked pointers |
+| Browser mockup | Screenshots inside a clean browser window that pans and zooms to the detail |
+| Pointer click | An arrow glides to a spot and clicks, with a ripple |
+| Rolling number | Digits roll from one value to another (e.g. $26.50 → $48.94) |
+| Highlight marker | Accent marker wipes behind a key phrase |
+| Side card | You move into a card beside the graphics (16:9) or below them (9:16) |
+| Headline to pill | A big headline shrinks into a small corner tag that stays on screen |
+| Word-by-word captions | On by default (looks: clean, block, highlight, pop) |
+| Whip pan | Fast blurred pan between two unrelated shots |
+| Push | The next scene pushes the last one out |
+| Mask wipe | A soft-edged wipe reveals the next scene |
+| Match cut | Cut hidden inside a shared shape or movement |
+| Dip | Quick dip through the background colour |
+| Speed ramp | Glide into slow-mo (or speed-up) and back out |
+| Beat cut | Cuts land on the beat of your music |
+| Tighten it | Silence and filler words removed, every join hidden as a punch-in |
+| Cut to the music | Whole edit built off the track: slow intro, faster build, hardest on the drop |
+| Film look | Grain, halation, light leak, gate weave (looks: clean, film, super8, cinema) |
+| Sound pass | Whooshes, impacts and risers placed off the cut list, ducked under the voice |
+| Morph into state | An element becomes its next state in place — the row you click turns into the confirmation, instead of one thing fading out and another in |
+| Directional blur | Anything moving fast smears and only resolves as it slows, including rolling digits and redrawing lines |
+| Overshoot and settle | Arrivals come in slightly too big, or just past the mark, and ease back |
+| Live data morph | A chart or list updates in place: only the data moves, the panel never re-enters |
+| Ghosted type-ahead | Text types itself into a pill that grows with it, the words still to come already there in pale grey |

package/template/templates/STYLE.md

@@ -1,179 +1,179 @@
-<!-- This is YOUR style guide, and it starts deliberately half-empty.
-
-     Parts 1 to 6 are craft standards: things that hold for any brand, most of them
-     measured rather than argued. Leave them alone until you have a reason not to, and
-     your edits will come out clean rather than random.
-
-     Parts 7 and 8 are yours and begin blank. Every time you approve or reject something,
-     write it down there. That is the half that makes edits look like YOURS instead of
-     merely competent, and it is the half nobody can hand you. -->
-
-# House style
-
-What every edit must look, move and sound like. `CLAUDE.md` says *how* to build; this
-file says *what it must come out like*.
-
-When this file and a reference disagree, this file wins unless you say otherwise.
-
----
-
-## 1. Your identity
-
-Everything visual comes from `src/design/tokens.ts`. That file is the single source of
-your typeface, your colours, your spacing and your type scale — change it there and every
-video changes with it. Never hard-code a colour or a font family into a composition.
-
-- **Type:** one display typeface. Heavy weights for headlines, numbers and hero words;
-  medium for labels and pointers.
-- **Colour:** one accent, plus ink and a light ground. Resist a second accent — two
-  accents read as a template, one reads as a brand.
-- On footage: accent text, with a soft glow so it survives a busy frame.
-- On a light ground: ink text, with the accent used only to mark the word that matters.
-
-## 2. Type scale
-
-Sizes are a starting ladder, not a law. What matters is that you keep to *a* ladder.
-
-| Role | 16:9 (1920x1080) | 9:16 (1080x1920) | Notes |
-|---|---|---|---|
-| Hero word | 200–320px | 130–220px | One on screen at a time, never two |
-| Headline | ~116px | ~100px | Tight tracking, around -0.03em |
-| Big number | ~170px | ~150px | Tabular digits while a counter runs |
-| Label / eyebrow | ~40px | ~32px | Uppercase, open tracking, ~0.14em |
-| Pointer / list item | ~42px | ~36px | |
-| Captions | 46px | 42px | Crisp white, bold, soft dark shadow |
-
-**If a word needs to be bigger than the ladder to feel important, the layout is wrong,
-not the size.** Oversized type is the most common way an edit starts looking amateur.
-
-## 3. Layout
-
-- **The speaker stays full screen by default.** Rounded cards and frames around a talking
-  head make the edit look assembled rather than shot. A card is fine as a *transition*,
-  not as a container.
-- Put text in the clear space the shot already gives you: sky, a wall, out-of-focus
-  background. Check where the head lands on every cut before committing a position.
-- Captions live in one consistent zone per layout, over a dark area. They hide while the
-  same words are on screen as a graphic, and never linger into the next scene.
-- Graphics are built from type, numbers, real screenshots and real footage. Decorative
-  shapes that mean nothing age badly and read as filler.
-
-## 4. Motion
-
-- The motion laws in `CLAUDE.md`, always. Eased, motion-blurred, nothing pops into place.
-- **Zoom through jump cuts.** A small push on the cut hides the join; a hard snap exposes it.
-- **Hard cuts only as a deliberate burst** — a few beats of solid colour synced to the
-  words, then back to smooth. Everything else morphs from one state to the next.
-- Cover anything off-camera — reading, looking away, a fumble — with a graphic or a cut.
-- Counters start at zero and only go up. No grey placeholder digits.
-- Vary your shot lengths. Cutting everything to the same duration is the clearest sign
-  an edit was made by a machine rather than by someone making decisions.
-
-## 5. Sound (half the reel)
-
-- **The voice is never processed.** No reverb, no heavy compression, no "enhancement".
-- Sound effects are short — whooshes 0.4–0.8s, hits 0.3–0.6s — faded, and placed in the
-  gaps between words rather than under them.
-- Every new visual gets its own fitting sound. Reusing a sound that belonged to a
-  different look is the audio version of a template.
-- **Subtle beats loud.** Big cinematic impacts on text almost always read as too much.
-- Hand over voice and SFX stems plus a timecoded cue sheet with every delivery.
-
-## 6. Colour, film looks and presets
-
-**Most of a look comes from the shoot, not the grade.** Golden hour or one good window,
-light behind or beside the subject, background well behind the subject, white balance
-fixed rather than auto. Automated grading is a starting point and only when the footage's
-light already resembles the reference — on mismatched light it will look wrong, and you
-should trust your eye over any automatic match.
-
-| Transition | When |
-|---|---|
-| whipPan | Between unrelated shots. Never twice in a row. |
-| push | Moving forward through a list or a sequence. |
-| maskWipe | A calm reveal. Pairs with a soft sound. |
-| colourFlip | A burst on a phrase. Two or three, then back to smooth. |
-| matchCut | Only when both shots share a shape or a direction. |
-| dip | Changing subject without drama. |
-
-| Caption look | When |
-|---|---|
-| clean | Default. Works over almost anything. |
-| block | Busy or bright footage, where white alone gets lost. |
-| highlight | Keeps the eye on the word being spoken. |
-| pop | Fast edits. Not over heavy motion. |
-
-| Film look | When |
-|---|---|
-| none | Graphics, screen recordings, anything where text is the subject. |
-| clean | Default for a talking head. Enough grain to stop flat areas banding. |
-| film | B-roll and travel. The one to reach for first. |
-| super8 | Memory and nostalgia moments only. Never a whole video. |
-| cinema | A held, wide, quiet shot. |
-
-**Three things here were measured, not guessed. Do not quietly undo them:**
-
-- Grain composites **normally**, not with `overlay`. On flat cream or flat ink there are
-  no midtones, and overlay grain measures 0.000 stddev — the layer does nothing at all.
-- Grain is paid for in black level — blacks lift measurably at medium strength. Raise it
-  per shot when a nostalgia moment is worth milkier blacks; never raise the default.
-- Halation blooms **highlights only**. The plate is crushed to black before it is blurred
-  and screened back. Without that crush, a bright frame blooms end to end and the blacks
-  go brown.
-
-Speed ramps are eased, never a hard speed switch. Below 0.4x needs 50fps or higher source
-footage — you cannot rescue slow motion that was not shot for it.
-
----
-
-## 7. Where these defaults end and you begin
-
-The sections above are **defaults**: a starting point tuned so that a video made on day one,
-before you have told the system anything, comes out clean rather than embarrassing. Captions
-sit at a readable size with a measured shadow, cuts are eased, grain is restrained, the voice
-is untouched.
-
-Defaults are also the reason an edit can come out *anonymous*. They are what everybody gets.
-Three things move an edit from the default toward yours, in increasing order of power:
-
-**1. Your tokens.** `src/design/tokens.ts` carries your typeface, your colours, your scale.
-This makes an edit *yours to look at* immediately.
-
-**2. Your references.** Saved moments from edits you admire, each with a timecode and a note
-on what you like about that exact moment. These are read before the plan for every video, and
-they beat the defaults wherever the two disagree — a default is a guess that suits everyone,
-a reference is a fact about you.
-
-Roughly: **none** gives you clean and forgettable. **Three** is enough to spot a pattern.
-**Seven or eight** is enough to tell a preference from a coincidence, and it is where edits
-start looking authored.
-
-**3. This file, as it fills up.** Sections 8 and 9 are the part no default can supply and no
-competitor can copy, because they are a record of decisions only you have made. Every entry
-narrows the next edit toward what you actually want.
-
-Nothing here learns on its own. It gets better because the brief gets richer — so the ten
-minutes spent writing down why you rejected something is the highest-return ten minutes
-available to you.
-
----
-
-## 8. Approved (your effects library)
-
-<!-- Empty on purpose. When something works, write it down here: what it is, and where
-     you approved it. Next time you can ask for it by name instead of describing it
-     again, and every future video inherits the decision. -->
-
-| Beat | What it is | Where you approved it |
-|---|---|---|
-| | | |
-
-## 9. Rejected (don't do these again)
-
-<!-- This table is worth more than the one above. A list of things you have ruled out is
-     the fastest way to stop an edit drifting back toward generic, because it removes
-     options rather than adding them. Add a line every time you say "not that". -->
-
-| What | Why | Where |
-|---|---|---|
-| | | |
+<!-- This is YOUR style guide, and it starts deliberately half-empty.
+
+     Parts 1 to 6 are craft standards: things that hold for any brand, most of them
+     measured rather than argued. Leave them alone until you have a reason not to, and
+     your edits will come out clean rather than random.
+
+     Parts 7 and 8 are yours and begin blank. Every time you approve or reject something,
+     write it down there. That is the half that makes edits look like YOURS instead of
+     merely competent, and it is the half nobody can hand you. -->
+
+# House style
+
+What every edit must look, move and sound like. `CLAUDE.md` says *how* to build; this
+file says *what it must come out like*.
+
+When this file and a reference disagree, this file wins unless you say otherwise.
+
+---
+
+## 1. Your identity
+
+Everything visual comes from `src/design/tokens.ts`. That file is the single source of
+your typeface, your colours, your spacing and your type scale — change it there and every
+video changes with it. Never hard-code a colour or a font family into a composition.
+
+- **Type:** one display typeface. Heavy weights for headlines, numbers and hero words;
+  medium for labels and pointers.
+- **Colour:** one accent, plus ink and a light ground. Resist a second accent — two
+  accents read as a template, one reads as a brand.
+- On footage: accent text, with a soft glow so it survives a busy frame.
+- On a light ground: ink text, with the accent used only to mark the word that matters.
+
+## 2. Type scale
+
+Sizes are a starting ladder, not a law. What matters is that you keep to *a* ladder.
+
+| Role | 16:9 (1920x1080) | 9:16 (1080x1920) | Notes |
+|---|---|---|---|
+| Hero word | 200–320px | 130–220px | One on screen at a time, never two |
+| Headline | ~116px | ~100px | Tight tracking, around -0.03em |
+| Big number | ~170px | ~150px | Tabular digits while a counter runs |
+| Label / eyebrow | ~40px | ~32px | Uppercase, open tracking, ~0.14em |
+| Pointer / list item | ~42px | ~36px | |
+| Captions | 46px | 42px | Crisp white, bold, soft dark shadow |
+
+**If a word needs to be bigger than the ladder to feel important, the layout is wrong,
+not the size.** Oversized type is the most common way an edit starts looking amateur.
+
+## 3. Layout
+
+- **The speaker stays full screen by default.** Rounded cards and frames around a talking
+  head make the edit look assembled rather than shot. A card is fine as a *transition*,
+  not as a container.
+- Put text in the clear space the shot already gives you: sky, a wall, out-of-focus
+  background. Check where the head lands on every cut before committing a position.
+- Captions live in one consistent zone per layout, over a dark area. They hide while the
+  same words are on screen as a graphic, and never linger into the next scene.
+- Graphics are built from type, numbers, real screenshots and real footage. Decorative
+  shapes that mean nothing age badly and read as filler.
+
+## 4. Motion
+
+- The motion laws in `CLAUDE.md`, always. Eased, motion-blurred, nothing pops into place.
+- **Zoom through jump cuts.** A small push on the cut hides the join; a hard snap exposes it.
+- **Hard cuts only as a deliberate burst** — a few beats of solid colour synced to the
+  words, then back to smooth. Everything else morphs from one state to the next.
+- Cover anything off-camera — reading, looking away, a fumble — with a graphic or a cut.
+- Counters start at zero and only go up. No grey placeholder digits.
+- Vary your shot lengths. Cutting everything to the same duration is the clearest sign
+  an edit was made by a machine rather than by someone making decisions.
+
+## 5. Sound (half the reel)
+
+- **The voice is never processed.** No reverb, no heavy compression, no "enhancement".
+- Sound effects are short — whooshes 0.4–0.8s, hits 0.3–0.6s — faded, and placed in the
+  gaps between words rather than under them.
+- Every new visual gets its own fitting sound. Reusing a sound that belonged to a
+  different look is the audio version of a template.
+- **Subtle beats loud.** Big cinematic impacts on text almost always read as too much.
+- Hand over voice and SFX stems plus a timecoded cue sheet with every delivery.
+
+## 6. Colour, film looks and presets
+
+**Most of a look comes from the shoot, not the grade.** Golden hour or one good window,
+light behind or beside the subject, background well behind the subject, white balance
+fixed rather than auto. Automated grading is a starting point and only when the footage's
+light already resembles the reference — on mismatched light it will look wrong, and you
+should trust your eye over any automatic match.
+
+| Transition | When |
+|---|---|
+| whipPan | Between unrelated shots. Never twice in a row. |
+| push | Moving forward through a list or a sequence. |
+| maskWipe | A calm reveal. Pairs with a soft sound. |
+| colourFlip | A burst on a phrase. Two or three, then back to smooth. |
+| matchCut | Only when both shots share a shape or a direction. |
+| dip | Changing subject without drama. |
+
+| Caption look | When |
+|---|---|
+| clean | Default. Works over almost anything. |
+| block | Busy or bright footage, where white alone gets lost. |
+| highlight | Keeps the eye on the word being spoken. |
+| pop | Fast edits. Not over heavy motion. |
+
+| Film look | When |
+|---|---|
+| none | Graphics, screen recordings, anything where text is the subject. |
+| clean | Default for a talking head. Enough grain to stop flat areas banding. |
+| film | B-roll and travel. The one to reach for first. |
+| super8 | Memory and nostalgia moments only. Never a whole video. |
+| cinema | A held, wide, quiet shot. |
+
+**Three things here were measured, not guessed. Do not quietly undo them:**
+
+- Grain composites **normally**, not with `overlay`. On flat cream or flat ink there are
+  no midtones, and overlay grain measures 0.000 stddev — the layer does nothing at all.
+- Grain is paid for in black level — blacks lift measurably at medium strength. Raise it
+  per shot when a nostalgia moment is worth milkier blacks; never raise the default.
+- Halation blooms **highlights only**. The plate is crushed to black before it is blurred
+  and screened back. Without that crush, a bright frame blooms end to end and the blacks
+  go brown.
+
+Speed ramps are eased, never a hard speed switch. Below 0.4x needs 50fps or higher source
+footage — you cannot rescue slow motion that was not shot for it.
+
+---
+
+## 7. Where these defaults end and you begin
+
+The sections above are **defaults**: a starting point tuned so that a video made on day one,
+before you have told the system anything, comes out clean rather than embarrassing. Captions
+sit at a readable size with a measured shadow, cuts are eased, grain is restrained, the voice
+is untouched.
+
+Defaults are also the reason an edit can come out *anonymous*. They are what everybody gets.
+Three things move an edit from the default toward yours, in increasing order of power:
+
+**1. Your tokens.** `src/design/tokens.ts` carries your typeface, your colours, your scale.
+This makes an edit *yours to look at* immediately.
+
+**2. Your references.** Saved moments from edits you admire, each with a timecode and a note
+on what you like about that exact moment. These are read before the plan for every video, and
+they beat the defaults wherever the two disagree — a default is a guess that suits everyone,
+a reference is a fact about you.
+
+Roughly: **none** gives you clean and forgettable. **Three** is enough to spot a pattern.
+**Seven or eight** is enough to tell a preference from a coincidence, and it is where edits
+start looking authored.
+
+**3. This file, as it fills up.** Sections 8 and 9 are the part no default can supply and no
+competitor can copy, because they are a record of decisions only you have made. Every entry
+narrows the next edit toward what you actually want.
+
+Nothing here learns on its own. It gets better because the brief gets richer — so the ten
+minutes spent writing down why you rejected something is the highest-return ten minutes
+available to you.
+
+---
+
+## 8. Approved (your effects library)
+
+<!-- Empty on purpose. When something works, write it down here: what it is, and where
+     you approved it. Next time you can ask for it by name instead of describing it
+     again, and every future video inherits the decision. -->
+
+| Beat | What it is | Where you approved it |
+|---|---|---|
+| | | |
+
+## 9. Rejected (don't do these again)
+
+<!-- This table is worth more than the one above. A list of things you have ruled out is
+     the fastest way to stop an edit drifting back toward generic, because it removes
+     options rather than adding them. Add a line every time you say "not that". -->
+
+| What | Why | Where |
+|---|---|---|
+| | | |