# explainer-assets

Adopt this skill: https://proskills.md/skills/other/busybee3333-animated-explainer-skills-skills-explainer-assets

Page: https://proskills.md/skills/other/busybee3333-animated-explainer-skills-skills-explainer-assets
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/explainer-assets/SKILL.md
size: 6966
sha: dc26956aeac0dce678e73fba6b4f21c874effa32
upstream: https://github.com/busybee3333/animated-explainer-skills/blob/main/skills/explainer-assets/SKILL.md

```text
---
name: explainer-assets
description: 'Generate crafted SVG/CSS components, props, characters, and environments for animated explainer videos — the build order, light rules, factory patterns, and engineering contracts that make assets read as illustrated objects AND survive choreography. Use when creating or upgrading any visual asset: a prop, mascot, component system, or background world.'
user-invocable: true
---

# Explainer assets — generating components and source art properly

Every asset in an explainer is either a **component** (chips, bars, cards, stamps — styled DOM), a **prop** (vessels, pages, cabinets, gauges — inline SVG), a **character** (host mascot, population minions — SVG factories), or an **environment layer** (parallax worlds — data-URI or inline SVG). Each has its own build discipline. The difference between "styled div" and "crafted object" is a fixed sequence of cheap moves — never skill, always order.

## The universal build order (any prop, every time)

1. **Silhouette first.** Flat single-fill shape at the FINAL footprint (left/top/width/height and viewBox locked before any detail). Get the read at thumbnail size — if the silhouette doesn't say "bucket," no amount of detail will.
2. **One light source, top-left, film-wide.** Then: 2-tone via `linear-gradient(180deg, lighter, base)` on the body, top gloss (`inset 0 2px 0 rgba(255,255,255,.3-.5)` or a highlight path), bottom shade (`inset 0 -3px 0 rgba(0,0,0,.1)`).
3. **Depth cues — the 3 that sell 3D:** a DARKER inner-opening ellipse for any mouth/rim (this single ellipse is what makes an opening read as 3D); a soft base-contact shadow ellipse; inter-unit shadow lines between stacked parts (drawers, sheets).
4. **Detail pass — 3 to 5 accents max:** bands/hoops with a 1px white highlight edge, label plates, grain lines, corner ticks, a specular curve. Stop before it gets busy; Kurzgesagt props are simple shapes with perfect light.
5. **Motion hooks LAST, planned not patched:** the class the timeline will target, a wrapper `<g>` for any transform the animation will own, and the pivot decided NOW (see svgOrigin below). An asset built without motion hooks gets rebuilt.

## Component systems before one-offs

Never style one chip. Build the SYSTEM in CSS once — every variant inherits:
- **The sticker recipe:** hard down-right ink drop (`3px 3px 0 var(--ink)`) + top gloss inset + bottom shade inset + `inset 0 0 0 1-2px rgba(255,255,255,.14)` die-cut rim. Translucent insets ride ANY background color, light or dark — one rule elevates every variant.
- One radius scale (sm 10 / base 13 / lg 16), one shadow angle, one light direction.
- **Text-safe rule:** on components carrying animated text (SplitText chars), gloss must be inset box-shadows (paint UNDER text) — never a positioned `::before` overlay (paints OVER the glyphs and dims them).
- Stamps get ink-bleed: same-hue soft `text-shadow` (glyphs) or shared `drop-shadow` filter (SVG marks).
- Drawn line-art (arrows, boxes): ONE selector — `filter: drop-shadow(0 1.5px .5px rgba(0,0,0,.17))` on all `.drw` strokes gives every arrow a 2-tone underside and reveals WITH DrawSVG (filters are independent of dashoffset).

## Character factories

Characters are **JS functions returning SVG strings**, not static markup — one edit upgrades every instance.
- **Singleton host** (one instance, e.g. the flying mascot): MAY carry `uid`-suffixed `<defs>` gradients (`'bwg'+uid`) for iridescent wings, radial antenna balls, body sheen. Expose a **faces API** (`host('aha'|'sad'|'happy', size)`) — swap eyes/brows/mouth blocks, keep everything else.
- **Multi-instance minions** (inlined 10-50×): must be **id-FREE** — plain fills only (wing vein stroke, top highlight ellipse, stripe highlight lines, cheek dot) or gradient ids duplicate across the document and break rendering.
- **Class-hook contract:** wrapper classes the CSS animates (`hwrap` bob, `hwl/hwr` wing flutter, `heyes` blink) are API — never rename during an asset pass without updating CSS + JS + docs together. New decorative transforms go on INNER wrapper `<g>`s so they compose with (never fight) the CSS animation on the outer hook.
- Ground-contact shadow under every character; badges/accessories as optional factory args.
- **Props characters hold get full prop treatment** (the pencil: gradient hex body + facet lines + specular, crimped ferrule, eraser cap with darker rim, wood taper with grain, graphite cone — same anchor/axis as the arm rotation expects).

## Environments (parallax worlds)

- Three layers with fixed roles: **far** (sky gradient, sun/moon, haze band, 2-tone volumetric clouds = tinted base ellipse + 3 white circles + bright top ellipse, far hills), **mid** (hero landmarks — hive/buildings with real detail, layered-petal flowers), **near** (blurred foreground foliage, CORNERS ONLY so it never covers captions, leaf midribs + side veins).
- Every layer needs a variant per scene mood (warm/paper/cold/dark) — same shapes, recolored; dark gets moon + fireflies.
- Ambient characters (drifting minions, dust motes) live in **margins and the top strip only** — their full drift path must never cross a text band.

## SVG engineering contracts (each one has broken production)

- **Pivot planning:** a px `transformOrigin` on an SVG group is BBOX-relative — rebuilding the group's geometry silently moves the pivot (a gauge needle swung off-stage for a full scene this way). For fixed pivots in SVG user-space always use GSAP's `svgOrigin:'x y'`, decided when the asset is built.
- **Selector inventory before touching anything:** grep the script for every class/positional selector; `.bkt3 path` means the FIRST `<path>` must remain the tweened body — lead with `<ellipse>` shadows, never a decorative path.
- **Footprint freeze:** re-crafting keeps left/top/width/height/viewBox identical; `overflow:visible` lets back-sheets/stacks peek without moving the box. Placement changes are a separate, deliberate pass.
- **Decorate timeline-driven props with pseudo-elements** (`::before` ruled lines, tape, cracks, meniscus) — they ride the transform with zero new choreography. Track which pseudos are "taken" per class; collisions are silent.
- **Hide with autoAlpha** (visibility:hidden), not bare opacity/scale — invisible elements must not leave phantom boxes that fool overlap audits.
- Files need `<meta charset="utf-8">`; HTML entities in DOM text, `�` escapes in JS strings.

## Quality gates for any new/changed asset

1. Reads correctly at 100% AND at thumbnail scale (the silhouette test).
2. One light direction across the whole frame — a new prop lit differently is a defect.
3. No flat fills on anything bigger than an accent.
4. `node --check` the script block + full selector-survival checklist after any DOM surgery.
5. Overlap audit (0.5s steps) after placing it — an asset isn't done until it coexists with everything else on stage.
```

## File: README.md
upstream: https://github.com/busybee3333/animated-explainer-skills/blob/main/README.md

````text
# Animated Explainer Skills — build Kurzgesagt-quality explainer videos as self-contained HTML

Everything you need to produce a **Kurzgesagt-style animated explainer video** that plays like a finished YouTube animation — layered parallax worlds, a flying host mascot, physics-feeling choreography, a seekable player — and ships as **one self-contained HTML file**. It's a complete production system: the choreography **patterns**, a **YouTube-retention method**, a **0.5s-resolution overlap auditor**, and a **per-scene ElevenLabs voiceover pipeline** — packaged as [Claude Code](https://claude.com/claude-code) skills **and** as standalone docs + tools you can run without Claude.

[![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](LICENSE)
[![GSAP 3.13 — free](https://img.shields.io/badge/GSAP-3.13%20free-88CE02.svg)](https://gsap.com/)
[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)

---

## New here? Start guided

Copy `skills/` into your project's `.claude/skills/`, then tell Claude Code: **"use explainer-studio and guide me through building an explainer about &lt;topic&gt;"** — it walks you through all 7 phases (script → assets → choreography → retention → gates → voiceover → publish) with an exit checklist at every step.

## What you get

- **Four skills**: `explainer-studio` (**start here** — the guided 7-phase path from blank file to published video), `explainer-assets` (generating crafted components, props, characters & worlds), `gsap-explainer` (choreography + production), `retention-pass` (the YouTube-retention method).
- **A runnable 5-scene reference build** (`skills/gsap-explainer/scaffold.html`) with every pattern in context — the worked example is "How Compound Interest Snowballs", fully swappable.
- **Physics that feels physical** — `CustomBounce` drops with **squash-and-stretch** (the squash *is* the weight), `Physics2D` bursts with replay-identical index-seeded debris.
- **The Kurzgesagt "fuse" move** — `MorphSVG` turns N objects into the concept they represent ("same objects, new shape", literally).
- **A camera rig** — vignette + grain, per-cut parallax dolly across 3 depth layers, push-ins on payoffs, scene-cut wipes.
- **A flying host mascot** that points, taps, hops and reacts — a friendly bee by default (like Kurzgesagt's birds), rebrandable by swapping one SVG string.
- **Population-as-characters** — quantities are little characters, not dots.
- **A seekable player** — click-to-seek bar, chapter ticks, ←/→ keys, autoplay-on-scroll, reduced-motion fallback.
- **A 3-round YouTube-retention method** — hook/peak loop audit, dead-zone killing, VO-sync, freeze-frame verification.
- **A 0.5s-resolution pairwise overlap auditor** — catches "words on words" and host-strikes-headline collisions the frozen preview silently hides.
- **A per-scene ElevenLabs voiceover pipeline** — write at 2.5 words/sec, synth one clip per scene, auto-report which scenes to extend.

## Quickstart

**With Claude Code (recommended):**
1. `git clone` this repo.
2. Copy the skills into your project: `cp -r skills/gsap-explainer skills/retention-pass /path/to/your/project/.claude/skills/`
3. Ask Claude Code: **"build me an explainer video about \<your topic\>"** — it picks up the `gsap-explainer` skill and follows the method.

**Standalone (no Claude):**
1. `git clone` this repo, then `cd skills/gsap-explainer`.
2. `python3 inline-gsap.py scaffold.html` — fetches GSAP 3.13 from the public CDN into a gitignored `vendor/` and inlines it.
3. Open `scaffold.html` in a browser. It plays. Now duplicate it and replace the scenes with your content, using the reference scenes as your idiom source (read `skills/gsap-explainer/SKILL.md` — it's a full standalone manual).

## Tools

**Overlap auditor** — inject into the running page, then sweep every scene for collisions at 0.5s resolution:
```js
// paste skills/gsap-explainer/tools/overlap-audit.js into the console
__ovlAuditAll(0.5)   // -> { S3: [ {a, b, pen, ...} ] }  (empty = clean)
```

**Beat auditor** — map choreography coverage vs scene durations, find dead zones:
```bash
node skills/retention-pass/tools/beat-audit.mjs your-video.html
# prints per scene: last-beat time, coverage %, gaps > 4s
```

**Voiceover pipeline** — generate one ElevenLabs clip per scene + a fit report:
```bash
export ELEVENLABS_API_KEY=...        # or put it in ./.env
python3 skills/gsap-explainer/tools/vo-generate.py your-video-script.md ./vo <voiceId>
# S0: 12.3s / 15s = 82%  OK
# S3: 31.4s / 30s = 105% OVER -> extend scene to 33
```

## The method

The short version: **script → scaffold → choreography → retention pass → VO-sync → zero-overlap gates → VO pipeline.** Write a shot script first (per scene: duration, visual, on-screen text, VO line). Copy the scaffold. Replace scenes one at a time, adapting patterns instead of inventing them. Run the retention pass *before* recording VO (that's when durations are free). Clear the overlap auditor at 0.5s steps. Then generate per-scene voiceover and extend any scene its clip overran.

The full pipeline narrative for humans is in **[docs/METHOD.md](docs/METHOD.md)**. The two skills — [`gsap-explainer`](skills/gsap-explainer/SKILL.md) and [`retention-pass`](skills/retention-pass/SKILL.md) — are the exhaustive references, readable on their own.

## FAQ

**Why HTML instead of After Effects?** It's diffable, scriptable, and version-controllable; it ships as a few hundred KB of vector that plays in any browser; every quantity, label and timing is data you can edit in seconds; and an LLM can author it. You screen-record the playback to get an MP4 for YouTube.

**Is GSAP really free?** Yes — 100% free, including every formerly-premium plugin (DrawSVG, MorphSVG, SplitText, Physics2D, MotionPath, Flip, the Custom* eases, ...), since Webflow's 2025 acquisition of GSAP. This repo ships no GSAP code; `inline-gsap.py` fetches it from the public CDN for you.

**Can I rebrand the mascot?** Yes. The default host is a friendly bee (Kurzgesagt-style). To reskin: change the color tokens in the scaffold's `:root` and replace the `host()` SVG string. The faces API, arm-pointing, and flight rig all keep working.

**Does it work without Claude Code?** Yes. The skills are Markdown; the tools are plain Python/Node; the scaffold is a normal HTML file. Claude Code just automates following the method.

## Contributing

PRs welcome — new choreography patterns, additional host mascots, retention findings, and tooling improvements especially. Keep the scaffold self-contained and the tools dependency-free.

## License

MIT — see [LICENSE](LICENSE).

---

<sub>Keywords: animated explainer video · GSAP animation · Kurzgesagt style · Claude Code skills · motion design · YouTube retention · educational video · SVG animation · ElevenLabs voiceover.</sub>
````