FRD: Funnel Visualization

Document Summary

Field	Details
Feature Name	Funnel Visualization
Status	Draft
Owner	David Holmes
Contributors	Design, Engineering
Target Release	v2.0.0 (P2)
Related Links	Roadmap item #49
Last Updated	2026-05-26

---

Introduction

Overview

Funnel Visualization is a growth-analytics widget that renders a multi-stage conversion funnel with drop-off percentages and optional CTAs per step. It composes the existing ProgressBar component to visualize stage-to-stage conversion rates. The widget is designed for SaaS dashboards where teams track user progression through signup, activation, and retention funnels.

Goals

• Deliver a <FunnelVisualization> component that renders an ordered list of funnel stages with conversion rates and drop-off percentages.
• Compose ProgressBar for per-stage visualization of conversion relative to the first stage.
• Support an optional CTA button per stage for actionable funnel analysis.
• Ship Storybook stories with realistic growth analytics data.

Non-Goals

• Interactive funnel editing or drag-to-reorder stages.
• Animated transitions between funnel states (deferred to motion enhancement).
• Horizontal or diagonal funnel shapes (vertical list layout only).
• Backend funnel calculation or event tracking integration.

---

Scope

In Scope

Area	Description
Component	<FunnelVisualization> rendering ordered stages with metrics
Stage Rendering	Each stage shows name, count, conversion %, and drop-off % from previous stage
Progress Bars	ProgressBar composition showing conversion relative to stage-1 count
CTAs	Optional action button per stage (e.g., “View Users”, “Send Nudge”)
States	Loading skeleton, empty state, error state
Stories	Storybook stories covering typical funnels, edge cases, and themed variants

Out of Scope

Area	Reason
Funnel shape (trapezoid/triangle SVG)	Horizontal bar/list layout is more accessible and composable
Branching funnels	Linear funnel only; branching is a different data model
Real-time updates	Consumer handles data refresh
Click-through to filtered user lists	Application-layer concern

---

Users and Pain Points

User Groups

User	Description	Needs
Developers	Engineers building growth dashboards	A composable funnel widget that uses DS primitives
Growth PMs	Product managers analyzing conversion	Visual funnel with drop-off rates at each stage
Designers	Design-system consumers	Token-aligned funnel that matches the DS visual language

Pain Points

User	Pain Point	Impact
Developers	Building funnels from scratch using divs and inline styles	Inconsistent funnels across products, high development cost
Growth PMs	Existing dashboards show raw numbers without visual drop-off indicators	Harder to identify conversion bottlenecks

---

Definitions

Term	Definition
Funnel	An ordered sequence of stages through which users progress, with decreasing counts at each stage
Drop-off	The percentage of users who did not progress from one stage to the next
Conversion Rate	The percentage of stage-1 users who reached a given stage
Stage CTA	An optional action button associated with a funnel stage

---

Current State

Existing Behavior

The design system has ProgressBar for single-value progress visualization but no funnel-specific component. Dashboard teams build funnels ad hoc using stacked divs with inline percentage widths.

Current Limitations

• No funnel component or pattern exists in the design system.
• ProgressBar is a standalone bar, not designed for sequential stage composition.
• Drop-off calculation and display are left entirely to consumers.

Existing Workarounds

• Teams build custom funnel UIs with hardcoded styles and manual percentage calculations.
• Some teams use third-party chart libraries that do not align with DS tokens.

---

Proposed Solution

Summary

Introduce <FunnelVisualization> that accepts a stages array where each stage has a name, count, and optional CTA config. The component calculates conversion rates and drop-off percentages automatically, renders each stage as a row with a ProgressBar (width proportional to stage-1 count), stage name, metrics, and optional CTA button.

Key Capabilities

• Automatic conversion rate and drop-off calculation from raw stage counts.
• ProgressBar per stage scaled to the first stage’s count (100%).
• Drop-off indicator between stages showing the percentage lost.
• Optional CTA button per stage with onClick callback.
• Accessible summary table for screen readers.

User Experience

Users see a vertical list of funnel stages. Each stage shows a progress bar (wider at top, narrower at bottom), the stage name, user count, conversion rate from stage 1, and the drop-off percentage from the previous stage. Between stages, a subtle connector shows the drop-off. Optional CTA buttons appear on the right side of each stage row.

Developer Experience

<FunnelVisualization
  title="Signup Funnel"
  stages={[
    { name: "Visited", count: 10000 },
    { name: "Signed Up", count: 3200, cta: { label: "View Users", onClick: () => {} } },
    { name: "Activated", count: 1800 },
    { name: "Subscribed", count: 450 },
  ]}
/>

---

Requirements

ID	Requirement	Priority	Notes
FR-001	FunnelVisualization renders ordered stages with progress bars	Must	-
FR-002	Conversion rate and drop-off are auto-calculated from counts	Must	-
FR-003	Each stage can have an optional CTA button	Should	-
FR-004	Loading, empty, and error states are supported	Must	-
FR-005	An accessible data table alternative is available for screen readers	Must	-

Priority Definitions

Priority	Meaning
Must	Required for this feature to ship.
Should	Important, but can be deferred if needed.
Could	Nice to have. Not required for initial release.

---

Functional Requirements

ID	Requirement	User Benefit	Priority
FUNC-001	stages prop accepts { name: string; count: number; cta?: { label: string; onClick: () => void } }[]	Simple, typed API	Must
FUNC-002	Each stage renders a ProgressBar with width proportional to count / stages[0].count * 100	Visual funnel shape	Must
FUNC-003	Drop-off percentage between adjacent stages is displayed	Highlights conversion bottlenecks	Must
FUNC-004	Conversion rate from stage 1 is displayed per stage	Overall funnel health at a glance	Must
FUNC-005	CTA button renders when cta is provided on a stage	Actionable funnel analysis	Should
FUNC-006	Stage with count of 0 renders as empty bar with “0%” label	Edge case handling	Must
FUNC-007	Single-stage funnel renders without drop-off indicators	Graceful degenerate case	Must

---

Non-Functional Requirements

ID	Requirement	Category	Priority
NFR-001	Renders in under 30ms for funnels with up to 20 stages	Performance	Must
NFR-002	Keyboard-navigable CTA buttons with visible focus rings	Accessibility	Must
NFR-003	Works in light and dark themes	Theming	Must
NFR-004	No new runtime dependencies	Maintainability	Must
NFR-005	Percentage calculations handle division by zero (stage-1 count of 0)	Robustness	Must

---

API / Interface Requirements

Public API

Name	Type	Description	Required
title	string	Funnel heading	No
stages	FunnelStage[]	Ordered array of funnel stages	Yes
showDropOff	boolean	Show drop-off indicators between stages	No (default: true)
showConversionRate	boolean	Show conversion rate from stage 1	No (default: true)
isLoading	boolean	Show loading skeleton	No
error	string	Error message	No
className	string	Additional CSS classes	No

FunnelStage Type

interface FunnelStage {
  name: string;
  count: number;
  cta?: {
    label: string;
    onClick: () => void;
  };
}

Example Usage

import { FunnelVisualization } from "@/components/ui/funnel-visualization";

<FunnelVisualization
  title="Onboarding Funnel"
  stages={[
    { name: "Page View", count: 50000 },
    { name: "Sign Up", count: 12000 },
    { name: "Email Verified", count: 8500 },
    { name: "First Action", count: 3200 },
  ]}
/>

API Notes

• stages must have at least one entry; empty array triggers empty state.
• Drop-off is calculated as (1 - stages[n].count / stages[n-1].count) * 100.
• Conversion rate is calculated as (stages[n].count / stages[0].count) * 100.

---

Accessibility Requirements

ID	Requirement	Notes
A11Y-001	A visually-hidden summary table presents funnel data to screen readers	<table> with stage name, count, conversion %, drop-off %
A11Y-002	Progress bars have aria-valuenow and aria-label with stage name and percentage	Delegates to existing ProgressBar a11y
A11Y-003	CTA buttons have descriptive aria-label including stage name	e.g., “View Users for Sign Up stage”
A11Y-004	Drop-off percentages are not conveyed by color alone	Text label always present

Checklist

• Keyboard support is defined.
• Focus behavior is defined.
• Screen reader behavior is defined.
• Color contrast requirements are met.
• Reduced motion behavior is considered.
• Semantic HTML expectations are documented.
• ARIA usage is defined only where needed.

---

Content and Documentation Requirements

ID	Requirement	Location	Priority
DOC-001	Storybook docs page with overview and props table	Storybook	Must
DOC-002	”When to use / When not to use” guidance	Storybook docs	Must
DOC-003	Stories with realistic growth funnel data (signup, activation, retention)	Storybook	Must
DOC-004	Edge case stories (single stage, zero counts, very long funnel)	Storybook	Must

---

Dependencies

Dependency	Type	Owner	Status	Notes
ProgressBar	Engineering	Design System	Ready	Per-stage bar rendering
Button	Engineering	Design System	Ready	Stage CTA buttons
Design tokens	Design	Design System	Ready	Color, spacing, typography

---

Risks and Tradeoffs

Risk / Tradeoff	Impact	Mitigation
Vertical list layout is less visually striking than a trapezoid SVG funnel	May not match user expectations from other analytics tools	Prioritize clarity and accessibility; SVG shape can be a future visual enhancement
Auto-calculation of percentages removes consumer control	Consumers with pre-calculated rates cannot use them directly	Add optional conversionRate and dropOff overrides per stage
Large funnels (20+ stages) may be unwieldy vertically	Long scroll required	Add optional maxVisibleStages with “Show more” expansion

---

Open Questions

ID	Question	Owner	Status	Resolution
Q-001	Should a trapezoid SVG funnel shape be offered as an alternative variant?	David Holmes	Open	—
Q-002	Should stages support a secondary metric (e.g., revenue per stage)?	David Holmes	Open	—
Q-003	Should the component support highlighting a specific stage as a bottleneck?	David Holmes	Open	—

---

Acceptance Criteria

ID	Criteria	Related Requirement
AC-001	Funnel renders stages with progressively narrower progress bars	FR-001, FUNC-002
AC-002	Drop-off percentages display between adjacent stages	FUNC-003
AC-003	Conversion rates from stage 1 display per stage	FUNC-004
AC-004	CTA buttons render and fire onClick when provided	FUNC-005
AC-005	Empty state renders when stages is empty	FR-004
AC-006	Screen reader table presents complete funnel data	A11Y-001
AC-007	Zero-count stage renders gracefully without NaN	FUNC-006
AC-008	All Storybook stories render without errors	DOC-003

---

LLM Handoff Instructions

Expected LLM Behavior

• Follow the requirements and acceptance criteria in this document.
• Do not expand scope beyond the In Scope section.
• Respect the Out of Scope section.
• Compose ProgressBar for each stage bar; do not reimplement progress rendering.
• Use Button for stage CTAs.
• Calculate conversion and drop-off automatically from stages[n].count.
• Handle division by zero when stage-1 count is 0.
• Place stories under the SaaS Widgets Storybook section.

LLM Should Not

• Build an SVG trapezoid funnel shape.
• Add third-party charting libraries.
• Modify the existing ProgressBar component.
• Add branching or non-linear funnel logic.

---

Decision Log

Date	Decision	Reason	Owner
2026-05-26	Use vertical list with ProgressBar rather than SVG trapezoid	More accessible, composable, and consistent with DS patterns	David Holmes
2026-05-26	Auto-calculate percentages from raw counts	Reduces consumer boilerplate and ensures consistency	David Holmes

---

Document History

Date	Author	Change
2026-05-26	David Holmes	Initial draft