Skip to content

ADR 017 Chart Library

Jump to bottom
Claude product-architect (Opus 4.6) edited this page Mar 5, 2026 · 1 revision

ADR-017: Chart Library: Recharts

Status

Accepted

Context

EPIC-09 (Dashboard & Project Health Center) requires donut charts for budget distribution and bar charts for budget variance visualization. The project needs a charting library that:

  1. Is pure JavaScript (no native binaries) -- required by our dependency policy (ADR-004, CLAUDE.md)
  2. Integrates well with React 19 and the existing component architecture
  3. Supports donut/pie charts and bar charts at minimum
  4. Is mature, well-maintained, and has a stable API
  5. Keeps bundle size reasonable for a small-scale app

Alternatives Considered

Library Version Bundle (gzip) Rendering React Integration Native Binaries
Recharts 3.7.0 ~45 KB SVG Native (declarative components) No
Chart.js + react-chartjs-2 4.5.1 + 5.3.1 ~11 KB (Chart.js core) + wrapper Canvas (2D) Wrapper library No
Victory 37.x ~60 KB SVG Native (declarative components) No

Evaluation

Recharts (recommended):

  • Built specifically for React with declarative JSX components (<PieChart>, <BarChart>, <ResponsiveContainer>)
  • SVG-based rendering aligns with the existing Gantt chart approach (ADR-013: Custom SVG)
  • Uses lightweight D3 submodules, not the full D3 library
  • Active maintenance: 24k+ GitHub stars, regular releases
  • Responsive containers and built-in tooltip/legend components
  • CSS-friendly: SVG elements can be styled with CSS Modules (consistent with ADR-006)
  • TypeScript support built-in

Chart.js + react-chartjs-2:

  • Smaller core bundle (~11 KB gzipped)
  • Canvas-based rendering -- different paradigm from the SVG-based Gantt chart
  • Requires a separate React wrapper library (react-chartjs-2) that adds indirection
  • Imperative API wrapped in declarative components -- less natural React integration
  • Canvas elements are harder to style with CSS and less accessible (no DOM nodes for screen readers)
  • Plugin system is powerful but more complex for simple use cases

Victory:

  • Good React integration with declarative components
  • Larger bundle size than both alternatives
  • Less community adoption than Recharts or Chart.js
  • More opinionated styling that may conflict with our design tokens

Decision

Use Recharts 3.7.0 for dashboard charts.

Key factors:

  1. SVG consistency: Both the Gantt chart (custom SVG) and dashboard charts (Recharts SVG) use SVG rendering. This means a single styling approach and consistent accessibility patterns.
  2. React-native API: Recharts components compose naturally in JSX without wrapper libraries or imperative configuration objects.
  3. CSS Modules compatibility: SVG elements rendered by Recharts can be targeted with CSS classes, maintaining consistency with our styling approach (ADR-006).
  4. Simplicity: For the small number of charts needed (2-3 chart types), Recharts' declarative API is the simplest to implement and maintain.
  5. No native binaries: Pure JavaScript, compliant with our dependency policy.

The ~45 KB gzipped bundle is acceptable for a self-hosted app with fewer than 5 users where initial load time is not a critical concern.

Consequences

Easier:

  • Dashboard charts can be built with familiar React component patterns
  • SVG rendering is consistent with the Gantt chart approach
  • Charts are inherently accessible (SVG DOM nodes for screen readers, ARIA attributes)
  • Responsive behavior via <ResponsiveContainer> component

More difficult:

  • Larger bundle than Chart.js (~45 KB vs ~11 KB gzipped), though acceptable at this scale
  • If extremely large datasets were needed (10k+ points), Canvas rendering would be more performant -- but dashboard aggregates will never reach this scale
  • Recharts is a dependency that must be kept up to date (Dependabot handles this)

Clone this wiki locally