add plans from usability testing: onboarding v2, notifications, live editor

Onboarding UX v2 supersedes the original plan — reworks setup into a
single guided journey with progress bar, forgiving validation, and
contextual prompts for skipped steps.

Notification overhaul replaces floating toasts with inline feedback
and persistent top banners (110+ flash messages audited).

Live site editor is a design exploration for on-site editing with
contenteditable text and live CSS variable injection.

Also adds SEO settings and multiple providers to the roadmap.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/plans/onboarding-ux.md

@@ -1,109 +1,168 @@
-# Onboarding UX improvements
+# Onboarding UX v2
 
 Status: Planned
 
-## Context
+Supersedes the original onboarding-ux plan. Based on usability testing session (March 2026) covering the setup wizard, launch checklist, email provider setup, and general onboarding flow.
 
-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.
+## Vision
+
+A non-technical seller should be able to go from zero to a live shop without confusion or frustration. The setup should feel like one cohesive journey, not a scavenger hunt through admin pages. Every step should explain *why* it's needed, be forgiving of mistakes, and never leave the user stranded.
 
 ## 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.
+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. 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
+## What changes
 
-### High priority
+### A. Simplify initial setup to account creation only
 
-#### 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.
+The first screen should be dead simple and low-friction: email, password (with confirmation field), shop name. That's it. No provider keys, no Stripe.
 
-**Fix:** After completing the final wizard step, redirect to `/admin` with a flash message like "You're in! Here's your launch checklist." (~30m)
+- Live validation on all fields (email format, password strength/match, shop name not blank)
+- Note under shop name: "You can change this later"
+- On submit: create account, log in, redirect to the guided setup flow
 
-**Files:** `lib/berrypod_web/live/setup/onboarding.ex`
+Email/password correction after this point is just normal admin account settings — no special "go back to setup" needed.
 
-#### 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.
+**Files:** `lib/berrypod_web/live/setup/onboarding.ex`, possibly `lib/berrypod_web/live/admin/settings.ex`
 
-**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)
+### B. Guided setup flow with progress bar
+
+After account creation, the user enters a single multi-step guided journey. This replaces the current approach of separate admin pages.
+
+**Intro screen** — before any steps, briefly explain what Berrypod does and why you need each thing:
+
+> "Berrypod connects your print-on-demand products to your own online shop. To get fully set up, you'll need three things:
+>
+> - A **print provider** account (like Printify or Printful) to make and ship your products
+> - A **Stripe** account to accept payments from customers
+> - An **email provider** account so your shop can send order confirmations and shipping updates"
+
+Then the steps with a clear progress bar at the top. Each step shows: step number, title, whether it can be skipped, estimated time.
+
+**Steps:**
+1. **Connect print provider** — allow connecting multiple providers (not forced to pick just one). "Skip for now" available.
+2. **Connect Stripe for payments** — "Skip for now" available.
+3. **Set up email provider** — "Skip for now" available.
+
+Each step embeds the same settings UI components that live in the admin pages (shared, not duplicated). The guided flow adds extra context and hand-holding around them.
+
+On completion (or after skipping all): redirect to dashboard with clear status messaging.
+
+**Key UX decisions:**
+- Progress bar visible at all times, showing completed/current/upcoming steps
+- Each step has a "Skip for now" with a brief, non-naggy note about what won't work without it
+- External service links (create Printify account, etc.) open in new tabs with external-link icon and aria label
+- Users can go back to previous steps to correct mistakes
+- If revisiting (e.g. after closing browser), detect existing state via `Setup.setup_status/0` and resume from the first incomplete step
+
+**Files:** `lib/berrypod_web/live/setup/onboarding.ex`, `lib/berrypod/setup.ex`, new shared components
+
+### C. Forgiving API key validation
+
+API key entry should be as forgiving as possible:
+
+- Auto-strip leading/trailing whitespace on paste and submit
+- Validate format where known:
+  - Printify: 36-character UUID format
+  - Printful: specific prefix/length
+  - Stripe: must start with `sk_live_` or `sk_test_`
+  - Email providers: provider-specific format checks
+- Specific, helpful error messages: "This looks too short — Printify API keys are usually 36 characters" rather than generic "Invalid"
+- Validate on blur for fast feedback, not just on submit
+- Link to where to find the key: "Find your Printify API key at Settings > Connections"
+
+**Files:** `lib/berrypod_web/live/setup/onboarding.ex`, `lib/berrypod_web/live/admin/providers.ex`, validation logic in contexts
+
+### D. Email provider setup UX
+
+Rework the email provider selection and configuration:
+
+- **Recommended pick** highlighted at top — whichever has the best free tier, easiest setup, and supports newsletters. One clear "if you're not sure, pick this" option.
+- **Two groups:** "Also sends newsletters" vs "Transactional only" with one-line explanation of the difference
+- **One-liner per provider:** free tier info, setup difficulty ("paste one API key" vs "requires domain verification")
+- **Self-hosted/SMTP** in a collapsible "Advanced" section at bottom
+- **Guided flow after selection:** link to create account (new tab), then "Now enter these settings:" with config fields
+- **Send test email** button after configuration
+- **Remove** the masked key display ("Current: 84159e26•••4f3")
+- **Default from address** to the admin email automatically — don't surface during setup, it's a general settings thing for later
+
+**Files:** `lib/berrypod_web/live/admin/email_settings.ex`, shared components for guided flow
+
+### E. Contextual prompts for skipped steps
+
+When a step is skipped, surface the need where it matters — once per context, never as global nags:
+
+- **Products page** (no print provider): empty state explaining why products are empty, with link to connect a provider
+- **Cart/checkout** (no Stripe): checkout button disabled with explanation and link to connect Stripe
+- **Order detail** (no email provider): note saying "Order confirmation emails aren't being sent. Set up an email provider to send them automatically."
+- **Dashboard checklist**: always shows outstanding items regardless of skips
+
+Principle: explain what's missing, link to the fix, one instance per context.
+
+**Files:** `lib/berrypod_web/live/admin/dashboard.ex`, `lib/berrypod_web/live/shop/` (various), `lib/berrypod_web/components/`
+
+### F. Dashboard checklist and messaging
+
+Rework the dashboard checklist to match the guided setup flow:
+
+- **Before setup complete:** "Your admin account has been created. Continue the full setup below." with checklist of outstanding items
+- **After all steps done and site live:** "Your shop is live! Ready to go"
+- Checklist item names match the setup wizard step names exactly (no mismatches)
+- Each checklist item links to its admin settings page (for when they return outside the wizard)
+- Help/FAQ links next to items involving API keys or complicated config
+- Collapsible rather than dismissable (can always get it back)
+- Shipping setup and shop settings as additional checklist items (carried forward from v1 plan)
 
 **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.
+### G. Coming soon page fixes
 
-**Fix:** Add "Configure your shop" as the first checklist item, linking to `/admin/settings`. Mark complete when shop name differs from default. (~45m)
+- Fix logo displaying oddly to the side
+- Add a subtle "Admin login" link (footer or corner)
 
-**Files:** `lib/berrypod_web/live/admin/dashboard.ex`, `lib/berrypod/setup.ex`
+**Files:** `lib/berrypod_web/live/shop/coming_soon.ex`, associated template
 
-### Medium priority
+### H. External links UX
 
-#### 4. Checklist dismissable and gone forever
-Once dismissed, no way to get it back. Stored as `checklist_dismissed` setting.
+All links to external services throughout the app get:
+- `target="_blank"` + `rel="noopener noreferrer"`
+- Small external-link icon
+- Aria label indicating it opens in a new window
 
-**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:** templates throughout `lib/berrypod_web/`
 
-**Files:** `lib/berrypod_web/live/admin/dashboard.ex`, possibly `lib/berrypod_web/components/layouts/admin.html.heex`
+### I. Input styling — WCAG compliance
 
-#### 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.
+Increase input field border contrast to meet WCAG AA (3:1 minimum for UI components), aim for AAA. Clear, visible field edges in all contexts.
 
-**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`
+**Files:** `assets/css/admin/components.css`, `assets/css/shop/` CSS files
 
 ## 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 |
+| # | Task | Est | Status |
+|---|------|-----|--------|
+| A | Simplify initial setup to account creation only | 1.5h | planned |
+| B | Guided setup flow with progress bar | 4h | planned |
+| C | Forgiving API key validation | 1.5h | planned |
+| D | Email provider setup UX rework | 2h | planned |
+| E | Contextual prompts for skipped steps | 2h | planned |
+| F | Dashboard checklist and messaging rework | 2h | planned |
+| G | Coming soon page fixes (logo + admin link) | 30m | planned |
+| H | External links UX (new tabs, icons, aria) | 1h | planned |
+| I | Input styling — WCAG compliance | 1h | planned |
 
-Total estimate: ~5.5h
+Total estimate: ~15.5h
+
+## Suggested order
+
+1. **A** first — simplify the entry point
+2. **B** — the big piece, the guided flow
+3. **C** — validation improvements (can be done alongside B)
+4. **D** — email provider UX (part of the guided flow)
+5. **F** — dashboard checklist rework (depends on the flow being defined)
+6. **E** — contextual prompts (depends on knowing what's skippable)
+7. **G, H, I** — smaller fixes, can be done any time