onboarding-ux

What this skill does

# 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 variant="outline" size="sm" onClick={onDismiss}>Got it</Button>
    </div>
  );
}
```

**Complex app (6+ features)**: Checklist-style onboarding
```tsx
// 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. Feature Tour

Generate a tour configuration for react-joyride (or equivalent):

```tsx
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',
  },
];
```

Also generate the `data-tour` attributes that need to be added to existing components.

#### 4. Tooltip and Help Content

For each complex UI element, generate tooltip copy:

```tsx
// 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>
```

Generate