FRD: Chart Card

Document Summary

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

---

Introduction

Overview

Chart Card combines a line, bar, or area chart with a card shell that includes a title, period selector, and delta badge. It provides a self-contained analytics widget that product teams can drop into dashboards without assembling chart, card, and metric primitives by hand. The existing charts.tsx (BarChart, LineChart, AreaChart) and metric-card.tsx provide the building blocks; Chart Card composes them into a single, opinionated widget.

Goals

• Deliver a single <ChartCard> component that renders a chart inside a metric-card-like container with title, period selector, and delta badge.
• Support line, bar, and area chart types via a chartType prop.
• Use design-system tokens for all colors, spacing, and typography so the widget adapts to themes.
• Ship Storybook stories covering all chart types, period selections, and edge cases.

Non-Goals

• Real-time streaming data or WebSocket integration.
• Server-side data fetching or query-layer concerns.
• Custom chart types beyond line, bar, and area.
• Drill-down or click-through interactions on chart data points.

---

Scope

In Scope

Area	Description
Component	<ChartCard> widget composing BarChart/LineChart/AreaChart + card shell
Period Selector	Built-in segmented control or select for time period switching (7d, 30d, 90d, 1y, custom)
Delta Badge	Badge showing absolute or percentage change with up/down/neutral trend styling
Token Alignment	All visual properties use design-system color, spacing, and typography tokens
Stories	Storybook stories for each chart type, period states, loading/empty/error, and themed variants

Out of Scope

Area	Reason
Data fetching	Consumer responsibility; widget accepts data via props
Animation library	Uses existing CSS transition tokens; no new motion library
Interactive tooltips beyond hover	Deferred to a future chart-interaction enhancement
Export-to-image	Separate concern, not part of the card widget

---

Users and Pain Points

User Groups

User	Description	Needs
Developers	Engineers building SaaS dashboards	A composable, token-aligned chart widget with minimal setup
Designers	Design-system consumers	Consistent chart presentation that matches the DS visual language
Product Managers	Dashboard stakeholders	Quick insight into metric trends at a glance

Pain Points

User	Pain Point	Impact
Developers	Must manually compose chart + card + badge + period selector for every dashboard metric	Repeated boilerplate, inconsistent layouts across products
Designers	Charts rendered with ad-hoc colors and spacing break visual consistency	Brand dilution and increased review burden

---

Definitions

Term	Definition
Chart Card	A self-contained widget that pairs a chart visualization with metric metadata (title, delta, period) inside a card shell
Delta Badge	A small indicator showing the change in a metric value, styled with trend direction (up/down/neutral)
Period Selector	A segmented control or dropdown allowing the user to switch the displayed time range
Chart Type	One of line, bar, or area determining the visualization style

---

Current State

Existing Behavior

The design system ships BarChart, LineChart, and AreaChart in charts.tsx, and MetricCard in metric-card.tsx. Developers combine these manually to build dashboard cards. There is no single widget that unifies a chart with a title, delta badge, and period selector.

Current Limitations

• No composition primitive that pairs a chart with metric metadata.
• Period selection must be implemented ad hoc by each consumer.
• Delta badges on MetricCard are disconnected from the chart data.

Existing Workarounds

• Developers wrap MetricCard and BarChart in a custom div and wire state manually.
• Period selectors are built from scratch using SegmentedControl or Select without a shared pattern.

---

Proposed Solution

Summary

Introduce a <ChartCard> widget that accepts a chartType, data array, title, optional delta/deltaDirection, and a periods config. The component renders a card shell with a header row (title + period selector + delta badge) and a chart body. The period selector calls an onPeriodChange callback so the consumer can swap data.

Key Capabilities

• Render line, bar, or area chart from a single component.
• Built-in period selector (segmented control for up to 4 options, select dropdown for more).
• Delta badge with automatic trend coloring via deltaDirection.
• Loading skeleton, empty state, and error state built in.

User Experience

Users see a card with a descriptive title, a period toggle in the header, the current delta, and a chart filling the card body. Switching periods triggers a brief skeleton transition while data loads.

Developer Experience

<ChartCard
  title="Revenue"
  chartType="area"
  data={revenueData}
  delta="+12.4%"
  deltaDirection="up"
  periods={["7d", "30d", "90d"]}
  activePeriod="30d"
  onPeriodChange={setPeriod}
/>

---

Requirements

ID	Requirement	Priority	Notes
FR-001	ChartCard renders line, bar, or area chart based on chartType prop	Must	Delegates to existing chart components
FR-002	ChartCard displays a title in the card header	Must	-
FR-003	ChartCard includes a period selector when periods is provided	Must	-
FR-004	ChartCard shows a delta badge when delta prop is set	Should	-
FR-005	ChartCard supports loading, empty, and error states	Must	-
FR-006	All colors and spacing use design-system tokens	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	chartType prop accepts "line", "bar", or "area" and renders the corresponding chart	Single API for multiple chart types	Must
FUNC-002	periods prop renders a segmented control (up to 4 items) or select (5+ items)	Familiar period switching UX	Must
FUNC-003	onPeriodChange fires when user selects a new period	Consumer controls data fetching	Must
FUNC-004	delta and deltaDirection render a badge with color-coded trend indicator	At-a-glance metric performance	Should
FUNC-005	When data is empty and not loading, display an empty state message	Clear feedback when no data exists	Must
FUNC-006	When isLoading is true, display a skeleton matching the chart shape	Smooth loading transition	Must
FUNC-007	When error prop is set, display an error state with retry option	Recoverable error handling	Must

---

Non-Functional Requirements

ID	Requirement	Category	Priority
NFR-001	Chart Card renders in under 50ms for datasets up to 365 data points	Performance	Must
NFR-002	Component tree-shakes unused chart types when bundled	Performance	Should
NFR-003	All interactive elements are keyboard-navigable	Accessibility	Must
NFR-004	Component works in light and dark themes without additional configuration	Theming	Must
NFR-005	No new runtime dependencies beyond existing chart primitives	Maintainability	Must

---

API / Interface Requirements

Public API

Name	Type	Description	Required
title	string	Card heading text	Yes
chartType	"line" | "bar" | "area"	Chart visualization type	Yes
data	ChartDataPoint[]	Array of label/value data points	Yes
delta	string	Change text displayed in badge	No
deltaDirection	"up" | "down" | "neutral"	Trend direction for badge coloring	No
periods	string[]	Available time period options	No
activePeriod	string	Currently selected period	No
onPeriodChange	(period: string) => void	Callback when period changes	No
isLoading	boolean	Show loading skeleton	No
error	string	Error message to display	No
height	number	Chart height in pixels	No
className	string	Additional CSS classes	No

Example Usage

import { ChartCard } from "@/components/ui/chart-card";

<ChartCard
  title="Monthly Revenue"
  chartType="line"
  data={[
    { label: "Jan", value: 4200 },
    { label: "Feb", value: 4800 },
    { label: "Mar", value: 5100 },
  ]}
  delta="+8.2%"
  deltaDirection="up"
  periods={["7d", "30d", "90d"]}
  activePeriod="30d"
  onPeriodChange={(p) => fetchData(p)}
/>

API Notes

• Reuses ChartDataPoint interface from charts.tsx.
• Period selector auto-selects segmented control or select based on option count.
• height defaults to 220px matching existing chart defaults.

---

Accessibility Requirements

ID	Requirement	Notes
A11Y-001	Chart region has role="img" with descriptive aria-label	Delegates to underlying chart component
A11Y-002	Period selector is keyboard-navigable with arrow keys	Uses existing SegmentedControl/Select a11y
A11Y-003	Delta badge conveys trend direction to screen readers	aria-label includes direction text, not just color
A11Y-004	Loading state announces to assistive technology	aria-busy="true" on card during loading
A11Y-005	Error state is announced as an alert	role="alert" on error message

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, props table, and usage examples	Storybook	Must
DOC-002	”When to use / When not to use” guidance	Storybook docs	Must
DOC-003	Example stories for each chart type with realistic data	Storybook	Must
DOC-004	Loading, empty, and error state stories	Storybook	Must

---

Dependencies

Dependency	Type	Owner	Status	Notes
charts.tsx (BarChart, LineChart, AreaChart)	Engineering	Design System	Ready	Existing components
metric-card.tsx (MetricCard)	Engineering	Design System	Ready	Reference for card shell pattern
SegmentedControl	Engineering	Design System	Ready	Used for period selector
Select	Engineering	Design System	Ready	Fallback for 5+ periods
Badge	Engineering	Design System	Ready	Delta badge
Design tokens (color, spacing, typography)	Design	Design System	Ready	-

---

Risks and Tradeoffs

Risk / Tradeoff	Impact	Mitigation
Composing three chart types in one component increases bundle size for consumers who only need one	Larger import size	Tree-shaking via conditional imports; document single-chart usage pattern
Period selector pattern may not cover all consumer date-range needs	Consumers with custom ranges must build their own	Accept periodSelector render prop as escape hatch
Chart data format is coupled to ChartDataPoint	Consumers with different data shapes must transform	Provide a transformData utility or document the expected shape clearly

---

Open Questions

ID	Question	Owner	Status	Resolution
Q-001	Should the period selector support a custom date range picker?	David Holmes	Open	—
Q-002	Should chartType support "sparkline" for compact inline usage?	David Holmes	Open	—
Q-003	Should the card support a footer slot for supplementary actions?	David Holmes	Open	—

---

Acceptance Criteria

ID	Criteria	Related Requirement
AC-001	<ChartCard chartType="line"> renders a line chart inside a card shell	FR-001
AC-002	<ChartCard chartType="bar"> renders a bar chart inside a card shell	FR-001
AC-003	<ChartCard chartType="area"> renders an area chart inside a card shell	FR-001
AC-004	Period selector renders and fires onPeriodChange on selection	FUNC-002, FUNC-003
AC-005	Delta badge displays with correct trend color for up/down/neutral	FUNC-004
AC-006	Empty state displays when data is empty and isLoading is false	FUNC-005
AC-007	Loading skeleton displays when isLoading is true	FUNC-006
AC-008	Error state displays with message when error is set	FUNC-007
AC-009	All Storybook stories render without errors	DOC-003
AC-010	Component passes axe accessibility audit	A11Y-001

---

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 from existing chart components in charts.tsx and patterns from metric-card.tsx.
• Use SegmentedControl for period selector when periods count is 4 or fewer; use Select for 5+.
• Use Badge for delta display with appropriate tone based on deltaDirection.
• Preserve existing ChartDataPoint interface; do not modify charts.tsx.
• Add stories under the SaaS Widgets Storybook section.
• Add or update tests that map to the acceptance criteria.

LLM Should Not

• Invent undocumented product behavior.
• Add charting libraries (recharts, chart.js, etc.) — use existing CSS-based chart components.
• Modify existing chart or metric-card components.
• Change unrelated components.

---

Decision Log

Date	Decision	Reason	Owner
2026-05-26	Compose from existing chart primitives rather than introducing a charting library	Keeps bundle small, maintains token alignment, avoids new dependency	David Holmes
2026-05-26	Use segmented control for period selector with select fallback	Matches existing DS patterns for option switching	David Holmes

---

Document History

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