guided-demo

ガイド付きデモのパターン

HTML／Web アプリケーションに、自己解説型のウォークスルーを追加します。宣言型のステップ配列を使ったsetTimeoutループが、DOM 要素の CSS クラスを切り替え、固定パネルにテキストを1文字ずつ書き込みます。エンジンは既存のページに重ねて表示され、ページのコードは変更しません。デモを停止すると、すべての状態がリセットされます。

コア部分は、約100行の JS と30行の CSS です。幕間、速度コントロール、キーボードショートカット、進行状況バーは、必要に応じて追加できます。

実装の前に

ユーザーに次の質問をします（会話ですでに回答されている質問は省略してください）。

1. セクションはいくつありますか？ タブ、ルート、スクロール位置、スライド番号などです。セクションの切り替え方法を決めます。
2. 使用しているフレームワークは何ですか？ Vanilla HTML ならそのまま動作します。React／Vue／Svelte では、エンジンを条件付きオーバーレイコンポーネントとして実装し、querySelector はレンダリング後に実行する必要があります。
3. 発表者が話しながら進めますか、それともデモが自動で解説しますか？ 発表者が話す場合は、テキストを短くし、間を長めにします。自動解説の場合は、テキストを詳しくし、間は適度にします。
4. 操作するインタラクティブ要素はありますか？ ステップのアクションに対応付けます。CSS セレクターが安定している（フレームワークが生成したハッシュではない）ことを確認してください。
5. オフラインでの利用が必要ですか？ 必要な場合は、すべてを1つのファイルにまとめます。代替手段なしで CDN に依存しないでください。
6. ステップはいくつありますか？ プレゼンでは15未満、詳しいウォークスルーでは20～30が目安です。40を超えると、注意を保ちにくくなります。
7. タッチデバイスへの対応は必要ですか？ ガイド付きデモの多くは、デスクトップ／ノート PC でのプレゼンを想定しています。ナレーターパネルには、タッチ操作に対応した画面上の前へ／再生／次へボタンがありますが、スワイプ操作やモバイル専用レイアウトが必要になることはほとんどありません。

実装

コードスニペット（Vanilla JS／静的 HTML）はreferences/implementation.mdを参照してください。対象アプリケーションが React と React Router を使用している場合は、古いクロージャ、ルートナビゲーションのタイミング、コンポーネントのアーキテクチャを扱う React 固有のパターンについて、references/react-integration.mdも参照してください。その他の SPA フレームワーク（Vue、Svelte など）でも、ルート変更後に要素を確認する、タイマー関連の状態をリアクティビティシステムの外部に保存するといった同じ考え方が使えますが、実装の詳細は異なります。

必須の要素は次の4つです。

1. ナレーターパネル - テキストコンテナと進行状況バーを備えた固定位置のバー
2. ハイライト用クラス - レイアウトシフトが起きないよう、アニメーション付きのグローをborderではなくoutlineで実現します
3. タイプライター関数 - 再帰的なsetTimeoutを使用し、解説テキストはtextContentで設定します（ユーザーが作成した解説テキストにinnerHTMLを使ってはいけません）。点滅するカーソルは CSS で実現します。各ティックの前にinnerHTML = ''で内容を消去する処理は、ユーザーコンテンツを扱わないため、意図的で安全です
4. 再生ループ - playStep(idx)でセクションを切り替え、アクションを実行し、ハイライトを表示してテキストを入力した後、自動で次のステップに進みます

ステップ配列

唯一の信頼できる情報源です。各ステップはプレーンなオブジェクトです。

const DEMO_SCRIPT = [
  { section: 0, target: '.card', text: "Narration text." },
  { section: 1, target: null, text: "Transition.", transition: true },
  { section: 1, target: '#el', text: "Detail.", action: 'open', actionTarget: 'panel-id' },
];

プロパティ：section（表示するビュー）、target（CSS セレクターまたは null）、text（ナレーターの文面）、transition（幕間を表示するかどうか）、action／actionTarget（UI の変更を実行）、delay（ステップごとの一時停止時間をミリ秒で指定する任意の値。デフォルトはPAUSE_MS）。

タイミングのデフォルト値

定数	デフォルト	調整する場合
TYPE_SPEED	5ms/文字	長いテキストでは3ms、短い文章を印象的に見せたい場合は15ms
PAUSE_MS	3000ms	視聴者が聞くよりも読む場合は4～5秒
速度の範囲	0.5x～2x	どちらの定数も倍率で割ります

ナレーターの文面を書く

タイプライター効果では、単語が1つずつ表示されるため、文体が重要です。

• 短く、断定的な文にします。各ステップで伝えるポイントは1つだけにします。
• 会話調の現在形にし、視聴者に直接語りかけます。
• 要素の意味を説明し、UI に表示されている内容を説明しないでください。「この列はコストへの影響を数値化しています」とし、「この列にコストが表示されています」とはしません。
• 視聴者になじみのない専門用語は避けます。実装ではなく、対象分野の用語に合わせてください。
• 発表者が進行するデモでは各ステップ30語未満、自動解説では最大50語にします。

キーボード操作

キーボード入力の捕捉は isActive フラグで制御し、通常のページ操作を妨げないようにします。Space = 再生／一時停止、矢印キー = ステップ移動、M = TTS ナレーションの切り替え、Escape = 終了してリセットします。

音声合成によるナレーション

ブラウザー標準の TTS を speechSynthesis Web Speech API 経由で利用し、タイプライター表示と並行して各ステップのナレーションを読み上げます。すべてのデモに含めますが、デフォルトではオフにしてください。ユーザーが明示的に操作しない限り、音声を再生してはいけません。ユーザーはコントロールバーのスピーカーアイコンまたは M キーで切り替えます。音声の選択、単一の呼び出し箇所、キャンセルについては、references/implementation.md（音声合成によるナレーション）を参照してください。

ステップのカウントダウンインジケーター

ステップの進捗バーの下に細いバーを表示し、タイプライター表示の完了後にある一時停止中に塗りつぶすことで、自動的に次のステップへ進むまでの時間を示します。すべてのデモに含めてください。CSS アニメーションの方法、配置、clearAllTimers() によるリセットについては、references/implementation.md（ステップのカウントダウンインジケーター）を参照してください。

任意：トランジション用のインタースティシャル

セクション間でステータスメッセージを切り替えながら表示する、全画面のオーバーレイです。処理中の時間を再現します。セクションごとのメッセージを 2 次元配列で定義します。各メッセージをフェード表示し、その後コールバックでオーバーレイを閉じます。

任意：ステップアクション

executeStep() 内で文字列を照合します。折りたたまれたパネル内の要素は、パネルが開くまで querySelector で見つからないため、アクションはハイライトより前に実行します。アクションの追加は if ブロックを 1 つ追加するだけです。シンプルに保ちましょう。展開／折りたたみ以外のよくあるパターンには、expandOne（1 つのパネルを開き、兄弟パネルをすべて閉じるアコーディオン形式）、call（requestBriefing() など、名前付き関数を呼び出す）、addClass／removeClass（グローバルな状態変更のために document.body の CSS クラスを切り替える）があります。

注意点

以下は、繰り返し発生する問題点です。

• レイアウトシフト：ハイライトには border ではなく outline を使います。Outline はボックスモデルに影響しません。
• 非表示の要素：対象が折りたたまれたコンテナ内にある場合は、アクションで先に開く必要があります。これが、ハイライトより先にアクションを実行する理由です。
• 動的なセレクター：フレームワークが生成するクラス名（.css-1a2b3c）は、ビルド間で変わるため使用できません。data-* 属性または ID を使います。
• スクロールの競合：scrollIntoView({ block: 'center' }) は固定ヘッダーやパネルと競合します。スクロールコンテナに scroll-padding-bottom を設定し、ナレーションパネルの高さを考慮します。
• Z-index：ナレーションパネルは 500 以上、インタースティシャルは 490、ハイライト対象の要素は 2 以上にします。既存のモーダルやドロップダウンとの競合がないか確認します。
• 終了時のクリーンアップ：デモで変更した状態をすべてリセットします。開いたパネルを閉じ、ハイライトを削除し、タイマーをクリアします。クリーンアップが不足すると、分かりにくい UI 状態が残ります。
• フォーム入力欄：ページにテキスト入力欄、テキストエリア、セレクトがある場合、キーボードハンドラーでそれらを除外する必要があります。そうしないと、テキストフィールドで Space キーを押したとき、入力ではなく再生／一時停止が実行されます。e.target.tagName を確認し、INPUT、TEXTAREA、SELECT の場合は処理を中止します。
• ES モジュール：<script type="module"> を使う場合、onclick から呼び出すすべてのデモ関数を window.* に定義する必要があります。
• 印刷：@media print でデモパネルとインタースティシャルを非表示にします。
• アクセシビリティ：ナレーションパネルには role="status" と aria-live="polite" を設定します。ハイライトのアウトラインはコントラスト要件を満たす必要があります。

適用範囲

利用できるもの：プロトタイプ、PoC、HTML スライドデッキ、データストーリーテリング用ダッシュボード、製品デモ、ワークショップの進行、投資家向けピッチ、オンボーディングのウォークスルー。

置き換えるものではないもの：ユーザーテストツール、画面録画ツール、本番環境のオンボーディングツアー（こうした用途には、永続化機能と分析機能を備えたツアーライブラリを使います）。

フレームワークアプリでは、デモエンジンを条件付きのオーバーレイコンポーネントとしてマウントし、スクリプト配列をプロパティとして渡します。単一ファイルのデモでは、オフラインや USB メモリでの配布に備えて、すべてをインライン化します。