Video Thumbnail Template

video-thumbnail-template

Turn a channel's thumbnail style into a design guideline (a brand kit) and a CoDesign template with named slots, then fill the template for each new video.

Builds on, without restating: the handbook loop, the brand skill's kit format, the layerize skill (Seedream decomposition), the models skill, the formats skill (youtube-thumbnail.md) and the judge gate.

Input

One of three, resolved with the intake contract (../handbook/intake.md):

• Channel link — its latest 10 thumbnails set the style.
• Example thumbnails or designs — one or more images, or design files (.imgly, .psd, …).
• Nothing — start fresh; ask for the visual direction per the intake contract.

The format defaults to youtube-thumbnail (1280 × 720). Everything goes into one output folder (default ./<channel-or-topic>-thumbnails/): reference/, brand-kit/, the template and the thumbnails. References live in the CoDesign workspace, not on disk: reference/refs.md lists them. A thumbnail style is the channel's brand: never invent it when references exist.

1 — Collect references

Every reference comes in through import as a one-page design; nothing is downloaded or copied to disk. Take them one at a time, because the next import moves on to a new design: import it, preview() it and record its layout (step 2), then read the image's uri in a read-only edit (render: false) — the imported image is the page's fill, (await engine.design.getProps(page, ['fill'])).fill.image.imageFileURI. reference/refs.md lists, per reference, the video id or file name, the page size and that uri, which stays valid after you move on. A reference is never saved: if the next import refuses over unsaved edits, repeat it with discard: true.

Channel link. CoDesign cannot read web pages, so the video ids come from your host's built-in web-fetch tool — used only to read the channel's /videos page (e.g. https://www.youtube.com/@handle/videos); no shell, no downloads. That tab lists regular uploads only, newest first; the ids are in the page source as "videoId":"<11 chars>". Take the first 10 distinct ids. Without a web-fetch tool, or when the page cannot be read, ask the user for links to their latest videos and take the id from each (watch?v=<id>, youtu.be/<id>, /shorts/<id>). Then import({ source: { url: 'https://i.ytimg.com/vi/<id>/maxresdefault.jpg' } }) for each id — public URLs, no API key or login. A 404 means the video has no full-size thumbnail: import hqdefault.jpg instead, a 480 × 360 frame whose 16:9 picture sits between black bars.

Example thumbnails. import({ source: { path } }) each file the user named. A design file goes through import the same way — its layers show the structure directly.

Nothing. No references; go to step 3 with the direction the user chose.

2 — Analyse the layouts

Look at every reference yourself — its preview from step 1. For each one, record its layout — positions and sizes as fractions of the canvas, so they compare across images:

• zones: where the host, the headline and the subject sit, and how much of the canvas each takes
• headline: the words, line count, the role of each line (hook vs punch word), case, relative size, colour, stroke, shadow, closest Google Font
• host: side, crop, expression, gaze, outline or glow
• background: image or colour, mood, whether it repeats
• devices: arrows, badges, frames, blur, emoji

Then compare the set: what repeats in most references is the system, what appears once is an option, and what changes from video to video becomes a slot. A set that splits into two or three distinct layouts gets one template per layout — name them and ask which to build if unsure.

3 — Design guideline (brand kit)

Write the guideline as a brand kit in the brand skill's format — brand-kit/tokens.json + brand-kit/BRAND.md. Read ../brand/reference/brandkit-spec.md for the shape and reference/authoring.md for the rules (screenshots are its source form D). Fill it from the analysis:

• colorPrimitives / semanticColors — the colours sampled from the references (say they are sampled)
• typography — the headline font(s), weights, case and the size ratio between the lines
• layout / composition — the zones from step 2, as fractions of the canvas
• safeArea — the platform's (the duration badge, bottom right, for YouTube)
• imagery — host crop and treatment, background mood
• device — the recurring devices
• voice — headline formulas: words per line, the punch words in use
• logo — the channel's mark if the thumbnails carry one; otherwise record it in $meta.gaps

Draft the avoid list from what the references never do and confirm it with the user, as authoring.md requires.

Starting fresh, the guideline comes first too: turn the chosen direction into the same kit, show the user its key choices (palette, fonts, layout) and confirm them before building.

4 — Layers and assets

When a reference supplies a host, subject or background worth reusing, split it with the layerize skill's Stage 1 (Seedream) and follow its rules, with the reference's uri from refs.md as the source image — it is already in the workspace. Keep the person, subject and residual background layers; drop the text layers — the headline is rebuilt as live text.

A user's host photo that is not cut out goes through background removal (models skill, bria-rmbg.md). A missing background can be generated from the kit's imagery mood, format: '16:9', with "no people, no text, no logos" in the prompt.

5 — Build the template

Build from the kit: one page at the format size, the zones from layout, back to front. Name the slots so they can be filled later:

Drop host when the style has no presenter; decoration from the style gets its own descriptive name. When a headline line is too long for its column, shrink it until it fits — never let it run to the edge or into the safe-area corner.

Test the template with a long punch word, a word with a capital diacritic (ÜBERNIMMT) and a thumbnail without the optional slots, then run the judge loop with the kit as the brief. The references are the style: tight headlines or a host bleeding off the canvas are not faults.

Export it with export({ format: 'imgly', outPath }) into the output folder and report the kit, the slots and any $meta.gaps.

6 — New thumbnails

For each thumbnail, start from the saved template — import({ source: { uri } }) with the uri its save returned — never chain one thumbnail onto the previous. Fill the slots, hide the empty ones, fit the headline, and export JPEG (export({ format: 'jpeg', blockId: <page>, outPath }); YouTube rejects uploads over 2 MB). Each import is a copy, so the template stays as it was; export({ format: 'imgly' }) a filled thumbnail only when the user wants it editable too. Look at every export and check it against the kit's avoid list.

For a batch, agree on a simple table with the user (e.g. a CSV with one row per video: headline lines and image files) and repeat the above per row. If they want to render outside the agent, write them a small @cesdk/node script that loads the exported .imgly, fills the same slots by name and exports each row; without a CE.SDK licence key it watermarks its output — say so.

Common mistakes