Skip to content
Back to search

semiotic

React data visualization library for streaming, networks, and AI-assisted development

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/nteract/semiotic with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/nteract/semiotic'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nteract--semiotic/badge.svg)](/listings/nteract--semiotic)

HTML

<a href="/listings/nteract--semiotic"><img src="/api/listings/nteract--semiotic/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install semiotic

Requires React 18.1+ or React 19.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,017 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. [![MCP Toplist](https://mcptoplist.com/badge/io.github.nteract%2Fsemiotic.svg)](https://mcptoplist.com/server/io.github.nteract%2Fsemiotic)
  2. [![Semiotic](semiotic_logo_horizontal.png "semiotic")](https://semiotic.nteract.io)
  3. [![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)
  4. [![npm version](https://img.shields.io/npm/v/semiotic.svg)](https://www.npmjs.com/package/semiotic)
  5. [![TypeScript](https://img.shields.io/badge/TypeScript-built--in-blue.svg)](https://www.typescriptlang.org/)
  6. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/nteract-semiotic-badge.png)](https://mseep.ai/app/nteract-semiotic)
  7. [![MCP Queen operational grade](https://mcpqueen.com/badge/io.github.nteract/semiotic.svg)](https://mcpqueen.com/s/io.github.nteract/semiotic)
  8. A React data visualization library designed for AI-assisted development and streaming data.
  9. ## Install
  10. ```bash
  11. npm install semiotic
  12. ```
  13. Requires React 18.1+ or React 19.
  14. ## First Chart
  15. ```jsx
  16. import { LineChart } from "semiotic/xy"
  17. const signups = [
  18. { week: 1, signups: 120 },
  19. { week: 2, signups: 180 },
  20. { week: 3, signups: 150 },
  21. { week: 4, signups: 240 },
  22. { week: 5, signups: 310 },
  23. ]
  24. export default function SignupsChart() {
  25. return (
  26. <LineChart
  27. data={signups}
  28. xAccessor="week"
  29. yAccessor="signups"
  30. xLabel="Week"
  31. yLabel="Signups"
  32. title="Weekly signups"
  33. />
  34. )
  35. }
  36. ```
  37. `xAccessor` and `yAccessor` name the fields to plot, and `title` gives the
  38. chart its accessible name. `LineChart` needs numeric x values (numbers or
  39. timestamps); for named categories such as month names, use `BarChart` with
  40. `categoryAccessor`. More complete examples follow under
  41. [Quick Examples](#quick-examples).
  42. Start with a small chart component. Add network graphs, streaming data and
  43. coordinated views when the task needs them. Structured schemas, diagnostics
  44. and rendering evidence help coding assistants implement, check and repair
  45. chart configurations.
  46. Work through a complete task: [check category totals](https://semiotic.nteract.io/tasks/compare-category-totals),
  47. [maintain a live chart](https://semiotic.nteract.io/tasks/update-live-chart), or
  48. [correct a published chart](https://semiotic.nteract.io/tasks/correct-published-chart).
  49. The [source task packets](ai/task-packets/index.json) identify their build and
  50. evidence scope; source availability does not establish installed or deployed parity.
  51. <!-- semiotic-readme-dashboard:start -->
  52. <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%">
  53. <!-- semiotic-readme-dashboard:end -->
  54. ## Quick Examples
  55. Each example is a complete component. Examples that use one chart family
  56. import from that family's entry; the coordination examples import from
  57. `semiotic`, which exports `LinkedCharts` and `ChartContainer` alongside the
  58. charts.
  59. ### Standard Charts
  60. Line, bar, scatter, and area charts share the same accessor-driven API:
  61. ```jsx
  62. import { LineChart } from "semiotic/xy"
  63. import { BarChart } from "semiotic/ordinal"
  64. const revenue = [
  65. { month: 1, revenue: 4200 },
  66. { month: 2, revenue: 5100 },
  67. { month: 3, revenue: 6800 },
  68. { month: 4, revenue: 5900 },
  69. ]
  70. const departments = [
  71. { department: "Design", region: "East", sales: 12 },
  72. { department: "Sales", region: "West", sales: 30 },
  73. { department: "Support", region: "East", sales: 18 },
  74. ]
  75. export function StandardCharts() {
  76. return (
  77. <>
  78. <LineChart
  79. data={revenue}
  80. xAccessor="month" yAccessor="revenue"
  81. curve="monotoneX" showPoints
  82. title="Monthly revenue"
  83. />
  84. <BarChart
  85. data={departments}
  86. categoryAccessor="department" valueAccessor="sales"
  87. orientation="horizontal" colorBy="region"
  88. title="Sales by department"
  89. />
  90. </>
  91. )
  92. }
  93. ```
  94. ### Coordinated Dashboard
  95. Hover one chart and highlight the same data in another through a shared selection:
  96. ```jsx
  97. import { LinkedCharts, Scatterplot, BarChart } from "semiotic"
  98. const people = [
  99. { age: 31, income: 52, region: "East" },
  100. { age: 44, income: 78, region: "West" },
  101. { age: 38, income: 61, region: "East" },
  102. { age: 52, income: 90, region: "West" },
  103. ]
  104. const totals = [
  105. { region: "East", total: 113 },
  106. { region: "West", total: 168 },
  107. ]
  108. export function RegionDashboard() {
  109. return (
  110. <LinkedCharts>
  111. <Scatterplot
  112. data={people} xAccessor="age" yAccessor="income" colorBy="region"
  113. linkedHover={{ name: "hl", fields: ["region"] }}
  114. selection={{ name: "hl" }}
  115. title="Income by age"
  116. />
  117. <BarChart
  118. data={totals} categoryAccessor="region" valueAccessor="total"
  119. selection={{ name: "hl" }}
  120. title="Total income by region"
  121. />
  122. </LinkedCharts>
  123. )
  124. }
  125. ```
  126. ### Streaming Metrics with Decay
  127. Live data fades old points, flashes new ones, flags stale feeds. Omit `data`
  128. and push through a ref from an effect, an event handler, or a socket callback:
  129. ```jsx
  130. import { useEffect, useRef } from "react"
  131. import { RealtimeLineChart } from "semiotic/realtime"
  132. export function CpuMonitor() {
  133. const chartRef = useRef(null)
  134. useEffect(() => {
  135. // Replace the timer with your metrics source.
  136. const timer = setInterval(() => {
  137. chartRef.current?.push({ time: Date.now(), value: 40 + Math.random() * 20 })
  138. }, 250)
  139. return () => clearInterval(timer)
  140. }, [])
  141. return (
  142. <RealtimeLineChart
  143. ref={chartRef}
  144. timeAccessor="time"
  145. valueAccessor="value"
  146. decay={{ type: "exponential", halfLife: 100 }}
  147. staleness={{ threshold: 5000, showBadge: true }}
  148. title="CPU load"
  149. />
  150. )
  151. }
  152. ```
  153. ### Network Graphs
  154. Force-directed graphs and Sankey diagrams — same API as LineChart:
  155. ```jsx
  156. import { ForceDirectedGraph, SankeyDiagram } from "semiotic/network"
  157. const people = [
  158. { id: "Ada", team: "Platform" },
  159. { id: "Lin", team: "Design" },
  160. { id: "Sam", team: "Platform" },
  161. ]
  162. const friendships = [
  163. { source: "Ada", target: "Lin" },
  164. { source: "Lin", target: "Sam" },
  165. ]
  166. const budgetFlows = [
  167. { from: "Budget", to: "Design", amount: 40 },
  168. { from: "Budget", to: "Engineering", amount: 60 },
  169. { from: "Engineering", to: "Platform", amount: 35 },
  170. ]
  171. export function Networks() {
  172. return (
  173. <>
  174. <ForceDirectedGraph
  175. nodes={people} edges={friendships}
  176. colorBy="team" nodeSize={8} showLabels
  177. title="Who works with whom"
  178. />
  179. <SankeyDiagram
  180. edges={budgetFlows}
  181. sourceAccessor="from" targetAccessor="to" valueAccessor="amount"
  182. title="Where the budget goes"
  183. />
  184. </>
  185. )
  186. }
  187. ```
  188. ### Geographic Visualization
  189. Choropleth maps, flow maps, and distance cartograms with canvas rendering,
  190. zoom/pan, tile basemaps, and animated particles. This example joins your rows
  191. to the bundled `world-110m` geography, which needs the optional `world-atlas`
  192. peer dependency (`npm install world-atlas`):
  193. ```jsx
  194. import { useEffect, useState } from "react"
  195. import { ChoroplethMap, mergeData, resolveReferenceGeography } from "semiotic/geo"
  196. const gdpByCountry = [
  197. { country: "United States of America", gdp: 27.4 },
  198. { country: "China", gdp: 17.8 },
  199. { country: "Germany", gdp: 4.5 },
  200. ]
  201. export function WorldGdpMap() {
  202. const [areas, setAreas] = useState([])
  203. useEffect(() => {
  204. let cancelled = false
  205. resolveReferenceGeography("world-110m").then((world) => {
  206. if (cancelled) return
  207. setAreas(
  208. mergeData(world, gdpByCountry, { featureKey: "properties.name", dataKey: "country" })
  209. )
  210. })
  211. return () => {
  212. cancelled = true
  213. }
  214. }, [])
  215. return (
  216. <ChoroplethMap
  217. areas={areas}
  218. valueAccessor={(feature) => feature.properties.gdp}
  219. colorScheme="viridis" projection="equalEarth" zoomable tooltip
  220. title="GDP by country"
  221. />
  222. )
  223. }
  224. ```
  225. `FlowMap` and `DistanceCartogram` follow the same accessor pattern. In this
  226. sketch `airports`, `routes`, and `cities` stand for your own arrays:
  227. ```jsx
  228. import { FlowMap, DistanceCartogram } from "semiotic/geo"
  229. <FlowMap
  230. nodes={airports} flows={routes} valueAccessor="passengers"
  231. showParticles particleStyle={{ color: "source", speedMultiplier: 1.5 }}
  232. />
  233. <DistanceCartogram
  234. points={cities} center="rome" costAccessor="travelDays"
  235. showRings costLabel="days" lines={routes}
  236. />
  237. ```
  238. ### Streaming System Monitor
  239. Live service topology with threshold alerting and click-to-inspect:
  240. ```jsx
  241. import { useEffect, useRef } from "react"
  242. import { StreamNetworkFrame, ChartContainer, DetailsPanel, LinkedCharts } from "semiotic"
  243. export function SystemMonitor() {
  244. const chartRef = useRef(null)
  245. useEffect(() => {
  246. // Replace the timer with your request stream.
  247. const timer = setInterval(() => {
  248. chartRef.current?.push({ source: "API", target: "Orders", value: 15 })
  249. }, 500)
  250. return () => clearInterval(timer)
  251. }, [])
  252. return (
  253. <LinkedCharts>
  254. <ChartContainer title="System Monitor" status="live"
  255. detailsPanel={
  256. <DetailsPanel position="right" trigger="click">
  257. {(datum) => <div>{datum.id}: {datum.value} req/s</div>}
  258. </DetailsPanel>
  259. }>
  260. <StreamNetworkFrame ref={chartRef} chartType="sankey"
  261. showParticles particleStyle={{ proportionalSpeed: true }}
  262. thresholds={{ metric: n => n.value, warning: 100, critical: 250 }}
  263. />
  264. </ChartContainer>
  265. </LinkedCharts>
  266. )
  267. }
  268. ```
  269. ## All Chart Components
  270. | Category | Components |
  271. |---|---|
  272. | **XY** | `LineChart` `AreaChart` `DifferenceChart` `StackedAreaChart` `BumpChart` `Scatterplot` `ConnectedScatterplot` `BubbleChart` `Heatmap` `QuadrantChart` `MultiAxisLineChart` `MinimapChart` `CandlestickChart` `WaterfallChart` `ScatterplotMatrix` |
  273. | **Categorical** | `BarChart` `StackedBarChart` `GroupedBarChart` `LikertChart` `SwimlaneChart` `FunnelChart` `SwarmPlot` `BoxPlot` `Histogram` `ViolinPlot` `RidgelinePlot` `DotPlot` `PieChart` `DonutChart` `GaugeChart` `RadarChart` |
  274. | **Network** | `ForceDirectedGraph` `ChordDiagram` `SankeyDiagram` `ProcessSankey` `TreeDiagram` `Treemap` `CirclePack` `OrbitDiagram` |
  275. | **Geo** (`semiotic/geo`) | `ChoroplethMap` `ProportionalSymbolMap` `FlowMap` `DistanceCartogram` |
  276. | **Realtime** | `RealtimeLineChart` `RealtimeHistogram` `TemporalHistogram` `RealtimeSwarmChart` `RealtimeWaterfallChart` `RealtimeHeatmap` |
  277. | **Physics** (`semiotic/physics`) | `GaltonBoardChart` `EventDropChart` `UnitPileChart` `CollisionSwarmChart` `GauntletChart` `CrucibleChart` `ProcessFlowChart` `PacketFlowChart` `ChainReactionChart` |
  278. | **Value and text** | `BigNumber` (`semiotic/value`) `WordCloud` (`semiotic/wordcloud`) |
  279. | **Custom layouts** | `XYCustomChart` `OrdinalCustomChart` `NetworkCustomChart` `GeoCustomChart` (`semiotic/geo`) `PhysicsCustomChart` (`semiotic/physics`) |
  280. | **Coordination** | `LinkedCharts` |
  281. | **Layout** | `ChartGrid` `ContextLayout` `CategoryColorProvider` |
  282. | **Frames** | `StreamXYFrame` `StreamOrdinalFrame` `StreamNetworkFrame` `StreamGeoFrame` (`semiotic/geo`) `StreamPhysicsFrame` (`semiotic/physics`) |
  283. ### Vega-Lite Translation
  284. Paste a Vega-Lite spec, get a Semiotic chart:
  285. ```jsx
  286. import { fromVegaLite } from "semiotic/data"
  287. import { configToJSX, fromConfig } from "semiotic"
  288. const config = fromVegaLite({
  289. mark: "bar",
  290. data: { values: [{ a: "A", b: 28 }, { a: "B", b: 55 }] },
  291. encoding: {
  292. x: { field: "a", type: "nominal" },
  293. y: { field: "b", type: "quantitative" },
  294. },
  295. })
  296. // Render directly
  297. const { componentName, props } = fromConfig(config)
  298. // → componentName: "BarChart", props: { data, categoryAccessor: "a", valueAccessor: "b" }
  299. // Or generate JSX code
  300. configToJSX(config)
  301. // → <BarChart data={[...]} categoryAccessor="a" valueAccessor="b" />
  302. ```
  303. Supports bar, line, area, point, rect, arc, tick marks with encoding translation
  304. for color, size, aggregation, and binning.
  305. ### Conversation Arc Telemetry
  306. Capture and replay the path an AI-assisted chart session took:
  307. ```ts
  308. import {
  309. createLocalStorageConversationArcSink,
  310. enableConversationArc,
  311. getConversationArcStore,
  312. loadConversationArc,
  313. registerConversationArcSink,
  314. } from "semiotic/ai"
  315. const sink = createLocalStorageConversationArcSink({ key: "my-app:arc" })
  316. registerConversationArcSink(sink)
  317. enableConversationArc({ sessionId: "session-abc" })
  318. getConversationArcStore().record({ type: "chart-rendered", component: "LineChart" })
  319. loadConversationArc(sink.load(), { enabled: false })
  320. ```
  321. ## What's New in 3.13.3
  322. 3.13.3 improves streaming chart suggestions with field cardinality, additivity,
  323. and schema warnings, and adds count aggregation for realtime histograms.
  324. Streaming charts preserve extents, hover detail, and keyboard focus as data
  325. changes. Pie, donut, and network charts use more of their available space,
  326. with matching server rendering. This release also improves chart error
  327. recovery, legend fitting, heatmap colors, and compositional routing.
  328. See [the changelog](CHANGELOG.md#3133---2026-10-29) for the complete fixes and additions.
  329. ## Why Semiotic
  330. Semiotic is a data visualization library for React that combines broad chart
  331. coverage with AI tooling. It supports network graphs, streaming data,
  332. statistical distributions and coordinated views, with schemas, examples and
  333. diagnostics for implementing and checking each task. Check the project's
  334. existing dependencies first: extending its current charting library may be
  335. the best fit for a small change.
  336. ### Built for AI-assisted development
  337. Semiotic provides a workflow for generating, checking and repairing chart
  338. configurations. The [July 27, 2026 evaluation](evals/reports/openai-gpt-5.6-2026-07-27/README.md)
  339. reports model- and task-specific results; it does not guarantee first-try correctness.
  340. - **`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. Named imports now tree-shake across published chunks. Prefer family subpaths (`semiotic/xy`, `semiotic/geo`, `semiotic/value`, …) in production code to keep the intended chart family explicit; the cold-consumer table below reports initial-load and on-demand costs.
  341. - **`ai/schema.json`** — machine-readable prop schemas for every component
  342. - **`npx -y -p semiotic semiotic-mcp`** — an MCP server for tool-based chart rendering in any MCP client
  343. - **`npx -p semiotic semiotic-ai --doctor`** — validate component + props JSON from the command line with typo suggestions and anti-pattern detection
  344. - **`diagnoseConfig(component, props)`** — programmatic anti-pattern detector with actionable fixes, spanning validation, encoding, accessibility, and misleading-design (deception) checks
  345. - **`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
  346. - **`AGENTS.md`** — concise repository workflow shared by modern coding agents;
  347. `CLAUDE.md` imports it and Copilot receives a short compatibility bridge
  348. - **`ai/reference.md`** — complete on-demand product reference, kept out of
  349. always-loaded coding-agent context
  350. - **`llms.txt`** — machine-readable documentation following the emerging standard
  351. Every chart includes a built-in error boundary, dev-mode validation
  352. warnings with typo suggestions, and accessibility features (canvas
  353. `aria-label`, keyboard-navigable legends, keyboard live-region announcements, SVG
  354. `<title>`/`<desc>`) so AI-generated code fails gracefully with
  355. actionable diagnostics instead of a blank screen.
  356. ### Accessibility is a release surface
  357. The [European Accessibility Act](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=legissum%3A4403933)
  358. has applied to covered products and services since 28 June 2025. A chart
  359. library cannot certify an application's legal compliance: scope, content,
  360. surrounding controls, testing, and national enforcement remain the
  361. application owner's responsibility. Semiotic supplies testable infrastructure
  362. for that work: keyboard interaction, accessible data tables, layered
  363. descriptions, structured navigation, reduced-motion and forced-colors paths,
  364. and WCAG-derived contrast tests for shipped theme presets. See the
  365. [Accessibility docs](https://semiotic.nteract.io/accessibility/overview) and
  366. run the application's own assistive-technology and user testing.
  367. ### Beyond standard charts
  368. **Network visualization.** Force-directed graphs, Sankey diagrams, chord
  369. diagrams, tree layouts, treemaps, circle packing, and orbit diagrams — all
  370. as React components with the same prop API as LineChart.
  371. **Streaming data.** Realtime charts render on canvas at 60fps with a
  372. ref-based push API. Rapid network edge pushes coalesce into one layout per
  373. animation frame, while read/mutation methods preserve synchronous read-after-write
  374. semantics. Built-in decay, pulse, and staleness encoding for monitoring dashboards.
  375. **Coordinated views.** `LinkedCharts` provides hover cross-highlighting,
  376. brush cross-filtering, coordinate-based linked crosshairs, and selection
  377. synchronization across any combination of chart types through shared selection state.
  378. **Geographic visualization.** Choropleth maps, proportional symbol maps, flow
  379. maps with animated particles, and distance cartograms — all canvas-rendered
  380. with d3-geo projections, zoom/pan, tile basemaps, and drag-rotate globe spinning.
  381. **Statistical summaries.** Box plots, violin plots, swarm plots, histograms,
  382. LOESS smoothing, forecast with confidence envelopes, and anomaly detection.
  383. Marginal distribution graphics on scatterplot axes with a single prop.
  384. **First-class annotations.** Annotations are data-bound objects, not post-hoc
  385. artwork. Labels, callouts, thresholds, enclosures, statistical overlays, and
  386. React widgets move with the chart and render through browser, SSR, and export
  387. paths. Opt into placement, hierarchy, density, progressive disclosure,
  388. audience-aware amount, provenance, and editorial lifecycle when the chart
  389. needs to communicate more than its encoding alone.
  390. ### Choose the API layer
  391. | Layer | For | Example |
  392. |---|---|---|
  393. | **Charts** | Common chart forms with chart-level props | `<LineChart data={d} xAccessor="x" yAccessor="y" />` |
  394. | **Frames** | Full control over rendering, interaction, and layout | `<StreamXYFrame chartType="line" lineStyle={...} />` |
  395. Chart HOCs register only the mark plugins they need. Direct `StreamXYFrame`
  396. loads the remaining built-ins on first client paint. Call
  397. `registerBuiltInXYPlugins()` from `semiotic/xy` or `semiotic/realtime/core`
  398. before the first render when SSR or the first frame must include marks.
  399. Every Chart component accepts a `frameProps` prop to access the underlying
  400. Frame API without leaving the simpler interface.
  401. ### Serialization and interop
  402. Charts serialize to JSON and back: `toConfig`, `fromConfig`, `toURL`,
  403. `copyConfig`, `configToJSX`. Have Vega-Lite specs? `fromVegaLite(spec)`
  404. translates them to Semiotic configs — works with `configToJSX()` for
  405. full round-trip from notebooks and AI-generated specs.
  406. Need an external pitfall review? The experimental `unstable_toDataPitfallsChain()` builds a
  407. dependency-free chain input for [`datapitfalls`](https://github.com/bjonesdataliteracy/datapitfalls),
  408. combining the Semiotic config, JSX, reader grounding, diagnostics,
  409. accessibility audit, and optional rendered SVG/image evidence:
  410. ```ts
  411. import { unstable_toDataPitfallsChain } from "semiotic/experimental"
  412. import { detectPitfalls } from "datapitfalls"
  413. const input = unstable_toDataPitfallsChain("LineChart", props, {
  414. narrative: "Monthly sales are accelerating.",
  415. rendered: { svg, evidence },
  416. })
  417. const report = await detectPitfalls(input, { apiKey: process.env.ANTHROPIC_API_KEY })
  418. ```
  419. The return path stays dependency-free too. Use whole-chart findings as
  420. `ChartContainer` notifications, and only turn findings into annotations after
  421. your app can anchor them to marks or semantic positions:
  422. ```tsx
  423. import { ChartContainer } from "semiotic"
  424. import { LineChart } from "semiotic/xy"
  425. import {
  426. unstable_toDataPitfallsAnnotations,
  427. unstable_toDataPitfallsNotifications,
  428. } from "semiotic/experimental"
  429. const notifications = unstable_toDataPitfallsNotifications(report)
  430. const annotations = unstable_toDataPitfallsAnnotations(report, {
  431. anchorFor: (finding) =>
  432. finding.ruleId === "truncated-axis" ? { x: 9, y: 9000 } : null,
  433. })
  434. <ChartContainer notifications={notifications}>
  435. <LineChart {...props} annotations={annotations} />
  436. </ChartContainer>
  437. ```
  438. ### When to use something else
  439. Need a standard bar or line chart for a dashboard you'll never need to
  440. customize beyond colors and labels? [Recharts](https://recharts.org) has a
  441. larger ecosystem and more community examples. Need GPU-accelerated rendering
  442. for millions of data points? [Apache ECharts](https://echarts.apache.org)
  443. handles that scale.
  444. Semiotic is for projects that outgrow those libraries — when you need
  445. network graphs alongside time series, streaming data alongside static
  446. snapshots, or coordinated views across chart types.
  447. ## Bundle Sizes
  448. Semiotic ships 42 stable JavaScript entry points (41 subpaths plus the root). **Don't import from `"semiotic"` unless you need everything** — use the smallest sub-path that matches your charts or tooling.
  449. Custom network layouts can opt into a virtual zoom/pan viewport through `semiotic/network/zoom`. It exports `ZoomableNetworkCustomChart` and projected-size/LOD hooks; ordinary chart imports exclude its gesture and LOD runtime.
  450. The numbers below are **first-party artifact cost**: the gzip size of Semiotic's own code for each sub-path. They exclude React and other runtime dependencies, and each row counts every chunk the entry can reach, including code loaded only on demand, so they are not a prediction of a cold application bundle. Do not add artifact rows to estimate an app: dependency resolution and cross-import deduplication happen in the consumer bundler and are measured separately below.
  451. <!-- semiotic-bundle-sizes:start -->
  452. <!-- Auto-generated by `scripts/sync-bundle-sizes.mjs`. Edit dist/*, not this block. -->
  453. | Entry Point | gzip | What's inside |
  454. |---|---|---|
  455. | `semiotic/atlas` | **330 KB** | Motif Braid, Dependency Forest, and Flow Circuit readers |
  456. | `semiotic/atlas/core` | **15 KB** | Network Atlas preparation, projections, and evidence queries |
  457. | `semiotic/access` | **32 KB** | Chart Access Contract factory and first-wave baseline contracts |
  458. | `semiotic/evidence` | **49 KB** | Chart Evidence Envelope, deterministic hashing, and publication gate |
  459. | `semiotic/artifact` | **128 KB** | Renderer-independent contracts, claims, time, policy, grounding, and transfer audits |
  460. | `semiotic/artifact/react` | **4 KB** | Accessible progressive disclosure for artifact contracts and policy evaluations |
  461. | `semiotic/line` | **156 KB** | LineChart only — one-chart micro boundary |
  462. | `semiotic/xy` | **195 KB** | LineChart, AreaChart, Scatterplot, Heatmap, + 8 more XY charts |
  463. | `semiotic/ordinal` | **142 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
  464. | `semiotic/network` | **188 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
  465. | `semiotic/network/zoom` | **198 KB** | Optional virtual network viewport, camera controls and consumer-owned LOD |
  466. | `semiotic/network/perspective` | **2 KB** | Isometric pictograms and an accessible perspective toggle (the prop ships in ./network) |
  467. | `semiotic/network/perspective/core` | **3 KB** | Projection sizing, resolution, and SVG placement helpers |
  468. | `semiotic/vite` | **1 KB** | Build plugin for unused Semiotic worker assets |
  469. | `semiotic/geo` | **117 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
  470. | `semiotic/wordcloud` | **131 KB** | WordCloud, shaped text placement, and portable layouts |
  471. | `semiotic/realtime` | **231 KB** | RealtimeLineChart, RealtimeHistogram, + 4 streaming charts |
  472. | `semiotic/realtime/core` | **230 KB** | Streaming chart types, HOCs, and buffer helpers |
  473. | `semiotic/realtime/react` | **7 KB** | Stream status and synced push hooks |
  474. | `semiotic/server` | **290 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
  475. | `semiotic/server/node` | **290 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
  476. | `semiotic/server/edge` | **296 KB** | renderChart, renderChartWithEvidence, renderToStaticSVG, renderDashboard |
  477. | `semiotic/utils` | **115 KB** | ThemeProvider, numeric/accessibility audits, serialization — no chart components |
  478. | `semiotic/utils/core` | **106 KB** | Pure theme helpers, numeric/accessibility audits, and serialization |
  479. | `semiotic/utils/react` | **9 KB** | ThemeProvider, useTheme, useReducedMotion, useHighContrast, useStreamStatus |
  480. | `semiotic/recipes` | **119 KB** | Pure layout functions (waffle, marimekko, flextree, dagre, …) |
  481. | `semiotic/recipes/core` | **116 KB** | Pure layout functions (waffle, marimekko, flextree, dagre, …) |
  482. | `semiotic/recipes/react` | **3 KB** | Glyph and React layout-selection helpers |
  483. | `semiotic/themes` | **13 KB** | Theme presets only (tufte, carbon, etc.) |
  484. | `semiotic/themes/core` | **13 KB** | Theme presets and token helpers |
  485. | `semiotic/themes/react` | **9 KB** | ThemeProvider/useTheme and hooks |
  486. | `semiotic/data` | **5 KB** | bin, rollup, groupBy, pivot, fromVegaLite |
  487. | `semiotic/value` | **6 KB** | BigNumber — focal-value KPI / scorecard (SingleValueFrame POC) |
  488. | `semiotic/physics` | **192 KB** | GaltonBoardChart, EventDropChart, UnitPileChart, CollisionSwarmChart, PacketFlowChart, PhysicsCustomChart |
  489. | `semiotic/physics/matter` | **1 KB** | Matter.js migration helpers + optional peer guard (no chart components) |
  490. | `semiotic/physics/rapier` | **1 KB** | Rapier peer guard + adapter decision metadata (no chart components) |
  491. | `semiotic/ai` | **710 KB** | All schema-backed charts + validation — optimized for LLM code generation |
  492. | `semiotic/ai/core` | **151 KB** | suggestCharts, auditData, describeChart, repairChartConfig, tool adapters — no chart components |
  493. | `semiotic/controls` | **19 KB** | DirectManipulationControl, CircularBrush, LinearBrush, MobileStandardControls, auditVisualizationControls — no frame renderer |
  494. | `semiotic/rough` | **3 KB** | Optional deterministic Rough.js paint backend — exact Semiotic geometry remains authoritative |
  495. | `semiotic/text` | **2 KB** | Optional Pretext annotation hook — peer package excluded |
  496. | `semiotic` | **451 KB** | Full chart API and shared utilities |
  497. <!-- semiotic-bundle-sizes:end -->
  498. ### Cold-consumer named imports
  499. The table above is **first-party artifact cost**, not an application bundle. The generated table
  500. below measures a different thing: a fresh consumer bundles one retained named import from a packed
  501. `semiotic` tarball through the public export path, with code splitting as an application build does.
  502. **Initial load** is what a page downloads before the chart renders; **on demand** is code fetched
  503. only when a feature needs it. It includes Semiotic and its resolved runtime dependencies,
  504. but externalizes React/React DOM and optional adapter peers that the host application owns. Each row
  505. starts cold, so use it to compare one public import choice—not to add together an application's rows.
  506. The checked machine-readable baseline is `benchmarks/setup/cold-consumer-imports.json`; refresh it
  507. after a production build with `npm run docs:cold-consumer`.
  508. <!-- semiotic-cold-consumer:start -->
  509. <!-- Auto-generated by `scripts/measure-cold-consumer.mjs`. Do not edit by hand. -->
  510. Method: fresh `npm pack --ignore-scripts` tarball → temporary consumer → minified/tree-shaken Rolldown (Vite's bundler) ESM build with code splitting and a production `NODE_ENV` → gzip -9 per file. **Initial load** counts the entry and its statically imported chunks; **on demand** counts chunks fetched only when a feature needs them (brushing, marginal graphics, animated transitions, a bare frame's built-in layouts). **Everything** is the same build with code splitting disabled: the ceiling if every optional feature loads. React/React DOM and optional adapter peers are external; Semiotic and its resolved runtime dependencies are included. The committed baseline also records a single-file esbuild build of each row.
  511. | Public named import | Runtime | gzip initial load | gzip on demand | gzip everything |
  512. |---|---:|---:|---:|---:|
  513. | `import { semioticVite } from "semiotic/vite"` | node | **0.6 KiB** | — | 0.6 KiB |
  514. | `import { getNetworkPerspectiveSize } from "semiotic/network/perspective/core"` | browser | **1.1 KiB** | — | 1.1 KiB |
  515. | `import { MotifBraidChart } from "semiotic/atlas"` | browser | **112.6 KiB** | 30.4 KiB | 139.4 KiB |
  516. | `import { prepareNetworkAtlas } from "semiotic/atlas/core"` | browser | **7.1 KiB** | — | 7.1 KiB |
  517. | `import { LineChart } from "semiotic"` | browser | **126.7 KiB** | 44.4 KiB | 154.4 KiB |
  518. | `import { LineChart } from "semiotic/xy"` | browser | **126.4 KiB** | 32.5 KiB | 154.4 KiB |
  519. | `import { LineChart } from "semiotic/line"` | browser | **126.3 KiB** | 32.6 KiB | 154.0 KiB |
  520. | `import { BarChart } from "semiotic/ordinal"` | browser | **107.2 KiB** | 14.7 KiB | 122.0 KiB |
  521. | `import { SankeyDiagram } from "semiotic/network"` | browser | **122.4 KiB** | 23.3 KiB | 141.0 KiB |
  522. | `import { ZoomableNetworkCustomChart } from "semiotic/network/zoom"` | browser | **115.9 KiB** | 30.3 KiB | 142.5 KiB |
  523. | `import { isometricGlyphs } from "semiotic/network/perspective"` | browser | **1.4 KiB** | — | 1.4 KiB |
  524. | `import { RealtimeLineChart } from "semiotic/realtime"` | browser | **126.7 KiB** | 43.2 KiB | 154.2 KiB |
  525. | `import { RingBuffer } from "semiotic/realtime/core"` | browser | **0.7 KiB** | 13.5 KiB | 0.7 KiB |
  526. | `import { useStreamStatus } from "semiotic/realtime/react"` | browser | **0.8 KiB** | — | 0.8 KiB |
  527. | `import { GaltonBoardChart } from "semiotic/physics"` | browser | **97.0 KiB** | 2.7 KiB | 99.4 KiB |
  528. | `import { MATTER_PHYSICS_CAPABILITIES } from "semiotic/physics/matter"` | browser | **0.1 KiB** | — | 0.1 KiB |
  529. | `import { RAPIER_PHYSICS_CAPABILITIES } from "semiotic/physics/rapier"` | browser | **0.2 KiB** | — | 0.2 KiB |
  530. | `import { renderChart } from "semiotic/server"` | node | **310.1 KiB** | — | 310.1 KiB |
  531. | `import { generateFrameSVGs } from "semiotic/server/edge"` | node | **128.7 KiB** | — | 128.7 KiB |
  532. | `import { renderToImage } from "semiotic/server/node"` | node | **310.5 KiB** | 0.6 KiB | 311.1 KiB |
  533. | `import { suggestCharts } from "semiotic/ai"` | browser | **32.7 KiB** | 13.5 KiB | 33.9 KiB |
  534. | `import { suggestCharts } from "semiotic/ai/core"` | browser | **32.4 KiB** | — | 32.4 KiB |
  535. | `import { buildArtifactContract } from "semiotic/artifact"` | browser | **4.5 KiB** | — | 4.5 KiB |
  536. | `import { ArtifactInspector } from "semiotic/artifact/react"` | browser | **3.7 KiB** | — | 3.7 KiB |
  537. | `import { createChartAccessContract } from "semiotic/access"` | browser | **29.3 KiB** | — | 29.3 KiB |
  538. | `import { toEvidenceEnvelope } from "semiotic/evidence"` | browser | **44.8 KiB** | — | 44.8 KiB |
  539. | `import { bin } from "semiotic/data"` | browser | **0.9 KiB** | — | 0.9 KiB |
  540. | `import { ChoroplethMap } from "semiotic/geo"` | browser | **109.7 KiB** | 1.7 KiB | 110.6 KiB |
  541. | `import { WordCloud } from "semiotic/wordcloud"` | browser | **111.0 KiB** | 39.9 KiB | 145.8 KiB |
  542. | `import { usePretextAnnotations } from "semiotic/text"` | browser | **1.5 KiB** | — | 1.5 KiB |
  543. | `import { createRoughRenderMode } from "semiotic/rough"` | browser | **3.1 KiB** | — | 3.1 KiB |
  544. | `import { resolveThemePreset } from "semiotic/themes"` | browser | **2.6 KiB** | — | 2.6 KiB |
  545. | `import { resolveThemePreset } from "semiotic/themes/core"` | browser | **2.6 KiB** | — | 2.6 KiB |
  546. | `import { ThemeProvider } from "semiotic/themes/react"` | browser | **5.7 KiB** | — | 5.7 KiB |
  547. | `import { validateProps } from "semiotic/utils"` | browser | **11.4 KiB** | — | 11.4 KiB |
  548. | `import { smartTickFormat } from "semiotic/utils/core"` | browser | **1.0 KiB** | — | 1.0 KiB |
  549. | `import { useReducedMotion } from "semiotic/utils/react"` | browser | **0.3 KiB** | — | 0.3 KiB |
  550. | `import { waffleLayout } from "semiotic/recipes"` | browser | **1.6 KiB** | — | 1.6 KiB |
  551. | `import { waffleLayout } from "semiotic/recipes/core"` | browser | **1.6 KiB** | — | 1.6 KiB |
  552. | `import { Glyph } from "semiotic/recipes/react"` | browser | **0.8 KiB** | — | 0.8 KiB |
  553. | `import { BigNumber } from "semiotic/value"` | browser | **5.9 KiB** | — | 5.9 KiB |
  554. | `import { DirectManipulationControl } from "semiotic/controls"` | browser | **1.5 KiB** | — | 1.5 KiB |
  555. **Line-boundary interpretation:** the retained named import from `semiotic/line` emits 373.4 KiB raw versus 373.4 KiB from `semiotic/xy`; gzip differs by 0.1 KiB (0.1%). Tree-shaking converges both paths on the same LineChart implementation graph. Treat `semiotic/line` as a narrower API/direct-ESM artifact boundary, not an application-bundle saving. Do not add another per-chart entry until its packed named import beats the family path by both 10 KiB gzip and 7%.
  556. <!-- semiotic-cold-consumer:end -->
  557. **d3 packaging model:** Semiotic externalizes the twelve d3 modules it imports
  558. and declares them as normal runtime dependencies. Consumers do not need to
  559. install d3 packages manually; their bundler resolves, deduplicates, and
  560. tree-shakes that dependency graph. A packed webpack comparison favored this
  561. model in three of four representative chart families, and a Next 16 webpack
  562. route was 22.7 KiB gzip smaller than the fully bundled alternative. The one
  563. bundled win, Sankey, was only 0.4 KiB gzip. This choice retains a 22-package,
  564. 1.9 MB unpacked d3 install closure in exchange for smaller common application
  565. graphs and an ordinary dependency contract. The checked policy is
  566. `npm run check:d3-packaging`; the reproducible evidence is in
  567. `benchmarks/setup/d3-packaging.json` and can be regenerated with
  568. `npm run measure:d3-packaging -- --toolchain-root <dir>` after installing
  569. webpack and Next in that isolated toolchain directory.
  570. ```jsx
  571. // Import from the sub-path, not from "semiotic"
  572. import { LineChart } from "semiotic/xy"
  573. import { BarChart } from "semiotic/ordinal"
  574. import { SankeyDiagram } from "semiotic/network"
  575. import { ChoroplethMap } from "semiotic/geo"
  576. ```
  577. **Tree-shaking & multi-subpath imports**: Family entries (`semiotic/xy`, `semiotic/network`, `semiotic/ai`, …) are built as one ESM graph with **shared chunks**. Stream frames, renderers, and other common code ship once and are imported by every entry that needs them — so combining `semiotic/ai` + `semiotic/xy` + `semiotic/network` does **not** mean paying for three full copies of the runtime. The package is marked `"sideEffects": false`, so modern bundlers keep only the named exports you retain (e.g. `LineChart` + `suggestCharts`). Prefer family subpaths for clarity; import AI helpers from `semiotic/ai` or the lighter `semiotic/ai/core` when you do not need the chart catalog.
  578. **When to use `"semiotic"`**: Fine when you want one import for mixed families. Shared chunks prevent duplicated runtime code across family subpaths; the cold-consumer table above is the better guide for a single named import.
  579. **CommonJS compatibility note:** `require("semiotic/xy")` loads the shared
  580. CommonJS client bundle (about 2.1 MB before compression) so React contexts stay
  581. singletons across family imports. Prefer ESM imports in browser builds when
  582. bundle size matters; splitting that CJS client without a context-identity
  583. contract would be unsafe.
  584. ## TypeScript
  585. Built with `strict: true`. Full type definitions ship with the package.
  586. Generics for type-safe accessors:
  587. ```tsx
  588. interface Sale { month: number; revenue: number }
  589. <LineChart<Sale>
  590. data={sales}
  591. xAccessor="month" // TS validates this is keyof Sale
  592. yAccessor="revenue"
  593. />
  594. ```
  595. ## Server-Side Rendering
  596. All chart components render SVG automatically in server environments — no
  597. special imports or configuration needed. Non-streaming chart HOCs can be
  598. imported and rendered directly from a Next.js Server Component: Semiotic's
  599. `"use client"` directive defines the package boundary, so the importing page
  600. does not need its own wrapper or directive. Props crossing that boundary must
  601. remain serializable; add an app-owned client wrapper only when you introduce
  602. hooks, callback props, browser state, or a push-driven streaming chart.
  603. ```jsx
  604. // app/dashboard/page.tsx — a Next.js Server Component
  605. import { LineChart } from "semiotic/xy"
  606. // Server: renders <svg> with path/circle/rect elements
  607. // Client: renders <canvas> with SVG overlay for axes
  608. export default async function DashboardPage() {
  609. const data = await fetchMetrics()
  610. return <LineChart data={data} xAccessor="date" yAccessor="value" />
  611. }
  612. ```
  613. For standalone SVG/PNG/GIF generation (email, OG images, PDF, Slack), use the server entry point:
  614. ```js
  615. import { renderChart, renderToImage, renderToAnimatedGif } from "semiotic/server"
  616. // SVG — sync, no dependencies
  617. const svg = renderChart("LineChart", {
  618. data, xAccessor: "date", yAccessor: "value",
  619. theme: "tufte", title: "Revenue Trend",
  620. })
  621. // PNG — async, requires sharp
  622. const png = await renderToImage("BarChart", { data, ... }, { format: "png", scale: 2 })
  623. // Animated GIF — async, requires sharp + gifenc
  624. const gif = await renderToAnimatedGif("line", data, { ... }, { fps: 12 })
  625. ```
  626. ## MCP Server
  627. mcp-name: io.github.nteract/semiotic
  628. Semiotic ships with an [MCP server](https://modelcontextprotocol.io) that lets AI coding assistants render charts, diagnose configuration problems, discover schemas, read packaged AI guidance, and get chart recommendations via tool calls.
  629. ### Setup
  630. Add to your MCP client config (e.g. `claude_desktop_config.json` for Claude Desktop):
  631. ```json
  632. {
  633. "mcpServers": {
  634. "semiotic": {
  635. "command": "npx",
  636. "args": ["-y", "-p", "semiotic", "semiotic-mcp"]
  637. }
  638. }
  639. }
  640. ```
  641. No API keys or authentication required for local stdio. HTTP mode is also available for inspectors, web clients, and ChatGPT Apps SDK experiments: `npx -y -p semiotic semiotic-mcp --http --port 3001`. It binds to `127.0.0.1` by default and accepts only its bind hostname (plus `localhost` for loopback). Browser requests require an explicit origin allowlist, for example `MCP_ALLOWED_ORIGINS=http://localhost:5173`; otherwise any request carrying `Origin` is rejected with 403. Native MCP clients that omit `Origin` continue to work. Since 3.7.2, HTTP mode is stateless: each request gets a fresh read-only MCP server + transport, so it can autoscale on serverless hosts without sticky sessions.
  642. For ChatGPT developer mode, expose the HTTP endpoint over HTTPS with a tunnel, set `MCP_ALLOWED_HOSTS` to the tunnel hostname, and create a connector that points at `https://<your-tunnel>/mcp`. For a public interface, explicitly use `--host 0.0.0.0` or `MCP_HOST=0.0.0.0` and configure `MCP_ALLOWED_HOSTS` with the served hostnames. An all-interface bind still permits only loopback Host values until configured. Both allowlists are comma-separated and checked before preflight, health, or MCP handling. CORS echoes only an explicitly allowed origin; wildcard origins are unsupported. Set `MCP_AUTH_TOKEN` when transport requests should require a bearer token. The experimental Apps SDK surface is `renderInteractiveChart`, which returns a `text/html;profile=mcp-app` widget template plus a hidden SVG payload rendered by Semiotic on the MCP server.
  643. For a hosted deployment, see `deploy/cloud-run`. The wrapper runs the published `semiotic-mcp`
  644. binary, exposes `/mcp` plus health endpoints, and supports `MCP_ALLOWED_HOSTS` for production
  645. host-header allowlisting. For ChatGPT Apps domain verification, set
  646. `OPENAI_APPS_CHALLENGE_TOKEN` so HTTP mode serves the raw token from
  647. `/.well-known/openai-apps-challenge`.
  648. Use `--profile=public` for the five-tool public surface; separated option values
  649. also work. Explicit invalid profiles or malformed options stop startup. Both
  650. profiles and transports cap complete tool responses at 2 MiB by default through
  651. `MCP_MAX_TOOL_OUTPUT_BYTES`, returning an explicit error for oversized results.
  652. ### Tools
  653. | Tool | Description |
  654. |------|-------------|
  655. | **`renderChart`** | Render a Semiotic chart to static SVG. Supports the components returned by `getSchema` that are marked `[renderable]`. Pass `{ component: "LineChart", props: { data: [...], xAccessor: "x", yAccessor: "y" } }`. Returns SVG string plus a "Render evidence" JSON block (mark counts by scene type, resolved axis domains, empty flag, annotation count, accessible name) so agents can verify the chart drew data marks, or validation errors with fix suggestions. |
  656. | **`renderInteractiveChart`** | Render a static-data chart as a ChatGPT Apps widget. Uses the same Semiotic server render path as `renderChart`, then hydrates an iframe UI with fit, zoom, data, hover, and render-evidence controls. |
  657. | **`getSchema`** | Return the prop schema for a specific component. Pass `{ component: "LineChart" }` to get its props, or omit `component` to list the complete schema-backed catalog. Components marked `[renderable]` are available through `renderChart`; realtime charts require a browser/live environment. |
  658. | **`suggestChart`** | Sample-row recommender. Pass `{ data: [{...}, ...] }` with 1–5 sample objects plus optional broad intent/capability filters. |
  659. | **`suggestCharts`** | Capability-based recommender for bounded row data. Returns ranked chart suggestions with scores, reasons, caveats, import paths, and ready-to-use props. |
  660. | **`suggestStreamCharts`** | Recommend streaming charts from a schema (shape, keys, throughput, field cardinality/additivity). Returns `{ suggestions, excluded, stretchSuggestions, rankingIntents, warnings }`. |
  661. | **`suggestStreamDashboard`** | Compose a multi-panel dashboard from stream schemas and an audience layout policy. |
  662. | **`suggestDashboard`** | Build a multi-panel dashboard suggestion that covers distinct analytical intents. |
  663. | **`suggestStretchCharts`** | Recommend audience-literacy stretch picks from an `AudienceProfile`. |
  664. | **`repairChartConfig`** | Check whether a requested chart fits a dataset and return ranked alternatives when it does not. |
  665. | **`interrogateChart`** | Return a statistical summary and chart-aware context for answering natural-language questions with optional annotations. |
  666. | **`diagnoseConfig`** | Check a chart configuration for common problems — empty data, bad dimensions, missing accessors, wrong data shape, and more. Returns a human-readable diagnostic report with actionable fixes. |
  667. | **`reportIssue`** | Generate a pre-filled GitHub issue URL for bug reports or feature requests. Pass `{ title: "...", body: "...", labels: ["bug"] }`. Returns a URL the user can open to submit. |
  668. | **`applyTheme`** | List named theme presets or return ThemeProvider/CSS/token usage for a preset such as `{ name: "tufte" }`. |
  669. | **`auditArtifact`** | Evaluate an explicit artifact contract under a named policy without inferring missing source, review, or timing facts. |
  670. | **`recommendRepresentation`** | Compare chart and non-chart outcomes against supplied data, claims, evidence, time state, and policy requirements. |
  671. | **`repairArtifact`** | Propose contract repairs and optionally fill missing identity fields; existing mismatches require a revision and claim reassessment. |
  672. | **`explainRefusal`** | Explain which explicit policy obligations prevent publication or action and identify safe follow-up work. |
  673. Artifact tools are opt-in diagnostics, not publication authorization. A
  674. `conditional` result (including CLI exit code 0) retains open work. Ordinary
  675. `renderChart` calls do not enforce artifact policy; governed hosts must enforce
  676. their own release boundary. Manual-check resolution and revision-bound release
  677. approval remain separate host workflow work.
  678. ### Resources
  679. | Resource | Description |
  680. |----------|-------------|
  681. | **`semiotic://artifact-contract-schema`** | Standalone JSON Schema for portable purpose, claim, evidence, timing, review, and transfer metadata. |
  682. | **`semiotic://schema`** | Full machine-readable component schema JSON. |
  683. | **`semiotic://schema-index`** | Compact discovery index with categories, renderability, import paths, and each component's schema resource URI. |
  684. | **`semiotic://schema/{component}`** | One component's schema, metadata, accessibility guidance, and behavior contracts (for example `semiotic://schema/LineChart`). |
  685. | **`semiotic://components`** | Backward-compatible component index showing renderable/browser-only status and MCP categories. |
  686. | **`semiotic://surface-manifest`** | Generated inventory of the current AI schema, exports, renderability, tools, resources, and prompts. |
  687. | **`semiotic://behavior-contracts`** | Agent-visible semantic rules for color precedence, required prop combinations, push refs, and renderability. |
  688. | **`semiotic://system-prompt`** | Compact AI instructions with import rules, chart props, SSR guidance, and pitfalls. |
  689. | **`semiotic://examples`** | Copy-paste chart examples by data shape. |
  690. | **`ui://semiotic/chart-widget.html`** | ChatGPT Apps / MCP Apps widget template used by `renderInteractiveChart`. |
  691. ### Prompts
  692. | Prompt | Description |
  693. |--------|-------------|
  694. | **`build-semiotic-chart`** | Reusable workflow for choosing a chart, reading schema, diagnosing props, and rendering a preview. |
  695. | **`debug-semiotic-chart`** | Reusable workflow for debugging invalid props, rendering failures, and issue reports. |
  696. ### Example: get schema for a component
  697. ```
  698. Tool: getSchema
  699. Args: { "component": "LineChart" }
  700. → Returns: { "name": "LineChart", "description": "...", "parameters": { "properties": { "data": ..., "xAccessor": ..., ... } } }
  701. ```
  702. ### Example: suggest a chart for your data
  703. ```
  704. Tool: suggestChart
  705. Args: {
  706. "data": [
  707. { "month": "Jan", "revenue": 120, "region": "East" },
  708. { "month": "Feb", "revenue": 180, "region": "West" }
  709. ]
  710. }
  711. → Returns:
  712. 1. BarChart (high confidence) — categorical field (region) with values (revenue)
  713. 2. StackedBarChart (medium confidence) — two categorical fields (month, region)
  714. 3. DonutChart (medium confidence) — 2 categories — proportional composition
  715. ```
  716. ### Example: render a chart
  717. ```
  718. Tool: renderChart
  719. Args: {
  720. "component": "BarChart",
  721. "props": {
  722. "data": [
  723. { "category": "Q1", "revenue": 120 },
  724. { "category": "Q2", "revenue": 180 },
  725. { "category": "Q3", "revenue": 150 }
  726. ],
  727. "categoryAccessor": "category",
  728. "valueAccessor": "revenue"
  729. }
  730. }
  731. → Returns: <svg>...</svg>
  732. ```
  733. ### Example: render a ChatGPT Apps widget
  734. ```
  735. Tool: renderInteractiveChart
  736. Args: {
  737. "component": "BarChart",
  738. "props": {
  739. "title": "Revenue by Quarter",
  740. "data": [
  741. { "quarter": "Q1", "revenue": 120 },
  742. { "quarter": "Q2", "revenue": 180 }
  743. ],
  744. "categoryAccessor": "quarter",
  745. "valueAccessor": "revenue"
  746. }
  747. }
  748. → Returns: structured chart summary for the model + hidden SVG/widget metadata for ChatGPT.
  749. ```
  750. Widget SVG is rebuilt from an element, attribute, CSS, and URL allowlist before
  751. embedding. Local fragment references and inline base64 PNG/JPEG/GIF/WebP images
  752. are supported; external resources, SVG data URLs, scripts, foreign HTML,
  753. animation, CSS imports, and font-face rules are removed. Allowed styles are
  754. scoped to the chart, preserving automatic dark palettes and annotation
  755. disclosure. Theme variables use color, length, font, and other supported token
  756. grammars. Malformed SVG returns an explicit tool error instead of an empty
  757. successful preview. The widget's host CSP provides an additional boundary.
  758. ### Example: diagnose a broken config
  759. ```
  760. Tool: diagnoseConfig
  761. Args: { "component": "LineChart", "props": { "data": [] } }
  762. → Returns: ✗ [EMPTY_DATA] data is an empty array — Fix: provide at least one data point
  763. ```
  764. ### Example: report an issue
  765. ```
  766. Tool: reportIssue
  767. Args: {
  768. "title": "Bug: BarChart tooltip shows undefined for custom accessor",
  769. "body": "When using valueAccessor='amount', tooltip displays 'undefined'.\n\ndiagnoseConfig output: ✓ no issues detected.",
  770. "labels": ["bug"]
  771. }
  772. → Returns: Open this URL to submit the issue: https://github.com/nteract/semiotic/issues/new?...
  773. ```
  774. ### CLI alternative
  775. For quick validation without an MCP client:
  776. ```bash
  777. npx -p semiotic semiotic-ai --list # list components with import paths and renderability
  778. npx -p semiotic semiotic-ai --list --json # machine-readable component index
  779. npx -p semiotic semiotic-ai --schema GaugeChart
  780. npx -p semiotic semiotic-ai --suggest '{"data":[{"category":"A","value":10}],"intent":"comparison"}'
  781. npx -p semiotic semiotic-ai --doctor # validate component + props JSON
  782. npx -p semiotic semiotic-ai --schema # dump all chart schemas
  783. npx -p semiotic semiotic-ai --compact # compact schema (fewer tokens)
  784. ```
  785. `--doctor` uses the full `diagnoseConfig` checks when `dist` is available and falls back to schema-only validation in clean source checkouts.
  786. ## Where to find Semiotic for AI assistants
  787. Semiotic is indexed by AI-coding-agent documentation tools so your assistant (Claude Code, Cursor, Cline, Copilot, etc.) can pull current docs and tools without copy-paste:
  788. - **Context7** — [context7.com/nteract/semiotic](https://context7.com/nteract/semiotic) (configured via `context7.json`)
  789. - **DeepWiki** — [deepwiki.com/nteract/semiotic](https://deepwiki.com/nteract/semiotic)
  790. - **GitMCP** — [gitmcp.io/nteract/semiotic](https://gitmcp.io/nteract/semiotic) (exposes the repo as an MCP endpoint directly)
  791. - **Official MCP Registry** — search "semiotic" at [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io)
  792. The Official MCP Registry is the canonical MCP directory record; it is distinct
  793. from acceptance into any assistant vendor's curated connector directory.
  794. Secondary-directory freshness and release ownership are tracked in
  795. [MCP_DISTRIBUTION.md](https://github.com/nteract/semiotic/blob/main/MCP_DISTRIBUTION.md).
  796. Agent-facing API surface:
  797. - **`AGENTS.md`** is the concise repository development contract and **`CLAUDE.md`** imports it for Claude Code. These stay repository-local rather than shipping irrelevant contributor instructions to package consumers.
  798. - **`ai/reference.md`**, **`ai/schema.json`**, **`ai/surface-manifest.json`**, **`ai/behaviorContracts.cjs`**, and **`agent-skill/semiotic-charts/SKILL.md`** are bundled in the npm tarball (see `package.json#files`). The reference is the on-demand product guide printed by `npx -p semiotic semiotic-ai`; the schema, manifest, contracts, and portable skill provide structured generation and validation guidance.
  799. - [**`semiotic.nteract.io/llms.txt`**](https://semiotic.nteract.io/llms.txt) + [**`/llms-full.txt`**](https://semiotic.nteract.io/llms-full.txt) — deployed at the docs site per the [llms.txt standard](https://llmstxt.org). Agents fetch the navigation map (`llms.txt`) or the full inlined docs (`llms-full.txt`) over HTTP; they're not part of the npm package itself.
  800. ## Documentation
  801. [Interactive docs and examples](https://semiotic.nteract.io)
  802. - [Getting Started](https://semiotic.nteract.io/getting-started)
  803. - [Charts](https://semiotic.nteract.io/charts) — chart types with live examples
  804. - [Frames](https://semiotic.nteract.io/frames) — full Frame API reference
  805. - [Features](https://semiotic.nteract.io/features) — axes, tooltips, interaction, responsive behavior, and composition
  806. - [Annotations](https://semiotic.nteract.io/annotations) — first-class annotation types, design guidance, provenance, and lifecycle
  807. - [Cookbook](https://semiotic.nteract.io/cookbook) — advanced patterns and recipes
  808. - [Playground](https://semiotic.nteract.io/playground) — interactive prop exploration
  809. ## Upgrading
  810. - [Migration Guide](./MIGRATION.md) — upgrading from v1.x or v2.x
  811. - [Changelog](./CHANGELOG.md) — full release history
  812. ## Contributing
  813. See [CONTRIBUTING.md](CONTRIBUTING.md). Our community follows the nteract
  814. [Code of Conduct](https://github.com/nteract/nteract/blob/main/CODE_OF_CONDUCT.md).
  815. ## Acknowledgments
  816. Development of this library owes a lot to Susie Lu, Jason Reid, James Womack,
  817. Matt Herman, Shelby Sturgis, and Tristan Reid.
  818. The Sankey layout engine is based on [sankey-plus](https://github.com/tomshanley/sankey-plus)
  819. by [Tom Shanley](https://github.com/tomshanley), which improved on his earlier
  820. `d3-sankey-circular` with better cycle detection, hierarchical arc stacking,
  821. and dynamic extent adjustment.
  822. _Semiotic icon based on an icon by Andre Schauer._
  823. ## License
  824. [Apache 2.0](./LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.