semiotic

[![MCP Toplist](https://mcptoplist.com/badge/io.github.nteract%2Fsemiotic.svg)](https://mcptoplist.com/server/io.github.nteract%2Fsemiotic)

[![Semiotic](semiotic_logo_horizontal.png "semiotic")](https://semiotic.nteract.io)

[![CI](https://github.com/nteract/semiotic/actions/workflows/node.js.yml/badge.svg?branch=main)](https://github.com/nteract/semiotic/actions/workflows/node.js.yml)
[![npm version](https://img.shields.io/npm/v/semiotic.svg)](https://www.npmjs.com/package/semiotic)
[![TypeScript](https://img.shields.io/badge/TypeScript-built--in-blue.svg)](https://www.typescriptlang.org/)
[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/nteract-semiotic-badge.png)](https://mseep.ai/app/nteract-semiotic)

[![MCP Queen operational grade](https://mcpqueen.com/badge/io.github.nteract/semiotic.svg)](https://mcpqueen.com/s/io.github.nteract/semiotic)

A React data visualization library designed for AI-assisted development.

Start with a small chart component. Add network graphs, streaming data and
coordinated views when the task needs them. Structured schemas, diagnostics
and rendering evidence help coding assistants implement, check and repair
chart configurations.

Work through a complete task: [check category totals](https://semiotic.nteract.io/tasks/compare-category-totals),
[maintain a live chart](https://semiotic.nteract.io/tasks/update-live-chart), or
[correct a published chart](https://semiotic.nteract.io/tasks/correct-published-chart).
The [source task packets](ai/task-packets/index.json) identify their build and
evidence scope; source availability does not establish installed or deployed parity.

<!-- semiotic-readme-dashboard:start -->
<img src="./docs/public/assets/img/semiotic-release-dashboard.svg" alt="Semiotic release dashboard showing chart count, bundle sizes, capability coverage, chart families, and documentation growth" width="100%">
<!-- semiotic-readme-dashboard:end -->

## What's New in 3.10.2

3.10.2 improves realtime aggregation, stream chart recommendations, server
rendering, and line labels.

- Stream recommendations cover ordinal and value charts, with audience-aware
  dashboard layouts and explanations for excluded candidates.
- Realtime charts support keyed changelogs, percentile and distinct-count
  aggregates, per-series line aggregation, and more controlled-data SSR paths.
- Event-time queues, incremental aggregates, and smaller validation imports
  reduce repeated work and bundle overhead.
- LineChart direct labels share measured placement across browser and server
  rendering; keyed path transitions preserve point identity during updates.

Stream suggestion callers should now destructure the result:
`const { suggestions } = suggestStreamCharts(...)`.

See [the changelog](CHANGELOG.md#3102---2026-09-18) for details.

## Why Semiotic

Semiotic is a data visualization library for React that combines broad chart
coverage with AI tooling. It supports network graphs, streaming data,
statistical distributions and coordinated views, with schemas, examples and
diagnostics for implementing and checking each task. Check the project's
existing dependencies first: extending its current charting library may be
the best fit for a small change.

### Built for AI-assisted development

Semiotic provides a workflow for generating, checking and repairing chart
configurations. The [July 27, 2026 evaluation](evals/reports/openai-gpt-5.6-2026-07-27/README.md)
reports model- and task-specific results; it does not guarantee first-try correctness.

- **`semiotic/ai`** — a single import with the schema-backed chart capability catalog (XY, ordinal, network, realtime, geo, value, and portable recipes), optimized for LLM code generation. See `ai/surface-manifest.json` for the generated current inventory. Note: the published entry files are pre-bundled, so importing one chart from `semiotic/ai` still ships most of the bundle — treat it as a codegen/tooling surface and use family subpaths (`semiotic/xy`, `semiotic/geo`, `semiotic/value`, …) in production code, at roughly half the single-chart cost.
- **`ai/schema.json`** — machine-readable prop schemas for every component
- **`npx semiotic-mcp`** — an MCP server for tool-based chart rendering in any MCP client
- **`npx semiotic-ai --doctor`** — validate component + props JSON from the command line with typo suggestions and anti-pattern detection
- **`diagnoseConfig(component, props)`** — programmatic anti-pattern detector with actionable fixes, spanning validation, encoding, accessibility, and misleading-design (deception) checks
- **`auditData(component, props, data?)`** — chart-aware numeric preflight for inputs that pass schema validation but break the math: non-finite values, zero-span domains, invalid log inputs, negative size geometry, unsafe normalized totals, and scale-dominating outliers. Returns bounded row evidence and flows into `diagnoseConfig`, Chart Clinic, CLI doctor, and opt-in `ChartContainer` notifications
- **`AGENTS.md`** — concise repository workflow shared by modern coding agents;
  `CLAUDE.md` imports it and Copilot receives a short compatibility bridge
- **`ai/reference.md`** — complete on-demand product reference, kept out of
  always-loaded coding-agent context
- **`llms.txt`** — machine-readable documentation following the emerging standard

Every chart includes a built-in error boundary, dev-mode validation
warnings with typo suggestions, and accessibility features (canvas
`aria-label`, keyboard-navigable legends, `aria-live` tooltips, SVG
`<title>`/`<desc>`) so AI-generated code fails gracefully with
actionable diagnostics instead of a blank screen.

### Accessibility is a release surface

The [European Accessibility Act](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=legissum%3A4403933)
has applied to covered products and services since 28 June 2025. A chart
library cannot certify an application's legal compliance: scope, content,
surrounding controls, testing, and national enforcement remain the
application owner's responsibility. Semiotic supplies testable infrastructure
for that work: keyboard interaction, accessible data tables, layered
descriptions, structured navigation, reduced-motion and forced-colors paths,
and WCAG-derived contrast tests for shipped theme presets. See the
[Accessibility docs](https://semiotic.nteract.io/accessibility/overview) and
run the application's own assistive-technology and user testing.

### Beyond standard charts

**Network visualization.** Force-directed graphs, Sankey diagrams, chord
diagrams, tree layouts, treemaps, circle packing, and orbit diagrams — all
as React components with the same prop API as LineChart.

**Streaming data.** Realtime charts render on canvas at 60fps with a
ref-based push API. Rapid network edge pushes coalesce into one layout per
animation frame, while read/mutation methods preserve synchronous read-after-write
semantics. Built-in decay, pulse, and staleness encoding for monitoring dashboards.

**Coordinated views.** `LinkedCharts` provides hover cross-highlighting,
brush cross-filtering, coordinate-based linked crosshairs, and selection
synchronization across any combination of chart types through shared selection state.

**Geographic visualization.** Choropleth maps, proportional symbol maps, flow
maps with animated particles, and distance cartograms — all canvas-rendered
with d3-geo projections, zoom/pan, tile basemaps, and drag-rotate globe spinning.

**Statistical summaries.** Box plots, violin plots, swarm plots, histograms,
LOESS smoothing, forecast with confidence envelopes, and anomaly detection.
Marginal distribution graphics on scatterplot axes with a single prop.

**First-class annotations.** Annotations are data-bound objects, not post-hoc
artwork. Labels, callouts, thresholds, enclosures, statistical overlays, and
React widgets move with the chart and render through browser, SSR, and export
paths. Opt into placement, hierarchy, density, progressive disclosure,
audience-aware amount, provenance, and editorial lifecycle when the chart
needs to communicate more than its encoding alone.

### Choose the API layer

| Layer | For | Example |
|---|---|---|
| **Charts** | Common chart forms with chart-level props | `<LineChart data={d} xAccessor="x" yAccessor="y" />` |
| **Frames** | Full control over rendering, interaction, and layout | `<StreamXYFrame chartType="line" lineStyle={...} />` |

Chart HOCs register only the mark plugins they need. Direct `StreamXYFrame`
loads the remaining built-ins on first client paint. Call
`registerBuiltInXYPlugins()` from `semiotic/xy` or `semiotic/realtime/core`
before the first render when SSR or the first frame must include marks.

Every Chart component accepts a `frameProps` prop to access the underlying
Frame API without leaving the simpler interface.

### Serialization and interop

Charts serialize to JSON and back: `toConfig`, `fromConfig`, `toURL`,
`copyConfig`, `configToJSX`. Have Vega-Lite specs? `fromVegaLite(spec)`
translates them to Semiotic configs — works with `configToJSX()` for
full round-trip from notebooks and AI-generated specs.

Need an external pitfall review? The experimental `unstable_toDataPitfallsChain()` builds a
dependency-free chain input for [`datapitfalls`](https://github.com/bjonesdataliteracy/datapitfalls),
combining the Semiotic config, JSX, reader grounding, diagnostics,
accessibility audit, and optional rendered SVG/image evidence:

```ts
import { unstable_toDataPitfallsChain } from "semiotic/experimental"
import { detectPitfalls } from "datapitfalls"

const input = unstable_toDataPitfallsChain("LineChart", props, {
  narrative: "Monthly sales are accelerating.",
  rendered: { svg, evidence },
})

const report = await detectPitfalls(input, { apiKey: process.env.ANTHROPIC_API_KEY })
```

The return path stays dependency-free too. Use whole-chart findings as
`ChartContainer` notifications, and only turn findings into annotations after
your app can anchor them to marks or seman