kjetilhartveit/kjetils-skills/explain-with-storytelling

Explain with Storytelling

A scroll-driven story: short text steps on the left scroll past one sticky graphic on the right. As each step reaches the middle, the graphic changes to show it. On phones the kit pins the graphic at the top and the steps scroll under it. Best for the big picture before the details.

Use this skill when

• The user asks for a visual explanation of changes with storytelling.
• Used by an orchestrator to explain changes visually with storytelling.

Story

• 5–7 steps, 1–2 short sentences each, one idea per step. Gloss each tool or term the first time it appears, in a

few words in the same sentence ("tsgolint, Oxc's type-checking helper,").

• An arc: the situation today → what it costs → the change → the result → the catch → what to do first.
• One graphic (one SVG) that evolves through all steps, and every step changes something visible on it

(a bar appears, a value turns red, the counter moves, and the caption line always says what this step shows). Not a dashboard of every fact at once, and not a different picture per step.

• Don't redraw the hero. The overview already shows the headline numbers; the story shows the thing they are

about, and draws the catch on it: e.g. one bar per option split into carried over / lost / to fix, or the toolchain as boxes that get swapped one by one, with the broken part turning red or struck through.

• It fills its panel from step 1: draw the whole frame (labels, empty tracks, axis) at rest and fill it in as the

story goes, so there is never a small drawing in a large empty panel.

• To scale and honest: bars on one scale share a unit and a base (seconds with seconds; counts out of different

totals become each one's % of its own total, labelled "263 of 276"). Label things on the graphic itself.

• Don't repeat the overview's numbers in every step, and don't append a details block; it ends when the story ends.

Build it from this template (no script, no layout CSS)

Copy it and change the labels, values and steps. It is a counter, to-scale rows whose empty tracks show from step 1, and a caption line that changes every step. Bar width = value ÷ largest × 240 (the track is 240 wide; values sit right of it).

<section class="ev-tab-content" data-tab="story" data-label="Story" data-hint="6 steps" data-part-title="…">
<div class="ev-side ev-side--pin" data-ev-story>
  <div>
    <div class="ev-step" id="story-today" data-toc="Today"><b>Today:</b> one or two sentences.</div>
    <div class="ev-step">…</div>  <!-- one per step; first step of each scene gets id + data-toc -->
  </div>
  <div class="ev-stick"><figure class="ev-visual"><svg class="ev-svg" viewBox="0 0 440 320" role="img" aria-label="…">
    <text x="20" y="62" class="ev-t-num" data-say="38 s||6 s|4 s||6 s">38 s</text>
    <text x="20" y="92" class="ev-t-muted" data-say="Build today (Webpack)|step 2 caption|…|…|…|…">Build today (Webpack)</text>  <!-- one caption per step -->
    <!-- row: label, empty track (always shown), bar (shown from its step), value right-aligned -->
    <text x="20" y="139">Webpack</text>
    <rect x="100" y="122" width="240" height="24" rx="4" class="ev-f-sunken"/>
    <rect x="100" y="122" width="240" height="24" rx="4" class="ev-f-line" data-hl="1,2"/>
    <text x="420" y="139" text-anchor="end" class="ev-t-b">38 s</text>
    <text x="20" y="183">Vite</text>
    <rect x="100" y="166" width="240" height="24" rx="4" class="ev-f-sunken"/>
    <rect x="100" y="166" width="38" height="24" rx="4" class="ev-f-acc" data-on="3-" data-hl="3"/>
    <text x="420" y="183" text-anchor="end" class="ev-t-b" data-on="3-">6 s</text>
    <!-- … one row per thing compared, 44 px apart … -->
    <line x1="20" y1="252" x2="420" y2="252" class="ev-wire"/>
    <text x="20" y="284" class="ev-t-risk" data-on="5">! the catch, in a few words</text>
    <text x="20" y="284" class="ev-t-new" data-on="6">✓ the first step to take</text>
  </svg></figure></div>
</div>
</section>

• The kit wires data-ev-story: for step n it sets data-step="n" on the panel and, inside it, shows

data-on elements only on their steps (2-4, 3- = from 3 on, 2,5), adds .is-hl on data-hl steps and sets data-say text to the n-th item (a|b||d; an empty item keeps the previous text). Step 1's state is what the page shows at rest; scrolling back restores states exactly. Add a scoped <style> keyed on [data-step="3"] only for what the attributes can't express.

• Fills: ev-f-acc the point, ev-f-new good, ev-f-risk bad, ev-f-line neutral, ev-f-sunken empty track.

For a flow instead of numbers, use boxes (<rect class="ev-node"> + is-acc|is-new|is-risk) joined by ev-wire lines, in the same frame-first way.

• Text: ev-t-num only for the one counter; labels at the default size (15) or ev-t-sm; nothing below ev-t-xs.

Keep viewBox about 440 × 320 so it stays legible when pinned on a phone.

• ev-side--pin spaces the steps and pins the graphic on phones; don't add padding, spacers or media queries.