saas-product（SaaS 产品）

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.

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:

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:

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

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

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

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:

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

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

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

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