Communitygithub.com

Stepwise Mechanism Animation

Explain a mechanism, principle, or process as one web page that advances a single step at a time, with a sentence on the left and the moving parts on the right.

What is Stepwise Mechanism Animation?

A teaching animation that opens a system and walks the viewer through cause and effect, one scroll at a time.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/QichangZheng/mechanism-animation/tree/HEAD/mechanism-animation

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Mechanism Animation (mechanism-animation)

Turn "how does it work" into a one-page step-by-step animation: the reader takes one step per scroll, each step explains one thing, and elements in the diagram appear, move, and disappear in causal order.

Reference: assets/template.html, a template with a built-in 4-step example (no cache → add a layer of cache). Open it directly in a browser.

0. Should You Make an Animation?

Start with the cheapest option and only move to the next when the previous one can't explain clearly:

LevelWhat to UseWhen It's Enough
1Just write it outTwo or three sentences can explain it
2Numbered steps (1. 2. 3.)It's a process, but each step is one sentence; the reader doesn't need to "see" it
3Numbered steps + 2–3 static images (before/after comparison)Structure or relationships; or a process that can be understood with two or three static snapshots
4This skill: step-by-step animationExplaining where things go, sequential order, shared data, or what step saves something, and three static images are not enough

Decision rule in one sentence: If you freeze the diagram at any frame and the reader still understands ⇒ static images suffice; if you need to see the motion to understand ⇒ make an animation.

Two boundaries:

  • Cost. Animation is several times more expensive than static images (fact-checking, sequencing, timing, testing, back-and-forth revisions). When no one explicitly asks for animation, propose it first, explain why the first three levels are insufficient, and get agreement before starting; do not default to animation.
  • Animation is only for "first-time understanding", not as a reference material: can't be skimmed, searched, or pasted into documentation. Therefore, the page must end with a "full process overview" (the template auto-generates one line per step); keep the original text version of the documentation and add a link to the animation page; do not replace the documentation.

1. Workflow

  1. Fact check. Animation vividly teaches errors. Before drawing, verify the mechanism against code / design documents / papers, distinguishing "designed this way" from "code currently does this" from "others (papers, defaults) do this". Mark guesses as "inferred, pending verification".
  2. Write a storyboard (no code). Follow references/storyboard.md to list a table: one row per step, clearly stating what one thing this step explains, what appears / moves in sequence on the screen, what remains at the end, and the left-hand text. Only start coding after the storyboard passes the rules in Section 2. If the number of steps is large (> 6) or you're unsure about the narrative, first discuss with the requester: send only the table plus one question for them to decide, not a full document; if the requester prefers to see the final product, just build it.
  3. Start from the template: cp assets/template.html <output-dir>/<name>.html. Only modify three areas:
    • HTML <title>, intro page (#top), diagram aria-label, ending page (#where, including the footer "Updated: Year-Month · Version checked against") — these still contain example content; replace each one;
    • Script Section A: PAGE, MODULES (modules, steps, text, duration per step);
    • Script Section C: visuals (what objects exist, how each step moves). Sections B1 / B2 are the engine and are generally not touched. Writing conventions, utilities, and common patterns can be found in references/engine.md.
  4. Self-test: node scripts/check.js <page.html> <screenshot-dir>. 10 items with no FAIL (contain is SKIP when the page has no corresponding tag, normal). Then manually review each screenshot: step-NN (end of each step), mid-NN (mid-step), page-NN (full page). The script can only check "did it stop, is text overlapping, did it go out of bounds, are fonts large enough", not "is the explanation clear". A 4-step page takes about 1 minute; a 12-step page about 3 minutes. Dependency installation and usage are at the end of engine.md. 4.5 (For many steps or when explaining to non-experts) "First-time viewer" test: Give a sub-agent who knows nothing about this mechanism and has read no prior material only the screenshot of each step in sequence. Ask them to review sequentially, then recall from memory what each step explained, whether they learned from the diagram or the text, and what they didn't understand. What they fail to understand is the page's problem, not theirs — more effective than reviewing ten times yourself.
  5. Deliver: Send the page (a single HTML file, no external dependencies) to the requester. After every subsequent change, rerun the self-test before delivery.
  6. (For critical content) Technical review: After the page is finalized, run a read-only review. Check every sentence and number against code and documentation line by line, producing a list of "wrong / misleading / imprecise" items, and let the requester decide what to fix. The review only checks facts; narrative quality is for the requester to evaluate.

2. Rules for Narration (most important, learned from rejections)

Order

  • Easy before hard, normal case before problem case. The reader needs to see normal behavior first to understand the problem. Example: first show multiple containers sharing memory in one VM (normal), then show each VM having its own copy when you have many VMs (problem), then the solution.
  • Bottom-up, layer by layer. First only the host → data from disk to host memory → VM appears → data into VM → finally the application inside. Don't display all boxes at the start, and don't let the application appear before the data arrives.
  • When multiple events in one step have a causal relationship, sequence them; don't make them simultaneous. "Container exits" then "its memory becomes free" then "returned to host".
  • The diagram appears only after scrolling stops; the first step's animation plays from the beginning. The template already handles this; don't break it.

What each step explains

  • One step, one thing, the title is that thing ("Each page reads once"), not a noun ("Read phase").
  • The main narrative only shows the actual practice. Default values, other approaches, or historical solutions should be mentioned in one sentence under the step's key points with "why this special approach", not made into a separate step — otherwise the reader thinks the actual practice also requires that step. (Counterexample: first "report at 2 MB" then "report at 4 KB"; reader asks "where did 2 MB come from? Which came first?")
  • Two steps that look identical will be perceived as the same thing. If two scenarios differ, visualize the difference (multiple arrows converging on the same data, a circle highlighting the shared copy), don't just state it in text.
  • Every number and word in the diagram must have a source. Numbers not previously introduced ("18", "2 MB") will trip up the reader; either introduce them or remove them.
  • A problem specific to one solution belongs in that solution's module, not in a general introduction where the reader assumes it applies to all.
  • Use concrete examples the reader recognizes, not abstract symbols. Lines, dots, and short bars moving around leave the reader wondering what they are (reader's original: "Those 4 progress bars... I don't know what they mean"). Replace them with something describable: who, to whom, said what (the "payment system" Agent asks the "data platform" Agent "How to call the order interface?", the latter replies "Interface documentation sent"); if you must use symbols, use ones the reader has already seen earlier (those rows from the previous list), don't invent new ones. One well-explained example is better than three abstract interactions; if one example is good, add a different one rather than repeating the same one three times.
  • Don't draw layers and objects not used in this step. "Appearing layer by layer" doesn't mean every layer must appear: when explaining "container returns memory to the VM", drawing the host adds a layer the reader must recognize without gaining understanding (reader's original: "Don't need to show the host, it's too complicated"). Before drawing, ask: without it, does the step's sentence still hold? If yes, remove it.
  • Answer "so what?" Each module's final step or the ending page should state: what this means for the reader, where things stand now (live / only in test / not yet done).
  • Depth is set by the reader. Before starting, write down "who is the reader, what do they already know, what don't they care about": explaining basics to an expert is tedious; piling up implementation details for a layperson is too specific.

Text

  • Each step: one sentence (lead) + at most 2–3 bullet points, bold only for conclusive numbers or terms. If the left text is too long, delete details; put details in the ending page or a small note at the bottom right of the diagram.
  • Don't reference things yet to come. Words like "no longer store separately", "still", "same as", "that copy", and "the one" must refer to something already introduced. After reordering chapters, read the text from beginning to end in the new order.
  • Explain a term the first time it appears with a half-sentence definition; use one name for the same thing throughout the page.
  • No internal names on the page: RFC numbers, PR numbers, filenames, function names, command names, internal machine names. Exception when the reader is the developer of this code.
  • Don't break lines between terms and "number + unit": wrap them in {{ }}, e.g., {{4 KB}}, {{1,380 billion tokens}}.
  • Footer: "Updated: Year-Month · Version of code checked against". The page is a snapshot of that day; code changes over time.
  • Mark inferred or unverified items as "inferred" or "pending verification"; for others' numbers, specify whose ("paper", "POC", "main branch").

Visuals

  • The same object is the same thing throughout: a data block flies from disk to memory, then to the VM, not disappears here and reappears there. The reader tracks the process through it.
  • Colors have fixed meanings, consistent across the page (e.g., cyan = data, purple = program, orange = happening action, blue = conclusion / returned item). Legend only for colors used.
  • Actions also have fixed meanings, not varied across the page (e.g., orange line drawn = sending a request, colored block flying = data delivered, orange circle = the shared copy, entire group fading = no longer needed). Similar actions at consistent speeds: flying further takes longer, don't compress all to the same duration.
  • State is indicated by color, and only two or three states: e.g., "blue = in use, gray = released". The reader can count how many blues and grays at a glance, so that later "grays are reclaimed" makes sense; don't simultaneously use color + icon + text for the same state.
  • Text to be read stays still: if a sentence must be transmitted from A to B, keep it stationary beside the speaker, send only a small marker along the line; the reader reads the stationary text and watches the marker's path. If the text flies with it, the reader sees neither clearly.
  • First move, then pause: the main action of a step finishes within the first 60% of the time, then the scene is quiet for the reader to read the left sentence; two important actions don't happen simultaneously; significant movements last at least half a second, crossing the whole diagram at least 0.7 seconds — faster and the eye can't follow.
  • Exit the way you entered: lines that draw a box retract to erase it; something that flew in flies out. Use only two or three entry/exit techniques across the page; don't default to fade in/out.
  • Multiple lines converging on the same target enter from different directions (one from left, one from top, one from right), not side by side on the same edge: they will overlap or pass behind other shapes (reader's original: "The phone's line and the client's line overlapped, and the phone itself blocked the client's line").
  • If the meaning is correct but it's not visually pleasing, it's not done (reader's comment on a cloud: "Meaning is correct, but the cloud is too ugly and rigid"). For key graphics (those that appear repeatedly or are the focus of the final step), draw two or three versions side by side, then pick one; while choosing, ask: does the line style match the rest of the page? Is the proportion comfortable? Can it be distinguished from the lines behind?
  • Highlights (circles, arrows, orange small text) appear only when mentioned, then disappear, at the latest at the start of the next step, not carried into subsequent steps. The end state of each step must make sense on its own (step-NN.png captures this).
  • For shared/same item: multiple arrows merge into one landing on the same target, plus an orange circle.
  • "Saved" or "returned" must be shown: the object flies to the corresponding segment on the usage bar, then that segment shrinks; don't shrink while flying. The destination must align with the segment that shrinks.
  • When schematic and real sizes don't match, mark "schematic" and don't let the grid size imply a non-existent unit.
  • Box nesting and names follow real ownership: before drawing, list "object → its real network namespace / container / process / service". Independent containers or processes (sidecar, proxy) are drawn as separate boxes, not inside business containers; the outer box clearly states what it is ("network namespace of a pod"), and the box name uses the reader's mental name ("business container", not "main container"); distinguish same-named items by ownership (when two services each have a component named sidecar, use full consistent names); avoid mixing in diagrams and left text.
  • Minimize line bends: endpoints land on the opposite edges of two boxes, not aiming at the box center; if the boxes' heights overlap, use a straight line; if a bend is needed, use one clear corner (max two for a U-shape around obstacles), avoiding text; data packets, red lines, etc. traveling the same path share these corners. Small bends make the reader think "this has special meaning". check.js's bends item will flag this.
  • Place explanatory small text beside the box, not on top of objects inside.
  • Text in the diagram is at least 14 canvas units. On a 13-inch laptop, the diagram shrinks to about 0.8x; smaller than that is illegible; check.js's fontsize item will flag anything below 11px at 1280×720. If it doesn't fit, delete content, not shrink text. The template also has a "zoom in" feature (top button / F key), which is an option for the reader, not a remedy for small text.

3. Common Reworks (when you receive this feedback, fix it this way)

FeedbackLikely CauseFix
"This step's animation didn't finish / has an issue at the end"Keyframes extend past the step's end, or a fade-in is stuck at the exact end timeAll actions in this step start before T(id, 0.88) and stop before T(id, 1); check.js's still item will flag
"Text flew out of the box / position is wrong"Parent box and child content start moving at different times; a keyframe only changed color but froze the positionUse the same timing for parent-child; mark them with data-box / data-in and use the contain item frame-by-frame. Don't substitute other metrics (font size, opacity) for "inside or outside the box"
"Step N and Step M look the same"Difference is only in the textVisualize the difference (see above: converging arrows + circle)
"Where did X come from?"A number/unit in the diagram is not introducedExplain the source, or remove from the diagram and only mention in "why"
"Wrong order; should be A then B"Not sequenced by causality / hierarchyReorder this step's timings using "bottom-up"; also check all other steps with the same rule
"XX is strange; wasn't mentioned before"Text references something yet to be introducedGrep for "no longer", "still", "same as", "that copy", "the one", "compared to", and verify each referenced item has appeared
"Too much text / can't read / too small"Details piled in the left column; diagram text less than 14Reduce to one sentence + bullet points; increase diagram text to ≥14; delete if it doesn't fit; check.js's fontsize and text items will flag
"Scrolling from the home page has no animation on the first step / no animation after refresh"Broke the engine's entry logicDon't touch Section B2's enteredFirst, pendingShow, or the initial lines; check.js's wheel item will flag
"Why is there this bend?" (with screenshot)Arrow aims at the box center, or each bend calculated independently causing back-and-forth bends; data packets and lines on the same path each have their own bendsPlace endpoints on opposite edges; go straight if possible; maximum one corner; data packets and lines share corners; check.js's bends item will flag. Check all lines across the diagram
"Is X an independent Y? Should it be drawn inside Z?" "Should this be called... for accuracy?"Box nesting doesn't follow real ownership (sidecar drawn inside business container), or box name uses internal terminologyFirst create a "object → real ownership" table, then fix nesting; outer box clearly states what it is; rename boxes to reader's mental names; verify all similar boxes across the diagram

After receiving one piece of feedback, first consider if the same feedback applies to other steps, and fix them all at once; don't wait for the requester to point out each one.

4. Files

FileContent
assets/template.htmlTemplate (engine + 4-step example)
scripts/check.jsSelf-test script (10 items + screenshots)
references/storyboard.mdHow to write a storyboard; a real 12-step storyboard
references/engine.mdTemplate structure, utilities, visual patterns, pitfalls, how to run self-test
references/lessons.mdFeedback records from several completed pages (source of the rules); when a rule doesn't cover your case, look for the closest one here

Related Skills