# New users see a welcome screen or guided orientation on first login

- **Pattern:** `ab-002344` (`saas-onboarding.first-run.welcome-screen-or-tour`)
- **Severity:** medium
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-002344
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-002344)

## Why it matters

New users dropped directly into the same dashboard as veteran users face a cold-start problem: no context on what the product does, what to click first, or what success looks like. The user-experience taxon flags this as an activation failure — without a welcome screen, guided tour, or first-run flag distinguishing new from returning users, activation rates collapse and most new accounts never return for a second session. The cost of a missed first-run experience compounds: these users churn before they ever experience the product's core value.

## Severity rationale

Medium because the product works for returning users, but new-user activation — the metric that drives retention — breaks silently.

## Remediation

Gate the dashboard on an `onboardingCompleted` flag and redirect new users to a dedicated onboarding route. Update `src/app/(app)/dashboard/page.tsx` to check the flag on the session or user row, then build a 3-5 step checklist at `src/app/(app)/onboarding/page.tsx` that guides the user to the core action.

```tsx
const { data: user } = await getUser();
if (!user.onboardingCompleted) {
  redirect('/onboarding');
}
```

## Detection

- **ID:** `welcome-screen-or-tour`
- **Severity:** `medium`
- **What to look for:** Enumerate all first-run detection mechanisms: checks for `isNewUser`, `onboarding_completed`, `first_login`, or similar flags in session/database. Count the total. Check for dedicated welcome routes, onboarding step components, product tours (Shepherd.js, Intro.js, driver.js, custom spotlight components), or modal overlays triggered for new users.
- **Pass criteria:** First-time users see a distinct welcome experience — either a dedicated welcome screen, an onboarding checklist, a product tour, or a modal that orients them. At least 1 first-run detection mechanism must be present that distinguishes new from returning users.
- **Fail criteria:** No first-run detection logic exists. New users and returning users land on the identical screen with no differentiation. There is no welcome screen, tour, checklist, or onboarding modal in the codebase.
- **Skip (N/A) when:** The project is a CLI tool, API-only backend, or developer library with no user-facing UI.
- **Detail on fail:** `"No first-run detection found. New users land directly on the dashboard identical to returning users. No welcome screen, onboarding tour, or setup checklist exists in the codebase."`
- **Remediation:** Add first-run detection in `src/app/(app)/dashboard/page.tsx`:

  ```tsx
  const { data: user } = await getUser();
  if (!user.onboardingCompleted) {
    redirect('/onboarding');
  }
  ```

  Create an onboarding checklist at `src/app/(app)/onboarding/page.tsx` with 3-5 key setup steps.

---

Taxons: user-experience

HTML version: https://auditbuffet.com/patterns/ab-002344