/web-dataviz-d3

name: web-dataviz-d3
description: D3.js data visualization — selections, data joins, scales, axes, shapes, transitions, force layouts, geo projections, framework integration

D3.js Data Visualization Patterns

> **Quick Guide:** D3 v7 is fully modular ES modules. Use `selection.join()` for the data join (replaces manual enter/update/exit). Prefer modular imports (`d3-selection`, `d3-scale`, etc.) to reduce bundle size. Scales map data domains to visual ranges; axes render tick marks from scales. Shape generators (`d3.line`, `d3.arc`, `d3.area`) produce SVG path strings from data arrays. Transitions animate attribute/style changes with automatic interpolation. For framework integration, let D3 handle data computation (scales, layouts, shapes) and let your framework own the DOM.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use `selection.join()` for data joins — NOT manual enter/append/merge/exit chains)**

**(You MUST use modular imports (`d3-selection`, `d3-scale`, `d3-shape`) — NOT `import * as d3 from "d3"` in production bundles)**

**(You MUST use named constants for ALL visual dimensions, colors, and timing values — NO magic numbers)**

**(You MUST type D3 selections and scales with TypeScript generics — `Selection<SVGGElement, Datum, ...>`, `ScaleLinear<number, number>`)**

</critical_requirements>

---

**Auto-detection:** D3, d3, d3.js, d3-selection, d3-scale, d3-shape, d3-axis, d3-transition, d3-force, d3-geo, d3-zoom, d3-brush, d3-drag, d3-array, selection.join, data join, enter update exit, scaleLinear, scaleBand, scaleTime, axisBottom, axisLeft, forceSimulation, geoPath, geoMercator, line generator, arc generator, SVG visualization, data-driven documents

**When to use:**

• Building custom SVG/Canvas data visualizations from scratch
• Bindings between data arrays and DOM elements (the data join)
• Mapping data domains to pixel ranges (scales and axes)
• Generating SVG paths from data (lines, arcs, areas, pies)
• Animating data transitions with interpolated attributes
• Force-directed graph layouts and geographic map projections
• Adding zoom, brush, and drag interactions to visualizations

**When NOT to use:**

• Standard chart types (bar, line, pie) with minimal customization — use a charting library built on D3
• Dashboards with many chart widgets — use a higher-level charting library
• Simple data tables or non-graphical data display

**Key patterns covered:**

• Selections and the data join (`selection.data().join()`)
• Scales (linear, band, time, ordinal) and axes
• Shape generators (line, area, arc, pie, stack)
• Transitions and animated updates
• Force-directed graph layouts
• Geographic projections and choropleth maps
• Zoom, brush, and drag interactions
• Framework integration: D3 for math, framework for DOM
• Responsive SVG with viewBox
• TypeScript typing for D3

---

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Selections, data joins, scales, axes, shapes, responsive SVG
• [examples/interaction.md](examples/interaction.md) - Transitions, zoom, brush, drag, tooltips
• [examples/advanced.md](examples/advanced.md) - Force layouts, geo projections, framework integration patterns
• [reference.md](reference.md) - Module reference, decision frameworks, anti-patterns

---

<philosophy>

Philosophy

D3 is a low-level visualization grammar, not a charting library. It provides primitives for binding data to DOM elements and applying data-driven transformations. This gives maximum control at the cost of more code than higher-level alternatives.

**Core mental model:**

1. **Select** elements (existing or placeholder) 2. **Bind** data to selections with `.data()` 3. **Join** to create/update/remove elements with `.join()` 4. **Encode** data as visual attributes with scales 5. **Annotate** with axes, labels, legends 6. **Animate** changes with transitions

**D3 v7 key decisions:**

• Pure ES modules — use modular imports for tree-shaking
• `selection.join()` replaces manual enter/update/exit boilerplate
• TypeScript types ship with each module (no `@types/d3` needed for core packages, but available for convenience)
• Works with any framework — D3 handles computation, your framework handles DOM rendering

**When NOT to use D3 directly:**

• Standard charts with minimal customization (use a charting library)
• Rapid prototyping where development speed matters more than customization
• Teams without SVG/visualization experience

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Selections and the Data Join

The data join is D3's core pattern: bind an array of data to DOM elements, then use `.join()` to create, update, and remove elements as data changes.

import { select } from "d3-selection";

const BAR_HEIGHT = 30;
const BAR_GAP = 5;

// Select, bind data, join
select(svgElement)
  .selectAll<SVGRectElement, number>("rect")
  .data(values, (d) => String(d))                   // key function for identity
  .join("rect")                                       // enter + update merged
    .attr("y", (_, i) => i * (BAR_HEIGHT + BAR_GAP))
    .attr("width", (d) => xScale(d))
    .attr("height", BAR_HEIGHT);

**Why good:** `join("rect")` handles enter/update/exit in one call, key function ensures correct element-data binding across updates, typed selection generics

For advanced join with separate enter/update/exit callbacks, see [examples/core.md](examples/core.md) Pattern 1.

---

Pattern 2: Scales — Mapping Data to Pixels

Scales are functions that map an input domain (data values) to an output range (pixel positions, colors).

import { scaleLinear, scaleBand, scaleTime, scaleOrdinal } from "d3-scale";

const CHART_WIDTH = 600;
const CHART_HEIGHT = 400;

// Continuous: numbers -> pixels
const x = scaleLinear<number>()
  .domain(