explain-with-storytelling

ストーリーテリングで説明する

スクロールに合わせて進むストーリーです。左側の短いテキストステップがスクロールし、右側の固定されたグラフィックを通り過ぎます。各ステップが中央に来ると、それに合わせてグラフィックが変化します。スマートフォンでは、キットがグラフィックを上部に固定し、ステップがその下をスクロールします。詳細に入る前に全体像を伝えるのに最適です。

このスキルを使う場面

• ユーザーが、変更点をストーリーテリングで視覚的に説明するよう求めた場合。
• オーケストレーターが、変更点をストーリーテリングで視覚的に説明する場合に使用します。

ストーリー

• 5～7ステップとし、各ステップは1～2文の短い文章で、1つのアイデアを扱います。ツールや用語は、初めて登場する際に同じ文の中で簡潔に説明します（「tsgolint、Oxcの型チェック用ヘルパー、」など）。
• ストーリーの流れは、現在の状況 → そのコスト → 変更 → 結果 → 注意点 → 最初にすべきこと、とします。
• グラフィックは1つ（SVGを1つ）とし、すべてのステップを通じて変化させます。また、各ステップで目に見える変化を加えます（バーが現れる、値が赤くなる、カウンターが動く、キャプション行が常にこのステップで何を示しているかを伝える、など）。 一度にすべての情報を載せたダッシュボードにしたり、ステップごとに別の図を使ったりしないでください。
• ヒーローを描き直さないでください。 概要にはすでに主要な数値が示されています。ストーリーでは、その数値が何を示すのかを伝え、注意点も図に描き込みます。たとえば、選択肢ごとにバーを1本ずつ用意し、引き継がれる部分／失われる部分／修正が必要な部分に分ける方法や、ツールチェーンをボックスで表し、1つずつ置き換えて、壊れた部分を赤くしたり取り消し線を付けたりする方法があります。
• ステップ1からパネル全体を使います。 静止状態ではフレーム全体（ラベル、空のトラック、軸）を描き、ストーリーが進むにつれて中身を埋めます。大きな空白のパネルに小さな図だけが表示される状態は避けてください。
• スケールを統一し、正確に表します。同じスケールのバーでは、単位と基準を揃えます（秒は秒で表します。合計数が異なる件数は、それぞれの合計に対する割合に変換し、「276件中263件」のようにラベルを付けます）。図そのものにラベルを付けてください。
• 概要にある数値を各ステップで繰り返さないでください。また、詳細ブロックを後ろに追加しないでください。ストーリーの終了と同時に終わります。

このテンプレートを使って作成する（スクリプト不要、レイアウト用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 を追加し、n番目の項目のテキストを data-say に設定します（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 の線でつなぎます。
• テキスト：カウンター1つだけに ev-t-num を使います。ラベルはデフォルトサイズ（15）または ev-t-sm を使い、ev-t-xs より小さいサイズは使いません。スマートフォンで固定表示しても読みやすいように、viewBox はおよそ440 × 320にしてください。
• ev-side--pin がステップの間隔を調整し、スマートフォンでグラフィックを固定します。パディング、スペーサー、メディアクエリーは追加しないでください。