Make Thumbnail

You're helping the owner design and render a YouTube thumbnail for one of their videos using the bundled studio at studio/thumbnails/. The studio is a Vite + React + Puppeteer pipeline producing 1280x720 PNGs that can either stay local or be uploaded to the owner's workspace (when connected). The thumbnail carries the owner's own brand, read from the root brand/brand.json, so every render is on their palette and their name.

Where the concept comes from. Inside the YouTube factory, the packaging concept (title options, angle, thumbnail concept) arrives from plan-my-youtube's pipeline row for the video, so you are executing a concept rather than inventing one. The studio's craft is brand-agnostic: it renders on whatever brand brand/brand.json carries, for any kind of video.

One studio, one brand. The bundled studio/thumbnails/ on the root brand/brand.json is the home, and that resolves itself for a single-brand install. If the working directory happens to hold a second thumbnail studio or a second brand kit (an owner running two businesses), confirm which brand this video belongs to before rendering and say which studio you used. Never render into a studio locked to a different brand: off-brand output, and its own lint will reject it.

The design rules + title patterns + banned framings live in three canonical files inside the studio (read them BEFORE designing anything, not after):

The methodology distilled from those three is also summarised at knowledge/youtube-thumbnail-method.md.

Step 1 — Confirm the brief

If a plan-my-youtube pipeline row or a <slug>.script.json packaging block exists for this video, read it first: the working title, the angle, and the thumbnail concept are already chosen there, so you're executing a concept, not inventing one. Otherwise, ask the owner for:

1. What's the video about? One-sentence outcome the viewer gets.
2. A working title already picked? If yes (from the channel plan or the owner), reuse it for SEO consistency. If no, you'll generate one following the YOUTUBE_TITLES.md patterns, on the owner's brand.
3. Hero family — what's the visual centrepiece going to be? This is the step whose size varies, so be honest with the owner about which path they're on:
   • A shipped hero fits, so reuse it (quick, JSON-only). The registry (heroes/index.js) ships two families. The CRM/workspace surfaces (pipeline, contacts, forms, approvals, e-signing, reports, and so on) carry software topics. And three topic-agnostic starter heroes carry trade and tutorial videos: step-checklist (a numbered how-to stepper), before-after (a starting-point to now transformation), and big-number (one bold stat, cost, or result). So a plumbing how-to reuses step-checklist and a "real cost of X" video reuses big-number: set "hero": "<key>" in samples.json and you're on the fill-in-JSON path.
   • Nothing fits, so a new hero gets authored (the rare case now). Only when none of the stock heroes carry your topic. An unknown key falls back to the generic activity card, which fails the squint test, so author a genuinely new React hero component and register it (real React work, following the "Adding a hero" steps in heroes/index.js), not a JSON edit. Say so before you start. With the starter heroes in stock, a trade or tutorial video usually reuses one, so this is the exception.

Step 2 — Add the design to samples.json

Run the interactive helper:

cd studio/thumbnails
npm run make

It asks for a key (lowercase, kebab-case), headline (4-7 words), accent word (which word in the headline gets the brand gradient fill), and the hero registry key. Writes a new entry to src/data/samples.json.

If the helper isn't available (the operator interrupted it / running non-interactively), edit src/data/samples.json directly. The minimum shape is:

"my-video-key": {
  "composition": null,
  "template": "youtube-thumbnail",
  "data": {
    "headline": "Forms That Auto-Fill Your CRM",
    "accentWord": "Auto-Fill",
    "hero": "forms",
    "title": "How to Build & Send Forms in Your Workspace"
  }
}

Step 3 — Iterate in the browser

Make sure the dev server is running:

npm run dev    # opens at http://localhost:3210

The left sidebar shows the new design. Click it. The right pane renders the live preview at actual pixel dimensions. Tweak samples.json or the hero / template files — Vite hot-reloads.

Quality checks before declaring it shipped:

1. Title check — does the title pass YOUTUBE_TITLES.md's own rules (it owns the word band and the lint, so read it rather than a copy here), and does it lead with the viewer's outcome?
2. Headline check — does the on-thumbnail headline have one accent word that appears VERBATIM in the title? Read the JSDoc in YouTubeThumbnail.jsx.
3. Hero check — does the hero look like real product UI (not a configurator)? Read the heroes/index.js header.
4. Guardrails — no third-party vendor names visible in the thumbnail, no invented number or claim, and the headline names something concrete rather than a vague mood (a vague headline is a craft failure: there is nothing for the eye to catch). Whether the owner frames it as a win or as a problem they solve is THEIR call, not this skill's (knowledge/content-rules.md).

Step 4 — Render to PNG

npm run shoot <design-key>

That runs puppeteer + real Chrome and writes the PNG to studio/thumbnails/output/. Opens it automatically when done. Inspect it at 100% — there are CSS features (background-clip:text, backdrop- filter) that ONLY render correctly via real Chrome, not via in-browser rasterisation libraries.

If something looks off in the rendered PNG that looked fine in the browser, the JSDoc has a "Common mistakes" section worth reading.

Step 5 — Publish (optional, when connected)

The keyless deliverable is the rendered PNG. If the operator has a connected workspace, you can also upload the PNG to their own workspace, in the Files > Images area under a YouTube Thumbnails folder:

npm run publish <design-key>

Auth resolves the same way as the BOS Python tools: $TRUSTPAGER_API_KEY env var first, then ~/.claude/bos.json. The script handles idempotency — re-running publish with the same design key skips if the file's unchanged, renames if the title shifted, replaces only on --replace.

To publish every design in one shot:

npm run publish -- --all              # skip existing
npm run publish -- --all --replace    # wipe + re-upload

Hard rules

• Don't invent design rules. The three canonical files in the studio (README, YOUTUBE_TITLES.md, the templates JSDoc) are the source of truth — they distil real corrections from 22+ iterations. Read them.
• The operator owns the title. Generate a draft if asked, but don't ship without their nod.
• Render before declaring done. A design that looks right in the Vite dev server can still misrender in puppeteer if it uses unusual CSS features. Run npm run shoot and look at the actual PNG.
• Examples ≠ inspiration to copy. The 6 PNGs in studio/thumbnails/examples/ are the studio's bundled example thumbnails. They show the design DNA but are not templates to clone verbatim.
• Publish is optional. If the operator wants the PNG to stay local (post manually to YouTube studio), skip publish. The shoot output in studio/thumbnails/output/ is the deliverable.