SaaS Product Design

Methodology for building production SaaS features that drive user adoption and retention. Focused on patterns that reduce time-to-value and handle the complexity of multi-tenant, subscription-based applications.

For design system tokens and accessibility, see /ux-design. For React component patterns, see /react. For API contracts behind features, see /api-design. For domain modeling, see /domain-design.

---

1. Design Philosophy

Progressive complexity

Start simple, reveal complexity as the user needs it. A new user should reach their first moment of value within 60 seconds. Advanced features unlock progressively.

Principle	Application
Time-to-value	Minimize steps between signup and first meaningful action
Progressive disclosure	Hide advanced options behind "Advanced" toggles or secondary menus
Jobs-to-be-done	Design around what the user is trying to accomplish, not around data entities
Sensible defaults	Pre-fill settings with the most common choices; make the default path correct
Undo over confirm	Prefer reversible actions with undo over confirmation dialogs that interrupt flow

Product hierarchy

Feature → Page → Section → Component

Each level has a clear responsibility:

• Feature: A complete capability (e.g., "Asset Tracking")
• Page: A view within a feature (e.g., "Asset List", "Asset Detail")
• Section: A logical grouping within a page (e.g., "Performance Chart", "Transaction History")
• Component: A reusable UI element (e.g., "Currency Badge", "Date Picker")

---

2. Onboarding & First-Run

Activation metrics

Define what "activated" means before building onboarding:

Metric	Example
Setup complete	User has connected at least one data source
First value	User has viewed their first dashboard with real data
Habit formed	User returns 3 times in the first 7 days

Progressive onboarding patterns

Setup wizard — for products requiring initial configuration:

// Loader returns current step from session/DB
export async function loader({ request }: LoaderFunctionArgs) {
  const progress = await getOnboardingProgress(request);
  return { step: progress.currentStep, steps: progress.steps };
}

// Action validates current step, saves, and advances
export async function action({ request }: ActionFunctionArgs) {
  const formData = await request.formData();
  if (formData.get("_intent") === "skip") return redirect("/app");
  const nextStep = await saveStepAndAdvance(formData);
  if (nextStep === "complete") return redirect("/app");
  return redirect(`/onboarding/step/${nextStep}`);
}

// Component renders the current step as a form
function SetupWizard() {
  const { step, steps } = useLoaderData<typeof loader>();
  return (
    <div>
      <StepIndicator steps={steps} current={step} />
      <Form method="post">
        <CurrentStepFields step={step} />
        <Button type="submit">Continue</Button>
      </Form>
      <Form method="post">
        <input type="hidden" name="_intent" value="skip" />
        <button type="submit" className="text-sm text-muted-foreground">
          Skip setup — I'll do this later
        </button>
      </Form>
    </div>
  );
}

Rules:

• Always allow skipping — never force completion of all steps
• Progress is saved automatically — each step is an action submission persisted server-side
• Max 3-5 steps — more than that and users abandon
• Show progress clearly (step 2 of 4)

Checklist pattern — for products where setup is gradual:

function OnboardingChecklist({ tasks }: { tasks: OnboardingTask[] }) {
  const completed = tasks.filter(t => t.done).length;
  return (
    <Card>
      <Progress value={completed} max={tasks.length} />
      <p>{completed} of {tasks.length} complete</p>
      {tasks.map(task => (
        <ChecklistItem key={task.id} task={task} />
      ))}
      {completed === tasks.length && <DismissButton />}
    </Card>
  );
}

Contextual tooltips — for feature discovery after initial setup:

• Show once per user, track dismissal in user preferences
• Point to the specific UI element, not a general area
• Include a single clear CTA ("Try it now" / "Got it")

Anti-patterns

• Forced video tours (users skip them)
• Tooltips on every element simultaneously (overwhelming)
• Blocking the app until onboarding is complete (drives abandonment)
• Showing onboarding to returning users who already completed it

---

3. Empty States

Every data-driven view must handle four empty conditions:

Type	When	Content
First-use	User hasn't created any data yet	Illustration + explanation + primary CTA
No results	Search or filter returned nothing	"No results for X" + suggestion to broaden search
Error	Data failed to load	Error message + retry button
Filtered empty	Applied filters exclude all results	Show active filters + "Clear filters" button

First-use empty state pattern

function EmptyState({ icon, title, description, action }: EmptyStateProps) {
  return (
    <div className="flex flex-col items-center justify-center py-16 text-center">
      <div className="mb-4 text-muted-foreground">{icon}</div>
      <h3 className="text-lg font-semibold">{title}</h3>
      <p className="mt-1 max-w-sm text-sm text-muted-foreground">{description}</p>
      {action && (
        <Button className="mt-4" asChild>
          <Link to={action.href}>{action.label}</Link>
        </Button>
      )}
    </div>
  );
}

// Usage — CTA navigates to a route, not an onClick handler
<EmptyState
  icon={<WalletIcon size={48} />}
  title="No assets yet"
  description="Add your first asset to start tracking your portfolio performance."
  action={{ href: "/assets/new", label: "Add Asset" }}
/>

Rules:

• First-use empty states must have a CTA that leads to creating the first item
• Never show a blank page or a lonely "No data" message
• Use illustrations or icons to make the empty state feel intentional, not broken
• Reduce the CTA to a single clear action — don't offer multiple paths

---

4. Dashboard Design

KPI card anatomy

A well-designed KPI card shows: current value, trend indicator, comparison period, and optional sparkline.

interface KPICardProps {
  label: string;
  value: string;
  change: number;      // percentage change
  period: string;      // "vs last month"
  sparklineData?: number[];
}

function KPICard({ label, value, change, period, sparklineData }: KPICardProps) {
  const isPositive = change >= 0;
  return (
    <Card>
      <p className="text-sm text-muted-foreground">{label}</p>
      <p className="text-2xl font-bold">{value}</p>
      <div className="flex items-center gap-1 text-sm">
        <TrendIcon direction={isPositive ? "up" : "down"} />
        <span className={isPositive ? "text-green-600" : "text-red-600"}>
          {Math.abs(change)}%
        </span>
        <span className="text-muted-foreground">{period}</span>
      </div>
      {sparklineData && <Sparkline data={sparklineData} />}
    </Card>
  );
}

Chart selection guide

Data relationship	Chart type	When to use
Part-to-whole	Donut (max 5 segments)	Budget allocation, portfolio mix
Change over time	Line / area	Revenue trends, growth metrics
Comparison	Horizontal bar	Category comparison, rankings
Distribution	Histogram	Value ranges, frequency
Composition over time	Stacked area	Revenue by segment over time

Rules:

• Never use pie charts for more than 5 segments — switch to horizontal bar
• Never use 3D charts
• Line charts require a continuous x-axis (time, sequence)
• Always label axes and include units

Dashboard layout

• Top row: 3-4 KPI cards summarizing the most important metrics
• Middle: Primary chart (full width or 2/3 width)
• Bottom: Secondary data tables or detail views
• Use CSS Grid for the layout: grid-cols-1 md:grid-cols-2 lg:grid-cols-4 for KPI row

Data density

• Dense displays for power users (tables with many columns, compact spacing)
• Summary views for casual users (KPI cards, sparklines, simplified charts)
• Let users toggle between views or remember their preference

---

5. Loading & Transition States

Skeleton screens

Match the skeleton shape to the actual content layout. Users perceive skeleton screens as faster than spinners:

function AssetListSkeleton() {
  return (
    <div className="space-y-3">
      {Array.from({ length: 5 }).map((_, i) => (
        <div key={i} className="flex items-center gap-4">
          <Skeleton className="h-10 w-10 rounded-full" />
          <div className="space-y-2">
            <Skeleton className="h-4 w-48" />
            <Skeleton className="h-3 w-32" />
          </div>
          <Skeleton className="ml-auto h-4 w-20" />
        </div>
      ))}
    </div>
  );
}

Loading state decision framework

Duration	Pattern
< 100ms	No indicator needed
100-300ms	Subtle inline indicator (button spinner)
300ms-2s	Skeleton screen
2-10s	Progress bar or skeleton with message
> 10s	Background task with notification on completion

Optimistic UI

For mutations where failure is rare, show the expected result immediately. In React Router v7, derive optimistic state from fetcher.formData — the pending submission data. Render pending items separately from the data list — the optimistic item is transient UI state, not data. The server assigns the real ID via loader revalidation:

function TodoList({ items }: { items: Todo[] }) {
  const fetcher = useFetcher();

  return (
    <>
      <ul>
        {items.map(item => (
          <li key={item.id}>{item.name}</li>
        ))}
        {fetcher.formData && (
          <li className="opacity-50">
            {String(fetcher.formData.get("name") ?? "")}
          </li>
        )}
      </ul>
      <fetcher.Form method="post">
        <input type="hidden" name="_intent" value="create" />
        <input name="name" required />
        <Button type="submit">Add</Button>
      </fetcher.Form>
    </>
  );
}

• fetcher.formData is non-null while the submission is in flight — derive the optimistic item directly from it
• When the action completes, loaders revalidate, items updates with the real data, and fetcher.formData resets to null
• On failure, loaders still revalidate with unchanged data — the optimistic item disappears because fetcher.formData is null
• No useOptimistic, no onSubmit, no startTransition — React Router's data layer handles the lifecycle

Streaming SSR

For pages with mixed fast/slow data sources:

• Fast data (navigation, layout) renders immediately in the shell
• Slow data (analytics, external APIs) streams in via Suspense boundaries
• Each Suspense boundary shows its own skeleton while loading

Server-first loading principle

With route loaders, data is available when the page renders — no loading spinners for initial data. Reserve skeleton screens for:

• Streaming SSR (slow data sources behind Suspense boundaries)
• Fetcher-driven updates (non-navigation mutations in progress)
• Client-only components that need a mount guard

---

6. Notification Design

Notification channels

Channel	Use for	Urgency
In-app toast	Action confirmation, minor errors	Low — auto-dismiss 5s
In-app bell	New activity, status changes	Medium — persists until read
Email	Transactional (receipts, invites), digests	Low — batched where possible
Browser push	Time-sensitive alerts only	High — interrupts

Toast best practices

// Success toast with undo
showToast("Asset deleted", {
  action: { label: "Undo", onClick: undoDelete },
  duration: 5000,
});

// Error toast — persists until dismissed
showToast("Failed to save changes. Please try again.", {
  variant: "error",
  duration: Infinity,
  action: { label: "Retry", onClick: retryAction },
});

Rules:

• Auto-dismiss success toasts after 5 seconds
• Never auto-dismiss error toasts — the user may not notice them
• Provide an undo action for destructive operations
• Stack multiple toasts vertically, limit to 3 visible simultaneously
• Never use toasts as the sole error indicator for form validation

Notification preferences

Implement as a channel-by-event matrix:

Event	In-App	Email	Push
New team member	Default on	Default on	Default off
Weekly digest	N/A	Default on	N/A
Payment failed	Default on	Default on	Default on
Feature update	Default on	Default off	Default off

Let users control each cell independently.

---

7. Billing & Subscription UX

Plan comparison

function PlanComparison({ plans }: { plans: Plan[] }) {
  return (
    <div className="grid gap-6 md:grid-cols-3">
      {plans.map(plan => (
        <PlanCard
          key={plan.id}
          name={plan.name}
          price={plan.price}
          period={plan.period}
          features={plan.features}
          recommended={plan.recommended}
          current={plan.current}
        />
      ))}
    </div>
  );
}

Rules:

• Highlight the recommended plan visually (border, badge, "Most Popular")
• Show the current plan clearly so the user knows where they are
• List features as checkmarks per plan — show what's included AND what's not
• Annual pricing should show the monthly equivalent and savings percentage

Upgrade prompts

Contextual prompts are 3x more effective than generic upsell banners:

// GOOD — contextual, shown when the user hits a limit
function FeatureLimitPrompt({ feature, limit, current }: LimitPromptProps) {
  return (
    <Alert>
      <p>You've used {current} of {limit} {feature}.</p>
      <Button variant="link" asChild>
        <Link to="/settings/billing">Upgrade for unlimited {feature}</Link>
      </Button>
    </Alert>
  );
}

// BAD — generic banner shown on every page
<Banner>Upgrade to Pro for more features!</Banner>

Trial and downgrade

• Show trial days remaining in a subtle, persistent indicator (not a popup)
• Before downgrade: show what the user will lose, not just the features list
• After downgrade: gracefully degrade features (read-only, not deleted)
• Never delete user data on downgrade — mark it as inaccessible and allow re-upgrade

---

8. Feature Gating

Implementation patterns

Pattern	Use when
Feature flag	Rolling out new features gradually (% of users)
Plan gating	Feature is available only on certain subscription tiers
Role gating	Feature is restricted to certain user roles (admin, member)
Usage limit	Feature has a quota per billing period

Graceful degradation

When a feature is gated, show the user what they're missing and how to get it:

// Check access in the loader — never send gated data to the client
export async function loader({ request }: LoaderFunctionArgs) {
  const user = await requireAuth(request);
  const access = await checkFeatureAccess(user, "advanced-analytics");
  if (!access.granted) {
    return { gated: true, requiredPlan: access.requiredPlan };
  }
  const data = await loadAnalytics();
  return { gated: false, data };
}

// Component renders based on loader data
function AnalyticsPage() {
  const loaderData = useLoaderData<typeof loader>();
  if (loaderData.gated) {
    return <UpgradeOverlay requiredPlan={loaderData.requiredPlan} />;
  }
  return <AnalyticsDashboard data={loaderData.data} />;
}

Rules:

• Never show a blank space where a gated feature should be — show a teaser
• Don't hide gated features entirely — discovery drives upgrades
• Use blurred previews or locked icons, not error messages
• Role-gated features should show a "Contact your admin" message, not an upgrade prompt

---

9. Settings & Admin UX

Settings organization

Section	Contents
Account	Profile, email, password, 2FA
Team	Members, invitations, roles
Billing	Plan, payment method, invoices
Preferences	Theme, language, notification settings
Integrations	Connected services, API keys
Danger zone	Delete account, export data

Danger zone

Destructive settings must be visually distinct and require confirmation:

// Action — server-side validation (client-side pattern is bypassable)
export async function action({ request }: ActionFunctionArgs) {
  const user = await requireAuth(request);
  const formData = await request.formData();
  if (formData.get("_intent") === "delete-account") {
    const confirmation = String(formData.get("confirmation") ?? "");
    if (confirmation !== "delete my account") {
      return Response.json(
        { error: "Confirmation phrase does not match", intent: "delete-account" },
        { status: 400 },
      );
    }
    await api.deleteAccount(user.id);
    return redirect("/goodbye");
  }
}

// Component
function DangerZone() {
  return (
    <Card className="border-red-200 bg-red-50">
      <h3 className="text-red-900">Danger Zone</h3>
      <div className="space-y-4">
        <Form method="post">
          <input type="hidden" name="_intent" value="delete-account" />
          <p className="text-sm">Permanently delete your account and all data. This cannot be undone.</p>
          <label htmlFor="delete-confirmation" className="text-sm font-medium">
            Type "delete my account" to confirm
          </label>
          <input
            id="delete-confirmation"
            name="confirmation"
            required
            pattern="delete my account"
          />
          <Button type="submit" variant="destructive">Delete account</Button>
        </Form>
      </div>
    </Card>
  );
}

Rules:

• Red border/background for the danger zone section
• Require typing a confirmation phrase for irreversible actions
• Server action validates the confirmation value — client-side pattern is a UX hint, not a security boundary
• Show a clear description of what will be deleted/lost
• Offer data export before account deletion

---

10. Audit Trails & Activity Feeds

Feed structure

Every audit entry answers: who did what to which resource and when.

interface AuditEntry {
  id: string;
  actor: { id: string; name: string; avatar?: string };
  action: string;         // "created" | "updated" | "deleted" | "exported"
  resource: { type: string; id: string; name: string };
  changes?: FieldChange[];
  timestamp: string;      // ISO 8601
}

interface FieldChange {
  field: string;
  from: string | null;
  to: string | null;
}

Display patterns

• Group entries by day with date headers
• Show the most recent activity first
• Paginate with "Load more" (not page numbers) for chronological feeds
• Filter by: actor, action type, resource type, date range
• For field changes, show a diff view: old value → new value

---

11. Multi-Tenancy Awareness

Tenant context in UI

• Always show the current organization/workspace name in the sidebar or header
• Org switcher should be prominent and always accessible
• After switching orgs, redirect to the new org's dashboard (not the same page, which may not exist)

Data isolation

• Every API request must include tenant context (header, path param, or session)
• Never show data from other tenants — even in error messages
• Search results must be scoped to the current tenant
• URL paths should include the tenant identifier for shareable links: /org/{org-id}/assets

Shared resources

Some resources span tenants (billing admin, super admin views). Clearly distinguish:

• Tenant-scoped views: normal styling
• Cross-tenant views: distinct visual treatment (different background, admin badge)

---

12. Anti-Patterns

Anti-pattern	Why it fails	Better approach
Blocking modal on first visit	Users close it immediately, miss the content	Inline checklist or contextual hints
"No data" as empty state	Feels broken, gives no guidance	First-use empty state with CTA
Spinner for every load	Users perceive it as slow	Skeleton screens matching content shape
Generic upgrade banner	Banner blindness, users ignore it	Contextual prompts when hitting limits
Settings as a flat list	Overwhelming, hard to find things	Grouped sections with clear hierarchy
Hiding features behind menus	Low discoverability	Progressive disclosure with visual cues
Confirmation dialog for every action	Dialog fatigue, users click without reading	Undo pattern for reversible actions
Email-only notifications	Users miss them, no in-app awareness	In-app notification center + email fallback
All-or-nothing free plan	High barrier to conversion	Generous free tier with usage-based limits
Instant data deletion on downgrade	Users fear committing to plans	Grace period + read-only access
Activity feed without filters	Noise drowns signal for active orgs	Filter by actor, action, resource, date
No tenant indicator in UI	Users accidentally modify wrong org	Always show current org + easy switching
SPA-era: client-side wizard state	Progress lost on refresh, no deep links, no back button	Server-managed steps via loader/action
SPA-era: onClick handlers for mutations	No progressive enhancement, no revalidation	<Form method="post"> with intent pattern
SPA-era: client-side feature gating	Gated data still sent to client, security risk	Check access in loader, never send gated data

---

Cross-references

• /ux-design — design tokens, accessibility, component API design, form UX
• /react — React component patterns, hooks, state management
• /api-design — REST contracts, pagination, error formats behind features
• /domain-design — aggregate boundaries, entity vs value object, domain events