Communitygithub.com

unit-story

Build an animated unit visualization where every item is its own mark - each test question, request, invoice, user or sample is a dot - and the dots move between arrangements (one pile, split by model, coloured by outcome, sorted) to tell a story about counts, composition and uncertainty. Includes showing small-sample uncertainty honestly with intervals and hypothetical outcome animations. Use when someone wants to visualize evaluation or benchmark results per item, compare models on a test set, show how many of N failed, explain why "0 out of N" or a small sample does not prove much, or make results tangible for a LinkedIn post, slide or README.

What is unit-story?

unit-story is a Claude Code agent skill that build an animated unit visualization where every item is its own mark - each test question, request, invoice, user or sample is a dot - and the dots move between arrangements (one pile, split by model, coloured by outcome, sorted) to tell a story about counts, composition and uncertainty. Includes showing small-sample uncertainty honestly with intervals and hypothetical outcome animations. Use when someone wants to visualize evaluation or benchmark results per item, compare models on a test set, show how many of N failed, explain why "0 out of N" or a small sample does not prove much, or make results tangible for a LinkedIn post, slide or README.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/k-sandhu/visual-explainer-skills/tree/HEAD/skills/unit-story

Ask in your favorite AI

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

Documentation

Unit story

"The model failed 18% of the time" is abstract. Forty dots with seven of them red is a thing you can see and count. Unit charts show the denominator, keep each item identifiable, and make proportions concrete (natural frequencies are easier to reason with than percentages: Gigerenzer and Hoffrage, 1995). Moving the same dots between arrangements lets one picture answer several questions in sequence without the reader losing track of what a dot is.

Build with explainer-kit (scaffold.py --kind stepper) using s.units and s.arrange.

The arc

  1. One dot is one item - show a single item large: its input, its expected answer, what a model did. Then shrink it into a dot and let the rest of the set appear around it. The reader now knows what a dot means. Say the count ("Each dot is one of 120 questions").
  2. Split - arrange the dots by group (model, method, category) into small waffles side by side, same cell positions in every group so groups are comparable.
  3. Colour by outcome - recolour in place (correct, wrong, unreadable). Keep the unreadable or failed- format items a separate colour from wrong answers; they mean different things.
  4. Sort or regroup - pull outcomes together within each group so the counts can be read, and write the count beside each group ("7 of 40").
  5. How sure can we be? - for each group, the range of true rates consistent with this count (see below).
  6. What it means - the decision or caveat, in words, with one highlighted dot as an example.

Give readers a way into individual items: tapping a dot shows a small card with that item's input and outcome (s.on on the dot, a card in the dynamic layer). Pick two or three dots for the demo().

Layout

  • Dot radius 3.5-5 units, gap 9-12 units. A 380-wide drawing holds about 30 dots per row.
  • Waffle per group: fixed columns (5 or 10 make counting easy), fill row by row, groups in a row or column with their label and count on the same line.
  • Same item, same place across groups when items are shared (question 17 is always the 17th cell), so the reader can compare groups item by item: a column of red across all models is a hard item.
  • For a social feed post, follow the card rules in explainer-director (fixed 4:5 card, labels at least 13 units, one idea per slide). A per-model grid with category columns is usually too dense for one card at phone width: give the grid its own slide with fewer columns, or show counts per model instead.
  • Large sets (over ~600 items): use smaller dots, or one dot per 10 items and say so on screen.
  • Order of motion: stagger by item (stagger 3-8 ms) so the transition reads as a flow, and use the order field to move the interesting items last.

Showing uncertainty from small samples

A count from a small sample is consistent with a range of true rates. Show it three ways, in this order:

  1. Words with the count: "0 of 40 wrong" (never "0%" alone).
  2. The interval: a horizontal rate axis (0-50% is often enough), one row per group, a dot at the observed rate and a bar for the 95% interval (K.wilson(k, n)). Zero failures in 40 still allows a true failure rate up to about 9%.
  3. Hypothetical outcomes (HOPs; Hullman, Resnick and Adar, 2015): animate what other samples of the same size would look like if the true rate were a plausible value. Redraw the waffle every 600-900 ms with K.rng-seeded draws from that rate and keep a tally: "If the true rate were 5%, a set of 40 would show zero failures in 13% of samples" (the chance of zero is (1 - p)^n). Let the reader pick the true rate with buttons or a slider. Seeing a clean sample come up again and again from a model that does fail is what moves the misconception.

Keep this calm: HOP animations flicker by nature, so use a slow cadence, a fade between draws, and a pause button.

Example storyboard (illustrative numbers)

A judge model compares two answers and must pick the better one; each test pair is shown in both orders. 40 pairs, three judges.

  1. One pair, large: question, two answers, which one is better and why. Shrinks to a dot.
  2. 40 dots per judge, three waffles, same cell per pair.
  3. Colour: picked the better answer in both orders (blue), in one order only (amber), in neither (red).
  4. Count beside each judge: "33 of 40 both orders". The amber dots line up across judges on four pairs: those pairs are hard, not the judges.
  5. Interval rows for "both orders" rate per judge; the intervals overlap, so this test cannot rank the top two.
  6. Takeaway: show each pair in both orders; a judge that agrees with itself only one way is guessing.

Honesty

  • Unreadable or refused replies are their own colour and count, not merged into "wrong".
  • When all groups are at the ceiling or the floor, say the test cannot separate them, and how many items did ("all three judges missed the same 2 of 40").
  • If a dot stands for more than one item, say so in the legend.
  • Simulated draws in HOPs are labelled "simulated" and use the stated true rate, not the observed one dressed up as truth.

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

explainer-director

Plan an animated or interactive explainer before building it. Finds the one message, picks the form that teaches it best (step-by-step lesson, replay of a real system run, explorable what-if, every-item-is-a-dot chart, or guess-then-reveal), and writes a storyboard with one idea per step. Use this first whenever someone asks to visualize, animate, explain visually, make an interactive, a GIF, a LinkedIn visual, a Khan Academy style lesson, or "something engaging" from data, an experiment, a process, an agent or a system, even if they do not name a form. Then hand off to the matching skill (stepper-lesson, system-replay, explorable-model, unit-story, predict-reveal) and build with explainer-kit.

explainer-kit

Engine, styles (four built-in looks or a custom theme with the user's own brand colours and fonts) and quality checks for animated and interactive SVG explainers delivered as one self-contained HTML file (artifact page, claude.ai widget, or GIF/MP4). Provides a scaffold script, a small JavaScript engine (hand-drawn shapes, draw-in reveals, travelling dots, step lessons with fixed controls, a scrubbable timeline player, standalone one-view figures, unit-chart motion, sliders), a render check that walks every step at phone and desktop widths and flags overlaps, moving controls and errors, and a recorder that turns the explainer into MP4 and GIF. Use it whenever you build any animated diagram, step-by-step lesson, interactive explainer or explainer GIF, together with the form skill chosen by explainer-director.

explorable-model

Build an explorable explanation - a live model the reader steers with one or two sliders or toggles while linked views show the outcome change - for questions where the answer depends on a choice or an assumption, such as a price, a threshold, a rate, a budget, an error cost, a break-even point or a tradeoff between options. Use when someone wants an interactive "what if" calculator that teaches, a break-even or crossover explainer, a sensitivity visual, or asks to let readers "play with the numbers", "see when it pays off" or "find where the answer flips", from data or a cost model.

stepper-lesson

Build a Khan Academy style step-by-step animated lesson that teaches one idea per step, with a Next button, short captions, and one or two steps the reader plays (tap, toggle, mini-game). Use when someone wants to teach how something works or why something changed to a newcomer - a concept, a mechanism, a rule, a workflow, a security trick, a statistics idea - as an interactive explainer, a "lesson", a walkthrough, or a GIF for social media. Pairs with explainer-director (plan) and explainer-kit (engine and checks).

system-replay

Build an animated replay of how a system runs - AI agents and subagents, an agent harness with tools and guardrails, a data pipeline, an API request path, a queue, a protocol - from recorded logs or traces (timestamps, spans, events) or from a designed demonstration run. Shows actors, calls travelling between them, waiting and blocking, hidden state like a context window or budget, and a live event log, on a timeline the reader can pause and scrub. Use when someone wants to visualize an agent trace, show who waited for whom, compare coordination patterns, explain how a harness or architecture works in motion, or turn run logs into an animation or GIF.

Related Skills