onboarding-ux

オンボーディング UX

ウェブアプリのオンボーディングの不足点を監査し、それを解消するためのアプリ内ガイダンスを生成します。目標は、新規ユーザーが何をすればよいのか分からず、空白の画面を見つめたままにならないことです。

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

機能は作り終えています。問題なく動作します。しかし、新規ユーザーが初めてログインしたとき、目にするのは次のような画面です。

• 列見出しだけがあり、中身が空のテーブル
• まだ意味が分からないラベルが並ぶサイドバー
• どこから始めればよいのか、アプリが何のためのものなのかを示すものがない
• 何も案内がないため、存在に気づかない機能

このスキルは不足点を見つけ、それを埋めるコンテンツとコードを作成します。

ブラウザツールの検出

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

URL の解決

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

ワークフロー

フェーズ 1：監査 — 不足点を見つける

まったくの新規ユーザーとしてアプリを閲覧します。各ページで、次の点を評価してください。

空の状態

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

確認項目	良い例	悪い例
データがゼロのページには何が表示されますか？	「まだクライアントがいません。最初のクライアントを追加して始めましょう。」＋ CTA ボタン	列見出しだけの空のテーブル、または何もない白い画面
明確なアクションがありますか？	ボタン：「最初の［項目］を追加」	何もない — ユーザーがナビゲーションやメニューからアクションを探す必要がある
機能の説明がありますか？	「クライアントとは、仕事で関わる人や企業のことです。追加すると、関係を管理できるようになります。」	ただの空のコンテナー
空の状態がデザインされていますか？	イラストまたはアイコン、役立つ説明、目立つ CTA	データがないだけで、データがある状態と同じ

第一印象

新規ユーザーとしてログインするか、状態をクリアしてシミュレートします。次の点を評価してください。

確認項目	確認すること
ランディングページ	ダッシュボードやホームに役立つ情報が表示されますか？それとも空ですか？
全体像の把握	10 秒以内に、このアプリでできることと始める場所が分かりますか？
最初のアクション	最初にすべきことが分かりやすく、目立っていますか？
認知負荷	メニュー項目、ボタン、選択肢がいくつ注意を引こうとしていますか？
ウェルカムコンテンツ	ウェルカムメッセージ、ツアー、またはスタートガイドがありますか？それともアプリがそのまま表示されますか？

機能の見つけやすさ

アプリ内の各機能について、次の点を確認します。

確認項目	確認すること
見つけられますか？	ナビゲーションに表示されていますか？それともメニューやサブメニューの奥に隠れていますか？
機能が分かりますか？	ラベルから機能が分かりますか？それともクリックして確認する必要がありますか？
キーボードショートカット	ショートカットはありますか？ツールチップやヘルプパネルなどから見つけられますか？
高度な機能	フィルター、一括操作、検索などは見えていますか？それとも隠れていますか？
設定と構成	設定を見つけられますか？各設定の役割が分かりますか？

コンテキストヘルプの不足点

各ページで、次の点を確認します。

確認項目	確認すること
フォームフィールド	複雑なフィールドにヘルプテキストやツールチップがありますか？
専門用語	専門家でない人には理解しにくいラベルはありませんか？
影響	破壊的または取り消せない操作で、何が起きるか説明されていますか？
入力検証	間違えたとき、エラーメッセージに修正方法が示されていますか？

監査レポートを作成する

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

# Onboarding Audit: [App Name]
**Date**: YYYY-MM-DD
**URL**: [app url]

## First Impression Score
[1-5] — Can a new user figure out what to do within 30 seconds?

## Empty States Found
| Page | Current state | Recommendation |
|------|--------------|----------------|
| /clients | Empty table, no guidance | Add empty state with CTA |

## Missing Guidance
| Location | Gap | Priority |
|----------|-----|----------|
| Dashboard | No welcome or getting started | High |
| Settings | No descriptions on settings | Medium |

## Feature Discovery Issues
| Feature | Problem | Fix |
|---------|---------|-----|
| Keyboard shortcuts | No way to discover them | Add help panel |

## Quick Wins
[Top 5 changes that would have the biggest impact on new user experience]

---

フェーズ 2：生成 — 解決策を構築する

監査の後、実際のコンテンツとコードを生成します。既存の技術スタックとコンポーネントのパターンに合わせるため、プロジェクトのコードベースを確認してください。

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

監査で特定した空の状態ごとに、コンポーネントを生成します。

// Pattern — adapt to the project's component library
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>
  );
}

各ページに合わせて具体的な文言を書きます。

• タイトル：機能の名前（「クライアント」）
• 説明：重要である理由を一文で伝えます（「仕事で関わる人や企業を管理します」）
• アクション：次に行うことを示します（「最初のクライアントを追加」）

マニュアルのようではなく、親切な同僚のように感じられる文言にしてください。

2. ようこそ / 初回起動体験

アプリの複雑さに応じて、次のパターンのいずれかを生成します。

シンプルなアプリ（機能 3〜5 個）: ダッシュボードにようこそバナーを表示

// Dismissable welcome banner — shown until user closes it or completes first action
function WelcomeBanner({ onDismiss }) {
  return (
    <div className="rounded-lg border bg-card p-6 mb-6">
      <h2 className="text-xl font-semibold mb-2">Welcome to [App Name]</h2>
      <p className="text-muted-foreground mb-4">Here's how to get started:</p>
      <ol className="space-y-2 mb-4">
        <li>1. Add your first client</li>
        <li>2. Create a policy for them</li>
        <li>3. Check your dashboard for what needs attention</li>
      </ol>
      <Button variant="outline" size="sm" onClick={onDismiss}>Got it</Button>
    </div>
  );
}

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

// Persistent getting-started checklist — tracks progress
function OnboardingChecklist({ steps, completedSteps }) {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Getting Started</CardTitle>
        <p className="text-sm text-muted-foreground">
          {completedSteps.length} of {steps.length} complete
        </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: 'Your clients live here. Add people and businesses you work with.',
    placement: 'right',
  },
  {
    target: '[data-tour="create-button"]',
    content: 'Click here to create something new — a client, policy, or email.',
    placement: 'bottom',
  },
  {
    target: '[data-tour="search"]',
    content: 'Use search to find anything fast. Try Cmd+K for the quick switcher.',
    placement: 'bottom',
  },
];

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

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

複雑な UI 要素ごとに、ツールチップの文言を生成します。

// Pattern for info tooltips
<TooltipProvider>
  <Tooltip>
    <TooltipTrigger asChild>
      <InfoIcon className="h-4 w-4 text-muted-foreground" />
    </TooltipTrigger>
    <TooltipContent>
      <p>Significance shows how important this client is to your business.
      5 = critical (your biggest client), 1 = minimal (one-off interaction).</p>
    </TooltipContent>
  </Tooltip>
</TooltipProvider>

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

5. コンテキストヒント

ユーザーが見つけられないかもしれない機能について、インラインヒントを生成します。

// Shown once, dismissable, stored in 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>
  );
}

// Usage
<ContextualHint id="keyboard-shortcuts">
  Tip: Press Cmd+K to quickly jump to any page or record.
</ContextualHint>

6. 学びにつながるシードデータ

アプリの機能を実演するサンプルレコードを生成します。

• リアルなデータを使ったサンプルクライアント（「Test Client」ではないもの）
• 各状態（下書き、有効、完了、アーカイブ済み）のサンプルレコード
• リレーションシップを示すレコード（クライアント → 連絡先 → ポリシー → メール）

オンボーディング品質のデータ でシードスクリプトを書いてください。つまり、良いデータとはどのようなものかをユーザーに教えるレコードです。

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

実際のアプリから導き出した内容で、ヘルプ / FAQ ページを生成します。

## Frequently Asked Questions

### How do I add a new client?
1. Click "Clients" in the sidebar
2. Click "Add Client" in the top right
3. Fill in the name and domain — everything else is optional
4. Click "Save"

### What does "significance" mean?
Significance is a 1-5 rating of how important a client is...

### Can I undo a deletion?
Deletions are permanent. You'll always see a confirmation before...

出力

生成されたすべてのコンテンツは .jez/artifacts/onboarding/ に出力されます。

.jez/artifacts/onboarding/
├── audit.md                    # The gap analysis report
├── empty-states.tsx            # Empty state components with copy
├── welcome-banner.tsx          # First-run welcome component
├── onboarding-checklist.tsx    # Getting-started checklist (if complex app)
├── tour-steps.ts               # Feature tour configuration
├── tooltip-content.ts          # Tooltip copy map
├── contextual-hints.tsx        # Inline hint component + content
├── seed-data.ts                # Onboarding seed records
└── help-content.md             # FAQ / help page content

どのファイルが生成されたのか、どこに統合すればよいのかをユーザーに伝えます。それぞれについて具体的な手順を提示してください。「クライアント一覧が空のときに、このコンポーネントを /clients ページに追加してください。」

ヒント

• 生成する前に、プロジェクトの既存のコンポーネントパターンを読んでください。スタイルに合わせ、新しいパターンを持ち込まないようにします
• プロジェクトで shadcn/ui コンポーネントを使っている場合は、それを使ってください
• マニュアルではなく、親切な同僚のように文言を書いてください
• 空の状態は最も効果の高い変更です。まずそこから着手してください
• 機能ツアーは長すぎると煩わしいので、最大 5 ステップにしてください
• コンテキストヒントは閉じられるようにし、一度だけ表示するようにしてください
• サンプルデータはリアルに見えるようにしてください。リアルなオーストラリアの名前、ドメイン、詳細を使ってください
• ヘルプページのコンテンツは、ux-audit の「同僚に説明する」出力から生成できます

他のスキルとの組み合わせ

併用するスキル...	このスキルが追加するもの...
ux-audit（徹底）	監査の結果を入力として使用し、見つかった問題を修正します
app-docs	ヘルプページのコンテンツをユーザーガイドに活用できます
product-showcase	空の状態とようこそフローにより、デモのスクリーンショットがより良く見えます