オンボーディング UX

ウェブアプリをオンボーディングのギャップについて監査してから、それを修正するためのアプリ内ガイダンスを生成します。目標は、新規ユーザーが空白の画面を見て何をすればよいのか悩むことがないようにすることです。

このスキルが解決する問題

機能を構築しました。機能は動作します。しかし、新規ユーザーが初めてログインすると、以下のような画面が表示されます。

• 列ヘッダーだけで何もないテーブル
• ユーザーにはまだ意味のないラベルでいっぱいのサイドバー
• どこから始めるべきか、アプリが何のためのものかを示す指示がない
• 何も指していないため、ユーザーが知らない機能

このスキルはそれらのギャップを見つけ、それらを埋めるためのコンテンツとコードを生成します。

ブラウザツール検出

ux-audit と同じ — Chrome MCP、Playwright MCP、または playwright-cli を検出します。必要に応じて ux-audit の browser-tools.md リファレンスを参照してください。

URL 解決

ux-audit と同じ — localhost よりも展開済み/ライブ URL を優先します。wrangler.jsonc、CLAUDE.md、または実行中の開発サーバーを確認してください。

ワークフロー

フェーズ 1: 監査 — ギャップを見つける

新規ユーザーとしてアプリを閲覧します。すべてのページで以下を評価します。

空の状態 (Empty States)

すべてのリスト/テーブル/コレクションページに移動します。それぞれについて、

チェック項目	良い例	悪い例
ゼロデータページは何を表示するか？	「クライアントがまだありません。最初のクライアントを追加して開始しましょう。」+ CTA ボタン	列ヘッダーだけの空のテーブル、または空白
明確なアクションがあるか？	ボタン：「最初の [項目] を追加」	何もない — ユーザーはナビゲーションまたはメニューでアクションを見つける必要があります
機能について説明しているか？	「クライアントは一緒に作業している人たちとビジネスです。1 つを追加して、関係の追跡を開始します。」	単に空のコンテナ
空の状態がデザインされているか？	イラストまたはアイコン、有用なコピー、目立つ CTA	データを除いて設定済みの状態と同じ

最初の印象

新規ユーザーとしてログインします（またはシミュレートするために状態をクリアします）。評価：

チェック項目	確認すること
ランディングページ	ダッシュボード/ホームは何か有用なものを表示しているか、それとも空か？
方向性	10 秒以内に、このアプリが何であって、どこから始めるべきかわかるか？
最初のアクション	私が最初にすべき #1 のことが明白で目立つか？
認知負荷	何個のメニュー項目、ボタン、オプションが注意を争っているか？
ウェルカムコンテンツ	ウェルカムメッセージ、ツアー、またはゲッティング スタート ガイドがあるか？それとも単なる生のアプリか？

機能の発見可能性

アプリの各機能について：

チェック項目	確認すること
見つけられるか？	ナビゲーションに表示されているか、それともメニュー/サブメニューに埋もれているか？
何をするかわかるか？	ラベルが説明しているか、それともクリックして調べる必要があるか？
キーボード ショートカット	ショートカットがあるか？発見可能か（ツールチップ、ヘルプパネル）？
高度な機能	フィルター、一括操作、検索 — これらは表示されているか、それとも隠れているか？
設定と構成	設定を見つけられるか？各設定が何をするかわかるか？

文脈的ヘルプのギャップ

各ページで：

チェック項目	確認すること
フォームフィールド	複雑なフィールドにはヘルプテキストまたはツールチップがあるか？
専門用語	素人が理解できないラベルがあるか？
結果	破壊的または不可逆的なアクションは何が起こるかを説明しているか？
検証	間違いを犯したとき、エラーメッセージは修正方法を教えてくれるか？

監査レポートを生成

.jez/artifacts/onboarding/audit.md に書き込みます：

# オンボーディング監査：[アプリ名]
**日付**: YYYY-MM-DD
**URL**: [アプリ URL]

## 最初の印象スコア
[1-5] — 新規ユーザーが 30 秒以内に何をするべきかを理解できるか？

## 見つかった空の状態
| ページ | 現在の状態 | 推奨事項 |
|------|--------------|----------------|
| /clients | 空のテーブル、ガイダンスなし | CTA 付きの空の状態を追加 |

## 不足しているガイダンス
| 場所 | ギャップ | 優先度 |
|----------|-----|----------|
| ダッシュボード | ウェルカムまたはゲッティング スタートなし | 高 |
| 設定 | 設定の説明がない | 中 |

## 機能発見の問題
| 機能 | 問題 | 修正 |
|---------|---------|-----|
| キーボード ショートカット | 発見する方法がない | ヘルプパネルを追加 |

## クイック ウイン
[新規ユーザーエクスペリエンスに最も大きな影響を与える上位 5 つの変更]

---

フェーズ 2: 生成 — ソリューションを構築

監査後、実際のコンテンツとコードを生成します。プロジェクトのコードベースを読んで、既存のテック スタックとコンポーネントパターンと一致させます。

1. 空の状態コンポーネント

監査で特定された各空の状態について、コンポーネントを生成します：

// パターン — プロジェクトのコンポーネントライブラリに適応させます
function EmptyState({ icon, title, description, actionLabel, onAction }) {
  return (
    <div className="flex flex-col items-center justify-center py-16 text-center">
      <div className="text-muted-foreground mb-4">{icon}</div>
      <h3 className="text-lg font-medium mb-2">{title}</h3>
      <p className="text-muted-foreground mb-6 max-w-md">{description}</p>
      <Button onClick={onAction}>{actionLabel}</Button>
    </div>
  );
}

各ページについて、特定のコピーを書きます：

• タイトル: 機能が何か（「クライアント」）
• 説明: なぜそれが重要かを 1 文で（「一緒に作業する人たちとビジネスを追跡します」）
• アクション: 次に何をするか（「最初のクライアントを追加」）

コピーが手動のようではなく、有用な同僚のように感じるように書きます。

2. ウェルカム/最初の実行エクスペリエンス

アプリの複雑さに基づいて、これらのパターンのいずれかを生成します：

シンプルなアプリ（3-5 機能）: ダッシュボード上のウェルカムバナー

// 消可能なウェルカムバナー — ユーザーがそれを閉じるか最初のアクションを完了するまで表示
function WelcomeBanner({ onDismiss }) {
  return (
    <div className="rounded-lg border bg-card p-6 mb-6">
      <h2 className="text-xl font-semibold mb-2">[アプリ名] へようこそ</h2>
      <p className="text-muted-foreground mb-4">始め方：</p>
      <ol className="space-y-2 mb-4">
        <li>1. 最初のクライアントを追加</li>
        <li>2. ポリシーを作成</li>
        <li>3. 注意が必要なことをダッシュボードで確認</li>
      </ol>
      <Button variant="outline" size="sm" onClick={onDismiss}>了解</Button>
    </div>
  );
}

複雑なアプリ（6 機能以上）: チェックリスト形式のオンボーディング

// 永続的なゲッティング スタートチェックリスト — 進捗を追跡
function OnboardingChecklist({ steps, completedSteps }) {
  return (
    <Card>
      <CardHeader>
        <CardTitle>ゲッティング スタート</CardTitle>
        <p className="text-sm text-muted-foreground">
          {completedSteps.length} / {steps.length} 完了
        </p>
      </CardHeader>
      <CardContent>
        {steps.map(step => (
          <div key={step.id} className="flex items-center gap-3 py-2">
            <Checkbox checked={completedSteps.includes(step.id)} disabled />
            <span>{step.label}</span>
          </div>
        ))}
      </CardContent>
    </Card>
  );
}

3. 機能ツアー

react-joyride（または同等）のツアー構成を生成します：

const tourSteps = [
  {
    target: '[data-tour="sidebar-clients"]',
    content: 'クライアントはここにあります。一緒に作業する人たちとビジネスを追加します。',
    placement: 'right',
  },
  {
    target: '[data-tour="create-button"]',
    content: 'ここをクリックして、何か新しいものを作成します — クライアント、ポリシー、またはメール。',
    placement: 'bottom',
  },
  {
    target: '[data-tour="search"]',
    content: '検索を使用して何かすばやく見つけます。クイック スイッチャーは Cmd+K を試します。',
    placement: 'bottom',
  },
];

また、既存のコンポーネントに追加される必要がある data-tour 属性を生成します。

4. ツールチップとヘルプコンテンツ

複雑な UI 要素ごとに、ツールチップコピーを生成します：

// 情報ツールチップのパターン
<TooltipProvider>
  <Tooltip>
    <TooltipTrigger asChild>
      <InfoIcon className="h-4 w-4 text-muted-foreground" />
    </TooltipTrigger>
    <TooltipContent>
      <p>重要度は、このクライアントがビジネスにとってどの程度重要かを示します。
      5 = 重要（最大のクライアント）、1 = 最小（1 回限りのインタラクション）。</p>
    </TooltipContent>
  </Tooltip>
</TooltipProvider>

コンテンツマップを生成：説明が必要なすべてのフィールドについて { fieldName: tooltipText }。

5. 文脈的ヒント

ユーザーが発見しない可能性がある機能のインラインヒントを生成します：

// 1 回表示、消可能、localStorage に保存
function ContextualHint({ id, children }) {
  const [dismissed, setDismissed] = useState(
    () => localStorage.getItem(`hint-${id}`) === 'dismissed'
  );
  if (dismissed) return null;
  return (
    <div className="text-sm text-muted-foreground bg-muted/50 rounded-md px-3 py-2 mb-3 flex items-center justify-between">
      <span>{children}</span>
      <button onClick={() => { localStorage.setItem(`hint-${id}`, 'dismissed'); setDismissed(true); }}>
        <XIcon className="h-3 w-3" />
      </button>
    </div>
  );
}

// 使用法
<ContextualHint id="keyboard-shortcuts">
  ヒント：Cmd+K を押して、任意のページまたはレコードにすばやくジャンプします。
</ContextualHint>

6. 教えるシードデータ

アプリの機能をデモンストレーションするサンプルレコードを生成します：

• 現実的なデータを持つサンプルクライアント（「テストクライアント」ではなく）
• 各状態（ドラフト、アクティブ、完了、アーカイブ）のサンプルレコード
• 関係を示すレコード（クライアント → 連絡先 → ポリシー → メール）

db-seed スキルパターンを使用しますが、オンボーディング品質のデータ — 優れたデータがどのように見えるかをユーザーに教えるレコードを使用します。

7. ヘルプページコンテンツ

実際のアプリから導出されたコンテンツを使用して、ヘルプ/FAQ ページを生成します：

## よくある質問

### 新しいクライアントを追加するにはどうすればよいですか？
1. サイドバーの「クライアント」をクリック
2. 右上の「クライアントを追加」をクリック
3. 名前とドメインを入力 — その他はすべてオプション
4. 「保存」をクリック

### 「重要度」とはどういう意味ですか？
重要度は、クライアントがビジネスにとってどの程度重要かを示す 1～5 の評価です...

### 削除を元に戻すことはできますか？
削除は永続的です。削除する前に常に確認が表示されます...

出力

生成されたコンテンツはすべて .jez/artifacts/onboarding/ に移動します：

.jez/artifacts/onboarding/
├── audit.md                    # ギャップ分析レポート
├── empty-states.tsx            # コピー付きの空の状態コンポーネント
├── welcome-banner.tsx          # 最初の実行ウェルカムコンポーネント
├── onboarding-checklist.tsx    # ゲッティング スタートチェックリスト（複雑なアプリの場合）
├── tour-steps.ts               # 機能ツアー構成
├── tooltip-content.ts          # ツールチップコピーマップ
├── contextual-hints.tsx        # インラインヒントコンポーネント + コンテンツ
├── seed-data.ts                # オンボーディングシードレコード
└── help-content.md             # FAQ/ヘルプページコンテンツ

生成されたファイルとそれらの場所をユーザーに伝えます。各ファイルの統合方法について具体的な指示を提供します：「クライアントリストが空の場合、このコンポーネントを /clients ページに追加します。」

ヒント

• コンポーネントパターンを生成する前にプロジェクトの既存パターンを読んでください — 新しいパターンを導入するのではなく、スタイルを一致させてください
• プロジェクトが shadcn/ui を使用している場合は、それを使用してください
• 手動のようではなく、有用な同僚のようなコピーを書いてください
• 空の状態は単一の最高影響変更です — まずそれらを実行してください
• 機能ツアーが長い場合は迷惑です — 最大 5 ステップ
• 文脈的なヒントは消可能で、1 回だけ表示される必要があります
• サンプルデータは現実的に見えるべき — 現実的なオーストラリアの名前、ドメイン、詳細を使用してください
• ヘルプページのコンテンツは ux-audit の「同僚に説明する」出力から生成できます

他のスキルとのペアリング

他のスキルも実行する場合...	このスキルが追加するもの...
ux-audit（徹底的）	監査の検出結果を入力として使用 — 見つかった問題を修正
db-seed	汎用テストデータの代わりにオンボーディング品質のシードデータを生成
app-docs	ヘルプページのコンテンツをユーザーガイドに取り込むことができます
product-showcase	空の状態とウェルカムフローは、デモスクリーンショットを見栄えよくします