First-Run Onboarding Experience — brief for Claude Designs

The complete first-time journey, splash → welcome → auth → setup → first-run guidance → dashboard. This is the emotional, story-driven wrapper around the data-collection steps. It supersedes Part 1 of the Profile/Settings/Onboarding reconciliation brief for the journey, and defers to it for the exact fields — that brief remains the single source of truth for column names (full_name, brand_name, business_domain_id, slug, …). Do not restate or rename fields here.

How to use

Paste the fenced block into Claude Designs with the PDPR, the Screen Coverage Mandate, and the field brief. Two product decisions are already made and baked in below: auth = production visual quality, placeholder wiring (real auth exists in src/); story = lightweight, skippable, performance-budgeted for the Digital Bharat audience.

Two things that make this brief different from a generic onboarding template

1. The audience is Digital Bharat — many users are on low-end Android and slow/intermittent networks. A cinematic, asset-heavy intro would hurt the exact people QRSetu is for. Every animation is CSS/SVG, lazy, skippable, and budgeted; nothing blocks time-to-value.
2. Value-first, not gate-first — the story earns trust in seconds, then gets out of the way. The user should reach a first win (a shareable Service Card / QR) as fast as possible; deep profile completion can continue progressively from the dashboard, not as an upfront wall.

Global rules for this experience (apply the PDPR too)

# QRSETU — FIRST-RUN ONBOARDING EXPERIENCE — BRIEF FOR CLAUDE DESIGNS

Design the complete first-time journey for the QRSETU mobile console (and a responsive desktop equivalent),
from app launch to the user's first meaningful moment on the Dashboard. This is the emotional first impression
of the platform — make it feel premium, warm, and purposeful, not a generic stepper.

TWO DECISIONS ALREADY MADE (do not re-open):
- AUTH: design to production visual quality (email/password, "Continue with Google", phone OTP), but the
  prototype wiring is placeholder/mock. The real auth is already built in the app; you are matching it visually,
  not inventing a new flow. Design the real states (idle/loading/error/success) but mock the transitions.
- STORY: lightweight and ALWAYS skippable. CSS/SVG motion only — no video, no heavy Lottie. Assets lazy-load.
  Must feel smooth on a low-end Android phone on a 3G connection. A persistent "Skip" is visible on every
  story/intro screen. Time-to-first-value is the priority.

DESIGN LANGUAGE (non-negotiable, same as the rest of the project):
- Apple-style soft corners (rounded-3xl shells, rounded-2xl panels). Zero hard-coded colors — use design
  tokens only (var(--token)); if a needed hue has no token, add a token, do not inline hex (this was a real
  defect on other screens). Mandatory light AND dark themes. No em dashes in copy. Use dsSelect, never native
  <select>. Respect prefers-reduced-motion (fall back to instant, no animation).
- Emotionally warm, confident, Indian-context imagery and copy — but restrained and premium, never cluttered
  or "loud". Hinglish-friendly tone is fine in microcopy where natural; keep it professional.

THE STORY TO TELL (weave across Welcome + Product intro, a few beats — not a lecture):
- The everyday reality of an Indian small business / service professional: hard to be found, hard to look
  trusted, customers ask "do you have it online?", competing on WhatsApp forwards and paper cards.
- QRSETU gives them a trusted DIGITAL IDENTITY in minutes — one Service Card, one QR, discoverable and shareable.
- It simplifies customer engagement, discovery, payments, reviews, and growth — in one place.
- The bigger vision: EMPOWERING DIGITAL BHARAT — every business, however small, with a trusted digital presence.
- Emotional throughline: "You built the business. QRSETU helps the world find and trust it." Make the user feel
  this is a platform for entrepreneurs like them, not just another app.

=====================================================================
THE STAGES (in order) — design each as a screen/state with the noted beats
=====================================================================

1. SPLASH — instant, <1s perceived. Brand wordmark (QR gradient + setu ink, from tokens) on a clean themed
   background, a subtle logo reveal (scale/opacity, CSS). No progress bar unless load genuinely needs it. Sets a
   premium tone immediately. Design light + dark.

2. LAUNCH ANIMATION — a brief, tasteful motion continuing from splash into the welcome (e.g. the QR mark
   "assembles" from dots, or a card slides up). ONE beat, ~600-900ms, skippable by tapping. Must degrade to a
   static state under prefers-reduced-motion / low power.

3. WELCOME — the first emotional beat. A confident headline that speaks to the entrepreneur ("Your business,
   discovered and trusted online") + one warm supporting line + a single primary CTA ("Get started") and a
   secondary "I already have an account" (→ Log in). Show a small trust signal (e.g. "Join businesses across
   India" — keep any number illustrative and flag it). Skip goes straight to auth.

4. PRODUCT INTRODUCTION — 2-3 swipeable story cards (dots indicator, Skip always visible), each ONE idea with a
   simple illustrative graphic (SVG/token-colored, not photos-heavy):
   a) "Be found & look trusted" — a digital Service Card + QR.
   b) "Everything in one place" — enquiries, payments, reviews, offers.
   c) "Grow with Digital Bharat" — the vision beat; roll into the CTA.
   Each card is a self-contained value promise, not feature soup. Last card's CTA → auth.

5. AUTHENTICATION — production visual quality, placeholder wiring. Design: Sign up and Log in (tabbed or
   switchable), "Continue with Google", phone number + OTP verify path, and forgot-password entry. Include real
   states: empty, focus, loading (button spinner), inline validation error, and success. Keep it short and
   trustworthy (why we need a number, privacy reassurance microcopy). Mock all transitions.

6. INITIAL SETUP — the account-type fork FIRST ("For my business" vs "For myself / personal"), then the setup
   steps. FOR THE EXACT FIELDS AND STEP ORDER, FOLLOW THE PROFILE/SETTINGS/ONBOARDING FIELD BRIEF VERBATIM
   (full_name, mobile_number; then business-only brand_name, business_domain_id; then country/location; then
   slug). Do not invent fields. Design the individual path as visibly SHORTER, not greyed-out business fields.
   Show a slim progress indicator ("Step 2 of 4", or a segmented bar) — commitment + orientation.

7. OPTIONAL PERMISSIONS — ask CONTEXTUALLY and honestly, not a wall of upfront prompts. Primarily: notifications
   ("Get notified when a customer enquires or pays" — tie the permission to a concrete benefit), and — only if a
   step needs it — camera/photos for the avatar/logo. Each has a clear "Not now" that is not a dead end. Never
   block progress on a declined optional permission.

8. LIVE VALUE PREVIEW ("aha moment") — the differentiator. As the user fills setup, show their Service Card
   building LIVE (brand_name, logo, industry, location appearing on a card preview) so they SEE their digital
   identity forming. This is the emotional payoff — "that's mine, and it looks professional." Reuse the existing
   Service Card visual, don't invent a new one.

9. FEATURE HIGHLIGHTS — brief, PERSONALIZED by the industry (business_domain_id) they chose: surface the 3-4
   most relevant modules for their domain (e.g. a café sees Menu/Orders/QR; a freelancer sees Portfolio/Payments/
   Enquiries). Not the full module list — the relevant few. Each is a one-line "here's what you can do next".

10. FIRST-TIME GUIDANCE — a short, dismissible "Get started checklist" concept that will live on the Dashboard
    (e.g. "Add your first item", "Share your QR", "Invite & Earn") rather than a blocking coach-mark tour. Design
    it as a card the user can complete over time. Optionally 1-2 lightweight coach-marks on the very first
    dashboard view, dismissible and skippable.

11. SUCCESSFUL COMPLETION — a genuinely celebratory moment (confetti/checkmark, tasteful, reduced-motion-safe):
    "Your QRSETU identity is live." Show their finished Service Card + their public URL (slug) + a big "Share my
    QR / card" action, and a secondary "Go to dashboard". This is where the referral loop can seed — a subtle
    "Invite friends & earn" nudge that links to the existing Invite & Earn surface (see the affiliate spec).

12. LANDING ON DASHBOARD (first-run state) — NOT the generic populated dashboard. Design the FIRST-RUN empty/
    guided state: a warm "Welcome, <name>" header, the Get-started checklist from stage 10 prominent, the live
    Service Card + Share action reachable, and empty-states for the key modules that teach the first action
    ("No enquiries yet — share your QR to get your first"). It should feel like a beginning, not a blank slate.

=====================================================================
RECOMMENDED EXTRAS (design these too — they lift activation)
=====================================================================

- REFERRAL-AWARE ENTRY: if the user arrived via a referral link/code (?ref=), acknowledge it warmly in
  Welcome/Auth ("Priya invited you to QRSETU") — ties into the affiliate Invite & Earn program. Design the
  with-referral and without-referral variants.
- SAVE & RESUME: if a user drops off mid-setup, they resume where they left off (design the "Welcome back,
  finish setting up" re-entry state). Never lose entered data.
- PROGRESSIVE ONBOARDING: let the user reach the dashboard and get a first win BEFORE 100% profile completion;
  the checklist nudges the rest. Design a "complete your profile (60%)" progress affordance on the dashboard.
- SOCIAL PROOF & TRUST: tasteful, honest trust signals (businesses onboarded, security/privacy reassurance at
  auth). Keep all numbers illustrative and flagged.
- MICRO-INTERACTIONS: button press feedback, field check-marks on valid input, the live card preview updating as
  they type, a satisfying step-complete transition, the completion celebration. All CSS/SVG, reduced-motion-safe.
- MOMENTUM COPY: encouraging, specific microcopy ("Nice — your card's taking shape"), never generic ("Step
  complete").

=====================================================================
WHAT NOT TO INVENT (flag instead)
=====================================================================

1. No new profile fields — follow the field brief's Part 0. If a screen seems to want "bio/tagline/website",
   flag it as a proposed new column; do not silently design it.
2. Do not design a real auth backend or a new auth model — production VISUALS, placeholder wiring only.
3. Do not invent specific numbers (businesses onboarded, ratings) — use illustrative values and mark them.
4. Do not add heavy media (video, large Lottie) — it breaks the Bharat performance budget. If you think a beat
   needs it, flag it rather than adding it.
5. Do not make any story/intro/permission screen unskippable, and do not block progress on a declined optional
   permission.
6. The exact number of product-intro cards (2 vs 3) and whether the individual path skips permissions are open —
   design a sensible default and flag the choice.

Additional strategy notes (for you, not Claude Designs)

• Why value-first matters for QRSetu specifically: your users are price- and time-sensitive SMBs. Activation research is consistent — the faster a user reaches a first tangible win (here: a live, shareable Service Card
  • QR), the higher retention. The story earns the emotional buy-in in seconds; the live card preview (stage 8) is the aha moment; everything heavy is deferred to the progressive dashboard checklist. That ordering is deliberate, not decorative.
• The Bharat performance budget is a real constraint, not a nicety. Designing a cinematic intro would showcase well in a demo and then jank on the ₹8,000 Android phone a real kirana owner uses — losing exactly the audience the Digital Bharat vision is about. Lightweight + skippable is the pro-vision choice, which is why it's baked in.
• This connects three existing decisions: the dual-audience fork (ADR-0001 D3), the real field set (the field brief), and the referral loop (affiliate spec — the referral-aware entry + completion nudge). It isn't a standalone screen set.
• Backend reality to keep in view: the setup steps write via the real manage-profile Edge Function, which today silently drops slug, gstin, and onboarding_completed (see tracker). The gorgeous completion screen will show a public URL the backend isn't saving until those allow-lists are widened — the design and that backend fix must land together.

After this ships in Claude Designs

Review the generated splash/welcome/intro/auth/completion/first-run screens the same way as every other screen: read the actual files, check the design-language rules (tokens, light+dark, no native selects, skippability, reduced-motion), confirm the setup steps still match the field brief, then log findings under design-system/screen-reviews/ and request revalidation.