Screens — Auth & Registration

Screen specifications for all authentication and self-registration flows. These screens live outside the main app shells — they are full-page, unauthenticated routes served by the Dashboard Next.js app.

Status notation: [Live] = confirmed working · [To Build] = specified, not yet implemented · [Unverified] = not yet checked against running app

Auth implementation: Auth docs | Onboarding flow after registration: Onboarding

Login → signup link: The /login page “Sign up” link points to /signup (the new self-signup wizard).

Screen Index

S1 — Self-Signup Step 1 — Contact

Route: /signup Layout: Centered (same as R1–R4 pattern) Step: 1 of 4 — Contact (Account Setup)

Form

Behaviour

• Continue calls POST /auth/v1/register/start — creates a RegistrationSession row and returns a session token
• Session token stored in sessionStorage as signup_session_token
• Step data stored in sessionStorage as signup_step1
• On success: navigate to /signup/company

Redirect Guards

• No guard on Step 1 itself (entry point)
• All later steps (/signup/company, /signup/location, /signup/plan) check for signup_step1 in sessionStorage; redirect to /signup if missing

S2 — Self-Signup Step 2 — Company

Route: /signup/company Layout: Centered Step: 2 of 4 — Company (Business Details)

Form

Behaviour

• Calls POST /auth/v1/register/step/2 with session token
• Stores to sessionStorage as signup_step2
• On success: if country = IN → navigate to /signup/location; if other country → navigate directly to /signup/plan (step 3 is auto-completed server-side for non-India)
• Back button → /signup

S3 — Self-Signup Step 3 — Location & Tax

Route: /signup/location Layout: Centered Step: 3 of 4 — Location (Tax & Region)

Form

Behaviour

• Entire step is optional — Continue works with empty fields
• Stores to sessionStorage as signup_step3
• Back button → /signup/company

S4 — Self-Signup Step 4 — Plan & Payment

Route: /signup/plan Layout: Centered (wider card) Step: 4 of 4 — Plan (Subscription)

Plan Selection

Same plan cards as R4 (Starter / Professional). Professional pre-selected by default.

Billing Address

Payment Flow

1. Submit calls POST /auth/v1/register/complete with session token + plan + billing address
2. API creates a Razorpay order for planPrice × 1.18 GST (prepaid, first month)
3. Razorpay Checkout modal opens in the browser
4. On payment success → client calls POST /auth/v1/register/payment/verify → tenant + user created → redirect to /login?registered=1
5. On payment failure / cancel → modal closes, user stays on /signup/plan

Post-payment redirect: The signup flow redirects to /login?registered=1 (not /onboarding). The login page shows “Account created! Sign in to get started.” when the registered=1 query param is present.

Test Credentials (Razorpay Test Mode)

SE — Expired Session

Route: /signup/expired Layout: Centered (single card, no step bar)

Shown when a user follows a signup-resume link whose session token has expired (sessions expire after 30 days of inactivity).

Layout Patterns

Split Layout (A1, A2, A3)

Auth screens use a 50/50 horizontal split:

┌─────────────────────────┬─────────────────────────┐
│                         │                         │
│   Feature Showcase      │   Auth Form Panel       │
│   (left panel)          │   (right panel)         │
│   Purple gradient bg    │   Dark bg #0D1117       │
│                         │                         │
│   · Headline copy       │   · Leadmetrics logo    │
│   · Feature carousel    │   · Form                │
│   · Dot pagination      │   · Footer links        │
│                         │                         │
└─────────────────────────┴─────────────────────────┘

Left panel — Feature Showcase:

• Background: deep purple-to-violet gradient (#3B0066 → #6B21A8)
• Scattered dot particles (decorative, subtle animation)
• Wave/hill shape along the bottom of screenshots
• Headline: “Transform Your Digital Marketing Strategy” (white, bold, large)
• Subheadline: “Powered by cutting-edge Agentic AI, delivering intelligent automation and real-time insights.” (“Agentic AI” in yellow/amber bold)
• Feature carousel: rotating screenshots of platform features
• Feature name (white, semibold) + description (white/70, smaller) below screenshot
• Dot pagination indicator at bottom of carousel

Right panel — Auth Form:

• Background: #0D1117 (near-black dark)
• Dark mode toggle icon — top right corner of right panel
• Leadmetrics logo — centered near top of panel (🎁 leadmetrics — icon + wordmark)
• Form card: slightly lighter dark background (#161B27), rounded corners, padding
• Copyright: ©2026, Leadmetrics. All Rights Reserved — bottom center, subdued

Centered Layout (R1–R4)

Registration screens use a centered single-column layout:

┌────────────────────────────────────────────────────┐
│                                                    │
│              🎁 leadmetrics  (logo)                │
│            Get Started Today  (h1)                 │
│       Create your account in just a few steps      │
│                                                    │
│   ①──────②──────③──────④   (step progress bar)   │
│                                                    │
│   ┌─────────────────────────────────────────────┐  │
│   │           Form card                         │  │
│   └─────────────────────────────────────────────┘  │
│                                                    │
│       Terms of Service · Privacy Policy            │
└────────────────────────────────────────────────────┘

Background: #080D1A (deepest dark navy).

Registration Step Progress Bar

The progress bar sits between the subtitle and the form card on all registration screens.

  ①              ②              ③              ④
  ◉──────────────○──────────────○──────────────○
Contact        Company        Location         Plan
Account Setup  Business Details  Tax & Region  Subscription

Step states:

Auto-save toast: After completing and submitting each step, a toast appears bottom-right:

• Background: dark green
• Title: Success
• Body: “Your progress has been saved”
• The user’s partially completed registration is persisted server-side so they can resume if they close the browser.

A1 — Login

Route: /login Layout: Split (left = Feature Showcase, right = Auth Form)

Right Panel Content

🎁 leadmetrics

Welcome back
Sign in to continue to your account

┌─────────────────────────────────────────┐
│                                         │
│  Email                                  │
│  ✉ Enter your email                     │
│                                         │
│  Password                               │
│  🔒 Enter your password          [👁]   │
│                                         │
│  ┌─────────────────────────────────┐    │
│  │          Login  →               │    │
│  └─────────────────────────────────┘    │
│                                         │
└─────────────────────────────────────────┘

Observed (live): The right panel uses a light/white background (not dark #0D1117). There is no “Forgot password” link, social login buttons, or “Sign up” link visible in the current implementation — this appears to be the internal/client-facing login, not the self-registration flow.

Fields & Controls

Tenant Selection Modal (post-login)

After credentials are validated, a modal dialog appears for users who belong to multiple tenants:

┌─────────────────────────────────────────┐
│  [choose-tenant illustration]           │
│                                         │
│  Select your Organization               │
│  Select an organization from the list   │
│  to continue                            │
│                                         │
│  ┌──────────────────────────────── ▾ ┐  │
│  │  Talent Solutions Group            │  │  ← searchable combobox
│  └────────────────────────────────── ┘  │
│                                         │
│  ┌─────────────────────────────────┐    │
│  │            Select               │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘

• The dropdown is a searchable combobox — user can type to filter orgs by name
• The org list can be very long (100+ tenants for super-admin accounts)
• Selecting an org and clicking “Select” sets the active tenant context and redirects to /dashboard
• Single-tenant users skip this modal entirely

Validation & Errors

• Empty email or password: inline field error below input
• Incorrect credentials: banner error above the form (“Invalid email or password”)
• Account locked (after 5 failed attempts): banner error with lockout duration remaining
• Unverified email: banner with “Please verify your email — resend link” action

Social Login

Social login buttons (Google, Microsoft, LinkedIn) appear below the Login button, separated by an “or” divider. See social-providers.md.

A2 — Forgot Password

Route: /forgot-password Layout: Split (left = Feature Showcase, right = minimal form, no logo)

Right Panel Content

Forgot Password?
Enter your email and we'll send you link to reset your password

Email *
┌────────────────────────────────────────┐
│  Enter your email id                   │
└────────────────────────────────────────┘

┌────────────────────────────────────────┐
│       Send link to email               │
└────────────────────────────────────────┘

Behaviour

1. User enters email and clicks “Send link to email”
2. Server always returns a success state — does not reveal whether the email exists (prevents enumeration)
3. Success state replaces the form with: “If an account exists for this email, a reset link has been sent. Check your inbox.”
4. Reset link expires in 1 hour
5. “Back to login” link at the bottom

Rate Limiting

3 reset requests per hour per email address. Excess requests silently succeed (same message) but no email is sent.

A3 — Reset Password

Route: /reset-password?token=<token> Layout: Split (same pattern as A2)

Right Panel Content

Reset Your Password
Enter your new password below

New Password *
┌──────────────────────────────────── [👁]┐
│  Enter new password                     │
└─────────────────────────────────────────┘
Minimum 12 characters. Must include letters and numbers.

Confirm Password *
┌──────────────────────────────────── [👁]┐
│  Confirm new password                   │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│          Reset Password                 │
└─────────────────────────────────────────┘

Behaviour

• Token validated on page load — if expired or invalid, show error: “This reset link has expired. Request a new one.” with link to /forgot-password
• Password strength indicator shown inline as user types
• On success: redirect to /login with success banner “Password updated. Sign in with your new password.”
• HIBP check: warns if the entered password appears in known data breaches

R1 — Registration Step 1 — Contact

Route: /register Layout: Centered Step: 1 of 4 — Contact (Account Setup)

Form

Your contact details
You will be the main account administrator

Your Country *
┌─────────────────────────────────────── ▾┐
│  Select your country                    │
└─────────────────────────────────────────┘
This will help us set the right phone code and regional settings

Title          First Name *          Last Name *
┌──────────▾┐  ┌──────────────────┐  ┌─────────────────┐
│  Mr.      │  │  John            │  │  Doe            │
└───────────┘  └──────────────────┘  └─────────────────┘

Your Email Address *
┌─────────────────────────────────────────┐
│  john@company.com                       │
└─────────────────────────────────────────┘

Mobile Number *
┌──────▾┐ ┌───────────────────────────────┐
│  +91  │ │  Mobile Number                │
└───────┘ └───────────────────────────────┘

Create Password *
┌─────────────────────────────── [👁] ┐  [Generate]
│  Enter password                     │
└─────────────────────────────────────┘
Minimum 8 characters, mix of letters and numbers

┌─────────────────────────────────────────┐
│               Continue  →               │
└─────────────────────────────────────────┘

By signing up, you agree to our Terms of Service and Privacy Policy

Fields

Behaviour

• Clicking Continue validates all required fields
• On success: auto-saves progress server-side, transitions to R2
• The account is not yet created until Step 4 (payment) is completed — Step 1 data is stored in a temporary registration session

R2 — Registration Step 2 — Company

Route: /register/company Layout: Centered Step: 2 of 4 — Company (Business Details)

Form

Tell us about your company
We will use this information for your account setup

Legal Company Name *
┌─────────────────────────────────────────┐
│  Your official company name             │
└─────────────────────────────────────────┘
This will appear on invoices and legal documents

Brand / Display Name *
┌─────────────────────────────────────────┐
│  How you want to be known               │
└─────────────────────────────────────────┘
┌─────────────────────────────────────────┐
│ ✨ This is how your company name will   │
│    appear throughout the platform       │
└─────────────────────────────────────────┘

PAN Number (Optional)
┌─────────────────────────────────────────┐
│  e.g., ABCDE1234F                       │
└─────────────────────────────────────────┘
Required for Indian tax purposes

[  ← Back  ]          [  Continue →  ]

Fields

Behaviour

• Brand name auto-populated from Legal Company Name on blur (user can override)
• Info banner uses a ✨ spark icon with a warm amber background to highlight the platform-wide impact
• Progress auto-saved on Continue; “Your progress has been saved” toast appears

R3 — Registration Step 3 — Location

Route: /register/location Layout: Centered Step: 3 of 4 — Location (Tax & Region)

Form

Regional & tax settings
Help us configure your account properly (Optional)

Your Country
┌─────────────────────────────────────────┐
│  India                        From Step 1│
└─────────────────────────────────────────┘

State *
┌─────────────────────────────────────── ▾┐
│  Kerala                                 │
└─────────────────────────────────────────┘

Do you have a GST registration?
┌──────────────────────┐  ┌──────────────────────┐
│   Yes, I have GST    │  │  ✓ No GST number     │
└──────────────────────┘  └──────────────────────┘
                              (selected = violet bg)

[  ← Back  ]          [  Continue →  ]

Fields

Behaviour

• Entire step is optional — user may click Continue without filling anything
• State list is filtered dynamically based on country
• GST toggle is a two-button group (not a checkbox or radio — full button pair for clarity)

R4 — Registration Step 4 — Plan & Payment

Route: /register/plan Layout: Centered (slightly wider card to accommodate plan cards side by side) Step: 4 of 4 — Plan (Subscription)

Plan Selection

Choose your plan
Select the plan that best fits your needs

┌──────────────────────┐  ┌──────────────────────┐
│                      │  │ ✦ Popular ✦          │
│  Starter             │  │  Professional  ✓     │
│  INR 34,999/monthly  │  │  INR 49,999/monthly  │
│                      │  │                      │
│  What's included     │  │  What's included     │
│  ✓ Feature A         │  │  ✓ Feature A         │
│  ✓ Feature B         │  │  ✓ Feature B         │
│  ✓ ...               │  │  ✓ ...               │
│                      │  │  ✓ Extra feature     │
└──────────────────────┘  └──────────────────────┘
                              Selected: violet border + checkmark

Plan cards:

• Selected plan: violet/purple border, checkmark badge top-right
• “Popular” badge on Professional plan: small pill above card, purple gradient
• Cards are full-height equal-height side by side

Note: These plan names and prices (INR) reflect the India-market SaaS offering. The platform’s internal plan enum (free, pro, agency, enterprise) maps to these display names. See onboarding.md for the full pricing matrix.

Billing Address

Your Billing Address

Name *
┌─────────────────────────────────────────┐
│  TesterComp2  (pre-filled from Step 2)  │
└─────────────────────────────────────────┘

Address *
┌─────────────────────────────────────────┐
│  Street address                         │
│                                         │
└─────────────────────────────────────────┘

City *                    Postal/Zip Code
┌──────────────────────┐  ┌──────────────────┐
│  City                │  │  Postal/ZIP code │
└──────────────────────┘  └──────────────────┘

State/Province *          Your Country *
┌──────────────────────▾┐  ┌──────────────────▾┐
│  Kerala               │  │  India            │
└───────────────────────┘  └───────────────────┘

• Name: pre-filled from Brand/Display Name (Step 2)
• State + Country: pre-filled from Step 3

CTA

[  ← Back  ]    [  Complete Sign-Up & Pay Securely  →  ]

The primary button triggers Razorpay Checkout (modal or redirect). On successful payment:

1. Full tenant account is created
2. User is redirected to /onboarding (the in-app onboarding wizard)
3. Welcome email sent via SendGrid

Design Tokens (Auth Screens)

Colours

Typography

Responsiveness

On mobile, the left feature showcase panel is hidden entirely — the auth form takes full width with the Leadmetrics logo above it.

Accessibility

• All form fields have associated <label> elements
• Error messages are linked via aria-describedby
• Password show/hide toggle has aria-label="Show password" / "Hide password"
• Step progress bar uses role="list" with aria-current="step" on the active step
• Buttons have sufficient colour contrast (≥4.5:1) against card background
• Focus ring visible on all interactive elements (not removed with outline: none without replacement)