User Flow – Designing the Auth Experience

Adding accounts is your first big, risky feature – get it wrong and people can't get into your app, or worse, see each other's data. So you'll slow down a little: design the whole experience first, then (in the next lessons) build it on a branch and test it on a preview before it touches your live site.

This lesson is about thinking in experiences – not "add a login button" but "how does a new user feel confident creating an account, and land somewhere useful?"

1. Understand auth UX patterns

Great auth is almost invisible – it just works. Keep these principles in mind:

  • Clarity: users always know what's happening and what to do next.
  • Trust: clear, familiar sign-in builds confidence.
  • Efficiency: the fewest steps to get in (offer social login).
  • Recovery: obvious paths when something goes wrong.
  • Continuity: after signup, land somewhere that shows value fast (onboarding).
Research modern auth UX
Research current best practices for authentication UX. Summarize:
- great signup and login flows (especially with Clerk),
- effective 3-5 screen onboarding patterns (skippable),
- where to place social login,
- error and recovery patterns.
Give me a few patterns to follow and a couple to avoid.

Outcome: You understand the patterns of a great auth experience.

I understand auth UX patterns and best practices

2. Create a branch for your auth work

Auth is exactly the kind of feature worth building on a branch and testing on a Vercel preview before merging to main (remember the Git Workflow lesson). Let Claude set that up.

Start an auth branch
Create a branch for my authentication work (e.g. auth) and switch to it. We'll build and test auth here, then merge to main once it works on the preview. Confirm which branch I'm on.

Outcome: You're on a dedicated branch for building auth safely.

I created a branch for my auth work

3. Map the authentication journey

Before building, map the full journey so nothing is missed. Have Claude write it up as a short design doc in your docs folder.

Map the auth user journey
Help me map the complete authentication journey for my app (read my concept in the docs folder for context), and save it as a short design doc in my docs folder. Cover:
- **New user:** landing → sign up (email + social) → first login → onboarding (3 screens, skippable) → main app.
- **Returning user:** login → straight to the main app (skip onboarding).
- **Error states:** invalid credentials, email already exists, network errors, expired session.
For each step, note what the user sees, what they can do, and what happens next.

Outcome: You have a clear map of every auth state and transition.

I mapped the complete authentication journey

4. Plan the build

Finish by shaping the build with Claude in plan mode – you'll execute it in the next lesson.

Plan the auth build (in plan mode)
We're in plan mode. Based on the auth journey we just mapped, plan how to build it with **Clerk for authentication** and **Neon for storing user data**. I want:
- signup/login pages and protected routes,
- a 3-screen skippable onboarding,
- each user's data scoped to them, enforced on the server.
Don't build yet – show me the plan and flag anything I need to decide.

Outcome: You have a plan for building auth, ready to execute next lesson.

I planned the auth build with Claude