thumbnails

Thumbnails

A thumbnail has one job: make the right viewer pick this video over the ones around it, and promise something the video then delivers. Platforms reward the promise being kept: YouTube's Test & Compare picks a winner by watch-time share, not clicks, so a thumbnail that over-promises wins the click and loses the test. Good here means clear in under a second, true to the video, distinct in the feed, and made without visible seams.

What holds

• The idea beats the template. No single design feature (face size, palette, word count, logo size) reliably wins across channels; what the thumbnail promises, and how literally it shows it, does. Spend the effort on the concept. Evidence and its strength: references/evidence.md.
• Real beats generic. Real product UI, real code or a diagram, the people who are in the video, and a line that states the payoff do better than a branded title card.
• Nobody predicts the winner, people or models, so the test decides. Arms must be genuinely different bets, not tweaks of one design.
• Legibility is physics. The smallest desktop render is about 215 px wide and a phone shows about 375 px; light type on a dark ground reads slower at those sizes, where size and weight carry it.

Fixed facts

• Platform. 16:9, at least 1280×720, ideally 3840×2160, under 50 MB (2 MB from a phone). One A/B arm under 1280×720 drops every arm to 480p. The duration badge covers the bottom-right corner. Hover and autoplay replace the thumbnail with the video's first seconds, so the opening should pay it off.
• Truth. Show only what the video contains: its real UI, code, numbers and people as they look. Quote people word for word. Never generate a person's likeness, a product screen, a logo or a number.
• Identity. The real mark from /workspace/brand/logos/ and the brand's type (/workspace/brand/tokens.css). Everything else (imagery, illustration, colour, composition) is chosen for the idea; the palette is home base, not a fence.
• People. Text the requester supplies ships as written, in their casing; their explicit edit outranks anything in this skill.

How to work

A small edit to a delivered thumbnail is: change it, re-render, run the gate, look, deliver. A new thumbnail, or a refresh of an older one, is a loop:

1. Understand the video. From the transcript (transcribe_audio if you only have the file) name the one thing a viewer walks away with, who it is for, who appears, and which real artifacts exist: a product screen, a diagram, a code moment, a good frame of the speaker. Ask for what you cannot get (a screenshot, a headshot), at most two questions.
2. Diverge before you draw. Write six to ten one-line concepts, each a different bet: the product doing the thing, the person, the verdict or claim, the diagram, the before and after, the number that is the finding. Drop the dishonest and the generic; render the best four to six quickly.
3. Build the strongest well. An HTML page authored at 1280×720 CSS px, words and the real mark set in HTML on top of whatever visual the idea needs: a frame from the footage, a real screen, a diagram (data-viz), a generated scene or object without text (image-generation). Mark the title data-thumb-role="hero" with px top/left/width/height so its contrast is measured.
4. See it as a viewer. Render, gate, and look at the small-size sheet, not the 4K file. Then give a fresh helper only the brief, a transcript summary and the sheets, and ask it to find defects and say whether each arm promises what the video delivers. A model's preference between arms is one opinion, not a prediction. Keep every version: a middle one is sometimes the best.
5. Deliver the set. Up to three arms, each a different bet, with one line on what each tests, safest honest arm first (an inconclusive test keeps the first). Lead with the small-size sheets, then the full-size files, in one upload_files call.
6. Learn from the result. When an approver states a standing preference or a test ends, record the arms, the bet each made and the winner's share where the project keeps its notes; your own results outrank everything in this skill.

Instruments

node /workspace/tools/html2png.mjs projects/<slug>/thumbnail/a.html --out projects/<slug>/renders \
  --name thumb-a --size 1280x720 --scale 3 --brand-fonts            # a 3840x2160 master
node /workspace/skills/thumbnails/scripts/thumb-gate.mjs projects/<slug>/renders/thumb-a-1280x720.png \
  --comp projects/<slug>/thumbnail/a.html
node /workspace/skills/thumbnails/scripts/small-size-gate.mjs projects/<slug>/renders/thumb-a-1280x720.png
node /workspace/tools/brand-lint.mjs projects/<slug>/thumbnail/a.html

• thumb-gate fails (exit 1) only on what the platform rejects or degrades: not 16:9, under 1280 px wide, over 50 MB. Everything else prints as a measurement for your judgment (resolution, phone upload size, drawn content under the duration badge, the hero's words, size and measured contrast, rasters drawn wider than their pixels). Exit 2 means it could not look; report it.
• small-size-gate writes one sheet: the frame with player chrome, the phone size on a light feed, the smallest rail size on a dark feed, and grayscale. Look at it; it decides nothing.

Cutting out and grading a person, product screenshots, alignment, type size, quotes and generated imagery: references/craft.md.