# Onboarding UX improvements

Status: Planned

## Context

The setup wizard and dashboard launch checklist work, but there are gaps that leave new users guessing. Goal: make onboarding totally fool-proof and guided so a non-technical seller can go from zero to live store without confusion.

## Current flow

1. **Setup wizard** (`lib/berrypod_web/live/setup/onboarding.ex`): 3 cards — admin account → provider API key → Stripe connection. Gated by secret in prod, auto-login after account creation.
2. **Dashboard checklist** (`lib/berrypod_web/live/admin/dashboard.ex`): 5 items with progress bar — sync products, connect Stripe, customise theme, place test order, go live. Visible when `site_live` is false and not dismissed.
3. **Coming soon page**: blocks public access before launch.
4. **Setup status** (`lib/berrypod/setup.ex`): `setup_status/0` returns booleans for each milestone.

## Gaps identified

### High priority

#### 1. Dead end after setup wizard
The wizard ends at Stripe connection with no redirect or next-steps message. User has to figure out where to go.

**Fix:** After completing the final wizard step, redirect to `/admin` with a flash message like "You're in! Here's your launch checklist." (~30m)

**Files:** `lib/berrypod_web/live/setup/onboarding.ex`

#### 2. No shipping rate setup in checklist
Checkout requires shipping rates. There's no checklist item for configuring shipping, and no warning that checkout will fail without it. A user could "Go live" with no shipping rates.

**Fix:** Add "Set up shipping" checklist item that links to `/admin/settings` (shipping section). Gate "Go live" on at least one shipping profile existing. (~1h)

**Files:** `lib/berrypod_web/live/admin/dashboard.ex`, `lib/berrypod/setup.ex`

#### 3. No shop settings in checklist
Shop name, currency, country are critical but not in the checklist. User could go live with "My Shop" as the name.

**Fix:** Add "Configure your shop" as the first checklist item, linking to `/admin/settings`. Mark complete when shop name differs from default. (~45m)

**Files:** `lib/berrypod_web/live/admin/dashboard.ex`, `lib/berrypod/setup.ex`

### Medium priority

#### 4. Checklist dismissable and gone forever
Once dismissed, no way to get it back. Stored as `checklist_dismissed` setting.

**Fix:** Replace dismiss with a collapse/expand toggle. Or add a "Show launch checklist" link in the dashboard sidebar when dismissed but site isn't live yet. (~15m)

**Files:** `lib/berrypod_web/live/admin/dashboard.ex`, possibly `lib/berrypod_web/components/layouts/admin.html.heex`

#### 5. "Place a test order" has zero guidance
Links to the shop home page. No mention of Stripe test mode, test card numbers, or what a successful test looks like.

**Fix:** Add inline help text under the checklist item: "Use card number 4242 4242 4242 4242 with any future expiry and CVC. You'll see the order appear in Orders when it works." (~45m)

**Files:** `lib/berrypod_web/live/admin/dashboard.ex`

#### 6. Skip completed wizard steps on revisit
If a user closes their browser mid-setup and comes back, the wizard restarts from scratch (session-based). Should detect existing state and skip completed steps.

**Fix:** In `mount/3`, call `Setup.setup_status/0` and set `current_step` to the first incomplete step. (~1h)

**Files:** `lib/berrypod_web/live/setup/onboarding.ex`

#### 7. Better provider connection error messages
If the API key is wrong, the error is generic. No link to where to find the key, no troubleshooting.

**Fix:** Add provider-specific help text: "Find your Printify API key at Printify → Settings → Connections" (with link). Show the actual API error when it's user-facing (auth failure vs server error). (~30m)

**Files:** `lib/berrypod_web/live/setup/onboarding.ex`, `lib/berrypod_web/live/admin/providers.ex`

### Low priority

#### 8. Guide theme customisation
`theme_customised` is true if any setting differs from defaults. Changing one colour counts. No guidance on what to customise.

**Fix:** Add a brief tip under the checklist item: "Upload your logo, pick your colours, and choose a font that matches your brand." (~15m)

**Files:** `lib/berrypod_web/live/admin/dashboard.ex`

#### 9. Clarify "Sync your products" checklist step
Links to `/admin/providers` but user needs to click "Sync" on an already-connected provider. Confusing if they connected during the wizard.

**Fix:** If provider is connected but no products synced, link directly to the provider detail page with a prompt to sync. If products exist, mark as complete. (~15m)

**Files:** `lib/berrypod_web/live/admin/dashboard.ex`

#### 10. Move email setup into checklist as optional step
The orange "email not configured" banner appears on every page but isn't in the checklist. Email is needed for abandoned cart, order confirmations, contact form.

**Fix:** Add as a non-blocking checklist item (doesn't gate "Go live" but shows as recommended). (~30m)

**Files:** `lib/berrypod_web/live/admin/dashboard.ex`, `lib/berrypod/setup.ex`

## Task breakdown

| # | Task | Priority | Est | Status |
|---|------|----------|-----|--------|
| 1 | Redirect to dashboard after wizard completion with welcome flash | High | 30m | planned |
| 2 | Add shipping setup to checklist, gate "Go live" on shipping existing | High | 1h | planned |
| 3 | Add shop settings to checklist (name, currency) | High | 45m | planned |
| 4 | Make checklist collapsible instead of dismissable | Medium | 15m | planned |
| 5 | Add test order guidance (test card number, what to expect) | Medium | 45m | planned |
| 6 | Skip completed wizard steps on revisit | Medium | 1h | planned |
| 7 | Better provider connection error messages with help links | Medium | 30m | planned |
| 8 | Add theme customisation tips to checklist | Low | 15m | planned |
| 9 | Smarter "Sync products" checklist link | Low | 15m | planned |
| 10 | Add email setup as optional checklist item | Low | 30m | planned |

Total estimate: ~5.5h