Semiotic

AI 支援開発とストリーミングデータ向けに設計された、React データ可視化ライブラリです。

小さなチャートコンポーネントから始め、必要に応じてネットワークグラフ、ストリーミングデータ、連動ビューを追加できます。構造化スキーマ、診断機能、レンダリング結果の証拠により、コーディングアシスタントはチャート設定の実装、確認、修正を行えます。

タスクを最初から最後まで進めてみましょう：カテゴリ別の合計を確認する、ライブチャートを維持する、または公開済みのチャートを修正することができます。ソースタスクパケットにはビルドと証拠の範囲が記載されています。ソースが利用可能であっても、インストール済みまたはデプロイ済みの状態との一致が保証されるわけではありません。

新着情報 3.13.2

3.13.2 では、ネストされたテーマの継承と props の更新を修正し、選択、古さ、アニメーションを通じてマークの不透明度を維持するとともに、ツールチップの計測処理を削減しました。ネットワークチャートではエッジの選択とカメラの更新が改善され、レイアウトのコミット中にカメラハンドルを利用できるようになりました。また、リリース成果物の準備では、名前を変更したチェックアウトへの対応と、失敗したビルドの再試行が可能になりました。

修正と追加の全内容については、変更履歴をご覧ください。

Semiotic を選ぶ理由

Semiotic は、幅広いチャートに対応する機能と AI ツールを組み合わせた React 用データ可視化ライブラリです。ネットワークグラフ、ストリーミングデータ、統計分布、連動ビューをサポートし、各タスクの実装と確認に使えるスキーマ、サンプル、診断機能を備えています。まずプロジェクトに既存の依存関係があるか確認してください。小規模な変更であれば、現在使用しているチャートライブラリを拡張するのが最適な場合があります。

AI 支援開発向けに構築

Semiotic は、チャート設定の生成、チェック、修正を行うワークフローを提供します。2026 年 7 月 27 日の評価 には、モデルおよびタスクごとの結果が記載されています。初回の試行で正しく動作することを保証するものではありません。

• semiotic/ai — スキーマに基づくチャート機能カタログ（XY、ordinal、network、realtime、geo、value、および portable recipes）を単一のインポートで利用でき、LLM によるコード生成に最適化されています。生成された最新の一覧については、ai/surface-manifest.json を参照してください。名前付きインポートは、公開済みチャンク間でツリーシェイクされるようになりました。本番コードでは、対象のチャートファミリーを明示できるファミリー別サブパス（semiotic/xy、semiotic/geo、semiotic/value、…）を優先してください。以下のコールドコンシューマー表には、初回読み込みとオンデマンドのコストが記載されています。
• ai/schema.json — すべてのコンポーネントの、機械可読なプロパティスキーマ
• npx -y -p semiotic semiotic-mcp — 任意の MCP クライアントでツールベースのチャート描画を行うための MCP サーバー
• npx -p semiotic semiotic-ai --doctor — コマンドラインから、タイプミスの候補提案とアンチパターン検出を用いて、コンポーネントとプロパティの JSON を検証
• diagnoseConfig(component, props) — 検証、エンコーディング、アクセシビリティ、誤解を招くデザイン（欺瞞）チェックを含む、具体的な修正案を提示するプログラム用アンチパターン検出器
• auditData(component, props, data?) — スキーマ検証を通過しても計算処理を破綻させる入力を対象とした、チャートに対応した数値の事前チェック。有限でない値、幅がゼロのドメイン、不正な対数入力、負のサイズ形状、安全でない正規化済み合計、スケールを支配する外れ値を検出します。上限付きの行単位の根拠情報を返し、diagnoseConfig、Chart Clinic、CLI doctor、オプトインの ChartContainer 通知に反映されます。
• AGENTS.md — 最新のコーディングエージェントが共有する、簡潔なリポジトリのワークフロー。 CLAUDE.md はこれをインポートし、Copilot には短い互換性ブリッジが提供されます。
• ai/reference.md — 常時読み込まれるコーディングエージェントのコンテキストから分離された、必要に応じて参照できる製品リファレンスの完全版
• llms.txt — 新たに普及しつつある標準に準拠した、機械可読なドキュメント

すべてのチャートには、組み込みのエラーバウンダリー、タイプミスの候補提案を含む開発モードの検証警告、およびアクセシビリティ機能（キャンバスの aria-label、キーボードで操作できる凡例、キーボード操作に対応したライブリージョンの通知、SVG <title>／<desc>）が備わっています。そのため、AI が生成したコードに問題があっても、空白の画面になるのではなく、具体的な診断情報を示して適切に処理できます。

アクセシビリティはリリースの対象です

欧州アクセシビリティ法 は、対象となる製品およびサービスに対して、2025 年 6 月 28 日から適用されています。チャートライブラリは、アプリケーションの法令遵守を証明できません。適用範囲、コンテンツ、周辺のコントロール、テスト、各国の法執行については、引き続きアプリケーションの所有者が責任を負います。Semiotic は、その取り組みに役立つテスト可能な基盤として、キーボード操作、アクセシブルなデータテーブル、階層化された説明、構造化されたナビゲーション、動きの抑制と強制カラーモードへの対応、および提供するテーマプリセットを対象とした WCAG 由来のコントラストテストを提供します。アクセシビリティのドキュメントを参照し、アプリケーション独自の支援技術テストとユーザーテストを実施してください。

標準的なチャートを超えて

ネットワークの可視化。 力指向グラフ、Sankey 図、コード図、ツリーレイアウト、ツリーマップ、円充填、オービット図 — これらはすべて LineChart と同じ props API を持つ React コンポーネントとして提供されます。

ストリーミングデータ。 リアルタイムチャートは ref ベースの push API を使い、canvas 上で 60fps でレンダリングします。ネットワークのエッジに対する高速な push は、アニメーションフレームごとに 1 回のレイアウトにまとめられます。一方、読み取り/変更メソッドは同期的な read-after-write セマンティクスを維持します。監視ダッシュボード向けに、減衰、パルス、古さ（staleness）のエンコーディングを組み込みで備えています。

連動ビュー。 LinkedCharts は、共有された選択状態を通じて、任意のチャート種別の組み合わせにわたって、ホバーによるクロスハイライト、ブラシによるクロスフィルタリング、座標ベースの連動クロスヘア、選択の同期を提供します。

地理的可視化。 コロプレスマップ、比例記号マップ、アニメーション粒子付きのフローマップ、距離カルトグラム — これらはすべて d3-geo の投影を使い canvas でレンダリングされ、ズーム/パン、タイルベースマップ、ドラッグ回転する地球儀のスピンを備えています。

統計的要約。 ボックスプロット、バイオリン図、スウォームプロット、ヒストグラム、LOESS 平滑化、信頼区間付き予測、異常検出。散布図の軸上の周辺分布グラフィックスを 1 つの prop で実現します。

ファーストクラスのアノテーション。 アノテーションは後付けの描画ではなく、データにバインドされたオブジェクトです。ラベル、呼び出し線、しきい値、囲み、統計オーバーレイ、React ウィジェットはチャートとともに移動し、ブラウザー、SSR、エクスポートの各経路でレンダリングされます。チャートがそのエンコーディングだけでは伝えきれない情報を伝える必要がある場合は、配置、階層、密度、段階的開示、読者に応じた量、来歴（provenance）、編集ライフサイクルをオプトインできます。

API レイヤーを選択する

レイヤー	用途	例
Charts	チャートレベルの props を使う一般的なチャート形式	<LineChart data={d} xAccessor="x" yAccessor="y" />
Frames	レンダリング、インタラクション、レイアウトを完全に制御	<StreamXYFrame chartType="line" lineStyle={...} />

Chart HOC は必要なマークプラグインだけを登録します。直接 StreamXYFrame を使うと、最初のクライアント描画時に残りの組み込みプラグインを読み込みます。SSR 時、または最初のフレームにマークを含める必要がある場合は、最初のレンダリングの前に semiotic/xy または semiotic/realtime/core から registerBuiltInXYPlugins() を呼び出してください。

すべての Chart コンポーネントは frameProps prop を受け取り、よりシンプルなインターフェースのまま、基盤となる Frame API にアクセスできます。

シリアライズと相互運用

チャートは JSON にシリアライズし、また元に戻せます: toConfig、fromConfig、toURL、copyConfig、configToJSX。Vega-Lite のスペックをお持ちですか？ fromVegaLite(spec) がそれらを Semiotic の config に変換します — configToJSX() と組み合わせれば、ノートブックや AI が生成したスペックからの完全なラウンドトリップが可能です。

外部による落とし穴レビューが必要ですか？ 実験的な unstable_toDataPitfallsChain() は、datapitfalls 向けの依存関係のないチェーン入力を作成し、Semiotic の config、JSX、リーダーのグラウンディング、診断、アクセシビリティ監査、およびオプションのレンダリング済み SVG/画像のエビデンスを組み合わせます:

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

戻り経路も依存関係のないままです。チャート全体に対する検出結果は ChartContainer の通知として使用し、アプリがそれらをマークやセマンティックな位置にアンカーできるようになってから、検出結果をアノテーションに変換してください:

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>

別のものを選ぶべき場合

色とラベル以外にカスタマイズする必要が決してないダッシュボード向けの標準的な棒グラフや折れ線グラフが必要ですか？ Recharts にはより大きなエコシステムとより多くのコミュニティ例があります。数百万のデータポイント向けに GPU アクセラレーションによるレンダリングが必要ですか？ Apache ECharts がその規模を扱えます。

Semiotic は、これらのライブラリを超えて成長したプロジェクト向けです — 時系列と並べてネットワークグラフが必要なとき、静的スナップショットと並べてストリーミングデータが必要なとき、あるいはチャート種別をまたいだ連動ビューが必要なときに適しています。

インストール

npm install semiotic

React 18.1 以降、または React 19 が必要です。

クイック例

連動ダッシュボード

あるチャートをホバーすると、共有された選択を通じて別のチャートで同じデータがハイライトされます:

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>

減衰するストリーミングメトリクス

ライブデータでは古いポイントが薄れ、新しいポイントが点滅し、更新が停止したフィードにフラグが立ちます：

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

ネットワークグラフ

力指向グラフとサンキーダイアグラムを、LineChart と同じ API で利用できます：

import { ForceDirectedGraph, SankeyDiagram } from "semiotic"

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

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

地理的な可視化

コロプレスマップ、フローマップ、距離カルトグラムを、Canvas 描画、 ズーム／パン、タイルベースマップ、アニメーションする粒子とともに利用できます：

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

ストリーミングシステムモニター

しきい値アラートとクリックによる詳細確認に対応した、サービスのライブトポロジーです：

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>

標準的なチャート

折れ線、棒、散布図、面チャートは、アクセサー駆動の同じ API を共有します：

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"
/>

すべてのチャートコンポーネント

カテゴリ	コンポーネント
XY	LineChart AreaChart DifferenceChart StackedAreaChart Scatterplot ConnectedScatterplot BubbleChart Heatmap QuadrantChart MultiAxisLineChart MinimapChart CandlestickChart ScatterplotMatrix
カテゴリ	BarChart StackedBarChart GroupedBarChart LikertChart SwimlaneChart FunnelChart SwarmPlot BoxPlot Histogram ViolinPlot RidgelinePlot DotPlot PieChart DonutChart GaugeChart
ネットワーク	ForceDirectedGraph ChordDiagram SankeyDiagram ProcessSankey TreeDiagram Treemap CirclePack OrbitDiagram
地理	ChoroplethMap ProportionalSymbolMap FlowMap DistanceCartogram
リアルタイム	RealtimeLineChart RealtimeHistogram RealtimeSwarmChart RealtimeWaterfallChart RealtimeHeatmap
連携	LinkedCharts
レイアウト	ChartGrid ContextLayout CategoryColorProvider
フレーム	StreamXYFrame StreamOrdinalFrame StreamNetworkFrame StreamGeoFrame

Vega-Lite の変換

Vega-Lite の仕様を貼り付けると、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" />

棒、折れ線、面、ポイント、矩形、弧、目盛りマークに対応し、色、サイズ、集計、ビニングのエンコーディングを変換します。

会話アークのテレメトリ

AI 支援によるチャートセッションでたどった経路を記録して再生できます：

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

バンドルサイズ

Semiotic は、安定版の JavaScript エントリーポイントを 41 個（サブパス 40 個とルート）提供します。すべてが必要な場合を除き、"semiotic" からインポートしないでください。チャートやツールに合った、最小のサブパスを使用してください。

カスタムネットワークレイアウトでは、semiotic/network/zoom を通じて仮想ズーム／パンビューポートを利用できます。ZoomableNetworkCustomChart と、投影サイズ／LOD フックをエクスポートします。通常のチャートインポートには、ジェスチャーと LOD のランタイムは含まれません。

以下の数値はファーストパーティ成果物のコスト、つまり各サブパスにおける Semiotic 独自コードの gzip 圧縮サイズです。React やその他のランタイム依存関係は含まれません。また、各行には、そのエントリから到達可能なすべてのチャンクが含まれます。オンデマンドでのみ読み込まれるコードも対象となるため、アプリケーションの初回バンドルサイズを予測する値ではありません。アプリのサイズを見積もるために成果物の行を合算しないでください。依存関係の解決やインポート間の重複排除は利用側のバンドラーで行われ、以下で別途計測されます。

エントリーポイント	gzip	内容
semiotic/atlas	322 KB	Motif Braid、Dependency Forest、Flow Circuit のリーダー
semiotic/atlas/core	15 KB	Network Atlas の準備、投影、エビデンスクエリ
semiotic/access	31 KB	Chart Access Contract ファクトリーと初期段階のベースラインコントラクト
semiotic/evidence	47 KB	Chart Evidence Envelope、決定論的ハッシュ、公開ゲート
semiotic/artifact	125 KB	レンダラーに依存しないコントラクト、クレーム、時間、ポリシー、グラウンディング、転送監査
semiotic/artifact/react	4 KB	アーティファクトコントラクトとポリシー評価のための、アクセシブルな段階的開示
semiotic/line	145 KB	LineChart のみ — 1 チャートのマイクロ境界
semiotic/xy	183 KB	LineChart、AreaChart、Scatterplot、Heatmap、その他 8 種類の XY チャート
semiotic/ordinal	134 KB	BarChart、PieChart、BoxPlot、Histogram、その他 11 種類のカテゴリーチャート
semiotic/network	180 KB	ForceDirectedGraph、SankeyDiagram、ProcessSankey、Treemap、その他 4 種類
semiotic/network/zoom	190 KB	任意の仮想ネットワークビューポート、カメラコントロール、コンシューマーが管理する LOD
semiotic/network/perspective	2 KB	アイソメトリックピクトグラムとアクセシブルなパースペクティブ切り替え（このプロパティは ./network に同梱）
semiotic/network/perspective/core	3 KB	投影のサイズ設定、解像度、SVG 配置用ヘルパー
semiotic/vite	1 KB	未使用の Semiotic ワーカーアセット向けビルドプラグイン
semiotic/geo	111 KB	ChoroplethMap、FlowMap、DistanceCartogram、ProportionalSymbolMap
semiotic/realtime	216 KB	RealtimeLineChart、RealtimeHistogram、その他 4 種類のストリーミングチャート
semiotic/realtime/core	214 KB	ストリーミングチャートの型、HOC、バッファーヘルパー
semiotic/realtime/react	2 KB	ストリーム状態と同期プッシュ用フック
semiotic/server	278 KB	renderChart、renderDashboard、renderToImage、renderToAnimatedGif
semiotic/server/node	278 KB	renderChart、renderDashboard、renderToImage、renderToAnimatedGif
semiotic/server/edge	284 KB	renderChart、renderChartWithEvidence、renderToStaticSVG、renderDashboard
semiotic/utils	112 KB	ThemeProvider、数値／アクセシビリティ監査、シリアライズ — チャートコンポーネントなし
semiotic/utils/core	102 KB	純粋なテーマヘルパー、数値／アクセシビリティ監査、シリアライズ
semiotic/utils/react	10 KB	ThemeProvider、useTheme、useReducedMotion、useHighContrast、useStreamStatus
semiotic/recipes	118 KB	純粋なレイアウト関数（waffle、marimekko、flextree、dagre、…）
semiotic/recipes/core	115 KB	純粋なレイアウト関数（waffle、marimekko、flextree、dagre、…）
semiotic/recipes/react	3 KB	グリフと React レイアウト選択用ヘルパー
semiotic/themes	13 KB	テーマプリセットのみ（tufte、carbon など）
semiotic/themes/core	13 KB	テーマプリセットとトークンヘルパー
semiotic/themes/react	9 KB	ThemeProvider/useTheme とフック
semiotic/data	5 KB	bin、rollup、groupBy、pivot、fromVegaLite
semiotic/value	6 KB	BigNumber — フォーカル値 KPI／スコアカード（SingleValueFrame POC）
semiotic/physics	188 KB	GaltonBoardChart、EventDropChart、UnitPileChart、CollisionSwarmChart、PacketFlowChart、PhysicsCustomChart
semiotic/physics/matter	1 KB	Matter.js 移行ヘルパーと任意のピア依存関係ガード（チャートコンポーネントなし）
semiotic/physics/rapier	1 KB	Rapier のピア依存関係ガードとアダプターの判断メタデータ（チャートコンポーネントなし）
semiotic/ai	668 KB	スキーマに対応したすべてのチャートと検証 — LLM によるコード生成に最適化
semiotic/ai/core	143 KB	suggestCharts、auditData、describeChart、repairChartConfig、ツールアダプター — チャートコンポーネントなし
semiotic/controls	19 KB	DirectManipulationControl、CircularBrush、LinearBrush、MobileStandardControls、auditVisualizationControls — フレームレンダラーなし
semiotic/rough	3 KB	任意の決定論的 Rough.js ペイントバックエンド — Semiotic の正確なジオメトリが引き続き優先されます
semiotic/text	2 KB	任意の Pretext 注釈フック — ピアパッケージは除外
semiotic	429 KB	チャート API 全体と共有ユーティリティ

コールド状態のコンシューマーによる名前付きインポート

上の表は、ファーストパーティアーティファクトのコストであり、アプリケーションバンドルではありません。以下に生成される表は別のものを測定しています。コード分割を使用し、アプリケーションのビルドと同様に、パッケージ化された semiotic tarball の公開エクスポート経路を通じて、保持された名前付きインポートを1つだけ、新しいコンシューマーがバンドルした場合のサイズです。初回読み込みは、チャートがレンダリングされる前にページがダウンロードするものです。オンデマンドは、機能が必要になった場合にのみ取得されるコードです。Semiotic と解決済みのランタイム依存関係を含みますが、ホストアプリケーションが所有する React／React DOM とオプションのアダプターピア依存関係は外部化されます。各行はコールド状態から始まるため、アプリケーションの各行を合算するのではなく、公開インポートの選択肢を1つずつ比較するために使用してください。確認済みの機械可読ベースラインは benchmarks/setup/cold-consumer-imports.json です。本番ビルド後に npm run docs:cold-consumer で更新してください。

方法：新しい npm pack --ignore-scripts tarball → 一時的なコンシューマー → コード分割と本番用 NODE_ENV を使用した、圧縮・ツリーシェイク済みの Rolldown（Vite のバンドラー）による ESM ビルド → ファイルごとに gzip -9 で圧縮します。初回読み込みには、エントリーと静的にインポートされるチャンクが含まれます。オンデマンドには、機能が必要になった場合にのみ取得されるチャンク（ブラッシング、マージナルグラフィックス、アニメーション付きトランジション、ベアフレームの組み込みレイアウト）が含まれます。React／React DOM とオプションのアダプターピア依存関係は外部化されます。Semiotic と解決済みのランタイム依存関係は含まれます。

Public named import	Runtime	gzip initial load	gzip on demand
import { semioticVite } from "semiotic/vite"	node	0.6 KiB	—
import { getNetworkPerspectiveSize } from "semiotic/network/perspective/core"	browser	1.1 KiB	—
import { MotifBraidChart } from "semiotic/atlas"	browser	109.8 KiB	29.3 KiB
import { prepareNetworkAtlas } from "semiotic/atlas/core"	browser	7.1 KiB	—
import { LineChart } from "semiotic"	browser	122.5 KiB	44.2 KiB
import { LineChart } from "semiotic/xy"	browser	122.1 KiB	32.2 KiB
import { LineChart } from "semiotic/line"	browser	122.3 KiB	32.2 KiB
import { BarChart } from "semiotic/ordinal"	browser	103.6 KiB	14.7 KiB
import { SankeyDiagram } from "semiotic/network"	browser	133.4 KiB	6.6 KiB
import { ZoomableNetworkCustomChart } from "semiotic/network/zoom"	browser	113.0 KiB	29.3 KiB
import { isometricGlyphs } from "semiotic/network/perspective"	browser	1.4 KiB	—
import { RealtimeLineChart } from "semiotic/realtime"	browser	119.5 KiB	42.0 KiB
import { RingBuffer } from "semiotic/realtime/core"	browser	0.7 KiB	13.6 KiB
import { useStreamStatus } from "semiotic/realtime/react"	browser	0.6 KiB	—
import { GaltonBoardChart } from "semiotic/physics"	browser	94.4 KiB	2.7 KiB
import { MATTER_PHYSICS_CAPABILITIES } from "semiotic/physics/matter"	browser	0.1 KiB	—
import { RAPIER_PHYSICS_CAPABILITIES } from "semiotic/physics/rapier"	browser	0.2 KiB	—
import { renderChart } from "semiotic/server"	node	298.0 KiB	—
import { generateFrameSVGs } from "semiotic/server/edge"	node	127.3 KiB	—
import { renderToImage } from "semiotic/server/node"	node	298.4 KiB	0.6 KiB
import { suggestCharts } from "semiotic/ai"	browser	37.9 KiB	13.6 KiB
import { suggestCharts } from "semiotic/ai/core"	browser	32.0 KiB	—
import { buildArtifactContract } from "semiotic/artifact"	browser	4.5 KiB	—
import { ArtifactInspector } from "semiotic/artifact/react"	browser	3.7 KiB	—
import { createChartAccessContract } from "semiotic/access"	browser	27.9 KiB	—
import { toEvidenceEnvelope } from "semiotic/evidence"	browser	43.5 KiB	—
import { bin } from "semiotic/data"	browser	0.9 KiB	—
import { ChoroplethMap } from "semiotic/geo"	browser	107.0 KiB	1.7 KiB
import { usePretextAnnotations } from "semiotic/text"	browser	1.5 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	6.2 KiB	—
import { validateProps } from "semiotic/utils"	browser	10.0 KiB	—
import { smartTickFormat } from "semiotic/utils/core"	browser	1.1 KiB	—
import { useReducedMotion } from "semiotic/utils/react"	browser	0.3 KiB	—
import { waffleLayout } from "semiotic/recipes"	browser	1.6 KiB	—
import { waffleLayout } from "semiotic/recipes/core"	browser	1.6 KiB	—
import { Glyph } from "semiotic/recipes/react"	browser	0.8 KiB	—
import { BigNumber } from "semiotic/value"	browser	5.8 KiB	—
import { DirectManipulationControl } from "semiotic/controls"	browser	1.5 KiB	—

**行境界の解釈：**保持された semiotic/line からの名前付きインポートは、生のサイズが 364.8 KiB で、semiotic/xy と同じです。gzip 圧縮時の差は 0.1 KiB（0.1%）です。ツリーシェイキングにより、どちらのパスも同じ LineChart 実装グラフに収束します。semiotic/line は、アプリケーションバンドルの削減ではなく、より限定的な API／直接 ESM の成果物境界として扱ってください。パッケージ化された名前付きインポートが、ファミリーパスより gzip 圧縮時に 10 KiB かつ 7% 軽くならない限り、チャートごとのエントリを追加しないでください。

d3 のパッケージ化モデル： Semiotic はインポートする d3 モジュール 12 個を外部化し、通常のランタイム依存関係として宣言します。利用者が d3 パッケージを手動でインストールする必要はありません。バンドラーが依存関係グラフを解決、重複排除し、ツリーシェイキングします。パッケージ化された webpack の比較では、代表的なチャートファミリー 4 つのうち 3 つでこのモデルが優位となり、Next 16 の webpack ルートでは、完全にバンドルする方式より gzip 圧縮時に 22.7 KiB 小さくなりました。バンドル方式が優位だった唯一の例は Sankey で、その差は gzip 圧縮時にわずか 0.4 KiB でした。この選択により、22 パッケージ、展開時 1.9 MB の d3 インストール依存関係を保持する代わりに、一般的なアプリケーショングラフを小さくし、通常の依存関係として扱えます。確認済みのポリシーは npm run check:d3-packaging です。再現可能な根拠は benchmarks/setup/d3-packaging.json にあり、隔離されたツールチェーンディレクトリに webpack と Next をインストールした後、npm run measure:d3-packaging -- --toolchain-root <dir> で再生成できます。

// 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"

ツリーシェイキングと複数サブパスのインポート：ファミリーエントリ（semiotic/xy、semiotic/network、semiotic/ai など）は、共有チャンクを含む 1 つの ESM グラフとしてビルドされます。ストリームフレーム、レンダラー、その他の共通コードは一度だけ出荷され、必要とする各エントリからインポートされます。そのため、semiotic/ai ＋ semiotic/xy ＋ semiotic/network を組み合わせても、ランタイムの完全なコピーを 3 つ分使うことにはなりません。このパッケージは "sideEffects": false とマークされているため、最新のバンドラーは保持する名前付きエクスポート（例：LineChart ＋ suggestCharts）だけを残します。明確さを優先する場合はファミリーのサブパスを使用してください。チャートカタログが不要なら、AI ヘルパーは semiotic/ai または、より軽量な semiotic/ai/core からインポートしてください。

"semiotic" を使う場合：異なるファミリーをまとめて 1 つのインポートにしたい場合に適しています。共有チャンクにより、ファミリーのサブパス間でランタイムコードが重複することはありません。単一の名前付きインポートについては、上のコールドコンシューマー表がより適切な目安です。

CommonJS 互換性に関する注意： require("semiotic/xy") は、ファミリー間で React コンテキストをシングルトンとして保つため、共有の CommonJS クライアントバンドル（圧縮前で約 2.1 MB）を読み込みます。バンドルサイズが重要な場合、ブラウザビルドでは ESM インポートを優先してください。コンテキストの同一性を保証する契約なしにこの CJS クライアントを分割するのは安全ではありません。

TypeScript

strict: true でビルドされています。型定義はパッケージに同梱されています。 型安全なアクセサーのためのジェネリクス：

interface Sale { month: number; revenue: number }

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

サーバーサイドレンダリング

すべてのチャートコンポーネントは、サーバー環境で SVG を自動的にレンダリングします。特別なインポートや設定は必要ありません。ストリーミングを行わないチャート HOC は、Next.js Server Component から直接インポートしてレンダリングできます。Semiotic の "use client" ディレクティブがパッケージ境界を定義するため、インポート元のページに独自のラッパーやディレクティブは必要ありません。この境界を越える Props はシリアライズ可能なままにする必要があります。フック、コールバック Props、ブラウザーの状態、またはプッシュ駆動型のストリーミングチャートを導入する場合に限り、アプリ側でクライアントラッパーを追加してください。

// 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" />
}

単独の SVG／PNG／GIF 生成（メール、OG 画像、PDF、Slack）には、サーバーエントリーポイントを使用してください。

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

MCP サーバー

mcp-name: io.github.nteract/semiotic

Semiotic には MCP サーバー が付属しています。AI コーディングアシスタントは、ツール呼び出しを通じてチャートをレンダリングし、設定の問題を診断し、スキーマを検出し、パッケージに含まれる AI ガイダンスを読み取り、チャートの推奨を取得できます。

セットアップ

MCP クライアントの設定に追加します（例：Claude Desktop の場合は claude_desktop_config.json）。

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

ローカルの stdio では、API キーや認証は不要です。インスペクター、ウェブクライアント、ChatGPT Apps SDK の実験向けに HTTP モードも利用できます：npx -y -p semiotic semiotic-mcp --http --port 3001。デフォルトでは 127.0.0.1 にバインドされ、バインド先のホスト名（およびループバック用の localhost）のみを受け付けます。ブラウザーからのリクエストには、MCP_ALLOWED_ORIGINS=http://localhost:5173 のように、オリジンの許可リストを明示する必要があります。指定しない場合、Origin を含むリクエストはすべて 403 で拒否されます。Origin を省略するネイティブ MCP クライアントは引き続き動作します。3.7.2 以降、HTTP モードはステートレスです。リクエストごとに読み取り専用の MCP サーバーとトランスポートが新たに作成されるため、セッションの固定化なしでサーバーレスホスト上で自動スケーリングできます。

ChatGPT の開発者モードでは、トンネルを使って HTTP エンドポイントを HTTPS 経由で公開し、MCP_ALLOWED_HOSTS にトンネルのホスト名を設定して、https://<your-tunnel>/mcp を指定するコネクターを作成します。公開インターフェースを使用する場合は、--host 0.0.0.0 または MCP_HOST=0.0.0.0 を明示し、提供するホスト名を MCP_ALLOWED_HOSTS に設定してください。すべてのインターフェースにバインドしても、設定するまでは許可される Host 値はループバックのみです。どちらの許可リストもカンマ区切りで、プリフライト、ヘルスチェック、MCP の処理より前に検証されます。CORS では、明示的に許可されたオリジンのみを返します。ワイルドカードのオリジンはサポートされていません。トランスポートのリクエストにベアラートークンを必須とする場合は、MCP_AUTH_TOKEN を設定してください。実験的な Apps SDK の機能は renderInteractiveChart です。これは、text/html;profile=mcp-app のウィジェットテンプレートと、MCP サーバー上で Semiotic によってレンダリングされる非表示の SVG ペイロードを返します。

ホスト型デプロイについては、deploy/cloud-run を参照してください。ラッパーは公開済みの semiotic-mcp バイナリーを実行し、/mcp とヘルスチェック用エンドポイントを公開します。また、本番環境での ホストヘッダー許可リストとして MCP_ALLOWED_HOSTS をサポートします。ChatGPT Apps のドメイン検証では、 OPENAI_APPS_CHALLENGE_TOKEN を設定すると、HTTP モードが /.well-known/openai-apps-challenge から生のトークンを提供します。

5 つのツールからなる公開インターフェースには --profile=public を使用します。オプションの値を 分けて指定することもできます。明示的に指定した無効なプロファイルや不正な形式のオプションがある場合、起動は中止されます。どちらの プロファイルとトランスポートも、デフォルトで MCP_MAX_TOOL_OUTPUT_BYTES によりツールの完全なレスポンスを 2 MiB に制限し、 上限を超える結果には明示的なエラーを返します。

ツール

ツール	説明
renderChart	Semiotic チャートを静的な SVG にレンダリングします。[renderable] とマークされた getSchema が返すコンポーネントをサポートします。{ component: "LineChart", props: { data: [...], xAccessor: "x", yAccessor: "y" } } を渡します。SVG 文字列に加えて、「Render evidence」JSON ブロック（シーンタイプ別のマーク数、解決済みの軸ドメイン、空かどうかのフラグ、注釈数、アクセシブルな名前）が返されるため、エージェントはチャートにデータマークが描画されたことを確認できます。または、修正案付きの検証エラーが返されます。
renderInteractiveChart	静的データのチャートを ChatGPT Apps ウィジェットとしてレンダリングします。renderChart と同じ Semiotic サーバーレンダリング経路を使った後、フィット、ズーム、データ、ホバー、レンダリング証拠のコントロールを備えた iframe UI をハイドレートします。
getSchema	特定のコンポーネントのプロパティスキーマを返します。{ component: "LineChart" } を渡すとそのプロパティが返されます。component を省略すると、スキーマに含まれるカタログ全体が一覧表示されます。[renderable] とマークされたコンポーネントは renderChart から利用できます。リアルタイムチャートにはブラウザー／ライブ環境が必要です。
suggestChart	サンプル行に基づく推奨ツールです。1～5 個のサンプルオブジェクトを含む { data: [{...}, ...] } と、任意の大まかな意図／機能フィルターを渡します。
suggestCharts	行数に上限のあるデータ向けの、機能ベースの推奨ツールです。スコア、理由、注意事項、インポートパス、すぐに使えるプロパティを含む、順位付けされたチャート候補を返します。
suggestStreamCharts	スキーマ（形状、キー、スループット）からストリーミングチャートを推奨します。{ suggestions, excluded, stretchSuggestions } を返します。
suggestStreamDashboard	ストリームスキーマと対象者向けのレイアウトポリシーから、複数パネルのダッシュボードを構成します。
suggestDashboard	異なる分析意図をカバーする、複数パネルのダッシュボード案を作成します。
suggestStretchCharts	AudienceProfile から、対象者のリテラシーを高めるためのチャート候補を推奨します。
repairChartConfig	指定されたチャートがデータセットに適合するかを確認し、適合しない場合は順位付けされた代替案を返します。
interrogateChart	任意の注釈を付けて自然言語の質問に回答するため、統計的な概要とチャートに対応したコンテキストを返します。
diagnoseConfig	空のデータ、無効な寸法、アクセサーの不足、データ形状の不一致など、チャート設定の一般的な問題を確認します。実行可能な修正案を含む、読みやすい診断レポートを返します。
reportIssue	バグ報告や機能リクエスト用に、入力済みの GitHub issue URL を生成します。{ title: "...", body: "...", labels: ["bug"] } を渡します。ユーザーが開いて送信できる URL が返されます。
applyTheme	名前付きテーマプリセットを一覧表示するか、{ name: "tufte" } などのプリセットに対応する ThemeProvider／CSS／トークンの使用方法を返します。
auditArtifact	不足しているソース、レビュー、タイミングの事実を推測せず、名前付きポリシーに基づいて明示的なアーティファクト契約を評価します。
recommendRepresentation	提供されたデータ、主張、証拠、時間状態、ポリシー要件に照らして、チャートと非チャートの結果を比較します。
repairArtifact	契約の修正を提案し、任意で不足している識別フィールドを補います。既存の不一致を解消するには、改訂と主張の再評価が必要です。
explainRefusal	公開や実行を妨げている明示的なポリシー上の義務を説明し、安全に続行できる作業を特定します。

アーティファクトツールはオプトインの診断ツールであり、公開の許可を与えるものではありません。 conditional の結果（CLI の終了コードが 0 の場合を含む）でも、未完了の作業は残ります。通常の renderChart 呼び出しではアーティファクトポリシーは適用されません。ガバナンスを担うホストは、 独自のリリース境界を適用する必要があります。手動確認の解決と、改訂に紐づくリリース承認は、 ホストのワークフローにおいてそれぞれ独立した作業です。

リソース

リソース	説明
semiotic://artifact-contract-schema	用途、主張、エビデンス、タイミング、レビュー、転送のメタデータをポータブルに扱うための、単独で利用できる JSON Schema です。
semiotic://schema	機械可読な全コンポーネントのスキーマ JSON です。
semiotic://schema-index	カテゴリ、レンダリング可否、インポートパス、各コンポーネントのスキーマリソース URI を含む、簡潔な検索用インデックスです。
semiotic://schema/{component}	各コンポーネントのスキーマ、メタデータ、アクセシビリティに関するガイダンス、動作契約です（例：semiotic://schema/LineChart）。
semiotic://components	レンダリング可能かブラウザー専用かのステータスと MCP カテゴリを示す、下位互換性のあるコンポーネントインデックスです。
semiotic://surface-manifest	現在の AI スキーマ、エクスポート、レンダリング可否、ツール、リソース、プロンプトの生成済みインベントリです。
semiotic://behavior-contracts	色の優先順位、必須のプロパティの組み合わせ、プッシュ参照、レンダリング可否に関する、エージェントが参照できるセマンティックルールです。
semiotic://system-prompt	インポートルール、グラフのプロパティ、SSR に関するガイダンス、注意点を含む簡潔な AI 向け指示です。
semiotic://examples	データ形状別のコピーして使えるグラフの例です。
ui://semiotic/chart-widget.html	renderInteractiveChart が使用する、ChatGPT Apps／MCP Apps ウィジェットのテンプレートです。

プロンプト

プロンプト	説明
build-semiotic-chart	グラフの選択、スキーマの確認、プロパティの診断、プレビューのレンダリングに使える再利用可能なワークフローです。
debug-semiotic-chart	無効なプロパティ、レンダリングの失敗、問題の報告をデバッグするための再利用可能なワークフローです。

例：コンポーネントのスキーマを取得する

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

例：データに適したグラフを提案する

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

例：グラフをレンダリングする

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>

例：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.

ウィジェットの SVG は埋め込み前に、要素、属性、CSS、URL の許可リストに基づいて再構築されます。ローカルフラグメント参照とインラインの base64 PNG／JPEG／GIF／WebP 画像はサポートされています。外部リソース、SVG データ URL、スクリプト、外部 HTML、アニメーション、CSS インポート、font-face ルールは削除されます。許可されたスタイルはグラフ内にスコープされ、自動的なダークパレットと注釈の開示を維持します。テーマ変数では、色、長さ、フォント、その他サポートされているトークン文法が使用されます。不正な SVG の場合、空のプレビューを成功として返すのではなく、明示的なツールエラーが返されます。ウィジェットのホスト CSP によって、さらに境界が設けられます。

例：壊れた設定を診断する

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

例：問題を報告する

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?...

CLI の代替方法

MCP クライアントを使わずに素早く検証するには：

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

dist が利用可能な場合、--doctor は diagnoseConfig のすべてのチェックを実行し、クリーンなソースチェックアウトではスキーマのみの検証にフォールバックします。

AI アシスタント向けの Semiotic の参照先

Semiotic は AI コーディングエージェント向けのドキュメントツールに登録されているため、アシスタント（Claude Code、Cursor、Cline、Copilot など）はコピー＆ペーストせずに最新のドキュメントやツールを取得できます。

• Context7 — context7.com/nteract/semiotic（context7.json で設定）
• DeepWiki — deepwiki.com/nteract/semiotic
• GitMCP — gitmcp.io/nteract/semiotic（リポジトリを MCP エンドポイントとして直接公開）
• Official MCP Registry — registry.modelcontextprotocol.io で「semiotic」を検索

Official MCP Registry は正式な MCP ディレクトリの登録先であり、アシスタントベンダーが厳選するコネクタディレクトリへの掲載とは別のものです。 セカンダリディレクトリの情報の鮮度とリリース管理については MCP_DISTRIBUTION.md で管理しています。

エージェント向け API の概要：

• AGENTS.md はリポジトリ開発に関する簡潔な規約であり、CLAUDE.md は Claude Code 用にこれを読み込みます。これらはリポジトリ内に置かれ、パッケージ利用者に関係のないコントリビューター向けの指示を配布しないようにしています。
• ai/reference.md、ai/schema.json、ai/surface-manifest.json、ai/behaviorContracts.cjs、agent-skill/semiotic-charts/SKILL.md は npm tarball に含まれています（package.json#files を参照）。リファレンスは npx -p semiotic semiotic-ai で出力される、必要に応じて参照する製品ガイドです。スキーマ、マニフェスト、コントラクト、ポータブルスキルは、構造化された生成と検証のガイダンスを提供します。
• semiotic.nteract.io/llms.txt + /llms-full.txt — llms.txt standard に従ってドキュメントサイトにデプロイされています。エージェントは HTTP 経由でナビゲーションマップ（llms.txt）またはドキュメント全体をインライン化したもの（llms-full.txt）を取得します。これらは npm パッケージ自体には含まれていません。

ドキュメント

インタラクティブなドキュメントと例

• はじめに
• チャート — ライブ例付きのチャートタイプ
• フレーム — Frame API の完全なリファレンス
• 機能 — 軸、ツールチップ、インタラクション、レスポンシブ動作、構成
• 注釈 — 第一級の注釈タイプ、デザインガイダンス、プロベナンス、ライフサイクル
• クックブック — 高度なパターンとレシピ
• プレイグラウンド — インタラクティブなプロパティの試行

アップグレード

• 移行ガイド — v1.x または v2.x からのアップグレード
• 変更履歴 — リリース履歴の全記録

コントリビューション

CONTRIBUTING.md を参照してください。コミュニティでは、nteract の 行動規範に従っています。

謝辞

このライブラリの開発は、Susie Lu、Jason Reid、James Womack、 Matt Herman、Shelby Sturgis、Tristan Reid の多大な貢献によって支えられています。

Sankey レイアウトエンジンは、Tom Shanley による sankey-plus をベースにしています。これは、以前の d3-sankey-circular を改良し、サイクル検出の改善、階層的なアークの積み重ね、 動的な範囲調整を実現しています。

Semiotic のアイコンは Andre Schauer によるアイコンをベースにしています。

ライセンス

Apache 2.0