explain-with-storytelling

Name: explain-with-storytelling
Author: kjetilhartveit

github.com/kjetilhartveit设计与 UI283 次安装1 周前更新

代码仓库

关于 explain-with-storytelling

explain-with-storytelling 是用于制作滚动叙事式可视化解释的技能，适合通过故事讲解变化或概念。它以左侧短文步骤配合右侧固定图形，要求同一张图随 5–7 个步骤逐步变化。

主要功能

01组织 5–7 个叙事步骤
02构建逐步演变的单一 SVG 图形
03让每步改变图形中的可见内容
04按一致尺度标注图表数据
05在手机布局中固定图形并滚动文字

适用场景

01以故事形式解释软件变更
02逐步展示选项之间的差异
03将复杂过程整理成可视化叙事

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/kjetilhartveit/kjetils-skills --skill explain-with-storytelling

安装后在 Claude Code 中输入/explain-with-storytelling确认已加载。

详细介绍

用故事讲解

这是一个由滚动驱动的故事：左侧的简短文本步骤依次滚过，右侧则显示一幅固定的图形。每当一个步骤滚动到中间，图形就会随之变化。在手机上，工具包会将图形固定在顶部，让步骤从下方滚过。适合先讲清整体概况，再介绍细节。

适用场景

用户要求用故事的方式直观讲解变更。
编排器用故事的方式直观讲解变更。

故事

5–7 个步骤，每步 1–2 个短句，每步只讲一个观点。工具或术语首次出现时，要用同一句话中的几个词解释一下（例如“tsgolint，Oxc 的类型检查辅助工具”）。
故事弧线：当前情况 → 代价 → 变更 → 结果 → 注意事项 → 首要行动。
一幅图形（一个 SVG）贯穿所有步骤逐步变化，且每个步骤都会让图形上有可见变化（出现一根条形、一个值变红、计数器移动，并且说明文字始终点明当前步骤展示的内容）。不要把所有信息一次性塞进仪表板，也不要每步换一张图。
**不要重画概览图。**概览已经展示了关键数字；故事应展示这些数字所描述的内容，并在图上呈现注意事项。例如，每个选项用一根条形区分已保留／已丢失／待修复部分，或者将工具链画成一组方框，逐个替换，并把损坏的部分标红或加删除线。
从第 1 步起就铺满图形面板：静止状态时先画出完整框架（标签、空白轨道、坐标轴），再随着故事推进逐步填充，这样大面板里就不会一直只有一幅小图。
按比例且真实呈现：使用相同尺度的条形图时，单位和基准必须一致（秒与秒；不同总数中的计数需换算为各自总数的百分比，并标注为“263 of 276”）。直接在图形上标注信息。
不要在每个步骤里重复概览中的数字，也不要附加详情区块；故事结束时就结束。

使用此模板构建（无需脚本，无需布局 CSS）

复制模板并修改标签、数值和步骤。这是一个计数器，行按比例展示，第 1 步起就显示空白轨道，并且每步都会更新说明文字。条形宽度 = 数值 ÷ 最大值 × 240（轨道宽 240；数值显示在轨道右侧）。

<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>  
  </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>  
    
    <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>
    
    <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>

工具包会处理 data-ev-story：对于第 n 步，它会在面板上设置 data-step="n"，并仅在对应步骤显示面板内的 data-on 元素（2-4、3- = 从第 3 步开始、2,5）；在 data-hl 指定的步骤上添加 .is-hl，并将 data-say 文本设置为第 n 项（a|b||d；空项会保留前一段文本）。第 1 步的状态就是页面静止时显示的状态；向回滚动会准确还原各状态。仅对属性无法表达的内容，添加作用范围限定在 [data-step="3"] 的 <style>。
填充色：ev-f-acc 表示重点，ev-f-new 表示良好，ev-f-risk 表示不利，ev-f-line 表示中性，ev-f-sunken 表示空白轨道。若要展示流程而非数字，请使用方框（<rect class="ev-node"> + is-acc|is-new|is-risk），并按照先绘制完整框架的方式用 ev-wire 线条连接。
文本：ev-t-num 仅用于唯一的计数器；标签使用默认字号（15）或 ev-t-sm；字号不得小于 ev-t-xs。将 viewBox 保持在约 440 × 320，以便固定在手机上时仍清晰易读。
ev-side--pin 会为步骤留出间距，并在手机上固定图形；不要添加内边距、间隔元素或媒体查询。

支持 Markdown

登录后评论