vizmatic 0.4.0 → 0.6.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/PROMPT.md +75 -531
- package/README.md +85 -1052
- package/ROADMAP.md +49 -67
- package/SCIENCE.md +250 -0
- package/assets/THIRD_PARTY_LICENSES.md +44 -1
- package/assets/fonts/InstrumentSerif-Italic.ttf +0 -0
- package/assets/fonts/InstrumentSerif-Regular.ttf +0 -0
- package/assets/fonts/SourceSerif4-24pt-Italic.ttf +0 -0
- package/assets/fonts/SourceSerif4-24pt-Regular.ttf +0 -0
- package/assets/licenses/raster-codecs-MIT.txt +74 -0
- package/dist/chunk-3F2VQ7NW.js +1 -0
- package/dist/{chunk-FEIPTPBZ.js → chunk-4XE64I2U.js} +53 -463
- package/dist/chunk-5ZAFH2JC.js +4231 -0
- package/dist/chunk-JHHPLALU.js +79 -0
- package/dist/chunk-LTX44BAE.js +112 -0
- package/dist/chunk-MLKGABMK.js +9 -0
- package/dist/chunk-PSBF4TEK.js +1 -0
- package/dist/chunk-RPAHMKAR.js +605 -0
- package/dist/chunk-RWF4VBUL.js +3617 -0
- package/dist/cli.js +369 -12
- package/dist/index.cjs +7413 -1810
- package/dist/index.d.cts +900 -599
- package/dist/index.d.ts +900 -599
- package/dist/index.js +5019 -3278
- package/dist/math-LXB4FH4E.js +7 -0
- package/dist/math-QVCETQDQ.js +1 -0
- package/dist/scene-browser-assets.d.ts +38 -0
- package/dist/scene-browser-assets.js +53 -0
- package/dist/scene-browser-chunks/chunk-5MVLYGXM.js +70 -0
- package/dist/scene-browser-chunks/chunk-ASXKN3NU.js +1 -0
- package/dist/scene-browser-chunks/chunk-CM5Y5LZP.js +1 -0
- package/dist/scene-browser-chunks/chunk-DP7NB4EW.js +6 -0
- package/dist/scene-browser-chunks/emscripten-module.browser-M5AEKJGE.js +1 -0
- package/dist/scene-browser-chunks/ffi-FL6ORJU3.js +1 -0
- package/dist/scene-browser-chunks/module-ES6BEMUI-JD5S5VKR.js +1 -0
- package/dist/scene-browser-chunks/module-asyncify-2EFITU5U-HWPFJFJC.js +1 -0
- package/dist/scene-browser-chunks/scene-browser-layout-M3XSXMV4.js +27 -0
- package/dist/scene-browser.d.ts +117 -0
- package/dist/scene-browser.js +220 -0
- package/dist/scene-cli.js +1 -1
- package/dist/scene-runtime.cjs +168 -103
- package/dist/scene-runtime.d.cts +3 -2
- package/dist/scene-runtime.d.ts +3 -2
- package/dist/scene-runtime.js +3 -1
- package/dist/server-2FYHZ4UO.js +331 -0
- package/dist/stage-browser/browser.d.ts +2483 -0
- package/dist/stage-browser/chunk-SQE76S5B.js +1 -0
- package/dist/stage-browser/chunk-VZNL6JY2.js +59 -0
- package/dist/stage-browser/dagre.esm-N2NIVIAZ.js +6 -0
- package/dist/stage-browser/math-4WFNHVV2.js +18 -0
- package/dist/stage-browser/stage.js +19 -0
- package/dist/stage-export.cjs +4980 -0
- package/dist/stage-export.d.cts +112 -0
- package/dist/stage-export.d.ts +112 -0
- package/dist/stage-export.js +544 -0
- package/dist/stage.cjs +9789 -0
- package/dist/stage.d.cts +1679 -0
- package/dist/stage.d.ts +1679 -0
- package/dist/stage.js +5418 -0
- package/dist/svg-import-Djj2q7Pc.d.cts +742 -0
- package/dist/svg-import-Djj2q7Pc.d.ts +742 -0
- package/dist/video-CcHW1qhV.d.cts +532 -0
- package/dist/video-CcHW1qhV.d.ts +532 -0
- package/examples/README.md +18 -0
- package/examples/agent-pipeline.tsx +4 -4
- package/examples/animated-pipeline.tsx +1 -5
- package/examples/attention-head.tsx +12 -12
- package/examples/aurora-incident.tsx +4 -3
- package/examples/building-blocks.tsx +8 -9
- package/examples/catalog-charts.tsx +4 -4
- package/examples/catalog-content.tsx +7 -9
- package/examples/catalog-convolution-kernel.tsx +116 -0
- package/examples/catalog-data.tsx +2 -8
- package/examples/catalog-dataflow.tsx +5 -9
- package/examples/catalog-dense.tsx +80 -0
- package/examples/catalog-deployment.tsx +5 -11
- package/examples/catalog-diagrams.tsx +13 -16
- package/examples/catalog-drawing.tsx +7 -7
- package/examples/catalog-flows.tsx +4 -4
- package/examples/catalog-foundations.tsx +11 -11
- package/examples/catalog-gaussian-blur.tsx +146 -0
- package/examples/catalog-image-tensors.tsx +115 -0
- package/examples/catalog-ml.tsx +36 -31
- package/examples/catalog-numeric-matrices.tsx +93 -0
- package/examples/catalog-photo-blur.tsx +209 -0
- package/examples/catalog-science-ai.tsx +130 -0
- package/examples/catalog-science-chemistry.tsx +103 -0
- package/examples/catalog-science-math.tsx +93 -0
- package/examples/catalog-science-physics.tsx +84 -0
- package/examples/catalog-sequence.tsx +59 -38
- package/examples/data-pipeline-lineage-presentation.tsx +5 -0
- package/examples/data-pipeline-lineage.tsx +85 -0
- package/examples/daybreak-launch.tsx +1 -0
- package/examples/desired-quadrant.tsx +7 -8
- package/examples/engineering-dashboard-presentation.tsx +13 -0
- package/examples/engineering-dashboard.tsx +160 -0
- package/examples/engineering-flow.tsx +2 -4
- package/examples/eval-dashboard.tsx +6 -6
- package/examples/films/attention.ts +278 -0
- package/examples/films/cache-miss.ts +431 -0
- package/examples/films/catalog.json +132 -0
- package/examples/films/central-limit.ts +269 -0
- package/examples/films/complex-maps.ts +273 -0
- package/examples/films/deck-example.ts +224 -0
- package/examples/films/euler-circle.ts +179 -0
- package/examples/films/fourier-epicycles.ts +265 -0
- package/examples/films/gradient-descent.ts +345 -0
- package/examples/films/linear-maps.ts +175 -0
- package/examples/films/lorenz.ts +207 -0
- package/examples/films/pythagoras.ts +185 -0
- package/examples/films/taylor-series.ts +159 -0
- package/examples/films/vizmatic-title.ts +117 -0
- package/examples/llm-serving-stack-presentation.tsx +5 -0
- package/examples/llm-serving-stack.tsx +94 -0
- package/examples/model-garden.tsx +1 -0
- package/examples/model-router.tsx +6 -6
- package/examples/nccl-all-gather.tsx +3 -3
- package/examples/nccl-all-reduce.tsx +3 -3
- package/examples/nccl-all-to-all.tsx +1 -1
- package/examples/nccl-broadcast.tsx +1 -1
- package/examples/nccl-reduce-scatter.tsx +5 -5
- package/examples/orthogonal-routing.tsx +4 -4
- package/examples/pareto-frontier.tsx +9 -10
- package/examples/presentation-frame.tsx +6 -6
- package/examples/production-system-map-presentation.tsx +5 -0
- package/examples/production-system-map.tsx +130 -0
- package/examples/rag-graph.tsx +7 -7
- package/examples/release-card.tsx +5 -5
- package/examples/spec-anatomy.tsx +5 -5
- package/examples/system-architecture.tsx +19 -32
- package/examples/theme-system.tsx +1 -1
- package/examples/token-matrix.tsx +4 -2
- package/examples/transparent-badge.tsx +1 -2
- package/examples/videos/README.md +36 -2
- package/examples/videos/calculus-tangent.tsx +101 -0
- package/examples/videos/catalyst-pathway.tsx +56 -0
- package/examples/videos/causal-attention.tsx +91 -0
- package/examples/videos/convolution-kernel.tsx +34 -0
- package/examples/videos/gaussian-blur.tsx +32 -0
- package/examples/videos/image-to-matrix.tsx +22 -0
- package/examples/videos/matrix-multiplication.tsx +128 -0
- package/examples/videos/photo-gaussian-blur.tsx +39 -0
- package/examples/videos/wave-interference.tsx +80 -0
- package/examples/vizmatic-bare.d.ts +1 -0
- package/examples/vizmatic-hero.tsx +9 -18
- package/examples/website-workflow.tsx +7 -7
- package/examples/weekend-field-notes.tsx +3 -2
- package/package.json +65 -11
- package/dist/chunk-TH3F4SDB.js +0 -79
package/PROMPT.md
CHANGED
|
@@ -1,592 +1,136 @@
|
|
|
1
1
|
# Vizmatic agent prompt
|
|
2
2
|
|
|
3
|
-
Use Vizmatic to
|
|
3
|
+
Use Vizmatic to explain things visually from code. It makes two kinds of output:
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
- A **film** is motion. Write a TypeScript function with `vizmatic/stage`. It plays live in a browser and exports to MP4, WebM, GIF, PNG, and SVG.
|
|
6
|
+
- A **figure** is a still. Write TSX with typed components from `vizmatic`. It renders to PNG and SVG in dark and light themes.
|
|
6
7
|
|
|
7
|
-
Vizmatic requires Node.js 20 or newer.
|
|
8
|
+
Vizmatic requires Node.js 20 or newer. MP4 and WebM also need FFmpeg.
|
|
8
9
|
|
|
9
10
|
```bash
|
|
10
|
-
npm install
|
|
11
|
+
npm install vizmatic
|
|
11
12
|
```
|
|
12
13
|
|
|
13
|
-
|
|
14
|
+
## Films
|
|
14
15
|
|
|
15
|
-
|
|
16
|
-
<Scene title="Agent visual pipeline">
|
|
17
|
-
<Flow
|
|
18
|
-
connectorTone="purple"
|
|
19
|
-
stages={[
|
|
20
|
-
{ title: "Prompt", tone: "blue" },
|
|
21
|
-
{ title: "Scene spec", tone: "purple" },
|
|
22
|
-
{ title: "PNG / SVG / GIF", tone: "green" },
|
|
23
|
-
]}
|
|
24
|
-
/>
|
|
25
|
-
</Scene>
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
Render dark and light assets:
|
|
16
|
+
Start from a template, or write the function yourself. Templates are `explainer`, `equation`, `architecture`, `chart`, and `deck`.
|
|
29
17
|
|
|
30
18
|
```bash
|
|
31
|
-
vizmatic
|
|
19
|
+
npx vizmatic new intro --template explainer
|
|
32
20
|
```
|
|
33
21
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
```bash
|
|
37
|
-
vizmatic check ./frame.tsx --theme dark,light --json
|
|
38
|
-
```
|
|
22
|
+
```ts
|
|
23
|
+
import { axes, draw, dynamic, dot, fadeIn, film, line, tex, write } from 'vizmatic/stage'
|
|
39
24
|
|
|
40
|
-
|
|
25
|
+
export default film({ title: 'A limit you can see' }, (s) => {
|
|
26
|
+
s.chapter('The curve')
|
|
27
|
+
const plot = s.add(axes({ x: [-1, 4], y: [-1, 9], grid: true, width: 1080, height: 660 }).at(-340, 60))
|
|
28
|
+
s.play(draw(plot.grid, { lag: 0.02 }), draw(plot.lines), fadeIn(plot.numbers))
|
|
29
|
+
s.play(draw(plot.plot((x) => x * x, { stroke: 'blue', width: 5 })))
|
|
41
30
|
|
|
42
|
-
The
|
|
31
|
+
s.chapter('The secant')
|
|
32
|
+
const h = s.value(2)
|
|
33
|
+
const secant = s.add(dynamic(() => {
|
|
34
|
+
const slope = 2 + h.value
|
|
35
|
+
return [
|
|
36
|
+
line(plot.world(0.2, 1 + slope * -0.8), plot.world(3.2, 1 + slope * 2.2), { stroke: 'yellow', width: 3.5 }),
|
|
37
|
+
dot(9, 'yellow').at(plot.world(1 + h.value, (1 + h.value) ** 2)),
|
|
38
|
+
]
|
|
39
|
+
}))
|
|
40
|
+
s.play(fadeIn(secant))
|
|
41
|
+
s.play(write(s.add(tex('m = 2 + h', { size: 64 }).at(600, -120))))
|
|
42
|
+
s.play(h.to(0.02, { duration: 4 }))
|
|
43
|
+
s.wait(1.5)
|
|
44
|
+
})
|
|
45
|
+
```
|
|
43
46
|
|
|
44
|
-
|
|
47
|
+
Rules of the engine:
|
|
45
48
|
|
|
46
|
-
|
|
49
|
+
- The stage is 1920 by 1080. (0, 0) is the center and y points down. Plots convert with `plot.world(x, y)`.
|
|
50
|
+
- The build function runs once and may run again while assets load. Keep it free of side effects.
|
|
51
|
+
- `s.play(...)` writes animation and moves time forward. `s.wait(seconds)` holds. `s.at(time, build)` authors at another time.
|
|
52
|
+
- A `dynamic(() => ...)` drawing rebuilds on every frame. Read `value.value` inside it to drive anything.
|
|
53
|
+
- `morph(a, b)` leaves `b` on stage and `a` hidden. Later code refers to `b`.
|
|
54
|
+
- Colors are look tokens such as `'blue'`, `'yellow'`, `'ink'`, and `'dim'`, so a film renders in every look.
|
|
55
|
+
- Run `vizmatic objects` and `vizmatic looks` to see what the installed version offers.
|
|
47
56
|
|
|
48
|
-
|
|
57
|
+
### Check, look, and export
|
|
49
58
|
|
|
50
|
-
|
|
59
|
+
An agent cannot watch a video, so judge a film from the check and from stills.
|
|
51
60
|
|
|
52
61
|
```bash
|
|
53
|
-
|
|
62
|
+
npx vizmatic check intro.ts --json
|
|
63
|
+
npx vizmatic film intro.ts --frame 3,6.5,12 --width 1280 --out stills
|
|
64
|
+
npx vizmatic film intro.ts --out dist/films --look midnight,paper --quality high
|
|
54
65
|
```
|
|
55
66
|
|
|
56
|
-
|
|
67
|
+
`vizmatic check` samples the moments where the film comes to rest. It reports `film.off_canvas`, `film.text_overlap`, `film.text_crossed`, and `film.missing_glyph`, each with times, a `box` in canvas pixels, and a `stage` center in authoring coordinates. Fix every error, then open the stills and look at them. `vizmatic preview intro.ts` opens a live player with a timeline for a person to review.
|
|
57
68
|
|
|
58
|
-
|
|
59
|
-
pnpm add github:bvolpato/vizmatic react
|
|
60
|
-
```
|
|
69
|
+
Motion guidance:
|
|
61
70
|
|
|
62
|
-
Use
|
|
71
|
+
- Use one idea per beat. Hold for a second after each reveal, so a viewer can read it.
|
|
72
|
+
- Move the thing being explained. Avoid decorative motion.
|
|
73
|
+
- Give color a meaning and keep it. A quantity keeps its color from its first appearance to its last.
|
|
74
|
+
- Use chapters. They mark the player's timeline and are the steps of a presentation.
|
|
63
75
|
|
|
64
|
-
##
|
|
76
|
+
## Figures
|
|
65
77
|
|
|
66
|
-
Create `
|
|
78
|
+
Create `frame.tsx`. `Scene` title and subtitle are optional.
|
|
67
79
|
|
|
68
80
|
```tsx
|
|
69
|
-
|
|
70
|
-
height = 560;
|
|
71
|
-
|
|
72
|
-
<Scene
|
|
73
|
-
title="Agent visual pipeline"
|
|
74
|
-
subtitle="prompt -> TSX scene -> render -> files"
|
|
75
|
-
gap={26}
|
|
76
|
-
>
|
|
81
|
+
<Scene title="Checkout, read path">
|
|
77
82
|
<Flow
|
|
78
|
-
connectorTone="purple"
|
|
79
83
|
stages={[
|
|
80
|
-
{
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
subtitle: "intent and constraints",
|
|
84
|
-
tone: "blue",
|
|
85
|
-
lines: ["domain language", "audience", "theme tokens"],
|
|
86
|
-
width: 190,
|
|
87
|
-
},
|
|
88
|
-
{
|
|
89
|
-
eyebrow: "contract",
|
|
90
|
-
title: "Scene spec",
|
|
91
|
-
subtitle: "typed structure",
|
|
92
|
-
tone: "purple",
|
|
93
|
-
lines: ["cards", "flows", "charts", "tables"],
|
|
94
|
-
width: 190,
|
|
95
|
-
},
|
|
96
|
-
{
|
|
97
|
-
eyebrow: "render",
|
|
98
|
-
title: "Node renderer",
|
|
99
|
-
subtitle: "headless output",
|
|
100
|
-
tone: "cyan",
|
|
101
|
-
lines: ["layout", "theme", "checks"],
|
|
102
|
-
width: 190,
|
|
103
|
-
},
|
|
104
|
-
{
|
|
105
|
-
eyebrow: "output",
|
|
106
|
-
title: "PNG / SVG / GIF",
|
|
107
|
-
subtitle: "rendered files",
|
|
108
|
-
tone: "green",
|
|
109
|
-
lines: ["dark + light", "alpha", "manifest"],
|
|
110
|
-
width: 190,
|
|
111
|
-
},
|
|
84
|
+
{ title: "Gateway", subtitle: "Envoy, p99 9 ms", tone: "blue" },
|
|
85
|
+
{ title: "Cart", subtitle: "Go, 840 rps", tone: "purple" },
|
|
86
|
+
{ title: "Orders DB", subtitle: "Postgres, primary + 3", tone: "green" },
|
|
112
87
|
]}
|
|
113
88
|
/>
|
|
114
|
-
<Row width="100%" gap={14}>
|
|
115
|
-
<CalloutCard
|
|
116
|
-
title="Use scene primitives"
|
|
117
|
-
detail="Common diagrams do not need hand-written SVG paths or x/y coordinates."
|
|
118
|
-
tone="purple"
|
|
119
|
-
width={470}
|
|
120
|
-
/>
|
|
121
|
-
<CalloutCard
|
|
122
|
-
title="Use theme tokens"
|
|
123
|
-
detail="Tokens set color, typography, radius, spacing, and contrast."
|
|
124
|
-
tone="green"
|
|
125
|
-
width={470}
|
|
126
|
-
/>
|
|
127
|
-
</Row>
|
|
128
89
|
</Scene>
|
|
129
90
|
```
|
|
130
91
|
|
|
131
|
-
Render it:
|
|
132
|
-
|
|
133
92
|
```bash
|
|
134
|
-
vizmatic
|
|
93
|
+
npx vizmatic check ./frame.tsx --theme dark,light --json
|
|
94
|
+
npx vizmatic ./frame.tsx --out ./figures --theme dark,light --format both
|
|
135
95
|
```
|
|
136
96
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
The static CLI defaults to PNG. Add `--format svg` for vector output or `--format both` to render PNG and SVG together in every requested theme.
|
|
97
|
+
Fix all errors before the final render. Warnings report low contrast, small text, overlapping labels, uneven panel whitespace, connector congestion, and asset fallbacks.
|
|
140
98
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
```bash
|
|
144
|
-
vizmatic frames --out public/vizmatic --theme dark,light --background theme
|
|
145
|
-
```
|
|
146
|
-
|
|
147
|
-
Or set it in the frame:
|
|
148
|
-
|
|
149
|
-
```tsx
|
|
150
|
-
<Scene background={c.bg} title="Opaque article figure">
|
|
151
|
-
<Flow stages={[{ title: "Theme fill", tone: "purple" }]} />
|
|
152
|
-
</Scene>
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
CSS alpha colors are preserved in PNG/SVG backgrounds. Use `<Scene background="rgba(15, 23, 42, 0.5)">` or `--background 'rgba(15, 23, 42, 0.5)'` for a semi-transparent canvas. Leave the background unset for fully transparent output. Contrast checks composite alpha text and nested backgrounds over known solid surfaces; a transparent canvas has no known host-page backdrop.
|
|
156
|
-
|
|
157
|
-
When a CLI frame omits `width` or `height`, Vizmatic starts at `960x540` and grows that axis if content overflows. Set `autoSize = false` when dimensions must remain fixed and clipping should fail the render.
|
|
158
|
-
|
|
159
|
-
Bare CLI frames do not need imports, `defineIllustration`, or `c` props. Use `c` for explicit tokens such as `background={c.bg}`. `Scene` title and subtitle are optional. Use a full module for other dependencies, reusable helpers, animation exports, or direct renderer APIs.
|
|
160
|
-
|
|
161
|
-
Frame modules can export a watermark element instead of using CLI flags:
|
|
162
|
-
|
|
163
|
-
```tsx
|
|
164
|
-
import { Watermark } from "vizmatic"
|
|
165
|
-
|
|
166
|
-
export const watermark = (
|
|
167
|
-
<Watermark position="bottom-right" opacity={0.82}>
|
|
168
|
-
<div style={{
|
|
169
|
-
display: "flex",
|
|
170
|
-
alignItems: "center",
|
|
171
|
-
gap: 6,
|
|
172
|
-
color: "#7c3aed",
|
|
173
|
-
fontFamily: "Inter",
|
|
174
|
-
fontWeight: 800,
|
|
175
|
-
fontSize: 12,
|
|
176
|
-
}}>
|
|
177
|
-
<img src="data:image/svg+xml;base64,..." width={14} height={14} />
|
|
178
|
-
Your Product
|
|
179
|
-
</div>
|
|
180
|
-
</Watermark>
|
|
181
|
-
)
|
|
182
|
-
```
|
|
183
|
-
|
|
184
|
-
Render a sampled state timeline with `createAnimation(theme)`:
|
|
185
|
-
|
|
186
|
-
```bash
|
|
187
|
-
vizmatic gif frames/animated-pipeline.tsx --out public/vizmatic --theme dark,light --fps 20 --watermark "Your Product" --watermark-image ./logo.svg --watermark-position top-right --scale 1
|
|
188
|
-
```
|
|
99
|
+
Figures default to the `dense` density, like a figure in an engineering paper. Fill the space with useful detail: runtimes, rates, schemas, and limits. Do not spread three boxes across a slide. Use `density="presentation"` on a `Scene`, or `density` in a render option, only for a room. The densities are `dense`, `compact`, `comfortable`, `presentation`, or a number.
|
|
189
100
|
|
|
190
|
-
|
|
101
|
+
Choose by meaning: `GraphDiagram` for systems, `SequenceDiagram` for interactions, `DataflowDiagram` for lineage, `DeploymentDiagram` for placement and trust, `TransformerTopology` for models, and `LineChart`, `BarChart`, `DataTable`, or `Heatmap` for data. Omit `width` and `height` to auto-grow from 960 by 540.
|
|
191
102
|
|
|
192
|
-
|
|
103
|
+
PNG and SVG output is alpha-transparent by default. Add `--background theme` or `background={c.bg}` for an opaque canvas. Use `preset = "engineering";` with `--theme light` for flat article figures.
|
|
193
104
|
|
|
194
|
-
|
|
105
|
+
Use a full module when a frame needs helper code or data:
|
|
195
106
|
|
|
196
107
|
```tsx
|
|
197
|
-
import
|
|
198
|
-
import { Scene, defineAnimation, getThemeColors, hold, keyframe, tween, type ThemeMode } from "vizmatic"
|
|
108
|
+
import { Flow, Scene, getThemeColors, type ThemeMode } from "vizmatic"
|
|
199
109
|
|
|
200
110
|
export const width = 1040
|
|
201
111
|
export const height = 560
|
|
202
112
|
|
|
203
|
-
type State = { operation: number; progress: number }
|
|
204
|
-
|
|
205
|
-
function buildFrame(theme: ThemeMode, state: State) {
|
|
206
|
-
const c = getThemeColors(theme)
|
|
207
|
-
return (
|
|
208
|
-
<Scene c={c} title={state.operation === 0 ? "Broadcast" : "AllReduce"}>
|
|
209
|
-
<div style={{ display: "flex", width: "100%", height: 260, position: "relative" }}>
|
|
210
|
-
<div style={{
|
|
211
|
-
display: "flex",
|
|
212
|
-
position: "absolute",
|
|
213
|
-
left: 40 + state.progress * 720,
|
|
214
|
-
top: 90,
|
|
215
|
-
padding: "10px 16px",
|
|
216
|
-
borderRadius: 8,
|
|
217
|
-
background: c.accent,
|
|
218
|
-
color: c.textOnColor,
|
|
219
|
-
}}>chunk</div>
|
|
220
|
-
</div>
|
|
221
|
-
</Scene>
|
|
222
|
-
)
|
|
223
|
-
}
|
|
224
|
-
|
|
225
|
-
export function createAnimation(theme: ThemeMode) {
|
|
226
|
-
return defineAnimation<State>({
|
|
227
|
-
initial: { operation: 0, progress: 0 },
|
|
228
|
-
timeline: [
|
|
229
|
-
hold(500, "Broadcast input"),
|
|
230
|
-
tween({ progress: 1 }, { duration: 900, easing: "ease-in-out", label: "Broadcast" }),
|
|
231
|
-
hold(500, "Broadcast output"),
|
|
232
|
-
keyframe({ operation: 1, progress: 0 }),
|
|
233
|
-
tween({ progress: 1 }, { duration: 900, easing: "ease-in-out", label: "AllReduce" }),
|
|
234
|
-
],
|
|
235
|
-
fps: 20,
|
|
236
|
-
render: (state) => buildFrame(theme, state),
|
|
237
|
-
})
|
|
238
|
-
}
|
|
239
|
-
|
|
240
113
|
export function create(theme: ThemeMode = "dark") {
|
|
241
|
-
|
|
114
|
+
const c = getThemeColors(theme)
|
|
115
|
+
return <Scene c={c} title="Runtime path"><Flow c={c} stages={[{ title: "Input", tone: "blue" }, { title: "Check", tone: "purple" }]} /></Scene>
|
|
242
116
|
}
|
|
243
|
-
|
|
244
|
-
export default create("dark")
|
|
245
|
-
```
|
|
246
|
-
|
|
247
|
-
Top-level timeline steps run sequentially. Properties inside one `tween` move together. Use `parallel({ x: [...], opacity: [...] })` when property tracks need different delays or durations. Default interpolation supports finite numbers; use a custom `interpolate(from, to, progress)` for colors, points, or other values. Infinite loops should finish on the same visual state where they start. Fade moving content out and reset it with a zero-duration `keyframe` while hidden instead of reversing a one-way operation. `createScenes(theme)` remains supported for deliberate scene cuts and pixel `fade`/`appear` transitions.
|
|
248
|
-
|
|
249
|
-
## Choose primitives
|
|
250
|
-
|
|
251
|
-
Use Vizmatic primitives for common layouts. Use raw SVG only for geometry the component set cannot express.
|
|
252
|
-
|
|
253
|
-
Shared values:
|
|
254
|
-
|
|
255
|
-
- `ThemeMode`: `"dark" | "light"`.
|
|
256
|
-
- `ToneName`: `"blue" | "purple" | "green" | "warm" | "cyan" | "pink" | "red" | "critical" | "neutral" | "sunset" | "ocean" | "dark"`.
|
|
257
|
-
- `ColorName`: `"primary" | "secondary" | "positive" | "warning" | "critical" | "info" | "accent" | "neutral"`.
|
|
258
|
-
- `FlexAlign`: `"start" | "center" | "end" | "stretch"`.
|
|
259
|
-
- `FlexJustify`: `"start" | "center" | "end" | "space-between" | "space-around"`.
|
|
260
|
-
- Bare CLI frames omit `c` props. The local `c` object remains available for explicit values such as `background={c.bg}`.
|
|
261
|
-
- Full modules pass the `c: ThemeColors` value from `defineIllustration((c) => ...)` to visual components.
|
|
262
|
-
- PNG/SVG renders are alpha-transparent by default. Use `--background theme`, `background: "theme"`, or `<Scene background={c.bg}>` for opaque theme fill.
|
|
263
|
-
- Omitted CLI dimensions auto-grow on overflow. Explicit `width` / `height` remain fixed and fail on clipping.
|
|
264
|
-
|
|
265
|
-
## Component API
|
|
266
|
-
|
|
267
|
-
Frame helpers:
|
|
268
|
-
|
|
269
|
-
- `defineIllustration(build, defaultTheme?)`: `build: (c: ThemeColors) => ReactElement`, `defaultTheme?: ThemeMode = "dark"`. Returns `{ create(theme), default }`.
|
|
270
|
-
- `Canvas`: `children?`, `c`, `padding?: number = 40`, `justify?: "center" | "flex-start" | "space-between" | "space-around" = "center"`, `background?: string`. Default root background is alpha-transparent during PNG/SVG rendering.
|
|
271
|
-
- `Board`: `children?`, `c`, `width?: number = 960`, `height?: number = 540`, `background?: string`. Fixed relative canvas with a transparent default background; clips content outside its bounds. Match frame dimensions to the board. Dimensions must be finite, greater than zero, and at most 8192.
|
|
272
|
-
- `CanvasItem`: `children?`, `x: number`, `y: number`, `width?: number`, `height?: number`. Absolute position in logical board pixels. Coordinates must be finite. Explicit dimensions must be greater than zero and at most 8192; they supply the child's width/height props. With both dimensions set, chart primitives scale proportionally to fit their complete plotting layer, headings, legends, and footer inside the item. Use literal coordinates and dimensions for preview move/resize controls.
|
|
273
|
-
- `Scene`: `c`, `children`, `title?`, `subtitle?`, `padding?: number = 40`, `gap?: number = 24`, `justify?: "center" | "flex-start" | "space-between" | "space-around" = "flex-start"`, `align?: FlexAlign = "stretch"`, `contentWidth?: number | string = "100%"`, `background?`, `contentStyle?: React.CSSProperties`. Title/subtitle are optional and the title bar is omitted when no title is provided. Use `background={c.bg}` for an opaque theme frame.
|
|
274
|
-
- `TitleBar`: `title`, `subtitle?`, `c`.
|
|
275
|
-
|
|
276
|
-
Layout primitives:
|
|
277
|
-
|
|
278
|
-
- `Row` / `Column`: `children`, `gap?: number = 12`, `align?: FlexAlign = "center"`, `justify?: FlexJustify = "center"`, `wrap?: boolean = false`, `width?: number | string`, `height?: number | string`, `style?: React.CSSProperties`.
|
|
279
|
-
- `Stack`: `children`, `direction?: "vertical" | "horizontal" = "vertical"`, `gap?: number = 12`, `align?: "start" | "center" | "end" | "stretch" = "center"`, `wrap?: boolean = false`.
|
|
280
|
-
- `Panel`: `title`, `c`, `children?`, `subtitle?`, `tone?: ToneName = "blue"`, `footer?`, `width?`, `minWidth?`, `height?`, `minHeight?`, `padding?: number | string = 14`, `radius?: number = 8`, `gap?: number = 10`, `align?: FlexAlign = "stretch"`, `justify?: FlexJustify = "start"`, `shadow?: boolean = true`, `background?`, `borderColor?`, `titleFontSize?`, `accentWidth?: number = 34`, `accentHeight?: number = 4`, `bodyStyle?: React.CSSProperties`.
|
|
281
|
-
- `Card`: `children?`, `c`, `title?`, `subtitle?`, `tone?`, `footer?`, `width?`, `minWidth?`, `height?`, `minHeight?`, `padding?: number | string = 20`, `radius?: number = 8`, `gap?`, `align?: FlexAlign = "stretch"`, `justify?: FlexJustify = "start"`, `shadow?: boolean = false`, `background?`, `borderColor?`, `bodyStyle?: React.CSSProperties`.
|
|
282
|
-
- `WindowFrame`: `c`, `children?`, `title?`, `variant?: "window" | "browser" | "terminal" = "window"`, `tone?: ToneName = "blue"`, `dots?: boolean = true`, `width?`, `minWidth?`, `height?`, `minHeight?`, `padding?: number | string = 16`, `radius?: number = 10`, `shadow?: boolean = true`, `background?`, `bodyStyle?: React.CSSProperties`.
|
|
283
|
-
|
|
284
|
-
Cards, labels, and compact UI:
|
|
285
|
-
|
|
286
|
-
- `TextLabel`: `text`, `c`, `variant?: keyof typography = "body"`, `color?`, `fontSize?`, `fontWeight?`, `width?`, `align?: "left" | "center" | "right" = "left"`, `math?: boolean = false`, `mono?: boolean = false`.
|
|
287
|
-
- `MathText`: `text`. Returns formatted unicode-ish math text for simple `_` and `^` notation.
|
|
288
|
-
- `formatMathText(text)`: `text: string`.
|
|
289
|
-
- `Icon`: `name`, `c`, `tone?: ToneName = "blue"`, `color?`, `size?: number = 24`, `strokeWidth?: number = 2`, `label?`, `muted?: boolean = false`. `IconName` includes presentation icons plus architecture icons: `browser`, `bucket`, `cache`, `cloud`, `cluster`, `container`, `database`, `firewall`, `gateway`, `load-balancer`, `mobile`, `monitor`, `network`, `queue`, `server`, `storage`, `stream`, and `user`.
|
|
290
|
-
- `ToneStrip`: `tone`, `width?: number = 34`, `height?: number = 4`.
|
|
291
|
-
- `StepCard`: `title`, `c`, `subtitle?`, `eyebrow?`, `tone?: ToneName = "blue"`, `width?: number | string = 210`, `minWidth?`, `minHeight?: number | string = 74`, `padding?: number | string = "12px 14px"`, `radius?: number = 8`, `shadow?: boolean = true`, `align?: "left" | "center" = "center"`, `math?: boolean = false`.
|
|
292
|
-
- `MetricCard`: `label`, `value`, `c`, `tone?: ToneName = "blue"`, `detail?`, `width?`, `minWidth?`, `minHeight?: number | string = 74`, `padding?: number | string = "10px 12px"`, `radius?: number = 8`, `shadow?: boolean = true`, `align?: "left" | "center" = "center"`, `math?: boolean = false`, `valueMono?: boolean = true`, `valueFontSize?: number = 22`, `valueColor?`.
|
|
293
|
-
- `CalloutCard`: `c`, `children?`, `title?`, `detail?`, `tone?: ToneName = "blue"`, `width?`, `minHeight?`, `padding?: number | string = 12`, `titleFontSize?: number`, `detailFontSize?: number`, `filled?: boolean = true`, `align?: "left" | "center" = "center"`.
|
|
294
|
-
- `ValuePill`: `label`, `value`, `c`, `tone?: ToneName = "blue"`, `detail?`, `width?: number | string = 112`, `math?: boolean = false`.
|
|
295
|
-
- `BadgePill`: `text`, `c`, `tone?: ToneName = "blue"`, `width?`, `minWidth?: number | string = 34`, `height?: number | string = 20`, `padding?: number | string = "0 8px"`, `radius?: number = 6`, `fontSize?: number = 11`, `mono?: boolean = true`, `filled?: boolean = false`, `math?: boolean = false`.
|
|
296
|
-
- `Badge`: `label`, `c`, `color?: ColorName = "primary"`.
|
|
297
|
-
- `GradientChip`: `title`, `c`, `subtitle?`, `tone?: ToneName = "blue"`, `gradient?`, `width?`, `minWidth?`, `height?`, `minHeight?: number | string = 78`, `padding?: number | string = "0 18px"`, `radius?: number = 8`, `shadow?: boolean = true`, `align?: "left" | "center" = "left"`, `subtitleMono?: boolean = true`, `math?: boolean = false`.
|
|
298
|
-
- `EquationCard`: `title`, `formula`, `c`, `tone?: ToneName = "purple"`, `result?`, `detail?`, `width?: number | string = 190`, `height?`, `math?: boolean = false`, `align?: "left" | "center" = "left"`.
|
|
299
|
-
- `DetailList`: `items`, `c`, `tone?`, `gap?: number = 7`, `padding?: number | string = "7px 8px"`, `fontSize?: number = 11`, `mono?: boolean = false`, `math?: boolean = false`.
|
|
300
|
-
|
|
301
|
-
Lists, tables, status, and comparison:
|
|
302
|
-
|
|
303
|
-
- `ProgressRow`: `label`, `value: number`, `valueLabel?`, `tone?: ToneName = "blue"`, `muted?: boolean = false`, `c`, `labelWidth?: number = 42`, `valueWidth?: number = 38`, `barHeight?: number = 8`, `fontSize?: number = 11`. Keep `value` in `[0, 1]`.
|
|
304
|
-
- `ProgressList`: `rows: ProgressRowSpec[]`, `c`, `gap?: number = 8`, `labelWidth?`, `valueWidth?`, `barHeight?`, `fontSize?`. `ProgressRowSpec`: `label`, `value`, `valueLabel?`, `tone?`, `muted?`.
|
|
305
|
-
- `StatusRow`: `label`, `detail?`, `status?: "check" | "cross" | "warn" | "info" | "pending" | "dot" = "check"`, `tone?`, `c`, `boxed?: boolean = true`, `fontSize?: number = 11`, `width?`, `math?: boolean = false`.
|
|
306
|
-
- `StatusList`: `rows: StatusRowSpec[]`, `c`, `gap?: number = 7`, `boxed?: boolean = true`, `fontSize?`, `width?`, `math?: boolean = false`. `StatusRowSpec`: `label`, `detail?`, `status?`, `tone?`.
|
|
307
|
-
- `Timeline`: `events: TimelineEventSpec[]`, `c`, `title?`, `subtitle?`, `direction?: "vertical" | "horizontal" = "vertical"`, `width?`, `eventWidth?`, `gap?: number = 12`, `markerSize?: number = 14`, `math?: boolean = false`. `TimelineEventSpec`: `title`, `detail?`, `time?`, `tone?`, `status?`, `width?`.
|
|
308
|
-
- `KeyValueList`: `rows: KeyValueRow[]`, `c`, `title?`, `width?`, `minWidth?`, `keyWidth?`, `gap?: number = 0`, `fontSize?: number = 11`, `divider?: boolean = true`, `keyMono?: boolean = false`, `math?: boolean = false`. `KeyValueRow`: `key`, `value`, `tone?`, `valueMono?`.
|
|
309
|
-
- `Comparison`: `sides: ComparisonSideSpec[]`, `c`, `divider?: ReactNode | boolean = false`, `gap?: number = 14`, `sideWidth?`, `minHeight?`, `align?: FlexAlign = "stretch"`, `math?: boolean = false`. `ComparisonSideSpec`: `title`, `subtitle?`, `eyebrow?`, `tone?`, `lines?`, `children?`, `footer?`, `width?`.
|
|
310
|
-
- `DataTable`: `rows: ReactNode[][]`, `c`, `cellWidth?: number = 54`, `firstColWidth?: number = cellWidth`, `cellHeight?: number = 28`, `gap?: number = 5`, `headerRows?: number = 1`, `headerCols?: number = 1`, `fontSize?: number = 11`, `math?: boolean = false`.
|
|
311
|
-
- `Grid`: `rows: Array<Array<ReactNode | GridCell>>`, `c`, `cellWidth?: number = 34`, `cellHeight?: number = 30`, `gap?: number = 5`, `radius?: number = 7`, `fontSize?: number = 11`, `math?: boolean = false`, `headerRows?: number = 0`, `headerCols?: number = 0`. `GridCell`: `label?`, `tone?`, `color?`, `backgroundColor?`, `borderColor?`, `opacity?`.
|
|
312
|
-
- `CodeBlock`: `lines: Array<ReactNode | CodeLineSpec>`, `c`, `title?`, `tone?`, `width?`, `minWidth?`, `fontSize?: number = 12`, `showLineNumbers?: boolean = false`, `padding?: number | string = 14`, `radius?: number = 10`, `background?`, `shadow?: boolean = false`, `math?: boolean = false`. `CodeLineSpec`: `text`, `tone?`, `dim?`, `prefix?`.
|
|
313
|
-
|
|
314
|
-
Tiles:
|
|
315
|
-
|
|
316
|
-
- `Tile`: combines `TileSpec` with display props. `TileSpec`: `title`, `subtitle?`, `eyebrow?`, `icon?`, `tone?`, `lines?`, `children?`, `width?`, `minHeight?`. Display props: `c`, `align?: "left" | "center" = "center"`, `padding?: number | string = "14px 16px"`, `radius?: number = 10`, `shadow?: boolean = true`, `math?: boolean = false`.
|
|
317
|
-
- `TileGrid`: `tiles: TileSpec[]`, `c`, `columns?`, `gap?: number = 12`, `tileWidth?`, `minHeight?`, `align?: "left" | "center" = "center"`, `math?: boolean = false`.
|
|
318
|
-
|
|
319
|
-
Flows and process diagrams:
|
|
320
|
-
|
|
321
|
-
- `Flow`: `stages: FlowStageSpec[]`, `c`, `direction?: "horizontal" | "vertical" = "horizontal"`, `gap?: number = 10`, `connectorLength?: number = 28`, `connectorTone?: ToneName = "neutral"`, `align?: FlexAlign = "center"`, `math?: boolean = false`. `FlowStageSpec`: `title`, `subtitle?`, `eyebrow?`, `tone?`, `lines?`, `children?`, `width?`, `minWidth?`, `minHeight?`, `padding?`.
|
|
322
|
-
- `FlowArrow`: `direction?: "down" | "right" | "up" | "left" = "right"`, `label?`, `length?: number = 40`, `c`, `tone?: ToneName = "blue"`, `color?`.
|
|
323
|
-
- `Connector`: same props as `FlowArrow`.
|
|
324
|
-
- `Pipeline`: `stages: PipelineStage[]`, `c`, `title?`. `PipelineStage`: `label`, `sublabel?`, `icon?`, `color?: ColorName`.
|
|
325
|
-
|
|
326
|
-
Graphs and networks:
|
|
327
|
-
|
|
328
|
-
- `LayeredNetwork`: `c`, `layers: LayeredNetworkLayer[]`, `activePath?: number[] = []`, `annotations?: string[] = []`, `formula?`, `legend?: string = "highlighted path"`, `width?: number = 900`, `height?: number = 400`, `nodeSize?: number = 56`, `showFormula?: boolean = true`. `LayeredNetworkLayer`: `title`, `nodes: string[]`, `tone?`.
|
|
329
|
-
- `GraphDiagram` routing options: `routing?: "dagre" | "straight" | "orthogonal" = "dagre"`, `routingClearance?: number = 12`. Dagre preserves existing routes; straight connects facing node sides; orthogonal avoids node boxes and group headers with right-angle paths. Node layout remains automatic or manual independently of routing. `GraphDiagramNode` additionally accepts `ports?: GraphDiagramPort[]`; a port is `{ id: string, side: "top" | "right" | "bottom" | "left", offset?: number = 0.5 }`. Offset is finite and in `[0, 1]`, running left to right or top to bottom. `GraphDiagramEdge` additionally accepts `fromPort?`, `toPort?`, `fromSide?`, and `toSide?`. An endpoint cannot combine a port reference with a side. Explicit anchors opt an edge into orthogonal geometry even in Dagre mode. Missing references, duplicate port IDs, and invalid offsets fail validation.
|
|
330
|
-
|
|
331
|
-
- Orthogonal routing separates parallel relationships, supports self-loops with distinct endpoint anchors, and uses `edgeGap` for lane spacing. It runs offline with limits of 64 node/header obstacles, 256 edges, 18,000 grid points per search, 54,000 search states per search, and 160,000 search states per diagram. A blocked path, unavailable separate lane, same-anchor self-loop, or exhausted limit omits that connector and emits a checker error with code `layout.connector_unroutable`. Increase canvas size or spacing, choose different sides/ports, or reduce clearance; do not publish missing connectors. See `examples/orthogonal-routing.tsx`.
|
|
332
|
-
|
|
333
|
-
- `GraphDiagram`: `nodes: GraphDiagramNode[]`, `edges: GraphDiagramEdge[]`, `groups?: GraphDiagramGroup[]`, `c`, `width?: number = 520`, `height?: number = 420`, `nodeWidth?: number = 150`, `nodeHeight?: number = 66`, `labelFontSize?: number = 14`, `detailFontSize?: number = 11`, `arrowSize?: number = 5`, `padding?: number = 28`, `layout?: "auto" | "manual"`, `direction?: "LR" | "RL" | "TB" | "BT" = "LR"`, `nodeGap?: number = 34`, `rankGap?: number = 64`, `edgeGap?: number = 14`, `sizing?: "content" | "fixed" = "content"`, `iconSize?: number = 20`, `id?`, `ariaLabel?`, `title?`, `description?`. `GraphDiagramNode`: `id`, `label`, `detail?`, `href?`, `title?`, `x?`, `y?`, `tone?`, `muted?`, `width?`, `height?`, `group?`, `icon?: IconName | DiagramIconDefinition | ReactElement`, `iconSize?`. Icon size is clamped inside its node; custom React elements own their theme colors and accessible label. `GraphDiagramGroup`: `id`, `label`, `detail?`, `parent?`, `tone?`, `muted?`. Groups nest through `parent` and require automatic layout. Omit coordinates on every node for automatic layout; array order is the stable tie-breaker and dimensions expand to fit unless `sizing="fixed"`. Set both coordinates on every node for manual normalized positioning when no groups are present. Mixed coordinate modes fail. `GraphDiagramEdge`: `id?`, `from`, `to`, `tone?`, `muted?`, `dashed?`, `label?`, `href?`, `title?`, `kind?: "sync" | "async" | "event" | "data" | "dependency" | "association"`, `style?: "solid" | "dashed" | "dotted"`, `arrow?: "forward" | "backward" | "both" | "none"`. Association edges default to no arrow. `title`, `description`, and `id` add structured SVG metadata and deterministic graph, node, and edge IDs. Nodes and edges can link to HTTP(S), `mailto:`, `tel:`, fragment, or relative URLs; unsupported schemes fail. Use these properties for `renderToSvg` and playground SVG downloads.
|
|
334
|
-
- `SequenceDiagram`: `participants`, ordered `items`, `c`, and optional `width`, `height`, spacing, title, subtitle, and `ariaLabel`. Participants have `id`, `label`, optional `detail`, `tone`, `kind`, and `icon`. Items are messages (`from`, `to`, `label`, `kind?: "sync" | "async" | "return"`), notes, activations, or recursive fragments with `kind: "alt" | "loop" | "parallel"` and labeled branches.
|
|
335
|
-
- `DataflowDiagram`: `nodes`, `edges`, optional nested `boundaries`, `c`, GraphDiagram sizing/layout props including `id`, `title`, and `description`, and `ariaLabel`. Nodes require `id`, `label`, and `kind: "source" | "transform" | "store" | "sink"`; optional schema metadata renders in node detail, with optional `href` and `title` for SVG links and tooltips. Edges use `mode?: "batch" | "stream"`, optional schema/label metadata, and optional `id`, `href`, and `title`.
|
|
336
|
-
- `DeploymentDiagram`: `nodes`, `connections`, optional nested `boundaries`, `c`, GraphDiagram sizing/layout props including `id`, `title`, and `description`, and `ariaLabel`. Boundaries distinguish region, zone, VPC, subnet, namespace, host, cluster, and trust scopes. Nodes declare infrastructure kind, boundary, and ports, with optional `href` and `title`. Connections declare ingress, egress, internal, or cross-boundary direction plus protocol and port references; `id`, `href`, and `title` add stable SVG identity and links.
|
|
337
|
-
- `DeploymentPort`: `id`, `port?`, `protocol?`, `label?`, `direction?: "ingress" | "egress" | "bidirectional"`, `side?: GraphPortSide`, `offset?: number`. With explicit `routing="straight"` or `routing="orthogonal"`, connection `fromPort` / `toPort` references require declared node ports and anchor geometrically. Side defaults follow graph direction and ingress/egress use; explicit side/offset overrides them. Default Dagre deployment rendering keeps the existing label-only behavior.
|
|
338
|
-
- `TransformerTopology`: `blocks`, optional `routes`, `c`, `expandRepeats?`, GraphDiagram sizing/layout props including `id`, `title`, and `description`, and `ariaLabel`. Blocks use embedding, attention, norm, MLP, residual, router, output, or custom kinds with tensor shapes and repeat counts, plus optional `href` and `title`. Routes use activation, residual, KV-cache, expert, or collective semantics, plus optional `id`, `href`, and `title`. `formatTensorShape(shape)` formats reusable shape metadata.
|
|
339
|
-
- `defineDiagramIcon(id, render)`: defines a reusable custom graph icon. `render` receives `c`, `color`, `size`, and optional `label`.
|
|
340
|
-
- `defineIconRegistry(icons)`: preserves typed names for a set of custom or provider icons without global mutable state.
|
|
341
|
-
- `TreeDiagram`: `root: TreeNodeSpec`, `c`, `title?`, `subtitle?`, `width?`, `height?`, `nodeWidth?: number = 156`, `nodeHeight?: number = 64`, `levelGap?: number = 58`, `siblingGap?: number = 24`, `padding?: number = 28`, `math?: boolean = false`. `TreeNodeSpec`: `label`, `id?`, `detail?`, `tone?`, `muted?`, `children?`.
|
|
342
|
-
|
|
343
|
-
Matrices and heatmaps:
|
|
344
|
-
|
|
345
|
-
- `Matrix`: `data: number[][]`, `c`, `rowLabels?`, `colLabels?`, `labels?`, `title?`, `cellSize?: number = 48`, `cellWidth?`, `cellHeight?`, `rowLabelWidth?`, `format?: "decimal" | "percent" | "integer" = "decimal"`, `colorize?: boolean = true`, `colorScale?: "heat" | "strength" = "heat"`.
|
|
346
|
-
- `Heatmap`: `data: number[][]`, `xLabels`, `yLabels`, `c`, `labels?`, `title?`, `cellSize?: number = 52`, `cellWidth?`, `cellHeight?`, `rowLabelWidth?`, `colorScale?: "heat" | "strength"`.
|
|
347
|
-
- `TiledMatrix`: `rows`, `cols`, `c`, `regions?: TiledMatrixRegion[] = []`, `title?`, `subtitle?`, `cellSize?: number = 24`, `gap?: number = 3`, `tone?: ToneName = "blue"`, `muted?: boolean = false`, `crossedOut?: boolean = false`. `TiledMatrixRegion`: `rowStart`, `rowEnd`, `colStart`, `colEnd`, `tone?`.
|
|
348
|
-
|
|
349
|
-
Charts and plots:
|
|
350
|
-
|
|
351
|
-
- `ChartFrame`: `children`, `c`, `title?`, `subtitle?`, `legend?: ChartLegendItem[]`, `footer?`, `width?: number | string = "100%"`, `height?`, `padding?: number = 16`. `ChartLegendItem`: `label`, `color: ColorName | string`.
|
|
352
|
-
- `PieChart`: `segments: DonutChartSegment[]`, `c`, `title?`, `subtitle?`, `width?: number = 360`, `height?: number = 240`, `size?`, `format?: ChartValueFormat = "decimal"`, `showLegend?: boolean = true`, `footer?`. Each segment has `label`, `value`, optional `color`, and optional `valueLabel`. Values must be finite and non-negative; zero slices are omitted. The full-circle pie shows part-to-whole proportions, with values and shares in the legend. Use `examples/pie-chart.tsx` for a complete frame.
|
|
353
|
-
- `DonutChart`: `segments: DonutChartSegment[]`, `c`, `title?`, `subtitle?`, `width?: number = 360`, `height?: number = 230`, `size?`, `thickness?`, `format?: ChartValueFormat = "decimal"`, `centerLabel?`, `centerValue?`, `showLegend?: boolean = true`, `footer?`. `DonutChartSegment`: `label`, `value`, `color?`, `valueLabel?`.
|
|
354
|
-
- `BarChart`: `data: BarChartDatum[]`, `c`, `title?`, `subtitle?`, `width?: number = 320`, `height?: number = 220`, `min?`, `max?`, `format?: ChartValueFormat = "decimal"`, `showGrid?: boolean = true`, `showValues?: boolean = true`, `yAxisLabel?`, `footer?`. `BarChartDatum`: `label`, `value`, `color?`, `valueLabel?`.
|
|
355
|
-
- `ParetoBarChart`: `data: BarChartDatum[]`, `c`, `title?`, `subtitle?`, `width?: number = 520`, `height?: number = 300`, `format?: ChartValueFormat = "integer"`, `showGrid?: boolean = true`, `showValues?: boolean = true`, `footer?`. A classic categorical Pareto chart with descending bars and a cumulative percentage line, separate value/share axes, and stable tie order. Values must be finite and non-negative. Sorting preserves the input array. A positive total ends at 100%; an all-zero total stays at 0%. Use this for the causes behind a total, and `ParetoChart` for a non-dominated scatter frontier. See `examples/pareto-bar-chart.tsx`.
|
|
356
|
-
- `LineChart`: `series: LineChartSeries[]`, `c`, `title?`, `subtitle?`, `width?: number = 420`, `height?: number = 240`, `labels?`, `min?`, `max?`, `format?: ChartValueFormat = "decimal"`, `showGrid?: boolean = true`, `showPoints?: boolean = true`, `yAxisLabel?`, `footer?`. `LineChartSeries`: `name`, `points`, `color?`, `area?`.
|
|
357
|
-
- `ScatterPlot`: `points: ScatterPoint[]`, `c`, `title?`, `subtitle?`, `width?: number = 380`, `height?: number = 260`, `xMin?`, `xMax?`, `yMin?`, `yMax?`, `xAxisLabel?`, `yAxisLabel?`, `formatX?: ChartValueFormat = "decimal"`, `formatY?: ChartValueFormat = "decimal"`, `showGrid?: boolean = true`, `footer?`. `ScatterPoint`: `x`, `y`, `label?`, `color?`, `size?`.
|
|
358
|
-
- `ParetoChart`: `points: ScatterPoint[]`, `c`, `title?`, `subtitle?`, `width?: number = 640`, `height?: number = 360`, `xMin?`, `xMax?`, `yMin?`, `yMax?`, `xAxisLabel?`, `yAxisLabel?`, `formatX?: ChartValueFormat = "decimal"`, `formatY?: ChartValueFormat = "decimal"`, `showGrid?: boolean = true`, `xScale?: "linear" | "log" = "linear"`, `xObjective?: "minimize" | "maximize" = "minimize"`, `yObjective?: "minimize" | "maximize" = "maximize"`, `frontierColor?`, `showGoal?: boolean = true`, `goalLabel?`, `footer?`. It detects non-dominated points automatically; logarithmic x scales omit non-positive points.
|
|
359
|
-
- `QuadrantChart`: `points: ScatterPoint[]`, `regions`, `c`, `title?`, `subtitle?`, `width?: number = 700`, `height?: number = 360`, `xMin?`, `xMax?`, `yMin?`, `yMax?`, `xThreshold?`, `yThreshold?`, `xAxisLabel?`, `yAxisLabel?`, `formatX?: ChartValueFormat = "decimal"`, `formatY?: ChartValueFormat = "decimal"`, `showTicks?: boolean = false`, `showGrid?: boolean = false`, `footer?`. Without explicit domains, points use normalized 0-1 coordinates and thresholds default to centered splits. `regions`: `{ topLeft, topRight, bottomLeft, bottomRight }`, each `QuadrantRegion`: `label`, `detail?`, `color?`, `emphasis?`.
|
|
360
|
-
- `IntervalPlot`: `data: IntervalDatum[]`, `c`, `title?`, `subtitle?`, `width?: number = 640`, `height?: number = 220`, `min?`, `max?`, `format?: ChartValueFormat = "decimal"`, `axisLabel?`, `footer?`. `IntervalDatum`: `label`, `low`, `mid`, `high`, `color?`, `lowLabel?`, `midLabel?`, `highLabel?`.
|
|
361
|
-
- `StackedBar`: `segments: StackedBarSegment[]`, `c`, `width?: number = 480`, `height?: number = 68`, `title?`, `subtitle?`, `showLegend?: boolean = true`. `StackedBarSegment`: `label`, `value`, `color?`, `valueLabel?`.
|
|
362
|
-
- `MiniBarChart`: `data: MiniBarDatum[]`, `c`, `max?`, `minBarHeight?: number = 8`, `height?: number = 92`, `barWidth?: number = 22`, `gap?: number = 10`, `radius?: number = 7`, `fontSize?: number = 11`, `showValues?: boolean = false`. `MiniBarDatum`: `label`, `value`, `tone?`, `color?`, `valueLabel?`, `opacity?`.
|
|
363
|
-
- `AxisPlot`: `c`, `width`, `height`, `xMin?: number = -1`, `xMax?: number = 1`, `yMin?: number = -1`, `yMax?: number = 1`, `padding?: number = 18`, `showFrame?: boolean = true`, `showAxes?: boolean = true`, `showGrid?: boolean = false`, `gridCount?: number = 5`, `frameRx?: number = 8`, `frameFill?`, `frameStroke?`, `axisColor?`, `points?: AxisPlotPoint[] = []`, `vectors?: AxisPlotVector[] = []`, `paths?: AxisPlotPath[] = []`, `xAxisLabel?`, `yAxisLabel?`, `children?`.
|
|
364
|
-
- `AxisPlotPoint`: `x`, `y`, `fill?`, `tone?`, `r?`, `stroke?`, `strokeWidth?`, `opacity?`.
|
|
365
|
-
- `AxisPlotVector`: `x1`, `y1`, `x2`, `y2`, `color?`, `tone?`, `strokeWidth?`, `opacity?`, `arrow?`, `arrowSize?`, `showStartDot?`, `showEndDot?`, `dotRadius?`.
|
|
366
|
-
- `AxisPlotPath`: `points: Array<{ x, y }>`, `color?`, `tone?`, `strokeWidth?`, `opacity?`, `interpolation?: "linear" | "step-after"`, `dashed?`.
|
|
367
|
-
- `ChartValueFormat`: `"decimal" | "percent" | "integer" | "compact" | ((value: number) => string)`.
|
|
368
|
-
|
|
369
|
-
SVG and geometry helpers:
|
|
370
|
-
|
|
371
|
-
- `SvgFrame`: `key?`, `x?: number = 0`, `y?: number = 0`, `width`, `height`, `c`, `rx?: number = 8`, `fill?`, `stroke?`, `strokeWidth?: number = 1`, `opacity?`.
|
|
372
|
-
- `SvgPoint`: `key?`, `cx`, `cy`, `r?: number = 5`, `fill`, `stroke?`, `strokeWidth?`, `opacity?`.
|
|
373
|
-
- `SvgMathText`: positioned HTML overlay with `text`, `x`, `y`, `fill`, `fontSize?: number = 13`, `fontFamily?: string = "JetBrains Mono"`, `fontWeight?: number = 800`, `textAnchor?: "start" | "middle" | "end" = "middle"`, `dominantBaseline?: string = "middle"`, `opacity?: number = 1`. Place it beside, not inside, raw SVG geometry in a `position: "relative"` container.
|
|
374
|
-
- `SvgFrame` pairs well with `VectorArrow`, `VectorSegment`, `SvgPoint`, `DotPoint`, `DashedLine`, and `Legend` inside custom SVG.
|
|
375
|
-
- `Arrow`: `direction?: "down" | "right" | "up" | "left" = "down"`, `label?`, `length?: number = 40`, `c`, `color?`.
|
|
376
|
-
- `VectorArrow`: `key?`, `x1`, `y1`, `x2`, `y2`, `color`, `strokeWidth?: number = 2`, `arrowSize?: number = 2.2`, `opacity?: number = 1`.
|
|
377
|
-
- `VectorSegment`: `key?`, `x1`, `y1`, `x2`, `y2`, `color`, `strokeWidth?: number = 4`, `opacity?: number = 1`, `showStartDot?: boolean = false`, `showEndDot?: boolean = true`, `dotRadius?: number = 4.5`.
|
|
378
|
-
- `Box`: `label`, `c`, `color?: ColorName = "primary"`, `width?`, `height?`, `fontSize?: number = 14`, `gradient?: boolean = false`, `sublabel?`, `icon?`, `radius?: number = 8`, `outlined?: boolean = false`.
|
|
379
|
-
- `ArrowMarkerDef`: `id`, `color`, `size?: number = 5`.
|
|
380
|
-
- `DotPoint`: `x`, `y`, `label`, `color`, `c`, `size?: number = 12`, `labelOffset?: { x?: number; y?: number }`.
|
|
381
|
-
- `DashedLine`: `x1`, `y1`, `x2`, `y2`, `color`, `dotSpacing?: number = 8`, `dotSize?: number = 2`.
|
|
382
|
-
- `Legend`: `items: LegendItem[]`, `c`, `title?`. `LegendItem`: `label`, `color`, `style?: "solid" | "dashed"`.
|
|
383
|
-
|
|
384
|
-
Theme and render APIs:
|
|
385
|
-
|
|
386
|
-
- `checkFrame(frame, options?)`: Check `{ scene: ReactNode }` or `{ create(theme): ReactNode }` inputs. Frame metadata accepts `source?`, `width?`, `height?`, and `autoSize?`. Options accept `themes?: ThemeMode[]`, `background?: "transparent" | "theme" | CSS color`, and `failOn?: "error" | "warning" | "info" | "never"`; defaults are both themes, transparent background, and errors only. `ok` means diagnostics pass `failOn`; `rendered` means every requested theme completed rendering. Reports include per-theme `dimensions` and `diagnostics`, plus `summary` severity counts.
|
|
387
|
-
- `CHECK_DIAGNOSTIC_CODES`, `CheckDiagnostic`, `CheckDiagnosticCode`, `CheckDiagnosticLocation`, `CheckAutoSize`, `CheckAutoSizeAxes`, `CheckFrameInput`, `CheckFrameReport`, `CheckOptions`: Stable code list and TypeScript contracts for programmatic checks. Locations contain a React `path` or rendered `x`, `y`, `width`, and `height`; available element identifiers appear as `elementId` and `relatedElementIds` on diagnostics.
|
|
388
|
-
- `getThemeColors(mode, preset?)`: `mode: ThemeMode`; `preset?: "default" | "engineering"`. Use `engineering` for flat technical-blog figures with a light gray palette, left-aligned black titles, pastel nodes, thin neutral connectors, compact corners, no shadows, Inter labels, and JetBrains Mono annotations. In a bare frame, set `preset = "engineering";` before the JSX. Add `background={c.bg}` to `Scene` for an opaque light gray canvas; omit it for alpha transparency.
|
|
389
|
-
- `getToneColor(tone, c)`, `getToneFill(tone, c)`, `getToneGradient(tone)`, `getColor(name, c?)`, `getGradient(name)`, `heatColor(value)`.
|
|
390
|
-
- `getReadableColor(name, c)`: returns the semantic color variant with greatest contrast against `c.bgCard`.
|
|
391
|
-
- `getReadableToneColor(tone, c, background?)`: maps a tone to a readable semantic color and falls back to readable foreground text when contrast is below 4.5:1. `background` defaults to `c.bgCard`.
|
|
392
|
-
- `getReadableTextColor(background, c)`: parses solid or alpha CSS colors and chooses a theme foreground meeting 4.5:1 contrast when possible.
|
|
393
|
-
- `createPlotArea(width, height, margin)`: returns `PlotArea` geometry with inner width and height clamped to at least one pixel.
|
|
394
|
-
- `renderToPng(element, options, createFn?, theme?)`: `element`, `options: RenderOptions`, `createFn?: (theme: "dark" | "light") => ReactNode`, `theme?: "dark" | "light"`.
|
|
395
|
-
- `renderToPngWithOutput(...)`: same arguments as `renderToPng`; returns logical `width` / `height`, physical `pixelWidth` / `pixelHeight`, and painted `contentBounds`.
|
|
396
|
-
- `CanvasOverflowError`: typed clipping failure from strict static or animated renders. Exposes `width`, `height`, `overflow`, and optional animation frame/scene/time/label metadata.
|
|
397
|
-
- `Watermark`: JSX marker component for frame-module exports. Props are `WatermarkOptions` plus `children?: ReactNode`; children become the complete watermark body.
|
|
398
|
-
- `WatermarkInput`: `boolean | string | WatermarkOptions | ReactElement<WatermarkElementProps>`. `true` uses Vizmatic defaults. A string sets the watermark text. A React element can be `<Watermark>...</Watermark>` or any custom element.
|
|
399
|
-
- `WatermarkImageOptions`: `src`, `width?: number`, `height?: number`, `alt?: string`. Programmatic `src` should be a URL or data URI. CLI `--watermark-image` accepts URL, data URI, or local path.
|
|
400
|
-
- `WatermarkOptions`: `text?: string | false`, `image?: string | WatermarkImageOptions`, `icon?: ReactNode | string | false`, `element?: ReactNode`, `position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" = "top-right"`, `opacity?: number`, `color?: string`.
|
|
401
|
-
- `normalizeWatermark(input)`: converts boolean, string, object, or React-element `WatermarkInput` to `WatermarkOptions | undefined`.
|
|
402
|
-
- `wrapWithBrand(element, width, height, theme?, label?)`: compatibility wrapper around `wrapWithWatermark`; theme defaults to `"dark"` and label defaults to `"Vizmatic"`.
|
|
403
|
-
- `getFonts()`: lazily loads and caches bundled Satori font data for advanced integrations.
|
|
404
|
-
- `loadAdditionalAsset(code, segment)`: Satori missing-glyph callback; resolves emoji segments from the compressed offline Twemoji bundle or public fallback and returns an empty font list for other codes.
|
|
405
|
-
- `RenderOptions`: `width`, `height`, `outputPath`, `background?: "transparent" | "theme" | CSS color = "transparent"`, `theme?: "dark" | "light" = "dark"` for direct-render watermark defaults, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `crop?: boolean | "height" | "both" = true`, `scale?: number = 2`. Default autocrop retains 24 source pixels around detected content. Use `crop: "height"` when host layouts require stable width but should still trim extra vertical whitespace.
|
|
406
|
-
- `renderToBuffer(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`, `scale?`.
|
|
407
|
-
- `renderToSvg(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`.
|
|
408
|
-
- `defineAnimation({ initial, timeline, render, fps? })`: creates deterministic typed state animation. `fps` defaults to `20` and accepts integers from `1` to `50`.
|
|
409
|
-
- `hold(duration, label?)`: keep current state for milliseconds.
|
|
410
|
-
- `tween(to, { duration, easing?, interpolate?, label? })`: transition listed properties together. Easing is `"linear" | "ease-in" | "ease-out" | "ease-in-out"` or pure progress function.
|
|
411
|
-
- `keyframe(value, label?)`: apply instant partial state update.
|
|
412
|
-
- `parallel(tracks, label?)`: run property tracks concurrently; each track accepts `hold`, `tween`, and `keyframe` steps.
|
|
413
|
-
- `sampleAnimation(animation, time)`: evaluate state at exact millisecond.
|
|
414
|
-
- `sampleAnimationFrame(animation, time, { index, count, delay, fps })`: sample state and timeline context at an exact video timestamp.
|
|
415
|
-
- `sampleAnimationFrames(animation, { fps? })`: return deterministic state/frame samples with GIF-compatible delays.
|
|
416
|
-
- `analyzeAnimationCadence(animation, { fps? })`: return frame count, encoded duration, target interval, and delay range without rendering.
|
|
417
|
-
- `renderAnimationGif(animation, options)`: stream timeline samples into GIF.
|
|
418
|
-
- `renderAnimationVideo(animation, { width, height, outputPath, fps?, scale?, theme?, background?, watermark?, audioPath?, crf?, preset?, threads?, signal? })`: render typed TSX frames to H.264 MP4. Defaults to 30 fps and an opaque theme background; streams frames and checks overflow at each timestamp. FFmpeg is installed separately.
|
|
419
|
-
- `renderRgbaVideo(renderFrame, { width, height, duration, outputPath, fps?, audioPath?, crf?, preset?, signal? })`: encode caller-painted RGBA frames without buffering the whole film.
|
|
420
|
-
- `tracePolyline(points, progress)` and `pointAlongPath(points, progress)`: reveal and follow a path by arc length; `arcSwap(from, to, progress, options?)` exchanges positions along mirrored arcs; `smoothstep(progress)` clamps and eases progress.
|
|
421
|
-
- `renderAnimationGifWithOutput(animation, options)`: same arguments and returns dimensions, input/encoded frame counts, delta-frame count, duration, and byte size.
|
|
422
|
-
- `renderAnimatedGif(scenes, options)`: legacy `AnimatedScene[]` renderer for scene cuts and pixel transitions. It also accepts a defined animation.
|
|
423
|
-
- `renderAnimatedGifWithOutput(scenes, options)`: same arguments as `renderAnimatedGif`; returns dimensions and encoding metrics.
|
|
424
|
-
- `AnimatedScene`: `element`, `duration` in ms, `transition?: "none" | "fade" | "appear"`, `transitionDuration?`, `label?`.
|
|
425
|
-
- `AnimationOptions`: `width`, `height`, `outputPath`, `loop?: number = 0`, `scale?: number = 1`, `fps?: number`, `deltaFrames?: boolean = true`, `background?: "theme" | "transparent" | CSS color = "theme"`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `theme?: "dark" | "light" = "dark"`. Every actual frame is checked for overflow. Opaque GIFs encode changed rectangles; transparent GIFs stay full-frame for correct one-bit compositing. Use PNG/SVG when smooth alpha edges matter.
|
|
426
|
-
|
|
427
|
-
## Prop-aware examples
|
|
428
|
-
|
|
429
|
-
### Window + code + status
|
|
430
|
-
|
|
431
|
-
```tsx
|
|
432
|
-
width = 1040;
|
|
433
|
-
height = 560;
|
|
434
|
-
|
|
435
|
-
<Scene title="Release gate" subtitle="tool output and checklist">
|
|
436
|
-
<Row gap={18} align="stretch">
|
|
437
|
-
<WindowFrame title="ci.log" variant="terminal" tone="green" width={520}>
|
|
438
|
-
<CodeBlock
|
|
439
|
-
fontSize={12}
|
|
440
|
-
showLineNumbers
|
|
441
|
-
lines={[
|
|
442
|
-
{ text: "pnpm typecheck", tone: "green", prefix: "$" },
|
|
443
|
-
{ text: "pnpm test", tone: "green", prefix: "$" },
|
|
444
|
-
{ text: "pnpm render:examples", tone: "cyan", prefix: "$" },
|
|
445
|
-
]}
|
|
446
|
-
/>
|
|
447
|
-
</WindowFrame>
|
|
448
|
-
<StatusList
|
|
449
|
-
width={360}
|
|
450
|
-
rows={[
|
|
451
|
-
{ label: "Types", detail: "clean", status: "check", tone: "green" },
|
|
452
|
-
{ label: "Visuals", detail: "dark/light generated", status: "check", tone: "cyan" },
|
|
453
|
-
{ label: "NPM", detail: "auth required", status: "warn", tone: "warm" },
|
|
454
|
-
]}
|
|
455
|
-
/>
|
|
456
|
-
</Row>
|
|
457
|
-
</Scene>
|
|
458
117
|
```
|
|
459
118
|
|
|
460
|
-
|
|
119
|
+
## Reference
|
|
461
120
|
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
<Row gap={18} align="stretch">
|
|
468
|
-
<Heatmap
|
|
469
|
-
title="Attention"
|
|
470
|
-
xLabels={["q1", "q2", "q3"]}
|
|
471
|
-
yLabels={["k1", "k2", "k3"]}
|
|
472
|
-
data={[
|
|
473
|
-
[0.9, 0.2, 0.1],
|
|
474
|
-
[0.4, 0.8, 0.2],
|
|
475
|
-
[0.1, 0.3, 0.7],
|
|
476
|
-
]}
|
|
477
|
-
/>
|
|
478
|
-
<Matrix
|
|
479
|
-
title="Scores"
|
|
480
|
-
format="decimal"
|
|
481
|
-
rowLabels={["A", "B", "C"]}
|
|
482
|
-
colLabels={["x", "y", "z"]}
|
|
483
|
-
data={[
|
|
484
|
-
[0.4, 0.7, 0.2],
|
|
485
|
-
[0.5, 0.2, 0.8],
|
|
486
|
-
]}
|
|
487
|
-
/>
|
|
488
|
-
<StackedBar
|
|
489
|
-
width={300}
|
|
490
|
-
title="Token budget"
|
|
491
|
-
segments={[
|
|
492
|
-
{ label: "prompt", value: 42, color: "primary" },
|
|
493
|
-
{ label: "context", value: 38, color: "info" },
|
|
494
|
-
{ label: "answer", value: 20, color: "positive" },
|
|
495
|
-
]}
|
|
496
|
-
/>
|
|
497
|
-
</Row>
|
|
498
|
-
</Scene>
|
|
499
|
-
```
|
|
500
|
-
|
|
501
|
-
## Rendering rules
|
|
502
|
-
|
|
503
|
-
- Use semantic tones instead of hard-coded colors: `blue`, `purple`, `green`, `warm`, `cyan`, `pink`, `critical`, `ocean`, `neutral`.
|
|
504
|
-
- For Datadog Engineering-style article diagrams, set `preset = "engineering";` and render the light theme. Keep each figure focused on one transition or tradeoff.
|
|
505
|
-
- Use explicit sizes for final assets. Common sizes are `1040x560` for article figures, `1280x720` for slide frames, and `900x520` for compact diagrams.
|
|
506
|
-
- During exploration, dimensions can be omitted. Vizmatic starts at `960x540` and grows to fit content.
|
|
507
|
-
- Prefer alpha-transparent PNG/SVG backgrounds for blog embeds and docs cards. Use theme backgrounds only when the host surface is unknown or needs full-frame fill.
|
|
508
|
-
- Use `width`, `minWidth`, `height`, `minHeight`, `gap`, and `padding` to keep layout stable.
|
|
509
|
-
- Keep text short. Use `TextLabel`, `Panel`, `StepCard`, `MetricCard`, `DataTable`, and `Grid` for wrapping-safe labels.
|
|
510
|
-
- Omit `x` and `y` from `GraphDiagram` nodes for automatic layered layout and nested groups. Add both only when an ungrouped graph needs editorial manual control.
|
|
511
|
-
- Render reusable assets in both themes with `--theme dark,light`.
|
|
512
|
-
- Run `vizmatic check <frame> --theme dark,light --json` before final render and fix every error.
|
|
513
|
-
- Use GIF only when motion explains state change. Prefer `createAnimation(theme)` with `hold` and `tween`, keep timelines short, match terminal and initial visuals for infinite loops, and keep static `create(theme)` fallback. Sampling follows exact cadence boundaries and includes terminal state. Use `analyzeAnimationCadence` when timing must be audited. Use `createScenes(theme)` only for deliberate cuts or crossfades.
|
|
514
|
-
- If render fails with `Canvas overflow detected`, increase the canvas, reduce content, or remove strict sizing. Do not ignore the error.
|
|
515
|
-
- Confirm generated files exist and open at least one image before finishing.
|
|
516
|
-
|
|
517
|
-
## Common recipes
|
|
518
|
-
|
|
519
|
-
### RAG graph
|
|
520
|
-
|
|
521
|
-
```tsx
|
|
522
|
-
width = 1040;
|
|
523
|
-
height = 560;
|
|
524
|
-
|
|
525
|
-
<Scene title="RAG control graph" subtitle="retrieval with a citation check" align="center">
|
|
526
|
-
<GraphDiagram
|
|
527
|
-
width={820}
|
|
528
|
-
height={390}
|
|
529
|
-
nodeWidth={132}
|
|
530
|
-
rankGap={44}
|
|
531
|
-
nodes={[
|
|
532
|
-
{ id: "query", label: "Query", detail: "intent", tone: "blue" },
|
|
533
|
-
{ id: "retrieve", label: "Retrieve", detail: "top-k docs", tone: "cyan" },
|
|
534
|
-
{ id: "rerank", label: "Rerank", detail: "quality gate", tone: "warm" },
|
|
535
|
-
{ id: "answer", label: "Answer", detail: "grounded draft", tone: "green" },
|
|
536
|
-
{ id: "verify", label: "Verify", detail: "citations", tone: "critical" },
|
|
537
|
-
]}
|
|
538
|
-
edges={[
|
|
539
|
-
{ from: "query", to: "retrieve", label: "search", tone: "blue" },
|
|
540
|
-
{ from: "retrieve", to: "rerank", label: "rank", tone: "cyan" },
|
|
541
|
-
{ from: "rerank", to: "answer", label: "context", tone: "green" },
|
|
542
|
-
{ from: "answer", to: "verify", label: "claims", tone: "critical" },
|
|
543
|
-
]}
|
|
544
|
-
/>
|
|
545
|
-
</Scene>
|
|
546
|
-
```
|
|
547
|
-
|
|
548
|
-
### Evaluation dashboard
|
|
549
|
-
|
|
550
|
-
```tsx
|
|
551
|
-
width = 1040;
|
|
552
|
-
height = 620;
|
|
553
|
-
|
|
554
|
-
<Scene title="Evaluation snapshot" subtitle="charts inherit theme, labels, and contrast">
|
|
555
|
-
<Row gap={18} align="stretch">
|
|
556
|
-
<BarChart
|
|
557
|
-
width={440}
|
|
558
|
-
height={260}
|
|
559
|
-
title="Pass rate by task"
|
|
560
|
-
format="percent"
|
|
561
|
-
data={[
|
|
562
|
-
{ label: "tools", value: 0.82, color: "positive" },
|
|
563
|
-
{ label: "math", value: 0.71, color: "secondary" },
|
|
564
|
-
{ label: "code", value: 0.77, color: "primary" },
|
|
565
|
-
{ label: "long", value: 0.58, color: "warning" },
|
|
566
|
-
]}
|
|
567
|
-
/>
|
|
568
|
-
<LineChart
|
|
569
|
-
width={440}
|
|
570
|
-
height={260}
|
|
571
|
-
title="Quality over releases"
|
|
572
|
-
format="percent"
|
|
573
|
-
labels={["v1", "v2", "v3", "v4", "v5"]}
|
|
574
|
-
series={[
|
|
575
|
-
{ name: "quality", points: [0.55, 0.61, 0.69, 0.74, 0.81], color: "positive", area: true },
|
|
576
|
-
{ name: "latency", points: [0.72, 0.69, 0.66, 0.62, 0.59], color: "warning" },
|
|
577
|
-
]}
|
|
578
|
-
/>
|
|
579
|
-
</Row>
|
|
580
|
-
</Scene>
|
|
581
|
-
```
|
|
121
|
+
- [CLI](https://bvolpato.github.io/vizmatic/docs/cli.html) and [Exporting](https://bvolpato.github.io/vizmatic/docs/exporting.html): every flag.
|
|
122
|
+
- [Animations](https://bvolpato.github.io/vizmatic/docs/animations.html), [Objects](https://bvolpato.github.io/vizmatic/docs/objects.html), [Camera](https://bvolpato.github.io/vizmatic/docs/camera.html), and [3D](https://bvolpato.github.io/vizmatic/docs/three-d.html): the film API.
|
|
123
|
+
- [Figure recipes](https://bvolpato.github.io/vizmatic/docs/figure-recipes.html) and [Figures reference](https://bvolpato.github.io/vizmatic/docs/figures.html): component props and complete frames.
|
|
124
|
+
- [Science guide](https://github.com/bvolpato/vizmatic/blob/main/SCIENCE.md): accurate diagrams for math, physics, chemistry, and machine learning.
|
|
125
|
+
- [`llms-full.txt`](https://bvolpato.github.io/vizmatic/llms-full.txt): this prompt, all guides, and the component catalog.
|
|
582
126
|
|
|
583
127
|
## Final response
|
|
584
128
|
|
|
585
129
|
After creating a visual, report:
|
|
586
130
|
|
|
587
131
|
- files created or changed
|
|
588
|
-
- render command used
|
|
589
|
-
- output
|
|
590
|
-
-
|
|
591
|
-
- whether
|
|
132
|
+
- the exact render command used
|
|
133
|
+
- output paths
|
|
134
|
+
- which looks or themes rendered
|
|
135
|
+
- whether `vizmatic check` passed
|
|
592
136
|
- any overflow or layout fixes made
|