diagram-animation

図とデータのアニメーション

時間の経過とともに構造やデータを見せ、一度に一つのアイデアを伝えます。ノードやエッジを段階的に表示し、コネクターに流れを持たせ、アニメーション付きのグラフ（棒が伸びる、線が描かれる、数値が増える）をWebや動画向けに作成します。

使用する場面

• 段階的に組み立てていくアーキテクチャ図、フロー図、シーケンス図。
• アニメーション付きのグラフ：棒が伸びる、線が描かれる、数値が増える。
• 「仕組み」の解説やプロセスの説明。
• コネクターに沿ってデータやシグナルが流れる様子の表示。

基本原則：段階的な情報開示

すべてを一度に見せてはいけません。ノード → エッジ → ラベルの順に表示します。アクティブな要素を強調し、ほかの要素は暗くします（フォーカス＋コンテキスト）。派手さではなく理解しやすさを優先してテンポを調整し、各ステップを0.5～1.5秒表示して内容を印象づけます。一貫性のあるビジュアルルールを保ちます。色には意味を持たせ、その対応関係を途中で変えてはいけません。

クイックリファレンス

目的	方法	イージング
ノードの表示	scale 0.8→1 + opacity、transform-origin:center	back.out(1.5) / easeOut
エッジの接続	stroke-dashoffset len→0	easeInOut、0.4～0.7s
データの流れ	stroke-dashoffsetをループ再生 + 移動するドット	linear、無限
棒の伸長	scaleY 0→1、transform-origin:bottom	easeOut、0.06sずつずらす
折れ線グラフ	パスのstroke-dashoffset len→0	easeInOut、0.8～1.2s
数値のカウントアップ	イージングしたtで値を補間	easeOutCubic
強調表示	アクティブ要素は不透明度を最大にし、ほかはopacity:.35	0.3s

ノード／エッジの段階的な表示（SVG + GSAP）

<svg viewBox="0 0 400 200" id="flow">
  <g class="node" opacity="0"><circle cx="60" cy="100" r="28" fill="#0A84FF"/></g>
  <g class="node" opacity="0"><circle cx="200" cy="100" r="28" fill="#0A84FF"/></g>
  <g class="node" opacity="0"><circle cx="340" cy="100" r="28" fill="#0A84FF"/></g>
  <path class="edge" d="M88 100 H172" stroke="#888" stroke-width="3" fill="none" pathLength="1"/>
  <path class="edge" d="M228 100 H312" stroke="#888" stroke-width="3" fill="none" pathLength="1"/>
</svg>
<script type="module">
  import gsap from "https://cdn.jsdelivr.net/npm/gsap/+esm";
  gsap.set(".edge", { strokeDasharray: 1, strokeDashoffset: 1 });
  const tl = gsap.timeline({ defaults: { ease: "power2.out" } });
  tl.to(".node", { opacity: 1, scale: 1, transformOrigin: "center",
                   duration: .45, stagger: .35, ease: "back.out(1.6)", startAt: { scale: .8 } })
    .to(".edge", { strokeDashoffset: 0, duration: .5, stagger: .35 }, "-=0.9");
</script>

pathLength="1"を使うと、任意の長さのエッジを一つのダッシュ値で制御できます。まずノードを表示し、次に表示されたノード同士をエッジでつなぎます。

コネクターの流れ（破線の移動 + 移動するドット）

.flow-line { stroke-dasharray: 8 8; animation: march 0.6s linear infinite; }
@keyframes march { to { stroke-dashoffset: -16; } }   /* = sum of dash pattern */
@media (prefers-reduced-motion: reduce){ .flow-line { animation: none; } }

パスに沿ってドットを移動（offset-path、JSなし）：

.packet { offset-path: path("M88 100 H312"); animation: travel 1.4s linear infinite; }
@keyframes travel { to { offset-distance: 100%; } }

グラフ

棒の伸長（ベースラインからのscaleY）：

.bar { transform: scaleY(0); transform-origin: bottom; }
.bar.in { transform: scaleY(1); transition: transform .6s cubic-bezier(.22,1,.36,1); }
/* stagger via inline transition-delay per bar */

折れ線グラフの描画（系列全体のパスを描画）：

const len = pathEl.getTotalLength();
pathEl.style.strokeDasharray = len;
pathEl.style.strokeDashoffset = len;
pathEl.getBoundingClientRect();                 // force reflow
pathEl.style.transition = "stroke-dashoffset 1s ease-in-out";
pathEl.style.strokeDashoffset = "0";

イージングを使った補間による数値のカウントアップ（rAF）：

function countUp(el, to, dur = 1200) {
  const t0 = performance.now();
  const fmt = new Intl.NumberFormat();
  (function tick(now){
    const k = Math.min(1, (now - t0) / dur);
    const e = 1 - Math.pow(1 - k, 3);           // easeOutCubic
    el.textContent = fmt.format(Math.round(to * e));
    if (k < 1) requestAnimationFrame(tick);
  })(t0);
}

ビルドツールの選択

• インラインのアニメーション付きSVG + GSAP/CSS：Webで独自の図を作成し、細かく制御するのに最適です。
• Framer Motion（React）：variants + staggerChildrenによる宣言的な表示に対応し、グラフにはVisx/Rechartsを組み合わせられます。
• D3 + transitions：データにバインドしたグラフ向けです。.transition().duration().attr()で伸長／描画し、tweenで数値をカウントアップします。
• Mermaid / Excalidraw：図の構造を素早く作成してSVGにレンダリングし、そのSVGをアニメーション化します。
• Remotion（React）：動画出力や再現可能なエクスポート向けの、データ駆動型で決定論的なレンダリングに対応します。

出力チェックリスト

• 表示順はノード → エッジ → ラベルです。一度にすべて表示してはいけません。
• 各ステップを読み取れるだけの時間（0.5～1.5秒）表示します。
• 色のルールに一貫性があり、意味が明確です。
• アクティブな要素を強調し、コンテキストを暗くします。
• prefers-reduced-motionの場合は、ループする動きを使わず、完成した図を表示します。

配布と検証（スタンドアロン HTML）

パッケージ化されたヘルパー（scripts/）：scripts/seek-shot.sh anim.html 0 1.5 3 は ?t=N ハーネスを固定して各時点をスクリーンショットに撮影します。scripts/contact-sheet.sh sheet.png frame-*.png はそれらをタイル状に並べ、一目で確認できるようにします。scripts/README.md を参照してください。

自己完結型の図（リビール、流れるコネクター、アニメーション付きチャート）では、成果物はブラウザーで直接開ける 1 つの HTML ファイルです。ビルド手順もレンダリングパイプラインも必要ありません。Web アニメーションには単一ファイルが適切な選択肢です。（図がレンダリング済み動画の一部である場合は、代わりに Remotion コンポジションとして構築し、remotion still で検証してください。remotion-video を参照してください。）

出力要件：

• .html ファイル 1 つ：SVG はインライン、Framer Motion／D3／anime／GSAP は CDN から読み込み、アニメーションはインラインの <script> 1 つ（ドライバー 1 つ）に記述します。
• スクリーンショット撮影用に、正確な時点で固定する方法を用意します。図のアニメーション方法に合わせてください。
  • GSAP／JS タイムライン：マスターの tl を 1 つ作成し、?t=N → tl.pause(); tl.seek(N) とします。
  • SVG SMIL：svg.pauseAnimations(); svg.setCurrentTime(N) とします。
  • CSS キーフレーム：animationDelay でリビールの順序を制御し、同等の JS タイムラインを一時停止／シークして固定します。

<script>
  // ... build your master timeline as `tl` ...
  const t = new URLSearchParams(location.search).get("t");
  if (t !== null) { tl.pause(); tl.seek(parseFloat(t)); }  // frozen at t seconds
  window.__ready = true;                                    // ready signal for headless wait
  console.log("duration", tl.duration());
</script>

検証サイクル — レンダリング → 固定 → スクリーンショット → 確認：

1. ファイルを開始／中間／終了時点で開きます。…/diagram.html?t=0、?t=<dur/2>、?t=<dur>（コンソールから tl.duration() を確認します）。
2. 固定した各フレームをヘッドレスでスクリーンショット撮影します。

   npx playwright screenshot --wait-for-timeout=500 "file://$PWD/diagram.html?t=1.2" frame-mid.png
   

3. 忠実度を確認します。段階的なリビールが順番どおりに表示され（ノード → エッジ → ラベル、それぞれのステップが該当フレームに表示される）、コネクターが正しいノードを指し、カウントアップが正確な値に到達することを確認します。また、アーティファクト（ラベルのクリッピング、キャンバス外のノード、フォント読み込み前の FOUC、つなぎ目でのカクつき）も確認します。

完了前に：

1. ブラウザーでスタンドアロンで開けること。コンソールエラーや CDN の読み込み漏れがないこと。
2. ドライバー／マスタータイムラインが 1 つであり、固定（?t=N／setCurrentTime）によって再現性のある静止画が表示されること。
3. 開始／中間／終了時点でスクリーンショットを撮影し、リビールの順序が正しく、コネクターが正しいノードに接続し、数値が正確であることを確認すること。
4. prefers-reduced-motion では、ループアニメーションなしで完成した図が表示されること。
5. 色のルールに一貫性があり、アクティブな要素が強調表示され、コンテキストが薄く表示されること。すべてが一度に表示されないこと。

参考ファイル

• references/diagram-and-chart-recipes.md — 実行可能なコードをより詳しく紹介しています。ラベル付きのノード／エッジの段階的なリビール、流れる破線と移動するドットのコネクター、棒グラフ／折れ線グラフ／カウントアップのレシピ、シーケンス図とアーキテクチャ図の構築パターン、イージングに関する注記付きの D3／Framer Motion／Remotion 実装を掲載しています。