Semiotic

Uma biblioteca de visualização de dados para React, projetada para desenvolvimento assistido por IA.

Gráficos simples em 5 linhas. Grafos de rede, dados em streaming e dashboards coordenados quando você precisar. Schemas estruturados e um servidor MCP para que assistentes de codificação com IA gerem código de gráfico correto na primeira tentativa.

Novidades na versão 3.9.0

A versão 3.9.0 fecha lacunas de renderização e de API, tornando a interação com gráficos mais fácil de expressar:

• Estilos de marca retidos aceitam cursores CSS específicos de dados em canvas, SVG e renderização estática; HOCs de gráficos em tempo real também aceitam um padrão de cursor de nível superior, incluindo TemporalHistogram. A apresentação do cursor permanece separada do comportamento de clique e teclado, para que os aplicativos mantenham o controle da semântica de interação.
• Gráficos em tempo real agora compartilham a tipagem genérica, metadados de acessibilidade, estados de carregamento/vazio, legendas, seleção, hover vinculado e contratos de observação das famílias de gráficos de alto nível; o RealtimeLineChart também suporta reordenação de tempo de evento limitada, agregação por janela e descarga explícita no fim do fluxo.
• A renderização estática ganha o OrbitDiagram, além de amplas correções de paridade com o cliente para dados XY agrupados, layouts personalizados, fluxos geográficos, gradientes, camadas de fundo, cenas vazias e arestas de rede com valor zero.
• Novos helpers públicos de observação, tooltip, fluxo de snapshot, alvo de clique em rede, responsividade e CSS de tema, enquanto portões mais rígidos de pacote, API, desempenho, documentação, npm, Cloud Run e MCP Registry protegem o artefato de lançamento de ponta a ponta.

import { ForceDirectedGraph } from "semiotic/network"

<ForceDirectedGraph
  nodes={nodes}
  edges={edges}
  styleRules={[
    { when: node => Boolean(node.url), style: { cursor: "pointer" } }
  ]}
  onClick={node => node?.url && openNode(node.url)}
/>

Gráficos simples continuam com cinco linhas:

import { LineChart } from "semiotic/xy"

<LineChart
  data={salesData}
  xAccessor="month"
  yAccessor="revenue"
/>

Por que Semiotic

Semiotic é uma biblioteca de visualização de dados para React que combina ampla cobertura de gráficos com ferramentas de IA de primeira linha. Ela lida com os tipos de gráfico que a maioria das bibliotecas ignora — grafos de rede, dados em streaming, distribuições estatísticas, visualizações coordenadas — e acompanha schemas legíveis por máquina para que LLMs possam gerar código correto sem exemplos.

Feito para desenvolvimento assistido por IA

Semiotic acompanha tudo o que um assistente de codificação com IA precisa para gerar visualizações corretas sem tentativa e erro:

• semiotic/ai — uma única importação com o catálogo de capacidades de gráficos baseado em schema (XY, ordinal, rede, tempo real, geo, valor), otimizado para geração de código por LLM. Veja ai/surface-manifest.json para o inventário atual gerado. Observação: os arquivos de entrada publicados são pré-empacotados, então importar um gráfico de semiotic/ai ainda envia a maior parte do bundle — trate-o como uma superfície de codegen/ferramentas e use subcaminhos de família (semiotic/xy, semiotic/geo, semiotic/value, …) em código de produção, com aproximadamente metade do custo de um gráfico único.
• ai/schema.json — schemas de props legíveis por máquina para cada componente
• npx semiotic-mcp — um servidor MCP para renderização de gráficos baseada em ferramentas em qualquer cliente MCP
• npx semiotic-ai --doctor — valide JSON de componente + props pela linha de comando, com sugestões de erros de digitação e detecção de anti-padrões
• diagnoseConfig(component, props) — detector programático de anti-padrões com correções acionáveis, abrangendo validação, codificação, acessibilidade e verificações de design enganoso (decepção)
• auditData(component, props, data?) — pré-verificação numérica ciente de gráficos para entradas que passam na validação de schema, mas quebram a matemática: valores não finitos, domínios de intervalo zero, entradas de log inválidas, geometria de tamanho negativo, totais normalizados inseguros e outliers que dominam a escala. Retorna evidências de linhas limitadas e flui para diagnoseConfig, Chart Clinic, CLI doctor e notificações opcionais de ChartContainer
• AGENTS.md — fluxo de trabalho de repositório conciso compartilhado por agentes de codificação modernos; CLAUDE.md o importa e o Copilot recebe uma ponte de compatibilidade curta
• ai/reference.md — referência completa do produto sob demanda, mantida fora do contexto de agente de codificação sempre carregado
• llms.txt — documentação legível por máquina seguindo o padrão emergente

Cada gráfico inclui um error boundary integrado, avisos de validação em modo de desenvolvimento com sugestões de erros de digitação e recursos de acessibilidade (canvas aria-label, legendas navegáveis por teclado, tooltips aria-live, SVG <title>/<desc>) para que o código gerado por IA falhe graciosamente com diagnósticos acionáveis em vez de uma tela em branco.

Acessibilidade é uma superfície de lançamento

O European Accessibility Act aplica-se a produtos e serviços cobertos desde 28 de junho de 2025. Uma biblioteca de gráficos não pode certificar a conformidade legal de um aplicativo: escopo, conteúdo, controles ao redor, testes e aplicação nacional permanecem de responsabilidade do proprietário do aplicativo. Semiotic fornece infraestrutura testável para esse trabalho: interação por teclado, tabelas de dados acessíveis, descrições em camadas, navegação estruturada, caminhos de movimento reduzido e cores forçadas, e testes de contraste derivados de WCAG para presets de tema enviados. Veja a documentação de Acessibilidade e execute os próprios testes de tecnologia assistiva e de usuário do aplicativo.

Além dos gráficos padrão

Visualização de rede. Grafos de força direcionada, diagramas de Sankey, diagramas de cordas, layouts de árvore, treemaps, empacotamento de círculos e diagramas de órbita — todos como componentes React com a mesma API de props do LineChart.

Dados em streaming. Gráficos em tempo real renderizam em canvas a 60fps com uma API de push baseada em ref. Pushes rápidos de arestas de rede coalescem em um layout por frame de animação, enquanto métodos de leitura/mutação preservam semânticas síncronas de leitura-após-escrita. Codificação integrada de decaimento, pulso e obsolescência para dashboards de monitoramento.

Visualizações coordenadas. LinkedCharts fornece destaque cruzado por hover, filtragem cruzada por brush, crosshairs vinculados baseados em coordenadas e sincronização de seleção em qualquer combinação de tipos de gráfico por meio de estado de seleção compartilhado.

Visualização geográfica. Mapas coropléticos, mapas de símbolos proporcionais, mapas de fluxo com partículas animadas e cartogramas de distância — todos renderizados em canvas com projeções d3-geo, zoom/pan, mapas de base em tiles e rotação de globo por arrastar.

Resumos estatísticos. Box plots, violin plots, swarm plots, histogramas, suavização LOESS, previsão com envelopes de confiança e detecção de anomalias. Gráficos de distribuição marginal nos eixos de scatterplots com uma única prop.

Anotações de primeira classe. Anotações são objetos vinculados a dados, não arte posterior. Rótulos, callouts, limites, cercas, sobreposições estatísticas e widgets React movem-se com o gráfico e renderizam pelos caminhos de navegador, SSR e exportação. Opte por posicionamento, hierarquia, densidade, divulgação progressiva, quantidade ciente do público, proveniência e ciclo de vida editorial quando o gráfico precisar comunicar mais do que apenas sua codificação.

Escolha a camada de API

Camada	Para	Exemplo
Charts	Formas de gráfico comuns com props de nível de gráfico	<LineChart data={d} xAccessor="x" yAccessor="y" />
Frames	Controle total sobre renderização, interação e layout	<StreamXYFrame chartType="line" lineStyle={...} />

Todo componente Chart aceita uma prop frameProps para acessar a API Frame subjacente sem sair da interface mais simples.

Serialização e interoperabilidade

Gráficos serializam para JSON e de volta: toConfig, fromConfig, toURL, copyConfig, configToJSX. Tem especificações Vega-Lite? fromVegaLite(spec) as traduz para configs Semiotic — funciona com configToJSX() para round-trip completo de notebooks e especificações geradas por IA.

Precisa de uma revisão externa de armadilhas? O experimental unstable_toDataPitfallsChain() constrói uma entrada de cadeia sem dependências para datapitfalls, combinando o config Semiotic, JSX, fundamentação do leitor, diagnósticos, auditoria de acessibilidade e evidência opcional de SVG/imagem renderizada:

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 })

O caminho de retorno também permanece sem dependências. Use descobertas de gráfico inteiro como notificações ChartContainer, e transforme descobertas em anotações somente depois que seu aplicativo puder ancorá-las a marcas ou posições semânticas:

import { ChartContainer } from "semiotic"
import { LineChart } from "semiotic/xy"
import {
  unstable_toDataPitfallsAnnotations,
  unstable_toDataPitfallsNotifications,
} from "semiotic/experimental"

const notifications = unstable_toDataPitfallsNotifications(report)
const annotations = unstable_toDataPitfallsAnnotations(report, {
  anchorFor: (finding) =>
    finding.ruleId === "truncated-axis" ? { x: 9, y: 9000 } : null,
})

<ChartContainer notifications={notifications}>
  <LineChart {...props} annotations={annotations} />
</ChartContainer>

Quando usar outra coisa

Precisa de um gráfico de barras ou linhas padrão para um dashboard que você nunca precisará personalizar além de cores e rótulos? Recharts tem um ecossistema maior e mais exemplos da comunidade. Precisa de renderização acelerada por GPU para milhões de pontos de dados? Apache ECharts lida com essa escala.

Semiotic é para projetos que superam essas bibliotecas — quando você precisa de grafos de rede ao lado de séries temporais, dados em streaming ao lado de snapshots estáticos ou visualizações coordenadas entre tipos de gráfico.

Instalação

npm install semiotic

Requer React 18.1+ ou React 19.

Exemplos Rápidos

Dashboard Coordenado

Passe o mouse sobre um gráfico e destaque os mesmos dados em outro por meio de uma seleção compartilhada:

import { LinkedCharts, Scatterplot, BarChart } from "semiotic"

<LinkedCharts>
  <Scatterplot
    data={data} xAccessor="age" yAccessor="income" colorBy="region"
    linkedHover={{ name: "hl", fields: ["region"] }}
    selection={{ name: "hl" }}
  />
  <BarChart
    data={summary} categoryAccessor="region" valueAccessor="total"
    selection={{ name: "hl" }}
  />
</LinkedCharts>

Métricas em Streaming com Decaimento

Dados ao vivo desbotam pontos antigos, piscam novos e sinalizam feeds obsoletos:

import { RealtimeLineChart } from "semiotic"

const chartRef = useRef()
chartRef.current.push({ time: Date.now(), value: cpuLoad })

<RealtimeLineChart
  ref={chartRef}
  timeAccessor="time"
  valueAccessor="value"
  decay={{ type: "exponential", halfLife: 100 }}
  staleness={{ threshold: 5000, showBadge: true }}
/>

Grafos de Rede

Grafos de força direcionada e diagramas de Sankey — mesma API do LineChart:

import { ForceDirectedGraph, SankeyDiagram } from "semiotic"

<ForceDirectedGraph
  nodes={people} edges={friendships}
  colorBy="team" nodeSize={8} showLabels
/>

<SankeyDiagram
  edges={budgetFlows}
  sourceAccessor="from" targetAccessor="to" valueAccessor="amount"
/>

Visualização Geográfica

Mapas coropléticos, mapas de fluxo e cartogramas de distância com renderização em canvas, zoom/pan, mapas de base em tiles e partículas animadas:

import { ChoroplethMap, FlowMap, DistanceCartogram } from "semiotic/geo"

<ChoroplethMap
  areas={geoJsonFeatures} valueAccessor="gdp"
  colorScheme="viridis" projection="equalEarth" zoomable tooltip
/>

<FlowMap
  nodes={airports} flows={routes} valueAccessor="passengers"
  showParticles particleStyle={{ color: "source", speedMultiplier: 1.5 }}
/>

<DistanceCartogram
  points={cities} center="rome" costAccessor="travelDays"
  showRings costLabel="days" lines={routes}
/>

Monitor de Sistema em Streaming

Topologia de serviço ao vivo com alertas de limite e clique para inspecionar:

import { StreamNetworkFrame, ChartContainer, DetailsPanel, LinkedCharts } from "semiotic"

const chartRef = useRef()
chartRef.current.push({ source: "API", target: "Orders", value: 15 })

<LinkedCharts>
  <ChartContainer title="System Monitor" status="live"
    detailsPanel={
      <DetailsPanel position="right" trigger="click">
        {(datum) => <div>{datum.id}: {datum.value} req/s</div>}
      </DetailsPanel>
    }>
    <StreamNetworkFrame ref={chartRef} chartType="sankey"
      showParticles particleStyle={{ proportionalSpeed: true }}
      thresholds={{ metric: n => n.value, warning: 100, critical: 250 }}
    />
  </ChartContainer>
</LinkedCharts>

Gráficos Padrão

Gráficos de linha, barra, dispersão e área compartilham a mesma API orientada por acessores:

import { LineChart, BarChart } from "semiotic"

<LineChart
  data={salesData}
  xAccessor="month" yAccessor="revenue"
  curve="monotoneX" showPoints
/>

<BarChart
  data={categoryData}
  categoryAccessor="department" valueAccessor="sales"
  orientation="horizontal" colorBy="region"
/>

Todos os Componentes de Gráfico

Categoria	Componentes
XY	LineChart AreaChart DifferenceChart StackedAreaChart Scatterplot ConnectedScatterplot BubbleChart Heatmap QuadrantChart MultiAxisLineChart MinimapChart CandlestickChart ScatterplotMatrix
Categórico	BarChart StackedBarChart GroupedBarChart LikertChart SwimlaneChart FunnelChart SwarmPlot BoxPlot Histogram ViolinPlot RidgelinePlot DotPlot PieChart DonutChart GaugeChart
Rede	ForceDirectedGraph ChordDiagram SankeyDiagram ProcessSankey TreeDiagram Treemap CirclePack OrbitDiagram
Geo	ChoroplethMap ProportionalSymbolMap FlowMap DistanceCartogram
Tempo Real	RealtimeLineChart RealtimeHistogram RealtimeSwarmChart RealtimeWaterfallChart RealtimeHeatmap
Coordenação	LinkedCharts
Layout	ChartGrid ContextLayout CategoryColorProvider
Frames	StreamXYFrame StreamOrdinalFrame StreamNetworkFrame StreamGeoFrame

Tradução Vega-Lite

Cole uma especificação Vega-Lite e obtenha um gráfico Semiotic:

import { fromVegaLite } from "semiotic/data"
import { configToJSX, fromConfig } from "semiotic"

const config = fromVegaLite({
  mark: "bar",
  data: { values: [{ a: "A", b: 28 }, { a: "B", b: 55 }] },
  encoding: {
    x: { field: "a", type: "nominal" },
    y: { field: "b", type: "quantitative" },
  },
})

// Render directly
const { componentName, props } = fromConfig(config)
// → componentName: "BarChart", props: { data, categoryAccessor: "a", valueAccessor: "b" }

// Or generate JSX code
configToJSX(config)
// → <BarChart data={[...]} categoryAccessor="a" valueAccessor="b" />

Suporta marcas de barra, linha, área, ponto, retângulo, arco e tick com tradução de codificação para cor, tamanho, agregação e binning.

Telemetria de Arco de Conversa

Capture e reproduza o caminho que uma sessão de gráfico assistida por IA percorreu:

import {
  createLocalStorageConversationArcSink,
  enableConversationArc,
  getConversationArcStore,
  loadConversationArc,
  registerConversationArcSink,
} from "semiotic/ai"

const sink = createLocalStorageConversationArcSink({ key: "my-app:arc" })
registerConversationArcSink(sink)
enableConversationArc({ sessionId: "session-abc" })

getConversationArcStore().record({ type: "chart-rendered", component: "LineChart" })
loadConversationArc(sink.load(), { enabled: false })

Tamanhos de Bundle

Semiotic envia 17 pontos de entrada de módulo estáveis. Não importe de "semiotic" a menos que precise de tudo — use o subcaminho que corresponde ao seu tipo de gráfico.

Os números abaixo são o custo de artefato de primeira parte: o tamanho gzip do código próprio do Semiotic para cada subcaminho. Eles excluem React e outras dependências de runtime, portanto não são uma previsão de um bundle de aplicativo frio. Não adicione linhas de artefato para estimar um aplicativo: a resolução de dependências e a deduplicação de importações cruzadas acontecem no bundler do consumidor e são medidas separadamente abaixo.

Ponto de Entrada	gzip	O que contém
semiotic/xy	151 KB	LineChart, AreaChart, Scatterplot, Heatmap, + 8 gráficos XY
semiotic/ordinal	127 KB	BarChart, PieChart, BoxPlot, Histogram, + 11 gráficos categóricos
semiotic/network	149 KB	ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4
semiotic/geo	108 KB	ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap
semiotic/realtime	162 KB	RealtimeLineChart, RealtimeHistogram, + 4 gráficos de streaming
semiotic/realtime/core	161 KB	Tipos de gráficos de streaming, HOCs e helpers de buffer
semiotic/realtime/react	1 KB	Status de stream e hooks de push sincronizados
semiotic/server	242 KB	renderChart, renderDashboard, renderToImage, renderToAnimatedGif
semiotic/server/node	242 KB	renderChart, renderDashboard, renderToImage, renderToAnimatedGif
semiotic/server/edge	247 KB	renderChart, renderChartWithEvidence, renderToStaticSVG, renderDashboard
semiotic/utils	94 KB	ThemeProvider, auditorias numéricas/de acessibilidade, serialização — sem componentes de gráfico
semiotic/utils/core	87 KB	Helpers puros de tema, auditorias numéricas/de acessibilidade e serialização
semiotic/utils/react	7 KB	ThemeProvider, useTheme, useReducedMotion, useHighContrast, useStreamStatus
semiotic/recipes	95 KB	Funções puras de layout (waffle, marimekko, flextree, dagre, …)
semiotic/recipes/core	87 KB	Funções puras de layout (waffle, marimekko, flextree, dagre, …)
semiotic/recipes/react	7 KB	Helpers de seleção de layout Glyph e React
semiotic/themes	7 KB	Apenas presets de tema (tufte, carbon, etc.)
semiotic/themes/core	7 KB	Presets de tema e helpers de token
semiotic/themes/react	6 KB	ThemeProvider/useTheme e hooks
semiotic/data	4 KB	bin, rollup, groupBy, pivot, fromVegaLite
semiotic/value	6 KB	BigNumber — KPI de valor focal / scorecard (POC SingleValueFrame)
semiotic/physics	163 KB	GaltonBoardChart, EventDropChart, UnitPileChart, CollisionSwarmChart, PacketFlowChart, PhysicsCustomChart
semiotic/physics/matter	1 KB	Helpers de migração Matter.js + guard de peer opcional (sem componentes de gráfico)
semiotic/physics/rapier	1 KB	Guard de peer Rapier + metadados de decisão de adaptador (sem componentes de gráfico)
semiotic/ai	519 KB	Todos os gráficos com schema + validação — otimizado para geração de código por LLM
semiotic/ai/core	87 KB	suggestCharts, auditData, describeChart, repairChartConfig, adaptadores de ferramenta — sem componentes de gráfico
semiotic/controls	11 KB	DirectManipulationControl, CircularBrush, MobileStandardControls, auditVisualizationControls — sem renderizador de frame
semiotic/rough	4 KB	Backend de pintura Rough.js determinístico opcional — a geometria exata do Semiotic permanece autoritativa
semiotic	332 KB	Tudo abaixo (bundle completo)

Imports nomeados para consumo a frio

A tabela acima é o custo de artefato de primeira parte, não um bundle de aplicação. A tabela gerada abaixo mede algo diferente: um consumidor novo empacota um import nomeado retido de um tarball semiotic empacotado pelo caminho de exportação pública. Ela inclui Semiotic e suas dependências de runtime resolvidas, mas externaliza React/React DOM e peers adaptadores opcionais que pertencem ao aplicativo host. Cada linha começa fria, então use-a para comparar uma escolha de import público — não para somar as linhas de um aplicativo. A linha de base verificável legível por máquina é benchmarks/setup/cold-consumer-imports.json; atualize-a após um build de produção com npm run docs:cold-consumer.

Método: tarball npm pack --ignore-scripts novo → consumidor temporário → bundle ESM esbuild minificado/com tree-shaking → gzip -9. React/React DOM e peers adaptadores opcionais são externos; Semiotic e suas dependências de runtime resolvidas são incluídos.

Import nomeado público	Runtime	Bundle gzip de consumo a frio
import { LineChart } from "semiotic"	browser	160.8 KiB
import { LineChart } from "semiotic/xy"	browser	160.5 KiB
import { BarChart } from "semiotic/ordinal"	browser	129.3 KiB
import { SankeyDiagram } from "semiotic/network"	browser	151.6 KiB
import { RealtimeLineChart } from "semiotic/realtime"	browser	133.9 KiB
import { RingBuffer } from "semiotic/realtime/core"	browser	0.7 KiB
import { useStreamStatus } from "semiotic/realtime/react"	browser	0.6 KiB
import { GaltonBoardChart } from "semiotic/physics"	browser	148.4 KiB
import { MATTER_PHYSICS_CAPABILITIES } from "semiotic/physics/matter"	browser	0.2 KiB
import { RAPIER_PHYSICS_CAPABILITIES } from "semiotic/physics/rapier"	browser	0.2 KiB
import { renderChart } from "semiotic/server"	node	304.7 KiB
import { generateFrameSVGs } from "semiotic/server/edge"	node	172.6 KiB
import { renderToImage } from "semiotic/server/node"	node	305.2 KiB
import { suggestCharts } from "semiotic/ai"	browser	237.4 KiB
import { suggestCharts } from "semiotic/ai/core"	browser	37.9 KiB
import { bin } from "semiotic/data"	browser	0.4 KiB
import { ChoroplethMap } from "semiotic/geo"	browser	113.7 KiB
import { createRoughRenderMode } from "semiotic/rough"	browser	3.2 KiB
import { resolveThemePreset } from "semiotic/themes"	browser	2.6 KiB
import { resolveThemePreset } from "semiotic/themes/core"	browser	2.6 KiB
import { ThemeProvider } from "semiotic/themes/react"	browser	5.1 KiB
import { validateProps } from "semiotic/utils"	browser	8.7 KiB
import { smartTickFormat } from "semiotic/utils/core"	browser	6.4 KiB
import { useReducedMotion } from "semiotic/utils/react"	browser	2.3 KiB
import { waffleLayout } from "semiotic/recipes"	browser	2.9 KiB
import { waffleLayout } from "semiotic/recipes/core"	browser	2.9 KiB
import { Glyph } from "semiotic/recipes/react"	browser	0.8 KiB
import { BigNumber } from "semiotic/value"	browser	5.9 KiB
import { DirectManipulationControl } from "semiotic/controls"	browser	1.3 KiB

// Import from the sub-path, not from "semiotic"
import { LineChart } from "semiotic/xy"
import { BarChart } from "semiotic/ordinal"
import { SankeyDiagram } from "semiotic/network"
import { ChoroplethMap } from "semiotic/geo"

Tree-shaking e imports de múltiplos subcaminhos: Entradas de família (semiotic/xy, semiotic/network, semiotic/ai, …) são construídas como um único grafo ESM com chunks compartilhados. Frames de stream, renderizadores e outros códigos comuns são enviados uma vez e importados por cada entrada que precisa deles — então combinar semiotic/ai + semiotic/xy + semiotic/network não significa pagar por três cópias completas do runtime. O pacote é marcado como "sideEffects": false, então bundlers modernos mantêm apenas os exports nomeados que você retém (ex.: LineChart + suggestCharts). Prefira subcaminhos de família para clareza; importe helpers de IA de semiotic/ai ou do mais leve semiotic/ai/core quando não precisar do catálogo de gráficos.

Quando usar "semiotic": Adequado quando você quer um único import para famílias mistas. Chunks compartilhados evitam código de runtime duplicado entre subcaminhos de família; a tabela de consumo a frio acima é o melhor guia para um único import nomeado.

TypeScript

Construído com strict: true. Definições de tipo completas acompanham o pacote. Genéricos para accessors type-safe:

interface Sale { month: number; revenue: number }

<LineChart<Sale>
  data={sales}
  xAccessor="month"    // TS validates this is keyof Sale
  yAccessor="revenue"
/>

Renderização no Lado do Servidor

Todos os componentes de gráfico renderizam SVG automaticamente em ambientes de servidor — sem imports ou configuração especiais. HOCs de gráfico não-streaming podem ser importados e renderizados diretamente de um Server Component do Next.js: a diretiva "use client" do Semiotic define o limite do pacote, então a página que importa não precisa de seu próprio wrapper ou diretiva. Props que cruzam esse limite devem permanecer serializáveis; adicione um wrapper de cliente de propriedade do app apenas quando introduzir hooks, props de callback, estado do navegador ou um gráfico de streaming orientado por push.

// app/dashboard/page.tsx — a Next.js Server Component
import { LineChart } from "semiotic/xy"

// Server: renders <svg> with path/circle/rect elements
// Client: renders <canvas> with SVG overlay for axes
export default async function DashboardPage() {
  const data = await fetchMetrics()
  return <LineChart data={data} xAccessor="date" yAccessor="value" />
}

Para geração standalone de SVG/PNG/GIF (e-mail, imagens OG, PDF, Slack), use o ponto de entrada do servidor:

import { renderChart, renderToImage, renderToAnimatedGif } from "semiotic/server"

// SVG — sync, no dependencies
const svg = renderChart("LineChart", {
  data, xAccessor: "date", yAccessor: "value",
  theme: "tufte", title: "Revenue Trend",
})

// PNG — async, requires sharp
const png = await renderToImage("BarChart", { data, ... }, { format: "png", scale: 2 })

// Animated GIF — async, requires sharp + gifenc
const gif = await renderToAnimatedGif("line", data, { ... }, { fps: 12 })

Servidor MCP

mcp-name: io.github.nteract/semiotic

Semiotic acompanha um servidor MCP que permite que assistentes de codificação de IA renderizem gráficos, diagnostiquem problemas de configuração, descubram schemas, leiam orientações de IA empacotadas e obtenham recomendações de gráficos por meio de chamadas de ferramentas.

Configuração

Adicione à sua configuração de cliente MCP (ex.: claude_desktop_config.json para Claude Desktop):

{
  "mcpServers": {
    "semiotic": {
      "command": "npx",
      "args": ["semiotic-mcp"]
    }
  }
}

Nenhuma chave de API ou autenticação necessária. O servidor roda localmente via stdio. O modo HTTP também está disponível para inspetores, clientes web e experimentos com o SDK de ChatGPT Apps: npx semiotic-mcp --http --port 3001. Ele vincula a 127.0.0.1 por padrão; exponha intencionalmente outra interface com --host 0.0.0.0 ou MCP_HOST=0.0.0.0. Desde a 3.7.2, o modo HTTP é stateless: cada requisição recebe um servidor MCP somente leitura novo + transporte, então ele pode escalar automaticamente em hosts serverless sem sessões sticky.

Para o modo desenvolvedor do ChatGPT, exponha o endpoint HTTP via HTTPS com um túnel e crie um conector que aponte para https://<your-tunnel>/mcp. A superfície experimental do Apps SDK é renderInteractiveChart, que retorna um template de widget text/html;profile=mcp-app mais um payload SVG oculto renderizado por Semiotic no servidor MCP.

Para uma implantação hospedada, veja deploy/cloud-run. O wrapper executa o binário semiotic-mcp publicado, expõe /mcp além de endpoints de health, e suporta MCP_ALLOWED_HOSTS para allowlisting de host-header em produção. Para verificação de domínio do ChatGPT Apps, defina OPENAI_APPS_CHALLENGE_TOKEN para que o modo HTTP sirva o token bruto de /.well-known/openai-apps-challenge.

Ferramentas

Ferramenta	Descrição
renderChart	Renderiza um gráfico Semiotic em SVG estático. Suporta os componentes retornados por getSchema que são marcados como [renderable]. Passe { component: "LineChart", props: { data: [...], xAccessor: "x", yAccessor: "y" } }. Retorna string SVG mais um bloco JSON de "evidência de renderização" (contagens de marks por tipo de cena, domínios de eixo resolvidos, flag de vazio, contagem de anotações, nome acessível) para que agentes possam verificar se o gráfico desenhou marks de dados, ou erros de validação com sugestões de correção.
renderInteractiveChart	Renderiza um gráfico de dados estáticos como widget de ChatGPT Apps. Usa o mesmo caminho de renderização do servidor Semiotic que renderChart, e então hidrata uma UI em iframe com controles de fit, zoom, dados, hover e evidência de renderização.
getSchema	Retorna o schema de props para um componente específico. Passe { component: "LineChart" } para obter suas props, ou omita component para listar o catálogo completo baseado em schema. Componentes marcados como [renderable] estão disponíveis por meio de renderChart; gráficos em tempo real exigem um ambiente de navegador/ao vivo.
suggestChart	Recomendador por linhas de amostra. Passe { data: [{...}, ...] } com 1–5 objetos de amostra mais filtros opcionais amplos de intenção/capacidade.
suggestCharts	Recomendador baseado em capacidade para dados de linhas limitados. Retorna sugestões de gráficos classificadas com pontuações, motivos, ressalvas, caminhos de import e props prontas para uso.
suggestStreamCharts	Recomenda gráficos em tempo real a partir de um schema de stream, throughput e dicas de retenção.
suggestDashboard	Constrói uma sugestão de dashboard multi-painel que cobre intenções analíticas distintas.
suggestStretchCharts	Recomenda escolhas desafiadoras de alfabetização do público a partir de um AudienceProfile.
repairChartConfig	Verifica se um gráfico solicitado se adequa a um dataset e retorna alternativas classificadas quando não se adequa.
interrogateChart	Retorna um resumo estatístico e contexto ciente de gráficos para responder perguntas em linguagem natural com anotações opcionais.
diagnoseConfig	Verifica uma configuração de gráfico para problemas comuns — dados vazios, dimensões ruins, accessors ausentes, formato de dados errado e mais. Retorna um relatório de diagnóstico legível por humanos com correções acionáveis.
reportIssue	Gera uma URL de issue do GitHub pré-preenchida para relatórios de bug ou solicitações de recursos. Passe { title: "...", body: "...", labels: ["bug"] }. Retorna uma URL que o usuário pode abrir para enviar.
applyTheme	Lista presets de tema nomeados ou retorna o uso de ThemeProvider/CSS/token para um preset como { name: "tufte" }.

Recursos

Recurso	Descrição
semiotic://schema	JSON completo do schema de componentes legível por máquina.
semiotic://components	Índice de componentes mostrando status renderizável/somente navegador e categorias MCP.
semiotic://surface-manifest	Inventário gerado do schema de IA atual, exports, capacidade de renderização, ferramentas, recursos e prompts.
semiotic://behavior-contracts	Regras semânticas visíveis para agentes sobre precedência de cores, combinações de props obrigatórias, push refs e capacidade de renderização.
semiotic://system-prompt	Instruções compactas de IA com regras de import, props de gráfico, orientação de SSR e armadilhas.
semiotic://examples	Exemplos de gráficos copiáveis por formato de dados.
ui://semiotic/chart-widget.html	Template de widget de ChatGPT Apps / MCP Apps usado por renderInteractiveChart.

Prompts

Prompt	Descrição
build-semiotic-chart	Fluxo de trabalho reutilizável para escolher um gráfico, ler o schema, diagnosticar props e renderizar uma prévia.
debug-semiotic-chart	Fluxo de trabalho reutilizável para depurar props inválidas, falhas de renderização e relatórios de problemas.

Exemplo: obter schema de um componente

Tool: getSchema
Args: { "component": "LineChart" }
→ Returns: { "name": "LineChart", "description": "...", "parameters": { "properties": { "data": ..., "xAccessor": ..., ... } } }

Exemplo: sugerir um gráfico para seus dados

Tool: suggestChart
Args: {
  "data": [
    { "month": "Jan", "revenue": 120, "region": "East" },
    { "month": "Feb", "revenue": 180, "region": "West" }
  ]
}
→ Returns:
  1. BarChart (high confidence) — categorical field (region) with values (revenue)
  2. StackedBarChart (medium confidence) — two categorical fields (month, region)
  3. DonutChart (medium confidence) — 2 categories — proportional composition

Exemplo: renderizar um gráfico

Tool: renderChart
Args: {
  "component": "BarChart",
  "props": {
    "data": [
      { "category": "Q1", "revenue": 120 },
      { "category": "Q2", "revenue": 180 },
      { "category": "Q3", "revenue": 150 }
    ],
    "categoryAccessor": "category",
    "valueAccessor": "revenue"
  }
}
→ Returns: <svg>...</svg>

Exemplo: renderizar um widget do ChatGPT Apps

Tool: renderInteractiveChart
Args: {
  "component": "BarChart",
  "props": {
    "title": "Revenue by Quarter",
    "data": [
      { "quarter": "Q1", "revenue": 120 },
      { "quarter": "Q2", "revenue": 180 }
    ],
    "categoryAccessor": "quarter",
    "valueAccessor": "revenue"
  }
}
→ Returns: structured chart summary for the model + hidden SVG/widget metadata for ChatGPT.

Exemplo: diagnosticar uma configuração quebrada

Tool: diagnoseConfig
Args: { "component": "LineChart", "props": { "data": [] } }
→ Returns: ✗ [EMPTY_DATA] data is an empty array — Fix: provide at least one data point

Exemplo: relatar um problema

Tool: reportIssue
Args: {
  "title": "Bug: BarChart tooltip shows undefined for custom accessor",
  "body": "When using valueAccessor='amount', tooltip displays 'undefined'.\n\ndiagnoseConfig output: ✓ no issues detected.",
  "labels": ["bug"]
}
→ Returns: Open this URL to submit the issue: https://github.com/nteract/semiotic/issues/new?...

Alternativa via CLI

Para validação rápida sem um cliente MCP:

npx semiotic-ai --list         # list components with import paths and renderability
npx semiotic-ai --list --json  # machine-readable component index
npx semiotic-ai --schema GaugeChart
npx semiotic-ai --suggest '{"data":[{"category":"A","value":10}],"intent":"comparison"}'
npx semiotic-ai --doctor       # validate component + props JSON
npx semiotic-ai --schema       # dump all chart schemas
npx semiotic-ai --compact      # compact schema (fewer tokens)

--doctor usa as verificações completas de diagnoseConfig quando dist está disponível e recorre à validação somente por schema em checkouts limpos do código-fonte.

Onde encontrar o Semiotic para assistentes de IA

O Semiotic é indexado por ferramentas de documentação de agentes de codificação de IA, para que seu assistente (Claude Code, Cursor, Cline, Copilot, etc.) possa acessar a documentação e as ferramentas atuais sem copiar e colar:

• Context7 — context7.com/nteract/semiotic (configurado via context7.json)
• DeepWiki — deepwiki.com/nteract/semiotic
• GitMCP — gitmcp.io/nteract/semiotic (expõe o repositório como um endpoint MCP diretamente)
• Official MCP Registry — pesquise "semiotic" em registry.modelcontextprotocol.io

O Official MCP Registry é o registro canônico do diretório MCP; ele é distinto da aceitação no diretório de conectores curado de qualquer fornecedor de assistente. A atualização do diretório secundário e a propriedade de lançamentos são rastreadas em MCP_DISTRIBUTION.md.

Superfície de API voltada a agentes:

• AGENTS.md é o contrato conciso de desenvolvimento do repositório e CLAUDE.md o importa para o Claude Code. Eles permanecem locais ao repositório, em vez de enviar instruções irrelevantes de contribuidores aos consumidores do pacote.
• ai/reference.md, ai/schema.json, ai/surface-manifest.json, ai/behaviorContracts.cjs e agent-skill/semiotic-charts/SKILL.md são incluídos no tarball do npm (veja package.json#files). A referência é o guia de produto sob demanda impresso por npx semiotic-ai; o schema, o manifesto, os contratos e a habilidade portátil fornecem orientação estruturada de geração e validação.
• semiotic.nteract.io/llms.txt + /llms-full.txt — implantados no site de documentação conforme o padrão llms.txt. Os agentes buscam o mapa de navegação (llms.txt) ou a documentação completa embutida (llms-full.txt) via HTTP; eles não fazem parte do pacote npm em si.

Documentação

Documentação interativa e exemplos

• Getting Started
• Charts — tipos de gráfico com exemplos ao vivo
• Frames — referência completa da API de Frames
• Features — eixos, tooltips, interação, comportamento responsivo e composição
• Annotations — tipos de anotação de primeira classe, orientação de design, proveniência e ciclo de vida
• Cookbook — padrões e receitas avançados
• Playground — exploração interativa de props

Atualização

• Migration Guide — atualização a partir da v1.x ou v2.x
• Changelog — histórico completo de versões

Contribuindo

Veja CONTRIBUTING.md. Nossa comunidade segue o nteract Código de Conduta.

Agradecimentos

O desenvolvimento desta biblioteca deve muito a Susie Lu, Jason Reid, James Womack, Matt Herman, Shelby Sturgis e Tristan Reid.

O mecanismo de layout Sankey é baseado em sankey-plus por Tom Shanley, que melhorou seu d3-sankey-circular anterior com melhor detecção de ciclos, empilhamento hierárquico de arcos e ajuste dinâmico de extensão.

Ícone do Semiotic baseado em um ícone de Andre Schauer.

Licença

Apache 2.0