# Margin kit: guide for editors

*Margin is a working name.* This kit gives you **12 short animation blocks** (a few seconds each) for English-lesson videos, plus a **brand book** that explains the colours, fonts, layout and motion. Each block is a web page: you type your content, it animates, and you bring it into DaVinci Resolve.

- Brand book: https://titi-motion-lab.pages.dev/experiments/08-brand-kit/
- Block library: https://titi-motion-lab.pages.dev/experiments/08-brand-kit/blocks/

You don't need to write any code for steps 1 to 4.

---

## 1. Fill in a block

1. Open the **block library** and click a block, e.g. **Mistake**.
2. On the left is the **edit panel**. At the top, **"Fill with an example from Arnel's script"** loads a ready-made example. Start from one of those.
3. Change the text in the **Content** boxes. The preview updates and replays on its own.
4. A few conventions the blocks understand:

| You type | Where | What it does |
|---|---|---|
| `pho-TO-gra-pher` | Syllables | Hyphens split syllables; the one in CAPITALS is stressed. (`pho-'to-gra-pher` also works.) |
| `[photographer:noun]` | Sentence, Pattern, Compare examples | Square brackets = highlight this word. `:noun` / `:verb` / `:adj` / `:adv` adds a class tag. |
| `complain + to + someone` | Pattern formula | `+` separates chips. Words like *subject, verb, something, someone* become open slots. |
| `word \| class \| note` | Word family, Drill | One line per item. The `\|` separates the columns. |
| `→` and `*stars*` | Section title | → becomes a drawn arrow; `*word*` becomes the italic accent. |
| `freeze - froze - frozen` | Verb forms | Hyphens with spaces around them separate the forms. |

5. **Timing** (in the panel):
   - **Speed**: makes the build-up faster or slower (0.5× to 2×) to match Arnel's voice.
   - **Hold**: how many seconds it stays still after building, so viewers can read.
   - **Total**: if you need an exact length (e.g. 8 s), type it here and the hold adjusts. 0 = automatic.
   - **Lead-in**: a short empty moment before it starts (handy when recording).
   - **Exit animation**: untick it if you'd rather cut or cross-dissolve in Resolve.
6. **Look**: theme (Ink / Daylight / Chalk), background (brand / transparent / chroma green / chroma blue), safe area (left 55% for the narrator layout, full frame, or centred), text size, **Narrator guide** (a dashed outline of where the narrator sits, never recorded) and **Card plate** (puts the block on a solid card).
7. Press **Replay** (or the R key) to watch it again, and Space to pause. Drag the scrub bar to check any moment.

**Warnings under the Look section tell you when:** the text is too long for the safe area (shorten it or split it into two blocks), or a colour in this block would be removed by the chroma key.

## 2. Save a block as a link

Everything you type is stored **in the page address**. So:

- **Copy link** copies the address of this exact filled-in block, with the panel. Paste it into your notes, a spreadsheet next to the script line, or a message. Opening it later brings back the same content and settings.
- **Copy clean link** copies the same block **without the panel**, full screen, for recording or exporting.
- The browser also remembers the last thing you did in each block. **Reset to the first example** clears it.

Tip: keep a simple sheet with one row per script moment: *time in the video · block link*. That's your whole motion plan.

## 3. Get it into DaVinci Resolve

### Option A: transparent PNG sequence (best quality, no keying)
You need Node.js (nodejs.org) and Google Chrome, installed once.

1. Download **margin-kit.zip** (brand book → Downloads), unzip it, and open a terminal in its `08-brand-kit/tools` folder.
2. Run once: `npm install`
3. For each block: click **Copy clean link** in the panel, then run
   ```
   node export-frames.mjs --url "PASTE THE LINK" --fps 25 --out mistake-09 --mov
   ```
   Use the frame rate of your timeline (25, 30…). The link can be the live website address, so you don't need to run a web server.
4. You get a folder `mistake-09/` of PNG frames with a real transparent background. With `--mov` you also get `mistake-09.mov` (ProRes 4444 with alpha) if ffmpeg is installed.
5. In Resolve: **Media Pool → Import** the folder (it shows up as one clip) or the .mov, and put it on a track **above** your narrator and background.

The **How to export…** button in each block shows this command with the link already filled in.

### Option B: screen-record
1. In the panel set **Background** to the brand background (the easiest), or to **Chroma blue / green** if you want to key it over something else. The panel tells you which chroma colour is safe for that block. With a chroma background, **Card plate** turns on by itself, because dimmed text needs a solid card behind it to key cleanly.
2. Click **Open clean view**, press **F11** for full screen, start recording (OBS, Xbox Game Bar Win+Alt+R, or ⌘⇧5 on a Mac) and click the page to replay the block.
3. In Resolve: trim the clip. If you used chroma: **Effects → 3D Keyer**, pick the background colour.

Record at 1920×1080. If your screen is a different shape, the block letterboxes itself, so crop in Resolve.

### Using the brand in Resolve
- **downloads/margin-brand-sheet.png**: put it in the Media Pool as a reference and eyedrop colours from it.
- HEX codes are in the brand book (Colour section) and `downloads/margin-palette.json`.
- Fonts are in `brand/fonts`. Install Lexend, Instrument Serif, Andika and Caveat on your computer to use them in Resolve's Text+ titles.

## 4. Change the brand

All colours, fonts, sizes, the safe area and the motion timing live in **one file: `brand/tokens.css`**. Every block and the brand book read from it.

- **Change a colour:** find the line, e.g. `--k-hl:#FFD23F;` (the Highlighter), and replace the HEX. There are three blocks of colours: the first is **Ink** (default), then `[data-theme="daylight"]` and `[data-theme="chalk"]`.
- **Change a font:** put the new `.woff2` file in `brand/fonts`, add an `@font-face` line like the ones at the top of the file, and change `--k-font-body` (words and sentences), `--k-font-title` (titles), `--k-font-ipa` (phonetics) or `--k-font-pen` (handwritten notes).
- **Bigger or smaller text everywhere:** change the type scale (`--k-t-hero`, `--k-t-sentence`…), or just use the Text size slider for one block.
- **Slower or faster motion everywhere:** change `--k-dur-m`, `--k-beat` or the easing curves at the bottom of the file.
- After editing, you can run `node brand/sync-tokens.mjs` to refresh `tokens.json` and the palette downloads (.json, .ase, .gpl). Optional.

To add a **new theme**, copy the whole `[data-theme="chalk"]{…}` block, rename it (e.g. `[data-theme="sunset"]`) and change the colours. Then add it to the Brand theme menu in `kit/kit.js` (search for `"chalk", "Chalk"`).

## 5. Add a new block type (for a developer, or a brave editor)

1. Copy a block folder that's close to what you want, e.g. `blocks/word` → `blocks/idiom`.
2. In `blocks/idiom/block.js` change `id: "idiom"` and `name: "Idiom"`, then edit:
   - `fields`: the boxes in the panel (`k` is the name used in the link, `def` the default text).
   - `examples`: presets for the example menu.
   - `build`: creates the elements and returns a function that adds the animation to a timeline. Use the helpers in `kit/kit.js`: `K.label`, `K.tag`, `K.hl` (highlighter), `K.rise`, `K.pop`, `K.swipe`, `K.draw` with `K.mark.check/cross/arrow/underline`, and so on. Colours and sizes come from `tokens.css` variables such as `var(--k-hl)` and `var(--k-t-word)`.
3. Put styles for the block in `blocks/idiom/style.css`, starting every rule with `.k-b-idiom`.
4. Add a line for it in the `K.catalog` list at the top of `kit/kit.js` so it appears in the block menu.
5. Run `node kit/make-pages.mjs` from the `08-brand-kit` folder. It creates `blocks/idiom/index.html` and refreshes the library page.
6. Optional: `node tools/make-thumbs.mjs http://localhost:8808/experiments/08-brand-kit/` (with a local server running) refreshes the gallery images and the brand sheet.

Rules to keep the system consistent: text only inside the safe area, at most one emphasis at a time, Highlighter only as a fill, Iris for what changed, green and red only with ✓ and ✗, and no blur or glow.