onboarding-ux

# Onboarding UX

Audit a web app for onboarding gaps, then generate the in-app guidance to fix them. The goal: a new user should never stare at a blank screen wondering what to do.

## The Problem This Solves

You've built the features. They work. But when a new user logs in for the first time, they see:
- Empty tables with column headers and nothing else
- Sidebars full of labels that mean nothing to them yet
- No indication of where to start or what the app is for
- Features they don't know exist because nothing points to them

This skill finds those gaps and produces the content and code to fill them.

## Browser Tool Detection

Same as ux-audit — detect Chrome MCP, Playwright MCP, or playwright-cli. See ux-audit's browser-tools.md reference if needed.

## URL Resolution

Same as ux-audit — prefer deployed/live URL over localhost. Check wrangler.jsonc, CLAUDE.md, or running dev server.

## Workflow

### Phase 1: Audit — Find the Gaps

Browse the app as a brand new user. On every page, evaluate:

#### Empty States
Navigate to every list/table/collection page. For each:

| Check | Good | Bad |
|-------|------|-----|
| What does a zero-data page show? | "No clients yet. Add your first client to get started." + CTA button | Empty table with column headers, or blank white space |
| Is there a clear action? | Button: "Add your first [thing]" | Nothing — user has to find the action in the nav or a menu |
| Does it explain the feature? | "Clients are the people and businesses you work with. Add one to start tracking your relationships." | Just an empty container |
| Is the empty state designed? | Illustration or icon, helpful copy, prominent CTA | Identical to the populated state minus the data |

#### First Impression
Log in as a new user (or clear state to simulate). Evaluate:

| Check | What to look for |
|-------|-----------------|
| **Landing page** | Does the dashboard/home show something useful or is it empty? |
| **Orientation** | Within 10 seconds, do I know what this app does and where to start? |
| **First action** | Is the #1 thing I should do obvious and prominent? |
| **Cognitive load** | How many menu items, buttons, and options compete for attention? |
| **Welcome content** | Is there a welcome message, tour, or getting-started guide? Or just the raw app? |

#### Feature Discoverability
For each feature in the app:

| Check | What to look for |
|-------|-----------------|
| **Can I find it?** | Is it visible in the nav, or buried in a menu/submenu? |
| **Do I know what it does?** | Does the label explain it, or do I need to click to find out? |
| **Keyboard shortcuts** | Are there shortcuts? Are they discoverable (tooltip, help panel)? |
| **Advanced features** | Filters, bulk actions, search — are these visible or hidden? |
| **Settings and configuration** | Can I find the settings? Do I know what each setting does? |

#### Contextual Help Gaps
On each page:

| Check | What to look for |
|-------|-----------------|
| **Form fields** | Do complex fields have help text or tooltips? |
| **Jargon** | Any labels that a non-expert wouldn't understand? |
| **Consequences** | Do destructive or irreversible actions explain what will happen? |
| **Validation** | When I make a mistake, does the error message tell me how to fix it? |

#### Produce an Audit Report

Write to `.jez/artifacts/onboarding/audit.md`:

```markdown
# 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]
```

---

### Phase 2: Generate — Build the Solutions

After the audit, generate the actual content and code. Read the project's codebase to match the existing tech stack and component patterns.

#### 1. Empty State Components

For each empty state identified in the audit, generate a component:

```tsx
// 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>
  );
}
```

For each page, write specific copy:
- **Title**: What the feature is ("Clients")
- **Description**: Why it matters, in one sentence ("Track the people and businesses you work with")
- **Action**: What to do next ("Add your first client")

Write the copy so it feels like a helpful colleague, not a manual.

#### 2. Welcome / First-Run Experience

Generate one of these patterns based on the app's complexity:

**Simple app (3-5 features)**: Welcome banner on the dashboard
```tsx
// 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 varia