Semiotic

Semiotic is a React data-visualization library that covers chart types most libraries skip: force-directed network graphs, Sankey and chord diagrams, streaming realtime charts, geographic projections, and statistical summaries, all through the same declarative component API as its LineChart or BarChart. A two-layer design separates simple Chart components (<LineChart data={d} xAccessor="x" yAccessor="y" />) from the underlying Frame components (StreamXYFrame, OrdinalFrame, NetworkFrame) that expose full control over rendering, interaction, and layout via a frameProps escape hatch.

The library is explicitly positioned for AI-assisted development: it ships machine-readable prop schemas (ai/schema.json), an MCP server (npx semiotic-mcp) for tool-based chart rendering, a CLI doctor (semiotic-ai --doctor) for validating component/prop JSON, and a diagnoseConfig/auditData pair that catches both configuration anti-patterns and numeric edge cases (non-finite values, zero-span domains, misleading normalized totals) before they render as broken or deceptive charts. Every chart also ships with a built-in error boundary, dev-mode validation warnings, and accessibility features (canvas aria-label, keyboard-navigable legends, aria-live tooltips) so generated code fails with actionable diagnostics rather than a blank screen.

What You Get

• Broad chart coverage beyond standard bar/line/pie: force-directed graphs, Sankey and chord diagrams, treemaps, circle packing, choropleth and flow maps, box/violin/swarm plots, ranking charts (BumpChart), and canvas-rendered realtime streaming charts
• LinkedCharts for coordinated dashboards — hover cross-highlighting, brush cross-filtering, and selection synchronization across any combination of chart types via shared selection state
• An AI-tooling surface (semiotic/ai, ai/schema.json, npx semiotic-mcp, semiotic-ai --doctor) with machine-readable prop schemas so LLM-generated chart code validates without trial and error, backed by a production MCP server verified end to end against the official MCP Registry entry
• diagnoseConfig and auditData — programmatic anti-pattern and numeric-preflight checks (invalid log inputs, zero-span domains, misleading normalized totals) that surface as ChartContainer notifications
• Serialization and interop helpers (toConfig, fromConfig, toURL, fromVegaLite, configToJSX) for round-tripping chart state through URLs, notebooks, or AI-generated specs
• Built-in accessibility across every chart: keyboard-navigable legends, aria-live tooltips, SVG <title>/<desc>, reduced-motion/forced-colors paths, and WCAG-derived contrast tests for shipped theme presets

Common Use Cases

• Coordinated analytics dashboards where hovering one chart cross-highlights linked data in another via LinkedCharts
• Realtime monitoring dashboards that push streaming metrics onto canvas-rendered charts at 60fps with decay/staleness encoding
• Network and flow visualization — org charts, dependency graphs, budget flows via Sankey, or airport-route flow maps with animated particles
• AI-assisted dashboard generation, where an LLM coding assistant uses ai/schema.json and the MCP server to generate valid chart props on the first try
• Geographic and choropleth reporting with d3-geo projections, zoom/pan, and tile basemaps for regional data
• Ranking-over-time visualization with BumpChart, connecting each series’ rank across x-columns with optional magnitude-encoded ribbon width

Under The Hood

Architecture Semiotic layers simple Chart components (LineChart, BarChart, Scatterplot, BumpChart in src/components/charts/xy/, ordinal/, etc.) on top of lower-level Frame components (StreamXYFrame, OrdinalFrame, NetworkFrame in src/components/stream/ and src/components/) that own layout, scales, and interaction; every Chart accepts a frameProps prop that passes straight through to its underlying Frame, so the abstraction never blocks access to the full API. Cross-chart coordination (LinkedCharts) is implemented via a shared selection-state store rather than prop-drilling, letting hover/brush/selection events propagate between arbitrarily different chart types. The ai/ directory is a parallel surface — a schema-backed capability catalog, an MCP server (ai/dist/mcp-server.js), and a CLI (ai/cli.js) — that ships alongside the rendering library rather than being bolted on separately, with a generated surface-manifest.json tracking the entry-point inventory and request/response and cancellation limits enforced directly in the MCP transport layer.

Tech Stack The library is TypeScript-first with peer dependencies on react/react-dom (^18.1.0 || ^19.0.0), and direct dependencies on granular d3 modules (d3-array, d3-force, d3-geo, d3-hierarchy, d3-scale, d3-shape, d3-zoom, etc.) plus topojson-client for geographic data, rather than the full d3 bundle. Optional peer dependencies (@dimforge/rapier2d-compat, matter-js, roughjs, world-atlas) are pulled in only for specific features (physics-based layouts, hand-drawn rendering style, world map data), keeping the core install lean. Multiple build outputs are published per subpath (./xy, ./network, ./geo, ./realtime, ./server, ./ai, etc.), each with its own minified/ESM/CJS/type-declaration variant, built and validated via Vite/vitest and Playwright for visual regression, with an explicit note that the semiotic/ai codegen surface trades bundle size for tooling convenience versus the leaner family subpaths.

Code Quality The repo carries roughly 479 test files (.test./.spec. suffixed) alongside ~1,251 TypeScript source files under src/, including component-level unit tests, capability-declaration files (*.capability.ts) that pair with the AI schema layer, and dedicated integration and visual-regression suites (integration-tests/, Playwright configs) split into a fast-feedback CI job (freshness/size/packed-consumer gates) ahead of the broader coverage and contract suite. Components consistently wrap rendering in a SafeRender/ChartError pattern with validateChartData and warnMissingField for dev-mode diagnostics. A granular CHANGELOG.md tracks not just features but capability-metadata corrections (e.g. tightening which physics HOCs may claim supportsSelection/supportsLinkedHover), indicating tests are used to keep documented behavior honest against actual code paths.

API Design The two-tier Chart/Frame split gives newcomers a low-friction entry point (<LineChart data={d} xAccessor="x" yAccessor="y" />) while preserving an escape hatch to the full Frame API for advanced needs, avoiding the common tradeoff between simple and powerful charting APIs. Prop naming is consistent across chart types (xAccessor/yAccessor/colorBy/selection recur across Scatterplot, BarChart, LineChart, network, and geo components), and the machine-readable ai/schema.json plus diagnoseConfig/auditData anti-pattern detectors are a distinctive DX investment — turning what would normally be silent prop-shape errors or misleading charts into actionable, typo-aware diagnostics at both build time and runtime.