FRD-059: Price Comparison Table Widget

Field	Value
Owner	David Holmes
Status	Draft
Last Updated	2026-05-26
Target Release	v2.0.0 (P2)
T-Shirt Size	M
Type	Widget

---

Document Summary

A pricing-tier comparison table widget that extends the existing ComparisonTable component with pricing-specific features: tier-level pricing display, recommended-tier highlighting, badge support for labels like “Most Popular” or “Best Value,” and a per-tier CTA button. Designed for SaaS pricing pages and plan-selection flows.

---

Introduction

Overview

SaaS products need a standardized way to present pricing tiers side by side. The existing comparison-table.tsx handles generic feature matrices but lacks pricing headers, CTA buttons per column, and badge affordances. This widget wraps or extends ComparisonTable to add those capabilities.

Goals

• Display pricing tiers with name, price, billing period, and optional badge.
• Highlight a recommended tier visually.
• Render per-tier CTA buttons (e.g., “Start Free Trial,” “Contact Sales”).
• Reuse the existing ComparisonTable feature-matrix rendering where possible.
• Ship Storybook stories covering 2-tier, 3-tier, 4-tier, and enterprise layouts.

Non-Goals

• Billing integration or subscription management.
• Plan switching logic or upgrade/downgrade flows.
• Feature-gating or entitlement checks.
• Responsive mobile accordion layout (follow-up work).

---

Scope

In Scope

Item	Description
PriceComparisonTable component	Widget composing ComparisonTable with pricing headers and CTAs
PricingTier type	Data shape for each tier column
Badge rendering	Configurable badge text and variant per tier
Recommended highlight	Visual emphasis on one tier via recommended: true
Per-tier CTA	Button with configurable label and onSelectTier callback
Storybook stories	2-tier, 3-tier, 4-tier, with-badge, enterprise-custom

Out of Scope

Item	Rationale
Billing API integration	Consumer responsibility
Toggle between monthly/annual	Can compose externally with state; may add in follow-up
Mobile accordion view	Separate enhancement tracked independently

---

Users and Pain Points

User	Pain Point
SaaS marketing teams	Building custom pricing tables per product with inconsistent designs
Design-system consumers	ComparisonTable lacks pricing-specific affordances
End users (buyers)	Difficulty comparing plans when layouts differ across products

---

Definitions

Term	Definition
Tier	A pricing plan level (e.g., Free, Pro, Enterprise)
Feature matrix	Grid of features vs. tiers showing availability
Badge	A small label overlay on a tier header (e.g., “Most Popular”)
CTA	Call-to-action button at the bottom of each tier column

---

Current State

comparison-table.tsx exists with ComparisonColumn, ComparisonRow, and ComparisonTableProps interfaces. It renders a TanStack Table-based feature matrix with check/x/text cells and supports a highlighted flag on columns. It does not support pricing headers, badges, or per-column action buttons.

---

Proposed Solution

Create a PriceComparisonTable widget at src/components/widgets/price-comparison-table.tsx that:

1. Accepts PricingTier[] which extends ComparisonColumn with price, billingPeriod, badge, ctaLabel, and recommended fields.
2. Renders a pricing header row above the feature matrix with formatted prices and optional badges.
3. Delegates feature-row rendering to the existing ComparisonTable component.
4. Appends a CTA button row below the feature matrix.
5. Applies visual highlight (elevated background, ring) to the recommended tier column.

---

Requirements

The widget must compose with ComparisonTable rather than forking it. All pricing display is driven by props; no internal price calculation occurs.

---

Functional Requirements

ID	Requirement	Priority
FR-01	Render tier columns with name, price, and billing period in the header	Must
FR-02	Display an optional badge on any tier header	Must
FR-03	Visually highlight the recommended tier with distinct styling	Must
FR-04	Render the feature matrix using ComparisonTable rows	Must
FR-05	Display a CTA button per tier at the bottom of the table	Must
FR-06	Call onSelectTier(tierId) when a CTA is clicked	Must
FR-07	Support an optional subtitle per tier for additional context	Should
FR-08	Allow a custom-tier column (e.g., “Enterprise — Contact Us”) with no price	Should
FR-09	Support grouped feature rows via ComparisonRow.group	Should

---

Non-Functional Requirements

ID	Requirement
NFR-01	Renders up to 6 tier columns and 40 feature rows without layout issues
NFR-02	Full light/dark theme support
NFR-03	Bundle addition under 3 KB gzipped (leverages existing ComparisonTable)

---

API / Interface Requirements

interface PricingTier extends ComparisonColumn {
  price?: string;            // e.g. "$29", "Custom"
  billingPeriod?: string;    // e.g. "/mo", "/year"
  badge?: string;            // e.g. "Most Popular"
  badgeVariant?: "default" | "active" | "complete" | "warning";
  ctaLabel?: string;         // e.g. "Start Free Trial"
  ctaVariant?: "default" | "primary" | "ghost";
  recommended?: boolean;
}

interface PriceComparisonTableProps {
  tiers: PricingTier[];
  rows: ComparisonRow[];
  title?: string;
  description?: string;
  onSelectTier?: (tierId: string) => void;
  className?: string;
}

---

Accessibility Requirements

ID	Requirement
A11Y-01	Table uses proper <table> semantics from ComparisonTable
A11Y-02	Recommended tier is conveyed via aria-label not just color
A11Y-03	Badge text is accessible to screen readers
A11Y-04	CTA buttons have descriptive aria-label including tier name
A11Y-05	Column headers use <th scope="col">

---

Content and Documentation Requirements

• Storybook doc page with usage guidance, props table, and composition examples.
• Stories: TwoTiers, ThreeTiers, FourTiers, WithBadges, EnterpriseTier, GroupedFeatures.
• Migration guide from raw ComparisonTable to PriceComparisonTable.

---

Dependencies

Dependency	Type	Notes
ComparisonTable	Internal	Core feature-matrix rendering
Badge	Internal	Tier badges
Button	Internal	Per-tier CTAs
@tanstack/react-table	External	Via ComparisonTable

---

Risks and Tradeoffs

Risk	Impact	Mitigation
ComparisonTable API changes	Breaks PriceComparisonTable	Pin to ComparisonTable’s current interface; add integration test
Wide tables on mobile	Poor UX on small screens	Document horizontal scroll; plan mobile accordion as follow-up
Badge overuse	Visual clutter	Document recommendation: max one badge per table

---

Open Questions

1. Should monthly/annual toggle be built in or always composed externally?
2. Do we need a “Compare selected” mode for selecting two tiers to compare?
3. Should feature-group headers be sticky on scroll?

---

Acceptance Criteria

• PriceComparisonTable renders pricing headers with name, price, period, and badge.
• Recommended tier has visually distinct styling and an accessible label.
• CTA buttons call onSelectTier with the correct tier ID.
• Feature matrix delegates to ComparisonTable and renders correctly.
• All Storybook stories render without errors.
• Passes axe accessibility audit with zero violations.
• Unit tests cover rendering with 2, 3, and 4 tiers, badge display, and CTA callbacks.

---

LLM Handoff Instructions

When implementing this FRD:

1. Create src/components/widgets/price-comparison-table.tsx.
2. Import and compose ComparisonTable from @/components/ui/comparison-table.
3. Extend ComparisonColumn for the PricingTier type.
4. Create src/components/widgets/price-comparison-table.stories.tsx with all listed stories.
5. Create src/components/widgets/price-comparison-table.test.tsx.
6. The pricing header and CTA footer should wrap the ComparisonTable in a flex layout.
7. Use Badge for tier badges and Button for CTAs.
8. Recommended tier highlight: use a ring or elevated background via Tailwind utilities.

---

Decision Log

Date	Decision	Rationale
2026-05-26	Compose with ComparisonTable rather than fork	Reduces duplication; inherits table accessibility and theming
2026-05-26	Prices are pre-formatted strings, not numbers	Avoids locale/currency formatting complexity in the widget

---

Document History

Date	Version	Author	Changes
2026-05-26	0.1	David Holmes	Initial draft