nteract/semiotic: a React chart library built for AI-assisted development

The problem semiotic targets: charts that an agent can generate and then check

Most React charting libraries assume a human reads the docs and writes the component. Semiotic assumes a model writes the first draft. The README frames the workflow as generating, checking and repairing chart configurations, and the package description calls it "Verified generative visualization for React and agents, with deterministic chart validation, repair, rendering evidence, and MCP." That is a different contract from a typical chart library, where the failure mode of bad generated code is a blank screen or a silently wrong axis.

Who it is for: React and TypeScript teams that already use coding assistants and want chart output they can validate mechanically. It is also for teams that need network graphs, streaming canvases or coordinated views without assembling three separate dependencies, since the same prop API covers LineChart and force-directed graphs. It is not aimed at someone who wants a single bar chart and nothing else. The README says so directly: check the project's existing dependencies first, because extending its current charting library may be the best fit for a small change.

How the AI surface works: schema, catalog, MCP server and two validators

The mechanism is a set of machine-readable artifacts shipped alongside the runtime components. `ai/schema.json` holds prop schemas for every component. `semiotic/ai` is a single import exposing a schema-backed capability catalog covering XY, ordinal, network, realtime, geo, value and portable recipes; the README points at `ai/surface-manifest.json` as the generated current inventory. `AGENTS.md` carries repository workflow, `CLAUDE.md` imports it, and `ai/reference.md` is kept out of always-loaded agent context on purpose.

The checking layer is where the design gets specific. `diagnoseConfig(component, props)` is a programmatic anti-pattern detector spanning validation, encoding, accessibility and misleading-design checks. `auditData(component, props, data?)` is a 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. It returns bounded row evidence and feeds into `diagnoseConfig`, Chart Clinic, the CLI doctor and opt-in `ChartContainer` notifications. That split matters. Schema validation catches a misspelled prop; auditData catches a log scale fed a zero.

For tool-based rendering, `npx semiotic-mcp` starts an MCP server declared in package.json as the `semiotic-mcp` binary pointing at `ai/dist/mcp-server.js`. The whole surface exists so an agent can render, inspect evidence and repair rather than guess. The README is explicit that the July 27, 2026 evaluation reports model- and task-specific results and does not guarantee first-try correctness, so treat the diagnostics as the product, not the generation.

Installing semiotic and rendering a first chart

The package is published on npm as `semiotic`. The README does not spell out an install command, but the package name and the `npx` invocations for its binaries are in package.json, so the standard npm install applies. Install it, then import a component from the root entry.

npm install semiotic

The root export maps to `dist/semiotic.module.min.js` for ESM and `dist/semiotic.min.js` for CommonJS, with types at `dist/semiotic.d.ts`. For a first check of a configuration without writing React, the CLI doctor validates component plus props JSON from the command line, with typo suggestions and anti-pattern detection:

npx semiotic-ai --doctor

For an agent-driven workflow, start the MCP server instead. It is declared as the `semiotic-mcp` binary and runs from `ai/dist/mcp-server.js`:

npx semiotic-mcp

In application code, import from a family subpath rather than the root. The README is blunt about why: the published entry files are pre-bundled, so importing one chart from `semiotic/ai` still ships most of the bundle. Family subpaths such as `semiotic/xy`, `semiotic/geo` and `semiotic/value` cost roughly half the single-chart cost, and package.json exposes `./xy`, `./line`, `./ordinal` and `./atlas` alongside the root `.` entry. What you should see after installing is a typed component you can render, and a CLI that reports anti-patterns for a props object before it reaches the browser.

The bundle trade-off you have to design around

The most concrete limitation is packaging, and the README states it rather than hiding it. The published entry files are pre-bundled, so a single chart imported from `semiotic/ai` still ships most of the bundle. The recommended workaround is to treat `semiotic/ai` as a codegen and tooling surface and to import family subpaths in production code, at roughly half the single-chart cost. That is a real constraint on how you organise imports, and it means an agent that writes `import { LineChart } from "semiotic/ai"` into a production component has produced working but heavier code than a reviewer might expect.

A second boundary is scope. The accessibility material is careful to say a chart library cannot certify an application's legal compliance, and that scope, content, surrounding controls, testing and national enforcement remain the application owner's responsibility. Semiotic supplies keyboard interaction, accessible data tables, layered descriptions, structured navigation, reduced-motion and forced-colors paths, and WCAG-derived contrast tests for shipped theme presets. It does not supply your compliance argument.

Where it is the wrong tool: a small change to an existing charting setup. The README's own advice is to check existing dependencies first, because extending the current library may fit better. If you need one static chart and no agent in the loop, the schema, MCP server and audit layer are weight you will not use.

How semiotic differs from Recharts and visx

Recharts takes a composable-component approach: you assemble charts from declarative primitives and the library renders SVG, with no schema file, no CLI doctor and no MCP server. visx goes further in the other direction, exposing low-level D3 primitives that you wire together yourself, which buys control at the cost of writing more of the chart. Semiotic sits closer to Recharts in ergonomics, with the same prop API spanning LineChart and network graphs, but it adds an artifact layer neither of those ships: `ai/schema.json`, `diagnoseConfig`, `auditData`, `llms.txt` and an MCP server.

The practical difference is what happens after generation. With a conventional React chart library, an incorrect chart from an assistant is caught by a human reading the code or noticing the picture is wrong. With semiotic, `auditData` is documented to return bounded row evidence for inputs that pass schema validation but break the math, and that evidence flows into the doctor, Chart Clinic and opt-in `ChartContainer` notifications. If you do not use agents, that layer is inert. If you do, it is the reason to pick this over a comparable React chart library.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-15. Releases are frequent and versioned tightly: v3.10.1 on 2026-09-15, v3.9.2 on 2026-09-01, v3.9.1 on 2026-08-20. The 3.10.1 notes describe Network Atlas recipes (Motif Braid, Dependency X-Ray, Flow Circuit) plus reduced repeated layout work: network charts reuse custom layouts when inputs are unchanged, avoid duplicate worker solves, and treat palette and font changes as paint-only updates where possible. That last item is worth reading as an upgrade signal, because it changes when layout recomputation happens rather than only what renders.

Upgrade cost is shaped by the same packaging decision. If production code imports family subpaths and tooling imports `semiotic/ai`, a version bump touches the subpath entries and the schema artifacts together, and the repository keeps `MIGRATION.md` at the top level for that purpose. The licence is Apache-2.0, a permissive licence with an explicit patent grant and attribution requirements; how that interacts with your distribution model is a question for your own counsel, not something this article can settle.

Editorial conclusion

Adopt semiotic when a coding agent needs schema-backed chart generation plus a repair path, or when you need network, streaming and coordinated views under one prop API. Skip it for a static marketing chart where extending an existing charting dependency is cheaper, and skip the root import in production bundles. Verify three things first: that a family subpath such as semiotic/xy covers your chart, that diagnoseConfig and auditData catch the failure modes your data actually hits, and that the accessibility infrastructure satisfies your own assistive-technology testing obligations.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. nteract/semiotic on GitHub
3. Project website
4. README
5. Releases