vizmatic 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/PROMPT.md +500 -0
- package/README.md +530 -0
- package/dist/chunk-ADU7JROD.js +627 -0
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +303 -0
- package/dist/index.d.ts +1433 -0
- package/dist/index.js +4702 -0
- package/docs/PROMPT.md +500 -0
- package/docs/assets/examples/.gitkeep +1 -0
- package/docs/assets/examples/agent-pipeline_dark.png +0 -0
- package/docs/assets/examples/agent-pipeline_light.png +0 -0
- package/docs/assets/examples/animated-pipeline_dark.gif +0 -0
- package/docs/assets/examples/animated-pipeline_dark.png +0 -0
- package/docs/assets/examples/animated-pipeline_light.gif +0 -0
- package/docs/assets/examples/animated-pipeline_light.png +0 -0
- package/docs/assets/examples/attention-head_dark.png +0 -0
- package/docs/assets/examples/attention-head_light.png +0 -0
- package/docs/assets/examples/embedding-map_dark.png +0 -0
- package/docs/assets/examples/embedding-map_light.png +0 -0
- package/docs/assets/examples/eval-dashboard_dark.png +0 -0
- package/docs/assets/examples/eval-dashboard_light.png +0 -0
- package/docs/assets/examples/gif-manifest.json +12 -0
- package/docs/assets/examples/manifest.json +108 -0
- package/docs/assets/examples/model-router_dark.png +0 -0
- package/docs/assets/examples/model-router_light.png +0 -0
- package/docs/assets/examples/presentation-frame_dark.png +0 -0
- package/docs/assets/examples/presentation-frame_light.png +0 -0
- package/docs/assets/examples/rag-graph_dark.png +0 -0
- package/docs/assets/examples/rag-graph_light.png +0 -0
- package/docs/assets/examples/release-card_dark.png +0 -0
- package/docs/assets/examples/release-card_light.png +0 -0
- package/docs/assets/examples/research-landscape_dark.png +0 -0
- package/docs/assets/examples/research-landscape_light.png +0 -0
- package/docs/assets/examples/sources.json +93 -0
- package/docs/assets/examples/spec-anatomy_dark.png +0 -0
- package/docs/assets/examples/spec-anatomy_light.png +0 -0
- package/docs/assets/examples/theme-system_dark.png +0 -0
- package/docs/assets/examples/theme-system_light.png +0 -0
- package/docs/assets/examples/token-matrix_dark.png +0 -0
- package/docs/assets/examples/token-matrix_light.png +0 -0
- package/docs/assets/icon.svg +16 -0
- package/docs/assets/logo.svg +30 -0
- package/examples/agent-pipeline.tsx +27 -0
- package/examples/animated-pipeline.tsx +72 -0
- package/examples/attention-head.tsx +27 -0
- package/examples/embedding-map.tsx +34 -0
- package/examples/eval-dashboard.tsx +44 -0
- package/examples/model-router.tsx +35 -0
- package/examples/presentation-frame.tsx +32 -0
- package/examples/rag-graph.tsx +36 -0
- package/examples/release-card.tsx +39 -0
- package/examples/research-landscape.tsx +34 -0
- package/examples/spec-anatomy.tsx +44 -0
- package/examples/theme-system.tsx +30 -0
- package/examples/token-matrix.tsx +49 -0
- package/package.json +84 -0
package/README.md
ADDED
|
@@ -0,0 +1,530 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="docs/assets/logo.svg" alt="Vizmatic logo" width="460" />
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
<strong>Theme-aware visuals from structured scenes.</strong><br/>
|
|
7
|
+
Give AI agents typed primitives. Get polished diagrams, figures, dashboards, slide frames, and animated GIFs.
|
|
8
|
+
</p>
|
|
9
|
+
|
|
10
|
+
<p align="center">
|
|
11
|
+
<a href="https://github.com/bvolpato/vizmatic/actions/workflows/ci.yml"><img src="https://github.com/bvolpato/vizmatic/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
|
|
12
|
+
<a href="https://github.com/bvolpato/vizmatic/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
|
|
13
|
+
<a href="https://www.npmjs.com/package/vizmatic"><img src="https://img.shields.io/npm/v/vizmatic?color=%2334d058" alt="npm version" /></a>
|
|
14
|
+
</p>
|
|
15
|
+
|
|
16
|
+
<p align="center">
|
|
17
|
+
<img src="docs/assets/examples/animated-pipeline_dark.gif" alt="Vizmatic animated render pipeline" width="760" />
|
|
18
|
+
</p>
|
|
19
|
+
|
|
20
|
+
<p align="center">
|
|
21
|
+
<a href="https://bvolpato.github.io/vizmatic/">Website</a> ·
|
|
22
|
+
<a href="examples">Examples</a> ·
|
|
23
|
+
<a href="PROMPT.md">Agent Prompt</a> ·
|
|
24
|
+
<a href="#quick-start">Quick Start</a> ·
|
|
25
|
+
<a href="#why-vizmatic">Why Vizmatic</a> ·
|
|
26
|
+
<a href="#api">API</a>
|
|
27
|
+
</p>
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Quick Start
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
pnpm add vizmatic react
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
If npm has not been published yet, install from GitHub:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
pnpm add github:bvolpato/vizmatic react
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Create a frame:
|
|
44
|
+
|
|
45
|
+
```tsx
|
|
46
|
+
import React from "react"
|
|
47
|
+
import { defineIllustration, Flow, Scene } from "vizmatic"
|
|
48
|
+
|
|
49
|
+
export const width = 1040
|
|
50
|
+
export const height = 560
|
|
51
|
+
|
|
52
|
+
const frame = defineIllustration((c) => (
|
|
53
|
+
<Scene c={c} title="Agent visual pipeline">
|
|
54
|
+
<Flow
|
|
55
|
+
c={c}
|
|
56
|
+
stages={[
|
|
57
|
+
{ title: "Prompt", subtitle: "intent", tone: "blue" },
|
|
58
|
+
{ title: "Scene spec", subtitle: "typed structure", tone: "purple" },
|
|
59
|
+
{ title: "PNG / SVG / GIF", subtitle: "rendered artifact", tone: "green" },
|
|
60
|
+
]}
|
|
61
|
+
/>
|
|
62
|
+
</Scene>
|
|
63
|
+
))
|
|
64
|
+
|
|
65
|
+
export const create = frame.create
|
|
66
|
+
export default frame.default
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Render it:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
vizmatic render ./frame.tsx --out ./dist/frames --theme dark,light --watermark "Acme" --watermark-image ./logo.svg
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Render an animation:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
vizmatic gif ./animated-frame.tsx --out ./dist/frames --theme dark,light --watermark "Acme" --watermark-image ./logo.svg
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Or call the renderer directly:
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
import { renderToPng } from "vizmatic"
|
|
85
|
+
import { create, width, height } from "./frame"
|
|
86
|
+
|
|
87
|
+
await renderToPng(create("dark"), {
|
|
88
|
+
width,
|
|
89
|
+
height,
|
|
90
|
+
outputPath: "dist/agent-pipeline.png",
|
|
91
|
+
watermark: { text: "Acme", image: "data:image/svg+xml;base64,...", position: "top-right" },
|
|
92
|
+
})
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Why Vizmatic
|
|
96
|
+
|
|
97
|
+
Models can write structure reliably. They are worse at raw SVG path work, fragile coordinate math, and one-off design choices.
|
|
98
|
+
|
|
99
|
+
Vizmatic gives them a constrained visual language:
|
|
100
|
+
|
|
101
|
+
| Need | Vizmatic answer |
|
|
102
|
+
|---|---|
|
|
103
|
+
| Rich educational illustrations | React primitives rendered through Satori and resvg |
|
|
104
|
+
| Theme-aware output | Semantic tones and dark/light theme tokens |
|
|
105
|
+
| Agent-friendly authoring | JSX scene modules with simple props |
|
|
106
|
+
| Reproducible artifacts | Pure Node render path, no browser required |
|
|
107
|
+
| Safer generated visuals | Overflow detection, autocrop, wrapping-safe labels |
|
|
108
|
+
| Animated explainers | GIF export from ordered scene states |
|
|
109
|
+
| Docs and decks | Same frame can become article art, report figure, or presentation slide |
|
|
110
|
+
|
|
111
|
+
## Gallery
|
|
112
|
+
|
|
113
|
+
<p>
|
|
114
|
+
<img src="docs/assets/examples/animated-pipeline_dark.gif" alt="Animated pipeline" width="380" />
|
|
115
|
+
<img src="docs/assets/examples/attention-head_dark.png" alt="Attention head" width="380" />
|
|
116
|
+
</p>
|
|
117
|
+
<p>
|
|
118
|
+
<img src="docs/assets/examples/rag-graph_dark.png" alt="RAG graph" width="380" />
|
|
119
|
+
<img src="docs/assets/examples/eval-dashboard_dark.png" alt="Evaluation dashboard" width="380" />
|
|
120
|
+
</p>
|
|
121
|
+
<p>
|
|
122
|
+
<img src="docs/assets/examples/token-matrix_dark.png" alt="Token matrix" width="380" />
|
|
123
|
+
<img src="docs/assets/examples/theme-system_dark.png" alt="Theme system" width="380" />
|
|
124
|
+
</p>
|
|
125
|
+
<p>
|
|
126
|
+
<img src="docs/assets/examples/presentation-frame_dark.png" alt="Presentation frame" width="380" />
|
|
127
|
+
</p>
|
|
128
|
+
|
|
129
|
+
More examples live in [`examples/`](examples) and on the [website](https://bvolpato.github.io/vizmatic/).
|
|
130
|
+
|
|
131
|
+
## Copy-Paste Examples
|
|
132
|
+
|
|
133
|
+
### Minimal flow
|
|
134
|
+
|
|
135
|
+
Use this for small docs snippets and quick agent-generated frames.
|
|
136
|
+
|
|
137
|
+
```tsx
|
|
138
|
+
import { defineIllustration, Flow, Scene } from "vizmatic"
|
|
139
|
+
|
|
140
|
+
export const width = 1040
|
|
141
|
+
export const height = 560
|
|
142
|
+
|
|
143
|
+
const frame = defineIllustration((c) =>
|
|
144
|
+
<Scene c={c} title="Agent pipeline">
|
|
145
|
+
<Flow c={c} stages={[
|
|
146
|
+
{ title: "Prompt", tone: "blue" },
|
|
147
|
+
{ title: "Scene spec", tone: "purple" },
|
|
148
|
+
{ title: "PNG / GIF", tone: "green" },
|
|
149
|
+
]} />
|
|
150
|
+
</Scene>
|
|
151
|
+
)
|
|
152
|
+
|
|
153
|
+
export const create = frame.create
|
|
154
|
+
export default frame.default
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### Flow + callouts
|
|
158
|
+
|
|
159
|
+
Use this for process diagrams, architecture walkthroughs, and agent pipelines.
|
|
160
|
+
|
|
161
|
+
```tsx
|
|
162
|
+
import React from "react"
|
|
163
|
+
import { CalloutCard, defineIllustration, Flow, Row, Scene } from "vizmatic"
|
|
164
|
+
|
|
165
|
+
export const width = 1040
|
|
166
|
+
export const height = 560
|
|
167
|
+
|
|
168
|
+
const frame = defineIllustration((c) => (
|
|
169
|
+
<Scene c={c} title="Agent visual pipeline" subtitle="prompt -> scene spec -> verified artifact" gap={26}>
|
|
170
|
+
<Flow
|
|
171
|
+
c={c}
|
|
172
|
+
connectorTone="purple"
|
|
173
|
+
stages={[
|
|
174
|
+
{ eyebrow: "input", title: "Prompt", subtitle: "intent", tone: "blue", lines: ["goal", "audience", "constraints"], width: 190 },
|
|
175
|
+
{ eyebrow: "contract", title: "Scene spec", subtitle: "typed structure", tone: "purple", lines: ["cards", "flows", "charts"], width: 190 },
|
|
176
|
+
{ eyebrow: "render", title: "Satori", subtitle: "React primitives", tone: "cyan", lines: ["layout", "theme", "safe text"], width: 190 },
|
|
177
|
+
{ eyebrow: "output", title: "PNG / GIF", subtitle: "verified asset", tone: "green", lines: ["autocrop", "overflow checks"], width: 190 },
|
|
178
|
+
]}
|
|
179
|
+
/>
|
|
180
|
+
<Row width="100%" gap={14}>
|
|
181
|
+
<CalloutCard c={c} title="Model writes structure" detail="No hand-written SVG paths." tone="purple" width={470} />
|
|
182
|
+
<CalloutCard c={c} title="Theme stays in control" detail="Colors and typography come from tokens." tone="green" width={470} />
|
|
183
|
+
</Row>
|
|
184
|
+
</Scene>
|
|
185
|
+
))
|
|
186
|
+
|
|
187
|
+
export const create = frame.create
|
|
188
|
+
export default frame.default
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
### Animated GIF
|
|
192
|
+
|
|
193
|
+
Use this for state changes, product flows, lesson steps, and timelines. Static frames export `create(theme)`. Animated frames also export `createScenes(theme)`.
|
|
194
|
+
|
|
195
|
+
```tsx
|
|
196
|
+
import React from "react"
|
|
197
|
+
import {
|
|
198
|
+
CalloutCard,
|
|
199
|
+
defineIllustration,
|
|
200
|
+
Flow,
|
|
201
|
+
Scene,
|
|
202
|
+
getThemeColors,
|
|
203
|
+
type AnimatedScene,
|
|
204
|
+
type ThemeColors,
|
|
205
|
+
type ThemeMode,
|
|
206
|
+
} from "vizmatic"
|
|
207
|
+
|
|
208
|
+
export const width = 1040
|
|
209
|
+
export const height = 560
|
|
210
|
+
|
|
211
|
+
const stages = [
|
|
212
|
+
{ title: "Prompt", tone: "blue" as const },
|
|
213
|
+
{ title: "Scene spec", tone: "purple" as const },
|
|
214
|
+
{ title: "PNG / GIF", tone: "green" as const },
|
|
215
|
+
]
|
|
216
|
+
|
|
217
|
+
function buildFrame(c: ThemeColors, active: number) {
|
|
218
|
+
return (
|
|
219
|
+
<Scene c={c} title="Animated agent pipeline">
|
|
220
|
+
<Flow
|
|
221
|
+
c={c}
|
|
222
|
+
stages={stages.map((stage, index) => ({
|
|
223
|
+
...stage,
|
|
224
|
+
title: index <= active ? stage.title : "Pending",
|
|
225
|
+
tone: index <= active ? stage.tone : "neutral",
|
|
226
|
+
}))}
|
|
227
|
+
/>
|
|
228
|
+
<CalloutCard c={c} title="Scene changes over time" detail="Render with vizmatic gif." tone="green" />
|
|
229
|
+
</Scene>
|
|
230
|
+
)
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
const frame = defineIllustration((c) => buildFrame(c, stages.length - 1))
|
|
234
|
+
|
|
235
|
+
export function createScenes(theme: ThemeMode): AnimatedScene[] {
|
|
236
|
+
const c = getThemeColors(theme)
|
|
237
|
+
return stages.map((_, index) => ({
|
|
238
|
+
element: buildFrame(c, index),
|
|
239
|
+
duration: index === stages.length - 1 ? 1000 : 700,
|
|
240
|
+
transition: index === 0 ? "appear" : "fade",
|
|
241
|
+
}))
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
export const create = frame.create
|
|
245
|
+
export default frame.default
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
```bash
|
|
249
|
+
vizmatic gif ./animated-frame.tsx --out ./dist/frames --theme dark,light --watermark "Acme" --watermark-image ./logo.svg --scale 1
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
### RAG graph
|
|
253
|
+
|
|
254
|
+
Use this for workflows with branches, retries, and validation loops.
|
|
255
|
+
|
|
256
|
+
```tsx
|
|
257
|
+
import React from "react"
|
|
258
|
+
import { defineIllustration, GraphDiagram, Scene } from "vizmatic"
|
|
259
|
+
|
|
260
|
+
export const width = 1040
|
|
261
|
+
export const height = 560
|
|
262
|
+
|
|
263
|
+
const frame = defineIllustration((c) => (
|
|
264
|
+
<Scene c={c} title="RAG control graph" subtitle="retrieval is a graph, not a prompt append" align="center">
|
|
265
|
+
<GraphDiagram
|
|
266
|
+
c={c}
|
|
267
|
+
width={820}
|
|
268
|
+
height={390}
|
|
269
|
+
nodes={[
|
|
270
|
+
{ id: "query", label: "Query", detail: "intent", x: 0.08, y: 0.52, tone: "blue" },
|
|
271
|
+
{ id: "retrieve", label: "Retrieve", detail: "top-k docs", x: 0.40, y: 0.25, tone: "cyan" },
|
|
272
|
+
{ id: "rerank", label: "Rerank", detail: "quality gate", x: 0.68, y: 0.25, tone: "warm" },
|
|
273
|
+
{ id: "answer", label: "Answer", detail: "grounded draft", x: 0.92, y: 0.52, tone: "green" },
|
|
274
|
+
{ id: "verify", label: "Verify", detail: "citations", x: 0.52, y: 0.78, tone: "critical" },
|
|
275
|
+
]}
|
|
276
|
+
edges={[
|
|
277
|
+
{ from: "query", to: "retrieve", label: "search", tone: "blue" },
|
|
278
|
+
{ from: "retrieve", to: "rerank", label: "rank", tone: "cyan" },
|
|
279
|
+
{ from: "rerank", to: "answer", label: "context", tone: "green" },
|
|
280
|
+
{ from: "answer", to: "verify", label: "claims", tone: "critical" },
|
|
281
|
+
{ from: "verify", to: "retrieve", label: "retry", dashed: true, tone: "warm" },
|
|
282
|
+
]}
|
|
283
|
+
/>
|
|
284
|
+
</Scene>
|
|
285
|
+
))
|
|
286
|
+
|
|
287
|
+
export const create = frame.create
|
|
288
|
+
export default frame.default
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
### Evaluation dashboard
|
|
292
|
+
|
|
293
|
+
Use this for compact report figures and release decks.
|
|
294
|
+
|
|
295
|
+
```tsx
|
|
296
|
+
import React from "react"
|
|
297
|
+
import { BarChart, defineIllustration, LineChart, Row, Scene } from "vizmatic"
|
|
298
|
+
|
|
299
|
+
export const width = 1040
|
|
300
|
+
export const height = 620
|
|
301
|
+
|
|
302
|
+
const frame = defineIllustration((c) => (
|
|
303
|
+
<Scene c={c} title="Evaluation snapshot" subtitle="charts inherit theme, labels, and contrast">
|
|
304
|
+
<Row gap={18} align="stretch">
|
|
305
|
+
<BarChart
|
|
306
|
+
c={c}
|
|
307
|
+
width={440}
|
|
308
|
+
height={260}
|
|
309
|
+
title="Pass rate by task"
|
|
310
|
+
format="percent"
|
|
311
|
+
data={[
|
|
312
|
+
{ label: "tools", value: 0.82, color: "positive" },
|
|
313
|
+
{ label: "math", value: 0.71, color: "secondary" },
|
|
314
|
+
{ label: "code", value: 0.77, color: "primary" },
|
|
315
|
+
{ label: "long", value: 0.58, color: "warning" },
|
|
316
|
+
]}
|
|
317
|
+
/>
|
|
318
|
+
<LineChart
|
|
319
|
+
c={c}
|
|
320
|
+
width={440}
|
|
321
|
+
height={260}
|
|
322
|
+
title="Quality over releases"
|
|
323
|
+
format="percent"
|
|
324
|
+
labels={["v1", "v2", "v3", "v4", "v5"]}
|
|
325
|
+
series={[
|
|
326
|
+
{ name: "quality", points: [0.55, 0.61, 0.69, 0.74, 0.81], color: "positive", area: true },
|
|
327
|
+
{ name: "latency", points: [0.72, 0.69, 0.66, 0.62, 0.59], color: "warning" },
|
|
328
|
+
]}
|
|
329
|
+
/>
|
|
330
|
+
</Row>
|
|
331
|
+
</Scene>
|
|
332
|
+
))
|
|
333
|
+
|
|
334
|
+
export const create = frame.create
|
|
335
|
+
export default frame.default
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
## Agent Prompt
|
|
339
|
+
|
|
340
|
+
[`PROMPT.md`](PROMPT.md) is a plug-and-play instruction file for coding agents. It covers install, frame structure, every visual component with props, render commands, examples, quality rules, and final verification.
|
|
341
|
+
|
|
342
|
+
## API
|
|
343
|
+
|
|
344
|
+
### Themes
|
|
345
|
+
|
|
346
|
+
```ts
|
|
347
|
+
import { getThemeColors } from "vizmatic"
|
|
348
|
+
|
|
349
|
+
const dark = getThemeColors("dark")
|
|
350
|
+
const light = getThemeColors("light")
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
Primitives receive `c`, the resolved theme object. This keeps every visual connected to one palette, typography scale, and contrast model.
|
|
354
|
+
|
|
355
|
+
### Component catalog
|
|
356
|
+
|
|
357
|
+
Vizmatic exports a fairly complete visual kit. Common cases should use these primitives before dropping to raw SVG or absolute positioning.
|
|
358
|
+
|
|
359
|
+
#### Frame and layout
|
|
360
|
+
|
|
361
|
+
| Component | Use |
|
|
362
|
+
|---|---|
|
|
363
|
+
| `defineIllustration` | Wraps a theme-aware frame builder and exports `create(theme)` plus a default element. |
|
|
364
|
+
| `Canvas` | Low-level full-frame root with background, padding, and vertical alignment. |
|
|
365
|
+
| `Scene` | Standard frame wrapper with title, subtitle, content column, and theme-aware typography. |
|
|
366
|
+
| `TitleBar` | Shared title/subtitle block used by `Scene`. |
|
|
367
|
+
| `Row` / `Column` | Flex layout primitives with gap, alignment, wrapping, width, and height props. |
|
|
368
|
+
| `Stack` | Layered vertical stack for repeated cards, tokens, or processing layers. |
|
|
369
|
+
|
|
370
|
+
#### Surfaces, labels, and cards
|
|
371
|
+
|
|
372
|
+
| Component | Use |
|
|
373
|
+
|---|---|
|
|
374
|
+
| `Panel` | Titled card surface with tone strip, subtitle, footer, shadow, and body controls. |
|
|
375
|
+
| `Card` | Flexible surface for custom content without a forced title. |
|
|
376
|
+
| `StepCard` | Compact stage card for flows, choices, and process steps. |
|
|
377
|
+
| `MetricCard` | KPI/value card with label, value, detail, tone, and monospace value support. |
|
|
378
|
+
| `CalloutCard` | Highlight block for takeaways, warnings, decisions, and summaries. |
|
|
379
|
+
| `WindowFrame` | Browser/terminal-style framed panel for code, UI, or tool output. |
|
|
380
|
+
| `Box` | Gradient or outlined labeled rectangle with optional icon and sublabel. |
|
|
381
|
+
| `Tile` / `TileGrid` | Uniform repeated tiles with tone, title, detail, and metric layouts. |
|
|
382
|
+
| `Badge` / `BadgePill` | Small labels for status, categories, and annotations. |
|
|
383
|
+
| `ValuePill` | Compact value badge for numbers or short state labels. |
|
|
384
|
+
| `GradientChip` | Small colored chip with gradient fill for legends and tone keys. |
|
|
385
|
+
| `ToneStrip` | Small semantic accent strip for visual grouping. |
|
|
386
|
+
| `TextLabel` | Wrapping-safe text with variant, color, math formatting, width, and alignment. |
|
|
387
|
+
| `MathText` / `formatMathText` | Converts simple `x_i` / `x^2` style strings into readable unicode math text. |
|
|
388
|
+
| `SvgMathText` | SVG text helper for math labels inside custom plots. |
|
|
389
|
+
|
|
390
|
+
#### Arrows, connectors, and SVG helpers
|
|
391
|
+
|
|
392
|
+
| Component | Use |
|
|
393
|
+
|---|---|
|
|
394
|
+
| `Arrow` | Simple directional arrow element. |
|
|
395
|
+
| `FlowArrow` / `Connector` | Theme-aware connector between flow stages. |
|
|
396
|
+
| `VectorArrow` | SVG vector arrow for coordinate-style diagrams. |
|
|
397
|
+
| `VectorSegment` | Labeled segment/vector primitive for geometry and embedding visuals. |
|
|
398
|
+
| `SvgFrame` | SVG container with theme-aware background and border. |
|
|
399
|
+
| `SvgPoint` / `DotPoint` | Point markers with optional labels. |
|
|
400
|
+
| `ArrowMarkerDef` | SVG arrowhead marker definition for custom line charts and graph edges. |
|
|
401
|
+
| `DashedLine` | Dotted/dashed SVG line helper. |
|
|
402
|
+
| `Legend` | Reusable legend block with colored items and optional title. |
|
|
403
|
+
|
|
404
|
+
#### Lists, comparisons, and status blocks
|
|
405
|
+
|
|
406
|
+
| Component | Use |
|
|
407
|
+
|---|---|
|
|
408
|
+
| `DetailList` | Compact repeated detail rows inside panels and flow stages. |
|
|
409
|
+
| `ProgressRow` / `ProgressList` | Progress bars with labels, values, tones, and optional math text. |
|
|
410
|
+
| `StatusRow` / `StatusList` | Check, cross, warning, info, pending, and dot rows. |
|
|
411
|
+
| `KeyValueList` | Structured label/value rows for configs and metadata. |
|
|
412
|
+
| `CodeBlock` | Themed code panel with highlighted lines and optional annotations. |
|
|
413
|
+
| `EquationCard` | Formula card with title, equation, and supporting detail. |
|
|
414
|
+
| `Comparison` | Side-by-side comparison panel with two titled sides and detail rows. |
|
|
415
|
+
|
|
416
|
+
#### Flows, pipelines, and graph diagrams
|
|
417
|
+
|
|
418
|
+
| Component | Use |
|
|
419
|
+
|---|---|
|
|
420
|
+
| `Flow` | Horizontal or vertical staged process diagram with optional detail rows. |
|
|
421
|
+
| `Pipeline` | Process pipeline with stage labels and a shared title. |
|
|
422
|
+
| `LayeredNetwork` | Neural-network/DAG diagram with layers, nodes, active path, annotations, and formula. |
|
|
423
|
+
| `GraphDiagram` | Positioned node-edge graph with labels, dashed/muted edges, and tone-aware nodes. |
|
|
424
|
+
|
|
425
|
+
#### Matrices, tables, and grids
|
|
426
|
+
|
|
427
|
+
| Component | Use |
|
|
428
|
+
|---|---|
|
|
429
|
+
| `Matrix` | Numeric matrix visualization for linear algebra and attention examples. |
|
|
430
|
+
| `Heatmap` | Color-scaled matrix/attention heatmap. |
|
|
431
|
+
| `TiledMatrix` | Matrix with region labels and grouped tiles. |
|
|
432
|
+
| `DataTable` | Compact text table with header rows/columns and monospace cells. |
|
|
433
|
+
| `Grid` | General-purpose cell grid with per-cell label, tone, color, border, and opacity. |
|
|
434
|
+
|
|
435
|
+
#### Charts and plots
|
|
436
|
+
|
|
437
|
+
| Component | Use |
|
|
438
|
+
|---|---|
|
|
439
|
+
| `ChartFrame` | Shared chart wrapper with title, subtitle, footer, and theme-aware shell. |
|
|
440
|
+
| `AxisPlot` | Low-level axis plot for custom lines, paths, and plotted values. |
|
|
441
|
+
| `MiniBarChart` | Small bar chart for cards and dashboards. |
|
|
442
|
+
| `StackedBar` | Segmented horizontal bar with labels and percentages. |
|
|
443
|
+
| `BarChart` | Full bar chart with ticks, labels, values, grids, and formats. |
|
|
444
|
+
| `LineChart` | Multi-series line chart with optional area fill, points, labels, and grid. |
|
|
445
|
+
| `ScatterPlot` | Labeled scatter plot with axes, ticks, point sizing, and collision-aware labels. |
|
|
446
|
+
| `QuadrantChart` | 2x2 decision matrix with regions, labeled points, and axis labels. |
|
|
447
|
+
| `IntervalPlot` | Timeline/range plot for spans, phases, latencies, and schedules. |
|
|
448
|
+
|
|
449
|
+
#### Rendering and verification
|
|
450
|
+
|
|
451
|
+
| API | Use |
|
|
452
|
+
|---|---|
|
|
453
|
+
| `renderToPng` | Render React scene to PNG through Satori and resvg, with optional watermark, crop, scale, and overflow check. |
|
|
454
|
+
| `renderAnimatedGif` | Render ordered `AnimatedScene[]` states to GIF with `fade`, `appear`, or no transition. |
|
|
455
|
+
| `renderToBuffer` | Render PNG to memory for tests and pipelines. |
|
|
456
|
+
| `renderToSvg` | Render SVG markup directly. |
|
|
457
|
+
| `wrapWithWatermark` | Add optional watermark text, image/icon, and position to a frame. |
|
|
458
|
+
| `detectBackgroundColor` | Find dominant transparent/background color for cropping. |
|
|
459
|
+
| `detectContentBounds` | Compute non-background bounds for autocrop. |
|
|
460
|
+
| `cropPixels` | Crop raw pixel buffers. |
|
|
461
|
+
| `detectOverflow` | Fail frames that clip content at canvas edges. |
|
|
462
|
+
|
|
463
|
+
### Rendering
|
|
464
|
+
|
|
465
|
+
```ts
|
|
466
|
+
import { renderAnimatedGif, renderToPng, renderToBuffer, renderToSvg } from "vizmatic"
|
|
467
|
+
```
|
|
468
|
+
|
|
469
|
+
`renderToPng` renders at 2x scale by default, checks for clipped content, crops extra vertical whitespace, and can apply an optional watermark. Use `watermark.image` for a URL or data URI; the CLI also accepts local image paths through `--watermark-image`. `brand` still works as a compatibility alias.
|
|
470
|
+
|
|
471
|
+
```ts
|
|
472
|
+
await renderToPng(element, {
|
|
473
|
+
width: 1040,
|
|
474
|
+
height: 560,
|
|
475
|
+
outputPath: "dist/frame.png",
|
|
476
|
+
watermark: { text: "Your Product", image: "https://example.com/logo.svg", position: "top-right" },
|
|
477
|
+
crop: true,
|
|
478
|
+
scale: 2,
|
|
479
|
+
})
|
|
480
|
+
```
|
|
481
|
+
|
|
482
|
+
`renderAnimatedGif` turns ordered scene states into a looping GIF.
|
|
483
|
+
|
|
484
|
+
```ts
|
|
485
|
+
await renderAnimatedGif(createScenes("dark"), {
|
|
486
|
+
width: 1040,
|
|
487
|
+
height: 560,
|
|
488
|
+
outputPath: "dist/agent-pipeline.gif",
|
|
489
|
+
watermark: { text: "Your Product", image: "data:image/png;base64,...", position: "bottom-right" },
|
|
490
|
+
theme: "dark",
|
|
491
|
+
scale: 1,
|
|
492
|
+
})
|
|
493
|
+
```
|
|
494
|
+
|
|
495
|
+
## Project Layout
|
|
496
|
+
|
|
497
|
+
```text
|
|
498
|
+
src/
|
|
499
|
+
theme.ts semantic colors, tones, typography
|
|
500
|
+
primitives.ts reusable scene building blocks
|
|
501
|
+
render.ts Satori -> SVG -> resvg -> PNG
|
|
502
|
+
animate.ts ordered scene states -> GIF
|
|
503
|
+
autocrop.ts content bounds and overflow checks
|
|
504
|
+
cli.ts vizmatic render / vizmatic gif
|
|
505
|
+
examples/
|
|
506
|
+
*.tsx generated gallery frames
|
|
507
|
+
docs/
|
|
508
|
+
index.html static website for GitHub Pages
|
|
509
|
+
```
|
|
510
|
+
|
|
511
|
+
## Development
|
|
512
|
+
|
|
513
|
+
```bash
|
|
514
|
+
pnpm install
|
|
515
|
+
pnpm test
|
|
516
|
+
pnpm render:examples
|
|
517
|
+
pnpm site:serve
|
|
518
|
+
```
|
|
519
|
+
|
|
520
|
+
## Publishing
|
|
521
|
+
|
|
522
|
+
```bash
|
|
523
|
+
pnpm test
|
|
524
|
+
pnpm render:examples
|
|
525
|
+
npm publish --access public
|
|
526
|
+
```
|
|
527
|
+
|
|
528
|
+
## License
|
|
529
|
+
|
|
530
|
+
MIT
|