FRD: Cohort Heatmap

Document Summary

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

---

Introduction

Overview

Cohort Heatmap is an analytics widget that renders a two-dimensional grid where rows represent user cohorts (grouped by signup period) and columns represent time periods after signup. Each cell is color-coded by intensity to show retention or engagement rates. The widget builds on the existing HeatStrip cell-rendering pattern and extends it into a full grid with row/column headers, a color legend, and an accessible summary.

Goals

• Deliver a <CohortHeatmap> component that renders a grid of color-intensity cells with row and column headers.
• Use design-system color tokens for cell tones with configurable intensity mapping.
• Include a legend explaining the color scale.
• Provide an accessible summary table for screen readers.
• Ship Storybook stories with realistic cohort retention data.

Non-Goals

• Interactive cell selection or drill-down to user lists.
• Editable cells or inline data entry.
• Server-side cohort calculation or query integration.
• Pivot-table or sortable-column behavior (that is DataGrid territory).

---

Scope

In Scope

Area	Description
Component	<CohortHeatmap> rendering a color-coded grid of cohort data
Cell Rendering	Each cell shows a background color based on intensity (0-1) and optional text value
Headers	Row headers for cohort names, column headers for time periods
Legend	Color scale legend mapping intensity values to colors
Accessible Summary	Visually-hidden table with full data for screen readers
States	Loading skeleton, empty state, error state
Stories	Storybook stories for retention, engagement, and edge cases

Out of Scope

Area	Reason
Sortable columns	DataGrid concern; heatmap is read-only visualization
Cell editing	Heatmap is a display-only widget
Custom cell renderers	Cells show color + optional value text; complex renderers deferred
Cohort calculation logic	Consumer provides pre-calculated data

---

Users and Pain Points

User Groups

User	Description	Needs
Developers	Engineers building retention dashboards	A token-aligned cohort heatmap component
Growth PMs	Product managers tracking cohort behavior	Visual cohort retention grid with clear drop-off patterns
Data Analysts	Dashboard consumers	Quick scan of cohort trends via color intensity

Pain Points

User	Pain Point	Impact
Developers	Building cohort heatmaps from scratch requires custom grid layout, color interpolation, and accessibility work	High development cost, inconsistent results
Growth PMs	Existing tables show raw numbers without visual intensity cues	Slower pattern recognition

---

Definitions

Term	Definition
Cohort	A group of users who share a common characteristic, typically signup date range
Intensity	A normalized value (0 to 1) representing the metric strength for a cell
Retention Rate	The percentage of a cohort still active after N time periods
Color Scale	A gradient mapping intensity values to background colors using design tokens

---

Current State

Existing Behavior

HeatStrip renders a single-row heatmap with intensity-based cell coloring. It uses a single color with opacity scaling (0.2 to 1.0) based on intensity. There is no multi-row grid heatmap component.

Current Limitations

• HeatStrip is single-row only; no grid layout support.
• No row/column header support.
• No color legend component.
• No accessible summary for multi-dimensional data.

Existing Workarounds

• Teams use raw HTML tables with inline background-color styles.
• Some teams use third-party heatmap libraries that do not align with DS tokens.

---

Proposed Solution

Summary

Introduce <CohortHeatmap> that accepts rows (cohort data with cell intensities), columnHeaders, and color configuration. The component renders a grid using the HeatStrip cell-rendering pattern (color + opacity scaling) extended to a 2D layout. A legend renders below the grid showing the color scale.

Key Capabilities

• Two-dimensional grid with cohort rows and time-period columns.
• Cell coloring via design-system color tokens with intensity-based opacity.
• Optional text value overlay on cells (e.g., “45%”).
• Color scale legend with min/max labels.
• Visually-hidden data table for screen reader accessibility.
• Sticky row headers for horizontal scrolling on wide grids.

User Experience

Users see a grid where the top-left cell is empty, the first row contains time-period headers (Week 1, Week 2, etc.), and each subsequent row is a cohort. Cells are colored from light (low intensity) to saturated (high intensity). Hovering a cell shows a tooltip with the exact value. A legend below explains the color scale.

Developer Experience

<CohortHeatmap
  title="Weekly Retention"
  columnHeaders={["Week 1", "Week 2", "Week 3", "Week 4"]}
  rows={[
    {
      label: "Jan 2026",
      cells: [
        { intensity: 1.0, value: "100%" },
        { intensity: 0.72, value: "72%" },
        { intensity: 0.55, value: "55%" },
        { intensity: 0.41, value: "41%" },
      ],
    },
  ]}
  color="primary"
/>

---

Requirements

ID	Requirement	Priority	Notes
FR-001	CohortHeatmap renders a 2D grid with color-intensity cells	Must	-
FR-002	Row and column headers display cohort names and time periods	Must	-
FR-003	A color scale legend renders below the grid	Must	-
FR-004	An accessible summary table is available for screen readers	Must	-
FR-005	Cell tooltips show exact values on hover	Should	-
FR-006	Loading, empty, and error states are supported	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	rows prop accepts { label: string; cells: { intensity: number; value?: string }[] }[]	Typed cohort data structure	Must
FUNC-002	columnHeaders prop accepts string[] for time period labels	Clear column identification	Must
FUNC-003	Cell background color uses color token with opacity from intensity * 0.8 + 0.2	Visual intensity mapping matching HeatStrip pattern	Must
FUNC-004	Optional value text overlays on each cell in a readable contrast color	Exact values visible without tooltip	Should
FUNC-005	Legend renders a gradient bar with “Low” and “High” labels	Color scale context	Must
FUNC-006	Row headers stick on horizontal scroll for wide grids	Cohort identification while scrolling	Should
FUNC-007	Hover tooltip shows row label, column header, and value	Precise data point identification	Should

---

Non-Functional Requirements

ID	Requirement	Category	Priority
NFR-001	Renders in under 100ms for grids up to 52 rows x 12 columns	Performance	Must
NFR-002	Cell text meets WCAG AA contrast against the cell background color	Accessibility	Must
NFR-003	Works in light and dark themes	Theming	Must
NFR-004	No new runtime dependencies	Maintainability	Must
NFR-005	Grid scrolls horizontally on narrow viewports without layout breakage	Responsiveness	Must

---

API / Interface Requirements

Public API

Name	Type	Description	Required
title	string	Heatmap heading	No
columnHeaders	string[]	Time period labels for columns	Yes
rows	CohortRow[]	Array of cohort rows with cells	Yes
color	string	Design token color class for cells (e.g., "primary", "success")	No (default: "primary")
showValues	boolean	Show value text on cells	No (default: false)
isLoading	boolean	Show loading skeleton	No
error	string	Error message	No
className	string	Additional CSS classes	No

CohortRow Type

interface CohortHeatmapCell {
  intensity: number; // 0 to 1
  value?: string;    // display text, e.g. "72%"
  tooltip?: string;  // custom tooltip override
}

interface CohortRow {
  label: string;
  cells: CohortHeatmapCell[];
}

Example Usage

import { CohortHeatmap } from "@/components/ui/cohort-heatmap";

<CohortHeatmap
  title="Monthly Retention"
  columnHeaders={["Month 1", "Month 2", "Month 3"]}
  rows={[
    { label: "Q1 2026", cells: [{ intensity: 1, value: "100%" }, { intensity: 0.65, value: "65%" }, { intensity: 0.42, value: "42%" }] },
    { label: "Q2 2026", cells: [{ intensity: 1, value: "100%" }, { intensity: 0.71, value: "71%" }] },
  ]}
  showValues
  color="primary"
/>

API Notes

• Rows with fewer cells than columnHeaders.length render empty cells for missing positions.
• intensity is clamped to 0-1 internally.
• color maps to a design-system token class, matching HeatStrip’s color prop pattern.

---

Accessibility Requirements

ID	Requirement	Notes
A11Y-001	A visually-hidden <table> presents complete grid data to screen readers	Includes row headers, column headers, and cell values
A11Y-002	Cell value text meets WCAG AA contrast ratio against the cell background	Auto-switch to dark or light text based on intensity
A11Y-003	Legend is described in a way accessible to screen readers	aria-label on legend element
A11Y-004	Tooltip content is accessible via keyboard focus	Cells are focusable; tooltip shows on focus
A11Y-005	Grid has role="img" with descriptive aria-label for the visual representation	Separate from the accessible table

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 retention and engagement cohort data	Storybook	Must
DOC-004	Story demonstrating horizontal scroll behavior on wide grids	Storybook	Should
DOC-005	Story demonstrating showValues mode	Storybook	Must

---

Dependencies

Dependency	Type	Owner	Status	Notes
HeatStrip cell pattern	Engineering	Design System	Ready	Reference for intensity-to-opacity mapping
Design tokens (color, spacing)	Design	Design System	Ready	Cell coloring and grid spacing

---

Risks and Tradeoffs

Risk / Tradeoff	Impact	Mitigation
Large grids (52x12) may be slow to render with many DOM nodes	Performance degradation	Virtualize rows if grid exceeds a threshold; benchmark during implementation
Opacity-based coloring may not provide enough differentiation at extremes	Hard to distinguish 0.8 from 0.9 intensity	Consider a stepped color scale with 5-6 discrete levels as an alternative
Cell value text on colored backgrounds may have contrast issues	Accessibility failure	Auto-switch text color to white or black based on computed background luminance

---

Open Questions

ID	Question	Owner	Status	Resolution
Q-001	Should a continuous gradient or discrete stepped color scale be the default?	David Holmes	Open	—
Q-002	Should row virtualization be included in v1 or deferred?	David Holmes	Open	—
Q-003	Should the heatmap support a secondary color for a “diverging” scale (positive/negative values)?	David Holmes	Open	—

---

Acceptance Criteria

ID	Criteria	Related Requirement
AC-001	Grid renders with correct row and column headers	FR-001, FR-002
AC-002	Cell colors reflect intensity values using the specified color token	FUNC-003
AC-003	Color legend renders with Low/High labels	FR-003
AC-004	Visually-hidden table presents data to screen readers	FR-004
AC-005	showValues displays text on cells with adequate contrast	FUNC-004, NFR-002
AC-006	Grid scrolls horizontally on narrow viewports with sticky row headers	FUNC-006, NFR-005
AC-007	Loading, empty, and error states render correctly	FR-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.
• Reference HeatStrip for the intensity-to-opacity mapping pattern (0.2 + intensity * 0.8).
• Use CSS position: sticky for row header pinning on horizontal scroll.
• Auto-switch cell text color for contrast: use white text when intensity > 0.6, dark text otherwise.
• Include a visually-hidden <table> with complete data for screen readers.
• Place stories under the SaaS Widgets Storybook section.

LLM Should Not

• Use a third-party heatmap library.
• Build interactive cell selection or editing.
• Modify the existing HeatStrip component.
• Add sorting or filtering to the grid.

---

Decision Log

Date	Decision	Reason	Owner
2026-05-26	Use opacity scaling matching HeatStrip rather than a discrete stepped palette	Consistency with existing DS pattern; discrete steps can be added later	David Holmes
2026-05-26	Provide a visually-hidden table rather than making the visual grid a <table>	Visual grid uses CSS Grid for flexible sizing; accessible table is a separate semantic element	David Holmes

---

Document History

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