Skip to content

OffchainLabs/arbitrum-docs / .claude/skills/arbitrum-brand-video-explainers

arbitrum-brand-video-explainers

Verified

Use when asked to rebrand, restyle, re-pace, resize, or re-render an existing explainer video, when a video's labels are baked-in raster pixels that cannot be edited, when a reviewer says an animation shows the wrong mechanism, or when building a new animated explainer or short looping animated diagram for the Arbitrum docs from a prompt or a doc section.

Arbitrum brand video explainers

Overview

A rendered video cannot be edited. Its labels are pixels on a raster grid — there is no "Block 1" text object, only pixels shaped like one. The deliverable is always a generator script, never an edited MP4. You rebuild the animation as code, then render it.

That makes the job two separate problems, and the second is not the hard one:

  1. Recover the content from the source (or invent it, from a prompt).
  2. Render it in brand styling at the requested pace.

When to use

  • "Make this video match our branding" / "restyle this animation"
  • "Slow this down so people can follow it" / "re-pace this"
  • A video is the wrong aspect ratio, or its text is too small at display size
  • "The animation shows the wrong behaviour" (a reviewer comment on an MP4)
  • Building a new animated explainer, or a short animated diagram, for a docs page

When NOT to use

  • Interactive or clickable diagrams → React widgets under components/widgets/. Those stay editable and respond to the site's dark mode; a video does neither.
  • Static concept art → arbitrum-brand-svg-diagrams.
  • Screen recordings of real UI → keep the recording, just trim/crop/compress.
  • Never Mermaid or any text-DSL animation tool (standing team preference).

Pick the deliverable first

Two formats, one generator discipline. Decide before any layout work; changing later means a rewrite.

BriefDeliverableWhy
A loop under about 15 s, fewer than about 15 moving parts, inline next to a paragraphCSS-animated SVG in public/img/, 8–15 KBNo player, scales with the column, renders through <ImageZoom>, markdown mirrors get the end-state frame
Longer, narrated, transcribed from a source video, or more than one sceneMP4, 1600×900, 30 fps, yuv420pA long CSS timeline is unreadable and cannot be re-paced per scene
Either, and the reader must step, pause, or clickNeither: a React widgetOut of scope here

Where the files live

A video or animation is three files, and all three are committed together:

public/img/<name>.svg | <name>.mp4        the rendered deliverable
docs/explainers/<name>/build.py           the generator
docs/explainers/<name>/SOURCE.md          one line per displayed value, with its source
docs/explainers/<name>/render.json        MP4 only: SPEED, fps, frame count, duration

render.json is what makes "keep the same pace as last time" a lookup instead of a reverse-engineering job: without it, the tempo has to be recovered from the frame count.

examples/ under this skill is read-only reference. Copy an example out to docs/explainers/<name>/ before changing a line, so the committed MP4 keeps a generator that a checkout cannot revert.

The failure this skill exists to prevent

An agent asked to restyle or slow down an explainer with no guidance correctly rebuilds it as a generator and still ships fabricated numbers, in a video that looks entirely plausible:

What goes wrongResult
Re-simulated the concept instead of transcribing itEvery transaction value in all six blocks was invented
Mis-read one chip and moved on4+7 rendered where the source shows 11
Expanded an acronym the source never expandsTwP became "two-way priority" — a fabricated technical term
Fitted a per-transaction gas model to make totals workIts own totals contradicted the readouts it claimed to reproduce (164 vs 161, 160 vs 187)
Tagged a block "sealed early" while showing its round-2 contentSelf-contradictory frame

None of these are visible by looking at the output. A plausible-looking wrong number is worse than an obviously broken render, because it ships.

The transcription contract

Every value you display must be traceable to a frame you actually read.

Before writing any rendering code, produce SOURCE.md containing:

  • one line per datum, with the frame number it came from
  • an explicit UNKNOWN for anything you could not read
  • a CONFLICTS section (see below), even when empty

Then treat that file as the only source of truth. Rules that follow from it:

  • Never fit, interpolate, or infer a displayed number. If a counter is not derivable from what is on screen, transcribe the observed values at the frames you sampled and script those. "Fitted so the totals work" is fabrication with arithmetic on top.
  • Never expand an acronym the source does not expand. Carry it verbatim and flag it to the user.
  • Never assume one displayed number derives from another. In the worked example the chip labels are tips and block gas is independent — chips reading 31 + 9 sit in a block whose gas ends at 34. Assuming gas = sum(chips) would have made every number wrong in a way that looks reasonable.
  • Recompute derived labels from the data, not from the source's pixels. A card tagged "sealed early" must be tagged by the same rule that decides whether round 2 ran.
  • A label that names an action appears only on the steps where that action happens. A forceInclusion sublabel that stays up during the outcome where force inclusion is not used is a factual bug, and only a probe frame finds it.

When the source is wrong. A reviewer comment that says the mechanism is wrong, or a docs page that contradicts the video, outranks the video. Write the conflict under CONFLICTS in SOURCE.md (what the video shows, what the prose says, which one you followed), follow the prose, and flag it to the user. When two docs pages contradict each other, pick one, record both, and flag it the same way. This is the one case where transcribe-exactly does not apply.

When the brief is a prompt, the contract inverts: you own the data, so write SOURCE.md first and show its contents in the question that asks for confirmation. A question that covers only scope and pace has not confirmed the data. Do not discover the content while writing the renderer.

Reading a source video

See references/reading-a-source-video.md for the extraction technique — ffprobe first, then the select + tile filter to read dozens of frames in a single image, and cropping to a status region to recover a state machine cheaply.

Labels are prose: read STYLE-GUIDE.md before you draft them

STYLE-GUIDE.md at the repo root governs every label and caption. Read it before writing the first label, not after the render: the write hook only fires on an MDX edit, so nothing else catches it. Sentence case, active voice, no "e.g.". Restyling is the moment to fix copy such as HEAVY LOAD and skipped — block filled in round 1, not to preserve it.

Pipeline: MP4

# 1. generate one TRANSPARENT svg per frame, into the session scratchpad
python3 docs/explainers/<name>/build.py --out "$SCRATCHPAD/<name>"

# 2. composite over the brand background and encode
bash .claude/skills/arbitrum-brand-video-explainers/tools/render.sh "$SCRATCHPAD/<name>/f" public/img/<name>.mp4 30

render.sh rasterises frames in parallel and composites them over a once-rendered background (726 frames → MP4 in about 40 s). Keep frame SVGs transparent: inlining the 44 KB background into every frame gives an identical picture several times slower.

Start from a copy of examples/pga-rounds/build.py. Replace its source-data block and layout; keep its keyframe/tween engine:

  • KEYS is a list of (duration, state). render(a, b, u) interpolates.
  • Chips carry stable ids, so a chip that changes slot between two keyframes glides; one that appears fades in; one that leaves fades out.
  • Tempo is a single constant (SPEED). Re-pacing is a one-line change, and the value goes into render.json with the fps and frame count.

Pipeline: CSS-animated SVG

Start from a copy of examples/nonce-retry-buffer/build.py. It is a single file that writes the SVG, and with a second argument writes a static frame at time t for verification. The recipe it follows:

  1. Base attributes are the end state. Every chip's transform, every caption's opacity, the timer's inline style, all describe the last frame. The keyframes override them while the loop runs. This is what gives you the prefers-reduced-motion fallback, a meaningful rsvg-convert render for the contrast gate, and a sensible image in the markdown mirror, for free.
  2. One <style> block, one @keyframes per moving element, percentages computed from a single LOOP constant. Position is transform: translate() (plus rotate() where a piece tumbles); visibility is opacity. A bar that grows or drains is transform-box: fill-box with scaleX() or scaleY() and transform-origin on the fixed edge (left center, bottom center), never an animated width or height.
  3. Captions are chips: a #152c4e rect at 92% opacity under #eaf5ff text, one per phase, stepped with animation-timing-function: step-end.
  4. A label shares the group of the thing it describes. A label placed as a sibling is visible from frame 0, before the thing it names has happened.
  5. The loop resolves the story. End on the state the reader must act on, and let it hold for a second before the fade. A loop that stops at the error leaves the obvious follow-up question ("and what if nonce 7 arrives late?") unanswered, so animate the answer in.
  6. Wire it into the page as <ImageZoom><img src="/img/<name>.svg" alt="…" data-wide /></ImageZoom>, with the full description in alt and the same text in the SVG's <desc>.

Icons and motion

RuleWhy
An icon uses three or more brand colours and its defining detailsA one-colour silhouette was "barely identifiable as a boot"; laces, a toe cap and a sole made it read
Draw the icon at a comfortable size, then wrap it in scale()A 74 px boot covered the label it kicked past; scaled to 0.7 it sat in the free band
A rotated piece pivots on its group origin, so lead the contact pointA −10° kick pulled the toe 6 px off the chip it was meant to hit; move the hit point in by that much
Every fixed element clears every panel, measured, not eyeballedThe colour key overlapped the sequencer panel by 10 px until its width was derived from the panel's x
Chips travel on straight segments; no easingLinear motion reads as mechanism; easing reads as decoration

Brand rules

REQUIRED BACKGROUND: arbitrum-brand-svg-diagrams owns the palette, the measured contrast table, the background asset, and check_contrast.py. Do not copy colour values around — read that skill.

Video-specific additions:

RuleWhy
MP4: 1600×900matches bg-frag.svg's native 16:9 exactly and the docs diagram family
MP4: keep content clear of x<330 AND y>810the brand logomark sits there; a full-width bottom panel clips it
SVG loop: brand gradient on a full-bleed rect, canvas to contentthe baked background is 44 KB for a loop that weighs 10
Run check_contrast.py on probe frames, not every framepick the extreme states — busiest, emptiest, and the one lowest on the gradient
Text on the lower gradient sits on an opaque card#c9dcef on the gradient at 75% depth measured 3.18:1
Text on magenta is #ffffff, never a tint#ffd6ec on #e6007a measured 3.46:1; white is 4.52:1 with no headroom
format=yuv420p when encodingwithout it the file plays in VLC but shows black in Safari
Orange is not the accent#ff7700 is Nova-specific, and white on it is 2.66:1

build.py --one N (MP4) or build.py out.svg <t> (SVG loop) writes a single frame with the backdrop in place, which is what check_contrast.py needs to sample the true backdrop.

check_contrast.py reads each label's own x/y and ignores a parent <g transform>. A chip label inside a translated group reports a FAIL against the gradient at the canvas origin. Confirm the real pairing with a zoom crop of the rendered frame and note the false FAIL in the hand-off; do not restructure the diagram to please the tool.

Verify against what you produced

MP4. Extract frames from the MP4 you made, not from your SVGs:

ffmpeg -v error -i public/img/<name>.mp4 -vf "select='eq(n\,60)+eq(n\,300)+eq(n\,520)+eq(n\,700)',tile=2x2,scale=iw*0.5:ih*0.5" -frames:v 1 -y grid.png

Then diff what you see against SOURCE.md, value by value. Also sample four consecutive frames mid-transition to confirm motion interpolates rather than cuts.

SVG loop. rsvg-convert ignores CSS animation, so bake frames instead:

for t in 1.2 3.4 6.0 8.6 9.8; do python3 build.py "$SCRATCHPAD/f_$t.svg" $t && rsvg-convert -b '#ffffff' -w 500 "$SCRATCHPAD/f_$t.svg" -o "$SCRATCHPAD/f_$t.png"; done
magick "$SCRATCHPAD"/f_*.png -append "$SCRATCHPAD/sheet.png"   # then read the sheet

The baked frames prove the choreography. Prove the browser runs it with the Claude-in-Chrome extension (/chrome in the session): serve public/img with python3 -m http.server 8765 --bind 127.0.0.1 (file:// is blocked), navigate to the SVG, and run document.getAnimations().length — it must equal the number of @keyframes you wrote. The Playwright and chrome-devtools MCPs hung on this in testing; do not spend more than one attempt on them. Stop the server and close the tab when done.

Red flags — stop and go back to the frames

  • "I'll fit the numbers so the totals work out"
  • "TwP probably stands for..."
  • "close enough to the original"
  • "I'll re-simulate the same concept" (that is invention, not transcription)
  • "The animation looks right" (looking right is what fabrication looks like)
  • Any displayed value you cannot name a frame number for
  • A generator that exists only in the scratchpad after the deliverable is committed

Common mistakes

MistakeFix
Editing the MP4 with ffmpeg filtersYou cannot change baked-in text. Rebuild as a generator.
Editing examples/*/build.py in placeCopy it to docs/explainers/<name>/ first. The example is reference; the copy is the project's generator and is committed with the deliverable.
Writing the deliverable to the repo rootpublic/img/<name>.svg or .mp4, like every other docs image.
Keeping the source's aspect ratioRe-lay out to 1600×900 unless asked otherwise.
Bottom panel spanning full widthClips the logomark. Start it at x≥340.
Deciding pace/styling/canvas yourselfThese are expensive to redo. Ask first — they materially change the layout. If you cannot ask, default to about 2x the source duration, because 4x reads as stalled.
Rendering before checking contrastProbe two frames first; a 700-frame render is 40 s wasted otherwise.
Animating width/height on an SVG rectBrowsers differ; scaleX()/scaleY() with transform-box: fill-box is uniform.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 196kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 196kUpdated Claude CodeCodexVerifiedInstall