FRD: Trend Comparison

Document Summary

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

Introduction

Overview

Trend Comparison is an analytics widget that overlays two data series on a single chart with an integrated legend and period toggle. It enables side-by-side comparison of metrics (e.g., this month vs. last month, plan A vs. plan B) within a single, self-contained card. The widget builds on the existing line and area chart primitives in charts.tsx.

Goals

Provide a <TrendComparison> component that renders two series on one chart with distinct visual treatments.
Include a built-in legend identifying each series by name and color.
Include a period toggle for switching comparison windows.
Ship complete Storybook stories covering typical analytics comparison patterns.

Non-Goals

More than two series in a single comparison (deferred to a multi-series chart widget).
Drill-down or click-to-filter interactions on data points.
Statistical analysis (correlation, regression) computed within the component.
Server-side data fetching or query integration.

Scope

In Scope

Area	Description
Component	`<TrendComparison>` widget rendering two overlaid series
Legend	Color-coded legend with series names, toggleable visibility
Period Toggle	Segmented control for switching comparison time ranges
Visual Differentiation	Primary series as solid line/area, comparison series as dashed line or lower-opacity area
States	Loading skeleton, empty state, error state
Stories	Storybook stories for line overlay, area overlay, period switching, and edge cases

Out of Scope

Area	Reason
Three or more series	Separate multi-series component; two-series keeps the UX focused
Bar chart comparison	Grouped/stacked bar is a different layout pattern
Data normalization	Consumer is responsible for aligning series to the same x-axis
Annotations or markers	Future enhancement, not part of initial comparison widget

Users and Pain Points

User Groups

User	Description	Needs
Developers	Engineers building analytics dashboards	A ready-made two-series comparison widget
Designers	Design-system consumers	Consistent dual-series visual treatment
Analysts	Dashboard end users	Quick visual comparison of two time periods or segments

Pain Points

User	Pain Point	Impact
Developers	Building dual-series overlays requires manual z-index management, duplicate chart instances, and custom legend wiring	Slow development, inconsistent results
Analysts	Comparing metrics requires opening two separate cards side-by-side	Harder to spot trends and correlations

Definitions

Term	Definition
Series	A named sequence of data points rendered as a single line or area on the chart
Primary Series	The main metric being examined; rendered with the primary color token
Comparison Series	The secondary metric or time-shifted variant; rendered with a muted or dashed treatment
Period Toggle	A control that switches which time window both series display

Current State

Existing Behavior

The design system provides single-series line and area charts in charts.tsx. There is no built-in support for rendering two series on a shared axis. MetricCard supports a single sparkline but not a dual-series comparison.

Current Limitations

Charts accept a single data: ChartDataPoint[] array with no multi-series concept.
No legend component exists for chart series identification.
No pattern for visually differentiating a primary vs. comparison series.

Existing Workarounds

Developers render two separate chart cards and ask users to compare visually.
Some teams overlay two absolute-positioned chart components, which is fragile and inaccessible.

Proposed Solution

Summary

Introduce <TrendComparison> that accepts primarySeries and comparisonSeries props, each containing a name, color token, and data array. The component renders both series on a shared axis using the existing chart rendering logic, adds a legend, and includes an optional period toggle.

Key Capabilities

Dual-series overlay on a single chart with shared x-axis and y-axis.
Built-in legend with series name, color swatch, and toggle to hide/show each series.
Period toggle for time range switching.
Visual differentiation: solid vs. dashed line, or full-opacity vs. reduced-opacity area.

User Experience

Users see a chart card with two overlaid lines or areas. A legend below the chart identifies each series. A period toggle in the header switches the time window. Hovering shows a tooltip with values from both series at the hovered x-position.

Developer Experience

<TrendComparison
  title="Revenue: This Month vs. Last Month"
  chartType="line"
  primarySeries={{ name: "This Month", data: currentData, color: "primary" }}
  comparisonSeries={{ name: "Last Month", data: previousData, color: "muted" }}
  periods={["7d", "30d", "90d"]}
  activePeriod="30d"
  onPeriodChange={setPeriod}
/>

Requirements

ID	Requirement	Priority	Notes
FR-001	TrendComparison renders two data series on a shared axis	Must	-
FR-002	A legend displays series names with color indicators	Must	-
FR-003	Legend items can be toggled to show/hide individual series	Should	-
FR-004	Period toggle switches the displayed time range	Must	-
FR-005	Primary series uses solid rendering; comparison uses dashed/muted	Must	-
FR-006	Loading, empty, and error states are handled	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	`primarySeries` and `comparisonSeries` each accept `{ name, data, color }`	Clear API for dual-series data	Must
FUNC-002	`chartType` accepts `"line"` or `"area"` to determine rendering	Flexibility for different visualization needs	Must
FUNC-003	Legend renders below the chart with color swatches and series names	Users can identify which line is which	Must
FUNC-004	Clicking a legend item toggles that series visibility	Focused analysis of a single series	Should
FUNC-005	Hover tooltip shows values from both series at the same x-position	Easy point-by-point comparison	Should
FUNC-006	Y-axis auto-scales to the visible range of both series	Accurate visual comparison	Must
FUNC-007	Empty state shows when both series have no data	Clear feedback	Must

Non-Functional Requirements

ID	Requirement	Category	Priority
NFR-001	Renders in under 50ms for two series of 365 points each	Performance	Must
NFR-002	All interactive elements (legend, toggle, tooltip) are keyboard-navigable	Accessibility	Must
NFR-003	Works in light and dark themes	Theming	Must
NFR-004	No new runtime dependencies	Maintainability	Must
NFR-005	Visual differentiation between series does not rely solely on color	Accessibility	Must

API / Interface Requirements

Public API

Name	Type	Description	Required
title	`string`	Card heading	Yes
chartType	`"line" \| "area"`	Visualization type	Yes
primarySeries	`{ name: string; data: ChartDataPoint[]; color?: string }`	Main data series	Yes
comparisonSeries	`{ name: string; data: ChartDataPoint[]; color?: string }`	Comparison data series	Yes
periods	`string[]`	Available time period options	No
activePeriod	`string`	Currently selected period	No
onPeriodChange	`(period: string) => void`	Period change callback	No
isLoading	`boolean`	Show loading skeleton	No
error	`string`	Error message	No
height	`number`	Chart height in pixels	No
className	`string`	Additional CSS classes	No

Example Usage

import { TrendComparison } from "@/components/ui/trend-comparison";

<TrendComparison
  title="Signups: This Week vs. Last Week"
  chartType="area"
  primarySeries={{
    name: "This Week",
    data: [{ label: "Mon", value: 120 }, { label: "Tue", value: 145 }],
  }}
  comparisonSeries={{
    name: "Last Week",
    data: [{ label: "Mon", value: 98 }, { label: "Tue", value: 110 }],
  }}
/>

API Notes

Both series must share the same label values for x-axis alignment.
color defaults to "primary" for primary and "muted-foreground" for comparison.
Comparison series renders dashed for line type and reduced opacity for area type.

Accessibility Requirements

ID	Requirement	Notes
A11Y-001	Chart region has `role="img"` with a label describing both series	-
A11Y-002	Legend items are focusable and togglable via keyboard	Enter/Space to toggle
A11Y-003	Series differentiation uses both color and line style (solid vs. dashed)	Not color-only
A11Y-004	Tooltip content is accessible to screen readers	`aria-live` region for hovered values
A11Y-005	Loading state sets `aria-busy="true"`	-

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 for line and area comparisons with realistic analytics data	Storybook	Must
DOC-004	Story demonstrating legend toggle interaction	Storybook	Should

Dependencies

Dependency	Type	Owner	Status	Notes
`charts.tsx` (LineChart, AreaChart)	Engineering	Design System	Ready	Base chart rendering
`SegmentedControl`	Engineering	Design System	Ready	Period toggle
Design tokens	Design	Design System	Ready	Color, spacing, typography

Risks and Tradeoffs

Risk / Tradeoff	Impact	Mitigation
Two series with very different scales can mislead users	Visual comparison may be inaccurate	Document that series should share the same unit; consider dual y-axis as future enhancement
Dashed-line rendering in CSS may have browser inconsistencies	Visual glitches in some browsers	Test across Chrome, Firefox, Safari; use `stroke-dasharray` on SVG or `border-style` fallback
Limiting to two series restricts power-user analytics	Users who need 3+ series cannot use this widget	Explicitly designed for two-series; multi-series is a separate roadmap item

Open Questions

ID	Question	Owner	Status	Resolution
Q-001	Should dual y-axis be supported for series with different units?	David Holmes	Open	—
Q-002	Should the tooltip show the delta between the two series at each point?	David Holmes	Open	—
Q-003	Should the comparison series support a time-offset mode (auto-shift labels)?	David Holmes	Open	—

Acceptance Criteria

ID	Criteria	Related Requirement
AC-001	Two series render on a shared chart with distinct visual treatments	FR-001, FR-005
AC-002	Legend displays both series names with color indicators	FR-002
AC-003	Clicking a legend item hides/shows the corresponding series	FR-003
AC-004	Period toggle fires `onPeriodChange` and updates display	FR-004
AC-005	Loading skeleton, empty state, and error state render correctly	FR-006
AC-006	Component passes axe accessibility audit	NFR-002
AC-007	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.
Build on existing chart rendering logic from charts.tsx; extend rather than replace.
Use solid/dashed differentiation for line charts and opacity differentiation for area charts.
Place stories under the SaaS Widgets Storybook section.
Add tests mapping to acceptance criteria.

LLM Should Not

Add a third-party charting library.
Support more than two series.
Modify existing single-series chart components.
Invent analytics features not described here.

Decision Log

Date	Decision	Reason	Owner
2026-05-26	Limit to exactly two series	Keeps UX focused and avoids multi-series complexity	David Holmes
2026-05-26	Use line-style differentiation (solid vs. dashed) rather than color-only	Accessibility: ensures series are distinguishable without color vision	David Holmes

Document History

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