---

description: "Cursor rules for Semiotic data visualization library with 30+ chart types, MCP server, and AI-assisted chart generation." globs: */ alwaysApply: false

Semiotic — AI Assistant Guide

Quick Start

• Install: npm install semiotic
• Import: semiotic, semiotic/xy, semiotic/ordinal, semiotic/network, semiotic/geo, semiotic/realtime, semiotic/ai, semiotic/data, semiotic/server
• CLI: npx semiotic-ai [--schema|--compact|--examples|--doctor]
• MCP: npx semiotic-mcp
• Every HOC has a built-in error boundary (never blanks the page) and dev-mode validation warnings

Architecture

• HOC Charts: Simple props, sensible defaults. Stream Frames: Full control.
• Always use HOC charts (ForceDirectedGraph, SankeyDiagram, LineChart, RealtimeLineChart, ChoroplethMap, etc.) unless you need sophisticated control they don't expose. Stream Frames (StreamNetworkFrame, StreamXYFrame, StreamOrdinalFrame, StreamGeoFrame) are low-level escape hatches — they accept raw RealtimeNode/RealtimeEdge wrappers in callbacks, not your data objects directly.
• Every HOC accepts frameProps to pass through. TypeScript strict: true.

Common Props (all HOCs)

title, width (600), height (400), responsiveWidth, responsiveHeight, margin, className, enableHover (true), tooltip (boolean | (datum) => ReactNode | config object), showLegend, showGrid (false), frameProps, onObservation (callback, see below), chartId, loading (false), emptyContent, legendInteraction ("none"|"highlight"|"isolate"), legendPosition ("right"|"left"|"top"|"bottom", default "right"), emphasis ("primary"|"secondary")

tooltip

tooltip accepts: true (default tooltip), false (disabled), a function (datum: Record<string, any>) => ReactNode, or a config { fields?: string[], title?: accessor, format?: fn, style?: CSSProperties }. The function form receives your raw data object directly.

onObservation

onObservation receives a ChartObservation with type and event-specific fields:

• hover: { type: "hover", datum: <your data>, x, y, timestamp, chartType, chartId }
• hover-end: { type: "hover-end", timestamp, chartType, chartId }
• click: { type: "click", datum: <your data>, x, y, timestamp, chartType, chartId }
• brush: { type: "brush", extent: { x: [min, max], y: [min, max] }, timestamp, chartType }
• selection: { type: "selection", selection: { name, fields }, timestamp, chartType }

The datum field contains your original data object (not a wrapper).

XY Charts (semiotic/xy)

LineChart — data, xAccessor ("x"), yAccessor ("y"), lineBy, lineDataAccessor ("coordinates"), colorBy, colorScheme, curve, lineWidth (2), showPoints, pointRadius (3), fillArea, areaOpacity (0.3), anomaly (AnomalyConfig), forecast (ForecastConfig), directLabel (boolean|{position,fontSize}), gapStrategy ("break"|"interpolate"|"zero"), xScaleType ("linear"|"log"), yScaleType ("linear"|"log")

AreaChart — LineChart props + areaBy, y0Accessor (band/ribbon), gradientFill (boolean|{topOpacity,bottomOpacity}), areaOpacity (0.7), showLine (true)

StackedAreaChart — flat array data + areaBy (required, groups into stacked areas), colorBy, normalize (false). Do NOT use lineBy or lineDataAccessor — those are LineChart props.

Scatterplot — data, xAccessor, yAccessor, colorBy, sizeBy, sizeRange, pointRadius (5), pointOpacity (0.8), marginalGraphics

BubbleChart — Scatterplot + sizeBy (required), sizeRange ([5,40]), bubbleOpacity (0.6)

ConnectedScatterplot — data, xAccessor, yAccessor, orderAccessor (number|Date field for sequencing), pointRadius (4). Viridis colored start→end, line width = point radius, white halo under lines when <100 points.

QuadrantChart — Scatterplot divided into four labeled, colored quadrants. data, xAccessor, yAccessor, quadrants (required: { topRight, topLeft, bottomRight, bottomLeft } each with label, color, optional opacity), xCenter (vertical center line in data units), yCenter (horizontal center line), centerlineStyle ({ stroke, strokeWidth, strokeDasharray }), showQuadrantLabels (true), quadrantLabelSize (12), colorBy, sizeBy, sizeRange, pointRadius (5), pointOpacity (0.8). Supports push API. Quadrant fills and labels drawn via canvasPreRenderers.

Heatmap — data, xAccessor, yAccessor, valueAccessor, colorScheme ("blues"|"reds"|"greens"|"viridis" or custom), showValues, cellBorderColor. Accessors can be string field names (including string/categorical fields) or functions.

Ordinal Charts (semiotic/ordinal)

BarChart — data, categoryAccessor, valueAccessor, orientation, colorBy, sort, barPadding (40) StackedBarChart — + stackBy (required), normalize, barPadding (40) GroupedBarChart — + groupBy (required), barPadding (60) SwarmPlot — data, categoryAccessor, valueAccessor, colorBy, sizeBy, pointRadius, pointOpacity BoxPlot — + showOutliers, outlierRadius Histogram — + bins (25), relative. Always horizontal. categoryAccessor is optional (defaults to "category") — for a single-group histogram, either omit it or ensure your data has a category field with a single value. ViolinPlot — + bins, curve, showIQR DotPlot — + sort (true), dotRadius, showGrid default true PieChart — data, categoryAccessor, valueAccessor, colorBy, startAngle, slicePadding DonutChart — PieChart + innerRadius (60), centerContent (ReactNode — any React element, e.g. <div>50%</div>)

Network Charts (semiotic/network)

ForceDirectedGraph — nodes, edges, nodeIDAccessor, sourceAccessor, targetAccessor, colorBy, colorScheme, nodeSize (number|string|fn), nodeSizeRange, edgeWidth, edgeColor, edgeOpacity, iterations (300), forceStrength (0.1), showLabels, nodeLabel, tooltip, showLegend, legendInteraction SankeyDiagram — edges, nodes, valueAccessor, edgeColorBy, orientation, nodeAlign, nodeWidth, showLabels, edgeOpacity ChordDiagram — edges, nodes, valueAccessor, edgeColorBy, padAngle, groupWidth, showLabels TreeDiagram — data (root), layout, orientation, childrenAccessor, colorBy, colorByDepth, edgeStyle Treemap — data (root), childrenAccessor, valueAccessor, colorBy, colorByDepth, showLabels, labelMode CirclePack — data (root), childrenAccessor, valueAccessor, colorBy, colorByDepth, circleOpacity OrbitDiagram — animated radial/orbital hierarchy. Use this (not TreeDiagram) when you want animated orbiting nodes. data (root), childrenAccessor, nodeIdAccessor, orbitMode ("flat"|"solar"|"atomic"|number[]), speed (0.25), revolution, eccentricity, orbitSize, nodeRadius, showRings, showLabels, animated (true), colorBy, colorByDepth, annotations (widget annotations anchor by nodeId). For static radial trees, use TreeDiagram layout="radial" instead.

Geo Charts (semiotic/geo)

Geographic visualization with d3-geo projections. Canvas-rendered via StreamGeoFrame. Import from semiotic/geo to avoid adding d3-geo to non-geo bundles.

ChoroplethMap — areas (GeoJSON Feature[] or reference string like "world-110m"), valueAccessor, colorScheme ("blues"|"reds"|"greens"|"viridis"), areaOpacity (1), projection ("equalEarth"), graticule, tooltip, showLegend ProportionalSymbolMap — points, xAccessor ("lon"), yAccessor ("lat"), sizeBy, sizeRange ([3,30]), colorBy, areas (optional background), projection FlowMap — flows ({source, target, value}), nodes, xAccessor, yAccessor, nodeIdAccessor ("id"), valueAccessor ("value"), edgeColorBy, edgeOpacity (0.6), edgeWidthRange ([1,8]), edgeLinecap ("round"), lineType ("geo"|"line"), areas (optional background), showParticles, particleStyle ({ radius, color, opacity, speedMultiplier, maxPerLine, spawnRate }). Particle color accepts a string, "source" (inherit line stroke), or (datum) => string. DistanceCartogram — points, center (id of center node), costAccessor, strength (0-1), lineMode ("straight"|"fractional"), nodeIdAccessor ("id"), lines, projection, showRings (true|false|number[]), ringStyle ({ stroke, strokeWidth, ... }), showNorth (true), costLabel (string for ring labels), transition (ms for smooth animation), pointRadius

All geo HOCs support: selection, linkedHover, onObservation, showLegend, legendInteraction, tooltip, loading, emptyContent, frameProps, fitPadding (0–1 fraction, insets auto-fit projection from edges), zoomable (defaults true with tileURL, false otherwise), zoomExtent, onZoom, dragRotate, graticule, tileURL, tileAttribution, tileCacheSize

Zoom/Pan: All geo charts accept zoomable (boolean), zoomExtent ([minZoom, maxZoom], default [1, 8]), and onZoom (callback with { projection, zoom }). Re-renders projection directly on every zoom tick (no CSS transform). Imperative API: ref.current.getZoom(), ref.current.resetZoom().

Geo Particles: FlowMap and StreamGeoFrame support showParticles (boolean) and particleStyle to animate dots flowing along line paths. Uses GeoParticlePool — an object-pool polyline particle system. Particle color accepts: "source" (inherit line stroke), a CSS string, or (datum) => string for per-line color.

Drag Rotate (Globe Spinning): dragRotate (boolean) — when true, drag gestures rotate the projection (globe spinning) instead of panning. Defaults to true for orthographic projection. Scroll-wheel zoom still works normally. Explicitly set dragRotate={false} on orthographic to get standard pan behavior, or dragRotate={true} on other projections to enable rotation. Latitude rotation is clamped to [-90, 90] to prevent flipping.

Tile Maps: All geo charts accept tileURL (string template like "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png" or (z, x, y, dpr) => string), tileAttribution (e.g., "© OpenStreetMap contributors"), tileCacheSize (default 256). Tiles render on a background canvas behind data layers. Mercator projection only — a dev warning is emitted for non-Mercator projections. Tiles update on zoom/pan. Retina support via {r} placeholder or DPR parameter. Production: OpenStreetMap tiles are for development/demo only. For production, use a commercial tile provider (Mapbox, MapTiler, Stadia Maps) with your own API key passed via environment variable (never hard-code keys in client code). Example: tileURL={\https://api.mapbox.com/styles/v1/mapbox/light-v11/tiles/{z}/{x}/{y}?access_token=${process.env.MAPBOX_TOKEN}`}`.

StreamGeoFrame — low-level frame with full control. Props: projection, areas, points, lines, xAccessor, yAccessor, areaStyle, pointStyle, lineStyle, graticule, projectionTransform (distance cartogram config), projectionExtent, enableHover, tooltipContent, zoomable, zoomExtent, onZoom, tileURL, tileAttribution, tileCacheSize, decay, pulse, transition. Push API: ref.current.push(datum), ref.current.pushMany(data), ref.current.clear().

Reference geography: resolveReferenceGeography("world-110m") returns GeoJSON features from Natural Earth data (world-atlas). Supported: "world-110m", "world-50m", "land-110m", "land-50m". All geo HOCs accept areas as GeoJSON.Feature[] or a reference string.

mergeData(features, data, { featureKey, dataKey }) — join external data into GeoJSON features by key field. Supports nested paths (e.g., "properties.iso_a3"). World-atlas uses ISO 3166-1 numeric codes as the id field. Also available from semiotic/data as a general