guiding-users

オンボーディングとヘルプシステムでユーザーをガイドする

目的

このスキルでは、初回利用時のプロダクトツアーから継続的な機能発見まで、ユーザーのオンボーディングと状況に応じたヘルプの提供に関する体系的なパターンを紹介します。ユーザーガイダンスの仕組みを網羅し、ユーザーのアクティベーション、機能の利用促進、セルフサービスサポートを最適化します。

使用するタイミング

次のような場合に、このスキルを有効にします：

• 初回ユーザー向けのエクスペリエンスやプロダクトツアーを構築するとき
• 機能の発見やお知らせを実装するとき
• インタラクティブなチュートリアルやガイド付きタスクを作成するとき
• ツールチップ、ヒント、状況に応じたヘルプを追加するとき
• セットアップフローや完了チェックリストを設計するとき
• ヘルプパネルやドキュメントシステムを構築するとき
• プログレッシブディスクロージャーパターンを実装するとき
• オンボーディングの効果とユーザーのアクティベーションを測定するとき
• オンボーディングのアクセシビリティを確保するとき

すばやく選べる判断フレームワーク

ユーザーの状態とコンテンツの種類に応じて、適切なガイダンスの仕組みを選択します：

First-time user          → Product Tour (step-by-step)
New feature launch       → Feature Spotlight (tooltip + animation)
Complex workflow         → Interactive Tutorial (guided tasks)
Account setup            → Checklist (progress tracking)
Contextual help needed   → Tooltip/Hint system
Ongoing support          → Help Panel (sidebar/searchable)
Feature unlock           → Progressive Disclosure

詳しい選択基準については、references/selection-framework.md を参照してください。

主なガイダンスの仕組み

プロダクトツアー

主要な機能をユーザーに案内する、ステップごとのウォークスルーです：

• モーダルオーバーレイを使った順次表示のスポットライト
• 進行状況インジケーター（ステップ 2/5）
• 「スキップ」「前へ」「次へ」コントロール
• 閉じて再開できる機能
• 状況に応じた起動

実装：

npm install react-joyride

完全な実装については、examples/first-time-tour.tsx を参照してください。 パターンとベストプラクティスについては、references/product-tours.md を参照してください。

機能スポットライト

既存ユーザーに新機能を知らせます：

• 脈動するホットスポットアニメーション
• 矢印付きの状況に応じたツールチップ
• 「了解」ボタン
• 初回表示後に自動で閉じる
• 操作を妨げないオーバーレイ

実装については、examples/feature-spotlight.tsx を参照してください。 パターンについては、references/tooltips-hints.md を参照してください。

インタラクティブなチュートリアル

検証機能付きで、タスクの完了を案内します：

• 「開始するには、次のタスクを完了してください」
• チェックボックスによる完了状況の追跡
• 完了時のお祝いアニメーション
• サンプルデータを使ったサンドボックスモード
• 元に戻す機能とリセット機能

実装については、examples/guided-tutorial.tsx を参照してください。 パターンについては、references/interactive-tutorials.md を参照してください。

セットアップチェックリスト

複数のステップからなるオンボーディングの進行状況を追跡します：

• 視覚的な進行状況インジケーター（3/4 完了）
• 各タスクへの直接リンク
• プロフィールの入力完了率
• 実績バッジとゲーミフィケーション
• 完了するまで表示を継続

実装については、examples/setup-checklist.tsx を参照してください。 パターンについては、references/checklists.md を参照してください。

状況に応じたツールチップとヒント

ユーザーが必要とするタイミングでヘルプを提供します：

• ホバーまたはクリックで表示するツールチップ
• 段階的なヒントレベル（1、2、3）
• 「ヘルプが必要ですか？」のヘルプ起動機能
• 状況を考慮した提案
• キーボードからアクセス可能

実装については、examples/contextual-help.tsx を参照してください。 パターンの詳細については、references/tooltips-hints.md を参照してください。

ヘルプパネル

包括的なヘルプシステムです：

• サイドバーまたはドロワーのインターフェース
• 現在のページに応じたヘルプ
• ヘルプ記事やドキュメントの検索
• 動画チュートリアルとデモ
• サポートへの問い合わせ機能との連携
• 折りたたみとサイズ変更に対応

実装については、examples/help-panel.tsx を参照してください。 パターンについては、references/help-systems.md を参照してください。

タイミングと起動方法の戦略

オンボーディングを表示するタイミング

適切な起動条件：

• 初回ログイン時（常に）
• サインアップ直後
• 新機能の公開時（既存ユーザー向け）
• ユーザーが行き詰まっているように見えるとき（操作がない状態に基づくスマートな起動）
• ユーザーが明示的にヘルプを求めたとき

オンボーディングを表示しないタイミング

次の場合は表示を避けます：

• ユーザーがタスクの途中、または作業に集中しているとき
• 毎回のセッションで表示するとき（煩わしくなります）
• 自由に操作する前
• ツアーが 7 ステップを超えるとき（長すぎます）
• ユーザーがすでに閉じた、または完了したとき

自動で閉じるまでの時間：

• シンプルなツールチップ：5～7 秒
• 機能のお知らせ：10～15 秒、または手動で閉じるまで
• ツアー：ユーザーが操作し、自動では閉じません
• 常時表示するヒント：ユーザーが確認するまで

詳しいガイドラインについては、references/timing-strategies.md を参照してください。

プログレッシブ開示パターン

必要なときに、必要な情報だけを表示します。

手法：

1. アコーディオン形式のヘルプ：デフォルトでは折りたたみ、詳細を表示するには展開します
2. 「詳細を見る」リンク：詳しい内容は任意で確認できます
3. 詳細設定：「詳細を表示」トグルの背後に隠します
4. 段階的な機能の導入：ユーザーの進捗に応じて機能を利用可能にします
5. コンテキストに応じたヒント：ユーザーの操作に基づいて表示します

実装パターンについては、references/progressive-disclosure.md を参照してください。

アクセシビリティ要件

キーボード操作

必須のキーボードサポート：

• Tab キーでツアーのステップやコントロール間を移動
• ESC キーでツアーやツールチップを閉じる
• 矢印キーで「前へ」／「次へ」を移動
• Enter キー／Space キーでボタンを有効化
• フォーカスの表示インジケーター

スクリーンリーダーのサポート

通知のための ARIA パターン：

• ステップ番号と合計数を通知します（全 5 ステップ中 2 ステップ目）
• ツールチップとヘルプコンテンツを読み上げます
• 強調表示された UI 要素を説明します
• 進捗の完了を通知します
• エラーやブロッカーを警告します

モーションの低減

prefers-reduced-motion を尊重します：

• パルスアニメーションを無効にします
• アニメーションの代わりに即時遷移を使用します
• 視差効果や複雑なエフェクトを取り除きます
• モーションがなくても機能を維持します

アクセシビリティを検証するには：

node scripts/validate_accessibility.js

完全な実装については、references/accessibility-patterns.md を参照してください。

ライブラリの推奨事項

第一候補：react-joyride（機能豊富でアクセシブル）

ライブラリ： /gilbarbara/react-joyride 信頼スコア： 9.6/10 コードスニペット： 29+

包括的なプロダクトツアーに最適です：

• 標準で WAI-ARIA に準拠
• キーボード操作を全面的にサポート
• スタイルを高度にカスタマイズ可能
• プログラムによる制御
• ローカライズをサポート
• 継続的にメンテナンスされています

npm install react-joyride

完全なセットアップについては、examples/joyride-tour.tsx を参照してください。

代替案：driver.js（軽量でモダン）

バンドルサイズを最小限にしたい場合に最適です：

• Vanilla JavaScript（フレームワークに依存しません）
• gzip 圧縮後約 5KB
• モダンな API 設計
• 依存関係なし

npm install driver.js

代替案：intro.js（定番で実績あり）

従来型のツアーに最適です：

• 実績のあるライブラリ
• 幅広いブラウザーをサポート
• JSON ベースのツアー設定
• 充実したプラグインエコシステム

npm install intro.js

詳細な分析と選定基準については、references/library-comparison.md を参照してください。

デザイントークンとの統合

すべてのオンボーディングコンポーネントは、テーマを統一するために design-tokens スキルを使用します。

使用するトークンのカテゴリ：

• 色：ツアーのスポットライト、オーバーレイ、ツールチップの背景、ホットスポットの色
• 間隔：ツアーのパディング、ツールチップの間隔、矢印のサイズ
• タイポグラフィ：タイトルのサイズ、本文テキスト、ヘルプコンテンツ
• 境界線：モーダルとツールチップの角丸
• シャドウ：ツアーのスポットライトとツールチップの奥行き
• モーション：遷移時間、パルスアニメーション

ライト、ダーク、ハイコントラスト、およびカスタムブランドのテーマに対応しています。 テーマ設定の詳細については、design-tokens スキルを参照してください。

成功の測定

主要指標

次の指標を追跡します：

• ツアー完了率（目標：>60%）
• 初回価値を得るまでの時間（短いほど良好）
• ツアー後の機能採用率
• サポートチケットの削減
• ユーザーアクティベーション率（主要な操作を完了した割合）
• ツアー中の離脱ポイント

最適化戦略

データに基づいて改善を繰り返します：

• ツアーの長さを A/B テストします（短いほうが良いことが多いです）
• メッセージや文言を変えてテストします
• 各ステップでの離脱を測定します
• 離脱率が高いステップを簡素化します
• 再訪ユーザー向けにスキップオプションを追加します
• ユーザーのタイプに応じてパーソナライズします

オンボーディング指標を分析するには：

python scripts/analyze_onboarding_metrics.py

分析の完全な実装については、references/measuring-success.md を参照してください。

避けるべきアンチパターン

ユーザー体験を損なうよくある間違い：

❌ 強制ツアー：ツアーを完了するまで製品を使えないようにする ❌ 長すぎる：7ステップを超えるツアーはユーザーの関心を失います ❌ 毎回表示：同じツアーを何度も表示する ❌ スキップ不可：ユーザーが自分で探索できないようにする ❌ 文字だらけ：ビジュアルの代わりに長い説明を使う ❌ すべてをブロック：ツアー中に操作できないようにする ❌ 案内が早すぎる：ユーザーが探索する前にヘルプを表示する ❌ タイミングが悪い：集中して作業しているときに中断する ❌ 文脈がない：具体的な関連性のない一般的なヒントを表示する

実装ワークフロー

ステップ 1：ユーザージャーニーを整理する

重要なタイミングを特定します：

1. 初回ログインとアカウント作成
2. 中核的な価値の提供（なるほどと思う瞬間）
3. 機能の発見ポイント
4. 混乱や離脱が起きる可能性のある箇所
5. 達成や進捗のマイルストーン

ステップ 2：案内方法を選ぶ

タイミングに合った方法を選びます：

• 初回ログイン → 製品ツアー（最大 3～5 ステップ）
• 中核機能 → インタラクティブチュートリアル
• セットアップ要件 → チェックリスト
• 新機能 → スポットライト＋ツールチップ
• 継続的なヘルプ → ヘルプパネル

ステップ 3：段階的な機能強化で実装する

段階的に構築します：

1. 必須の案内だけから始める
2. ユーザーの行動に基づいて、状況に応じたヘルプを追加する
3. 効果を測定するための分析機能を実装する
4. データに基づいて改善を繰り返す
5. バリエーションを A/B テストする

ステップ 4：アクセシビリティをテストする

準拠状況を確認します：

• キーボード操作がすべて正しく機能する
• スクリーンリーダーが適切に読み上げる
• 動きを減らす設定が尊重される
• フォーカス管理が正しい
• ARIA ラベルがわかりやすい

検証を実行します：

node scripts/validate_accessibility.js

ステップ 5：監視して最適化する

追跡して改善します：

• 完了率を監視する
• 離脱ポイントを特定する
• ユーザーからフィードバックを集める
• 改善案を A/B テストする
• 調査結果に基づいて更新する

実例

ユースケースに合った例から始めましょう：

first-time-tour.tsx           # Product walkthrough with react-joyride
feature-spotlight.tsx         # New feature announcement
guided-tutorial.tsx           # Interactive task completion
setup-checklist.tsx           # Multi-step onboarding progress
contextual-help.tsx           # Tooltips and progressive hints
help-panel.tsx                # Sidebar help with search
celebration-animation.tsx     # Completion feedback

リソース

スクリプト（トークンを消費しない実行）

• scripts/generate_tour_config.js - ユーザーフローからツアー設定を生成します
• scripts/analyze_onboarding_metrics.py - 完了率と離脱率を分析します
• scripts/validate_accessibility.js - キーボードとスクリーンリーダーのサポートをテストします

リファレンス（詳細ドキュメント）

• references/product-tours.md - ツアーのパターン、ステップ設計、ナビゲーション
• references/interactive-tutorials.md - ガイド付きタスクとサンドボックスモード
• references/tooltips-hints.md - 状況に応じたヘルプと段階的なヒント
• references/checklists.md - 進捗の追跡とゲーミフィケーション
• references/help-systems.md - ヘルプパネル、動画、ドキュメント
• references/progressive-disclosure.md - 高度なパターンと機能のロック解除
• references/timing-strategies.md - 案内をいつ、どのように表示するか
• references/accessibility-patterns.md - WCAG 準拠と ARIA パターン
• references/measuring-success.md - 分析と最適化
• references/library-comparison.md - ライブラリの詳細な評価
• references/selection-framework.md - 案内方法を選ぶための判断ツリー

例（実装コード）

• すべての案内タイプを網羅した、完全に動作する実装例
• 一般的なフレームワークとの統合例
• アクセシビリティに準拠したパターン
• デザイントークンの統合例

アセット（テンプレートと設定）

• assets/celebration-animations/ - 成功時のアニメーションと紙吹雪
• assets/tour-templates.json - 再利用可能なツアー設定
• assets/message-templates.json - ツールチップとヒントの文面テンプレート
• assets/timing-config.json - 推奨タイミング値

スキル間の連携

このスキルは、ほかのコンポーネントスキルと連携します：

• フォーム：フォーム入力のガイド、入力検証のヒント
• ダッシュボード：機能ツアー、ウィジェットの説明
• テーブル：データグリッドのチュートリアル、機能の発見
• AI チャット：チャットインターフェースのウォークスルー
• ナビゲーション：メニューとナビゲーションの案内
• フィードバック：成功を祝う演出、進捗通知
• デザイントークン：すべてのビジュアルスタイルとテーマ

重要な原則

1. ユーザーの時間を大切にする：ツアーは7ステップ以内にし、スキップできるようにします
2. 説明するより見せる：テキストよりもビジュアルやインタラクションを活用します
3. 段階的に機能を強化する：シンプルに始め、必要に応じてガイダンスを追加します
4. コンテキストを重視する：関連性のある場面で、適切な場所にヘルプを表示します
5. すべてを計測する：完了状況を追跡し、データに基づいて改善します
6. アクセシビリティを最優先する：キーボード、スクリーンリーダー、動きの抑制に対応します
7. 進捗を称える：完了や達成を認めます
8. 自由な探索を可能にする：ツアーを強制せず、ユーザーが自分で見つけられるようにします

次のステップ

1. ユーザージャーニーをマッピングし、重要な場面を特定します
2. 各場面に適したガイダンスの仕組みを選びます
3. react-joyride または希望するライブラリをインストールします
4. 重要なフローを1つ選んで開始します（通常は初回利用時の体験です）
5. アクセシビリティを組み込んで実装します
6. アナリティクスによる追跡を追加します
7. 実際のユーザーでテストします
8. 指標とフィードバックに基づいて改善します