First-Minute Aha: User Onboarding Design for Vibe Projects

Let me start with a fact many vibe project makers don't want to admit: your product probably isn't dying from too few features. It's dying in the first minute after signup.

Think about your own behavior. You spot a cool new tool on Product Hunt or X, click through, sign up — and then? Email verification, company name, team size, a three-minute welcome video, then "complete your profile for a better experience." By the third screen, you've forgotten why you came, you close the tab, and go back to scrolling. You never used a single feature, yet the tool already feels "not good" in your head.

That's the cruelest funnel of the vibe coding era. Shipping used to be slow and acquisition expensive, so people at least polished first impressions. Now one person can vibe-code a SaaS over a weekend. Launching became trivially easy, so everyone pours energy into "adding more features" while nobody tends to "what happens in the first minute." Result: traffic comes, signups come, retention is zero. Your signup curve looks great; your DAU curve looks like a flatlined EKG. The problem isn't product value. It's onboarding.

This guide is a field manual for that first minute. Three core theses up front:

First: the goal of onboarding is not "teach the user how to use the product." It's "let the user experience the value you promised, as fast as possible." That difference decides whether your onboarding reads like a tutorial or an ad. Tutorials care about "what this button does." Ads care about "what you get right now." Users don't care about your feature map. They care about one thing: is this minute worth it?

Second: vibe projects must design onboarding in minutes, not days. Big companies can run email sequences and seven-day habit programs — they have brand, sunk cost, and sales follow-up. You have none of that. An indie product's user is just passing by, and their patience budget is 60 to 180 seconds. Over budget, they leave, and most likely never come back.

Third: good onboarding is subtraction, not addition. Most onboarding isn't missing a step — it has ten steps too many. Later in this guide you'll get a "field-cutting checklist" and a pre-launch audit list, all built on one idea: every unnecessary step you delete lifts conversion a notch.

This guide is for indie developers and small teams building with vibe coding: 8 sections, from a canvas template for finding your Aha moment, to a decision table for picking among three onboarding patterns, to a paste-ready React onboarding component, to an analytics event naming spec. After reading, you should be able to redo your product's first minute within a week.

1. Why Vibe Projects Die at Onboarding: Three Structural Reasons

Diagnose first. Vibe projects don't fumble onboarding from lack of care — the category has three structural handicaps.

Handicap one: features are vibed into existence; the path was never walked. One defining trait of AI-written code is that adding features is dirt cheap: one prompt, three new pages. So products get "complete" fast, but nobody — including the author — has ever walked the whole main path with fresh "first-open" eyes. You open your own product and think "I know where to click." A new user opens it and thinks "what is all this." That perspective gap is the root of most onboarding problems. The cure is simple, and it's item six in the pre-launch checklist later: find a friend who's never used your product, screenshare, and watch where they get stuck in minute one. You'll want to rewrite half your onboarding.

Handicap two: treating "signup" as the finish line. Many indie developers mentally end at "the user signed up," as if signup equals acquired. But signup just means the user gave you a contact. Real acquisition happens the first time they say "oh, this is useful" — the Aha moment. Every step between signup and Aha is a leaking funnel. Why does Duolingo's signup take 15 seconds and drop you into your first exercise immediately after picking a language? Because it bets that once you've had fun, you'll come back and fill in the profile. The order cannot be reversed.

Handicap three: copying big-company onboarding at indie scale. Notion's new-user experience is beautiful: template gallery, starter docs, sample pages. But Notion has hundreds of people and mature user segmentation. Copy the form and you only copy the complexity. A three-person todo app copying Notion's "workspace template hub" loses users on the template-picker screen — because the user just wanted a place to jot things down. For small products, onboarding works best when it feels like "the street vendor handing you a free taste," not a guided museum tour.

One sentence to sum up: vibe projects' onboarding problem is fundamentally "too little value density in the first minute." If the effort a user spends in that minute (filling forms, watching tutorials, learning concepts) exceeds the value they perceive, they leave. Everything that follows is about raising first-minute value density.

2. Aha Moment First: Draw Your "Value Promise Canvas"

Before designing any onboarding, answer one question: if the user could do only one thing, which action would make them feel "this was worth it"?

That's the Aha moment — the instant a user truly experiences your promised value for the first time. Note the three keywords: first (the earlier the better), truly (not watching a promo video — doing it with their own hands), and your promised value (it must match the claim on your landing page).

A few textbook examples to calibrate what "matching" means: Loom promises "one-click screen recording and sharing," and its Aha moment is the second a user finishes their first recording and gets a share link. Canva promises "design without being a designer" — Aha is the moment a user finishes customizing their first template and exports something post-worthy. Todoist promises "get it out of your head" — Aha is building the first project, checking off the first task, and hearing that crisp completion sound. These products' onboarding designs differ wildly, but their first minute does the same thing: push the user toward the Aha moment, as fast as possible.

Counterexamples are easy to find too: plenty of AI writing tools headline "generate viral copy in 10 seconds," then greet new users with "pick your industry (12 options) → pick a writing style (8 options) → connect your knowledge base (optional but recommended) → watch a 2-minute tutorial." Four steps in, the user is still three steps away from "generate the first paragraph." A form wall stands between the promise and the experience; the Aha moment is buried in minute five — and most users leave in minute three.

How do you find your product's Aha moment? Three routes, ranked by reliability:

1. Look at data (if you have any). Split users into "retained after 7 days" vs. "churned," then look back at the biggest behavioral difference on day one. The action the retained group did and the churned group didn't is very likely your Aha moment. This is how Facebook found its famous "10 friends in 7 days" number. Crude, but it works.

2. Ask users (use this if you have no data). Don't ask "what do you think of our product." Ask "when did you first think 'this is useful' — what were you doing at that moment?" The scene they describe is a sketch of your Aha moment. Ask 5 to 10 real users; the answers will converge.

3. Stare at your landing page. Copy the biggest value claim on your homepage, then ask: how many steps does it take a user to verify that claim with their own hands? More than 3 steps — your onboarding has a problem. More than 5 — your whole product architecture may have a problem.

Once found, draw it into the "Value Promise Canvas" below. Grab a piece of paper (or open a doc) and fill it in now — if you can't fill it out, stop here, because everything downstream hangs on this table:

Canvas item	How to fill it	Example (fictional: AI meeting-notes tool "Minuta")
One-sentence value promise	Copy the biggest line from your landing page. Max 20 words.	Meeting ends, notes write themselves
Aha moment	Which action, done by the user's own hand, triggers the "wow"? Must be an action, not a page.	Uploading the first meeting recording and watching structured notes generate
Steps to Aha	Count from "opens the site" to Aha. List every step.	Sign up → verify email → upload recording → wait → view notes (5 steps)
Which steps can be cut	For each step ask: without it, does the Aha still hold?	Email verification can be deferred; upload can be replaced with "try a sample recording" → down to 3 steps
Is the "wow" wow enough	Score honestly, 1–5. Below 3, go fix the product first.	4: watching AI compress a 40-minute meeting into one page hits hard the first time

The last row is the ruthless one: if the Aha moment itself isn't "wow" enough, no onboarding polish will save you. Onboarding is an amplifier, not a magician. It can deliver a 4-out-of-5 experience in the first minute, but it can't conjure a 4-out-of-5 experience that doesn't exist. Many people iterate on onboarding endlessly with no results — the root cause is here. First confirm your product genuinely has a "wow" worth delivering quickly, then talk onboarding design.

3. Picking Among Three Onboarding Patterns: Don't Start with a Tour

Onboarding design boils down to three patterns. Picking the wrong one is worse than doing nothing — forcing a social product's tour onto a utility tool is like shipping an instructional video with a screwdriver. The user just wants to turn screws.

Pattern one: Progressive disclosure — "Here's 20%. Ask me for the rest when you need it."

This is the best default for most vibe projects. The move: the first screen exposes only the single path to the Aha moment; everything else stays hidden until the user develops a need. Linear is a master of this: a fresh workspace opens almost absurdly clean, with one visual center — the empty state saying "create your first issue." Once you've created a dozen issues and things feel messy, labels, filters, and automation rules gradually surface. Figma does the same: first open, you're facing a canvas and a few basic shapes; power features like components and auto layout hide in secondary menus.

The essence of progressive disclosure is one judgment: a feature the user doesn't need right now is noise. Your 40 beloved features look like 40 "things I have to learn" to a new user. Hiding them isn't shameful; when the user comes looking, hand them over, and they'll feel understood.

Pattern two: Empty-state onboarding — "Every empty pixel is ad inventory."

A new user's product is empty everywhere: no tasks, no docs, no data, no friends. Most products drop a gray "No data yet" here — leaving the best ad slot on the site vacant. Empty-state onboarding turns every "empty" into a micro-onboarding moment.

Positive example: Todoist doesn't open empty for new users — the task list ships with a few pre-loaded sample tasks, the first one reading "Click this task and check it off 👇." The user checks it, hears the completion sound, sees the celebration animation — the Aha moment lands with zero tutorial. Notion learned this the hard way: early new users faced a literal blank page, churn was brutal, and only later did the Template Gallery arrive so users "start from something finished and modify it" instead of "start from blank and think." Every vibe project should carve this on the wall: never let a user face a truly blank page.

Pattern three: Interactive product tour — a stimulant. Use with caution.

Those "click here to create a project → great! Now click here to invite teammates → awesome!" bubble tours. Arc browser's onboarding tour is the genre's peak: a plotted "starter quest" with instant feedback at every step. But note the cost: Arc dedicated designers and months of polish to that tour. For a one-or-two-person vibe project, tours have three fatal flaws: they're expensive to build (every UI change means re-recording steps), users hate them (90% hit "skip"; the other 10% aren't really reading while clicking "next"), and they're fragile (one responsive-layout shift and the bubble points at the wrong thing).

My take is blunt: a tour should be the last pattern you consider, not the first. Only build one when your product genuinely has a "users will get lost without guidance" multi-step flow (like a configuration wizard). Otherwise, solve 80% of the problem with empty-state onboarding and progressive disclosure first.

Here's the decision table. Find your product type, pick a row:

Product type	Recommended pattern	What the first screen should be	Aha target (which minute)	Never do this
Utility (todos, notes, budgeting)	Empty-state onboarding first	One pre-loaded, interactive sample item — one click, instant feedback	Within 1 minute	No feature tour; don't make users create a "workspace" first
Creation (design, writing, video)	Empty state + templates	Template gallery / sample works — click one and start editing	Within 2 minutes (first template customized)	Don't start from a blank canvas; don't teach layer concepts first
AI chat / generation	Progressive disclosure	One pre-filled prompt example — hit send, get a result	Within 1 minute (first generation seen)	Don't ask users to pick models or tune parameters first; no "prompting tutorial"
Social / collaboration	Progressive disclosure + empty state	Let the user play solo first (personal tasks/drafts); collaboration comes later	Within 3 minutes (solo delight first, then invite)	Never force "invite 3 teammates to continue" — that's a churn accelerator
Data / analytics (dashboards)	Empty-state onboarding	Render a "already gorgeous" dashboard with sample data	Within 1 minute (seeing "my data will look like this")	Don't ask users to connect data sources or paste API keys first

Notice the last column: every "never" is a gate placed before the Aha moment. The ultimate test of your pattern choice is one question: starting from this pattern, did the step count to the Aha moment go down? If not, you picked wrong. Pick again.

4. Stop Making Users Fill Forms: 7 Field Types to Cut from Signup

The signup form is the biggest wall standing before the Aha moment. Anyone who's run A/B tests knows a rough-but-reliable rule: every extra field drags conversion down a notch — the exact drop varies by product, but the direction never changes. So this section isn't about "how to design forms." It's about "how to cut forms."

Here are the 7 most common signup-page freeloaders in vibe projects, ranked by cut priority:

1. "How did you hear about us?" — Cut it, no hesitation. That's marketing's need, not the user's. For channel attribution, capture UTM parameters automatically — don't make the user fill your survey. When users see this question on a signup page, they think: "I just wanted to try it out, and you're taking a census?"

2. Company name / team size / job title. — Unless your pricing is literally tiered by team size and must be set at signup, defer all of it. These fields exist so sales can profile leads, but your vibe project probably has no sales team. Want segmentation? Watch behavior: someone who created 5 projects is obviously a power user — no need for them to check "I am a power user."

3. Avatar upload. — Asking for an avatar at signup is like hanging a sign that says "go find a nice photo and come back." With OAuth (GitHub/Google), just take the existing avatar. With email signup, generate a default (colored initials) and let users swap it once they love the product.

4. Phone number + SMS verification (up front). — Unless you're in finance, social, or another heavily regulated / fraud-sensitive category, push SMS verification later. Delivery rates, wait times, mistyped codes, resends — every step bleeds users. Same for email verification: if you can do "try first, verify later," don't block the door. That's what Loom did back in the day — record first, sign up when you want the share link.

5. Password complexity + confirm-password field. — It's 2026. A product still demanding "8–20 characters with upper/lowercase and symbols" typed twice deserves its churn. Use magic links or OAuth and be done in one step. Passwords: avoid if you can; if you must, cut the "confirm password" box first and add a show-password eye icon instead.

6. Birthday / gender / location. — Unless your features genuinely depend on them (a birthday-reminder app needs birthdays), the only reason these sit on a signup page is "might be useful someday." "Might be useful someday" is the most expensive product requirement there is — it's mortgaging today's conversion.

7. Full terms-of-service read confirmation. — Keep the legally required "I have read and agree" checkbox, but don't design it as "scroll through 8,000 words to continue." One checkbox plus a link is enough. Offloading legal's anxiety onto users is the cheapest form of cost-shifting.

After the cuts, what should signup look like? Ideally: one email field (or two OAuth buttons) + one "Get started" button. That's it. Duolingo, Loom, Arc — all variations of this.

But you still need profile data eventually. The answer is progressive profiling: split the questions apart and ask each at the moment the user is most willing to answer. There's an iron law of timing — ask right after the user just got value, when response rates peak. A Todoist user who just checked off their first task will happily tell you what they do for work; a freshly registered user who hasn't had fun yet will resent any question.

Here's a copy-paste collection schedule:

When	What to ask (1–2 max)	Why now
At signup	Email / OAuth only. Ask nothing.	Zero friction — just get them in
Right after the first Aha moment	Nickname (for personalization)	Defenses are lowest right after delight; a nickname pays off instantly in the UI
2nd–3rd visit	Use-case single choice (work / study / personal — max 3 options)	They've decided to stay; they'll spend 5 seconds helping you "make it better"
Around day 7 (or after N core actions)	Industry / team size (if truly needed)	You're asking a "regular" now — response rate and accuracy are in a different league
Never at signup	Phone number, company name, "how did you hear about us"	See the 7 field types above

The essence of this sequence: give value first, ask for information later. Every question should come after the user "owes" you one. That's not manipulation — it's respect. Respect for their time, and for your own conversion rate.

5. Pre-Load the "Wow": The Empty State Is Your Best Ad Slot

After signup, the first screen a user sees is probably empty: no tasks, no notes, no data. That's the most dangerous minute — and the biggest opportunity — because user attention is 100% on the screen with zero distractions. Every word you put in an empty state gets read at a rate you'd kill for anywhere else.

But most products' empty states look like this: a gray icon + "No data yet" + a "Create" button. The problem with that trio: it only tells the user "there's nothing here," never "here's what could be here." Users see "No data yet" and think "oh, I have to build this from scratch," then close the tab.

A good empty state has three elements, all required: ① explain why it's empty (kill the self-doubt — "did I do something wrong?"); ② one immediately clickable action (button copy starts with a verb, not a noun); ③ a "here's what done looks like" (a sample or template showing the destination).

Below are copy templates for three high-frequency scenarios, bilingual, ready to use by swapping keywords. Note the button style: always lead with a verb so users feel "clicking does something."

Scenario A: Todo / task apps

	Anti-pattern (don't)	Template (steal this)
Headline	No tasks yet	Your first list is ready 👇
Body	(none)	Below are 3 sample tasks. Try checking off the first one and see what happens.
Button	New task	＋ Add my first task

Scenario B: Creation tools (notes / design / docs)

	Anti-pattern (don't)	Template (steal this)
Headline	No works yet — go create!	Don't start from blank — pick one of these 3 templates
Body	(none)	Each template is a finished piece. Change a few words and it's yours.
Button	New	Browse templates →

Scenario C: Dashboards / analytics

	Anti-pattern (don't)	Template (steal this)
Headline	No data	Sneak peek: this is what your data will look like 📊
Body	Connect a data source to view	Below is a live preview rendered with sample data. Connect your source and it becomes yours.
Button	Connect data	Explore with sample data / Connect my data

Note scenario C's button order: "Explore with sample data" first, "Connect my data" second. The order is deliberate — let users get delighted at zero cost (seeing a gorgeous dashboard) before asking them to do the real work. Putting "explore" first actually increases clicks on "connect," because users have seen the destination with their own eyes. That's the point from this section's opening: an empty state isn't a sad apology for missing data — it's the one moment you get an uninterrupted monologue. Don't waste it on "No data."

One more detail: sample content must be interactive and deletable. Todoist's sample tasks can be checked off, Notion's template pages are directly editable, the dashboard's sample data is clickable for detail — "can touch" vs. "can only look" is an order-of-magnitude difference in Aha intensity. And once users clear the samples, the empty state should gracefully fall back to "truly empty" (a line like "Nice — this is your turf now"), not haunt them with zombie samples.

6. Code Lab: A 3-Step Onboarding Component on localStorage

Theory's done — here's code. Many vibe projects ship bad onboarding not from laziness but because "building an onboarding component" sounds like a big project. The core logic is ~50 lines: track which step the user is on, persist to localStorage, don't nag them again. Below is a complete component you can paste into a Next.js project — TypeScript + Tailwind, zero dependencies.

Design decisions first, so you don't copy blindly: ① Exactly 3 steps. Past 3 steps, completion rates fall off a cliff — not theory, but a conclusion re-verified by countless products' analytics. If your Aha moment can't be told in 3 steps, your homework from the earlier sections isn't done: cut steps, don't add a fourth. ② localStorage, not a backend field. Onboarding state is purely frontend — don't touch your DB schema or add API calls just to record "has the user seen the tour." Your backend schema is messy enough already. ③ The skip button must be visible at a glance. Forced walkthroughs teach users one thing: "this product is annoying." ④ Every step carries a concrete action, not just text. Remember the first thesis: onboarding is an ad, not a tutorial.

"use client";

import { useEffect, useState } from "react";

const STORAGE_KEY = "myapp-onboarding-done-v1";
// Note the versioned key. When you revamp the flow later,
// bump v1 to v2 and existing users will see the new version —
// no need to clean anyone's localStorage.

type Step = {
  title: string;
  desc: string;
  actionLabel: string;
  // Each step binds a REAL action: clicking moves the user
  // one step closer to the Aha moment.
  onAction: () => void;
};

const STEPS: Step[] = [
  {
    title: "Taste first, no signup needed",
    desc: "Hit the button below and we'll render a dashboard from sample data, so you can see what yours will look like.",
    actionLabel: "Explore with sample data",
    onAction: () => {
      // TODO: replace with your own logic, e.g. router.push("/demo")
      window.dispatchEvent(new CustomEvent("onboarding:preview"));
    },
  },
  {
    title: "Now make it yours",
    desc: "Got the idea? Connect your data source and the same charts become your real data — under a minute.",
    actionLabel: "Connect my data",
    onAction: () => {
      window.dispatchEvent(new CustomEvent("onboarding:connect"));
    },
  },
  {
    title: "Done — go see your first dashboard",
    desc: "Data is syncing. Take a look around — this is what every morning will look like from now on.",
    actionLabel: "View my dashboard",
    onAction: () => {
      window.dispatchEvent(new CustomEvent("onboarding:finish"));
    },
  },
];

export default function OnboardingTour({
  onEvent,
}: {
  // Analytics hook: events pass through here (see Section 7)
  onEvent?: (name: string, props?: Record<string, unknown>) => void;
}) {
  const [step, setStep] = useState<number | null>(null);

  useEffect(() => {
    // Key: read localStorage only on the client to avoid SSR hydration errors
    try {
      if (!localStorage.getItem(STORAGE_KEY)) {
        setStep(0);
        onEvent?.("onboarding_started");
      }
    } catch {
      setStep(0);
    }
    const onKey = (e: KeyboardEvent) => {
      if (e.key === "Escape") dismiss("esc");
    };
    window.addEventListener("keydown", onKey);
    return () => window.removeEventListener("keydown", onKey);
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, []);

  if (step === null) return null;
  const current = STEPS[step];
  const isLast = step === STEPS.length - 1;

  const dismiss = (reason: "skip" | "esc" | "done") => {
    try {
      localStorage.setItem(STORAGE_KEY, "1");
    } catch {
      /* never block on private-mode write failures */
    }
    onEvent?.(
      reason === "done" ? "onboarding_completed" : "onboarding_skipped",
      { at_step: step, reason }
    );
    setStep(null);
  };

  const next = () => {
    onEvent?.("onboarding_step_viewed", { step });
    current.onAction();
    if (isLast) dismiss("done");
    else setStep(step + 1);
  };

  return (
    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50 p-4">
      <div className="w-full max-w-md rounded-2xl bg-white p-6 shadow-xl">
        {/* Progress dots: showing "how many steps left" is itself a pressure valve */}
        <div className="mb-4 flex gap-1.5">
          {STEPS.map((_, i) => (
            <div
              key={i}
              className={`h-1.5 flex-1 rounded-full ${
                i <= step ? "bg-blue-600" : "bg-gray-200"
              }`}
            />
          ))}
        </div>
        <h3 className="text-lg font-bold">{current.title}</h3>
        <p className="mt-2 text-sm text-gray-600">{current.desc}</p>
        <div className="mt-6 flex items-center justify-between">
          {/* Skip button: gray, small, but always there */}
          <button
            onClick={() => dismiss("skip")}
            className="text-sm text-gray-400 hover:text-gray-600"
          >
            Skip tour
          </button>
          <button
            onClick={next}
            className="rounded-lg bg-blue-600 px-5 py-2.5 text-sm font-medium text-white hover:bg-blue-700"
          >
            {current.actionLabel} →
          </button>
        </div>
      </div>
    </div>
  );
}

Usage: drop <OnboardingTour onEvent={track} /> into your homepage or dashboard — one line — where track is your analytics function. Swap the copy and onAction handlers in the STEPS array for your own — and remember, each step's onAction must be a real action (navigate, open a modal, trigger a sample), not "next page." Three clicks, each one closer to Aha — that's onboarding. Three clicks through three paragraphs of text is a slideshow.

Two production details: first, the versioned STORAGE_KEY — bump the version when you revamp the flow and existing users will re-see it. Second, wrap localStorage reads/writes in try/catch — in Safari private mode or incognito windows localStorage can throw; don't let an onboarding component crash the whole page.

7. Measure: Look at the Funnel Before You Optimize

After onboarding ships, the first job isn't celebration — it's data. Many indie developers (my younger self included) have a bad habit: tuning onboarding by feel — "I think step two's copy is off, let me tweak it." Feel is the most expensive optimization method there is, because every "feel" is a release without a control group. The correct posture: define 4 core metrics first, let the funnel tell you which step is leaking, then act.

Metric 1: Signup → Aha completion rate (the one metric). Definition: the share of registered users who complete the Aha-moment action within their first session. This is the north star of the entire onboarding design — every cut, every line of copy, every pattern choice in the previous six sections exists to push this number up. If you can only watch one number, watch this one.

Metric 2: Completion vs. skip rate, broken down by step. Definition: the share of users who start onboarding and finish all steps, plus the skip/drop distribution per step. The point is not to chase "100% completion" — quite the opposite. Healthy onboarding tolerates 30–50% skip rates, because returning and power users never needed the tour. What you're hunting is a sudden skip-rate spike at one specific step: if step 2's skip rate is 3× step 1's, step 2 has a problem (scary copy? asks for input? too slow?). Fix that step.

Metric 3: Median time to first value. Definition: median time from a user's first product open to completing the Aha action. This metric forces an uncomfortable question: how long did it actually take users to feel delighted? A 47-second median is beautiful; a 6-minute median means your Aha sits too far from the entrance — go back to the Section 2 canvas.

Metric 4: Day-1 retention, completers vs. skippers. Definition: the retention gap between users who finished onboarding and those who didn't. This is the evidence that "onboarding is worth doing," and the basis for deciding "whether to keep investing in it." If the two groups retain identically, your onboarding is just "going through motions" without delivering value — the problem isn't the format, it's the Aha itself (see the last paragraph of Section 2).

Four metrics. That's enough. Don't launch a 20-metric dashboard on day one — with too many metrics you won't know which to read first, which equals reading none. Add more only once these four are humming.

Analytics event naming spec (works directly with the onEvent hook from Section 6):

Event name	When it fires	Required params
onboarding_started	Tour shown for the first time	source (new user / version bump)
onboarding_step_viewed	Each step displayed	step (zero-indexed)
onboarding_step_action	User clicks a step's action button	step, action (button id)
onboarding_skipped	User skips / hits Esc / closes modal	at_step, reason
onboarding_completed	Final step finished	duration_sec (total time)
aha_moment_reached	User completes the Aha action (core!)	minutes_since_signup

Three naming rules the whole team (even a team of one) must follow: ① all-lowercase snake_case — no mixing camelCase and kebab-case; ② verbs in past tense (started / completed / reached) — they describe things that already happened; ③ track aha_moment_reached separately from tour completion — because users can absolutely skip the tour and still find Aha on their own (that's a win!), or finish the tour without ever feeling delighted (that's an incident). Separating the two events is the only way to see the truth.

Finally, a counterintuitive suggestion: for the first week after launch, look at Metric 1 only. If signup→Aha completion is climbing, the direction is right. If it isn't, don't fiddle with button colors or copy wording — go redraw the Section 2 Value Promise Canvas. The greatest value of funnel data isn't telling you "which button should change color." It's telling you "whether the direction is wrong."

8. Pre-Launch Audit: 10 Checks

After the onboarding rework, before shipping — check each item off. No theory in this section, just the list. Print it and tape it next to your monitor.

1. Signup fields ≤ 3. Ideally 1 (email) or 0 (OAuth buttons). Beyond 3, revisit Section 4 — each extra field needs a "we die without it" justification.

2. The first screen has one glanceable value action. Within 5 seconds of opening the product, the user can say "I click there and get that." If not, redo the first screen.

3. No forced tutorial. Every onboarding step is skippable, and the skip button doesn't need hunting. Remember: a user skipping your tour to explore on their own is a victory, not a failure.

4. Every empty state has sample content or templates. Sweep the whole product: every "empty" a new user can see needs element ③ ("what done looks like"). See Section 5.

5. Signup to Aha ≤ 3 steps. Pull out the Section 2 canvas and count. Over 3 steps, each one must answer "why can't this be cut."

6. Run a 5-minute test with a friend who's never used the product. Screenshare, and you're not allowed to talk. Watch where they get stuck in minute one. Wherever they stall is where your onboarding "thought it was clear." The cheapest user research with the highest ROI.

7. Walk through on mobile. Vibe project authors spend 90% of their time on desktop, but half your users may be on phones. Does the onboarding modal cover key buttons on small screens? Does the stepper misalign? Tap through three times on a real phone.

8. Test offline and error states. If your flow includes "connect a data source" or "invite teammates" — anything depending on the outside world — what shows on failure? A bare "something went wrong, retry" pushes users off a cliff. Tell them which step succeeded, where it's stuck now, and where to click to route around it.

9. The "finished product" is visible without logging in. If feasible, ship a no-login demo/preview mode (see Section 6, step 1's "explore with sample data"). The single highest-ROI change you can make: let users feel delighted first, register later. Loom and Canva both do this.

10. Analytics verified. Walk all 6 events from Section 7 in a test environment and confirm each lands in your analytics tool with correct params. Optimizing onboarding without data is driving blindfolded — and most shipped onboarding has analytics filed under "later."

All checked? Ship it. Then watch "signup → Aha completion rate" daily for two weeks. You'll likely discover that the all-nighters you pulled "adding two more features" bought less growth than this first-minute rework. Vibe coding made "building a product" cheap, but "getting people to use it" is still expensive — expensive in the willingness to design the first minute as if it were the product itself.

Signup isn't the finish line. It's the starting line. And a good starting line deserves half the care you'd give a core feature.