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.
Files changed (57) hide show
  1. package/LICENSE +21 -0
  2. package/PROMPT.md +500 -0
  3. package/README.md +530 -0
  4. package/dist/chunk-ADU7JROD.js +627 -0
  5. package/dist/cli.d.ts +1 -0
  6. package/dist/cli.js +303 -0
  7. package/dist/index.d.ts +1433 -0
  8. package/dist/index.js +4702 -0
  9. package/docs/PROMPT.md +500 -0
  10. package/docs/assets/examples/.gitkeep +1 -0
  11. package/docs/assets/examples/agent-pipeline_dark.png +0 -0
  12. package/docs/assets/examples/agent-pipeline_light.png +0 -0
  13. package/docs/assets/examples/animated-pipeline_dark.gif +0 -0
  14. package/docs/assets/examples/animated-pipeline_dark.png +0 -0
  15. package/docs/assets/examples/animated-pipeline_light.gif +0 -0
  16. package/docs/assets/examples/animated-pipeline_light.png +0 -0
  17. package/docs/assets/examples/attention-head_dark.png +0 -0
  18. package/docs/assets/examples/attention-head_light.png +0 -0
  19. package/docs/assets/examples/embedding-map_dark.png +0 -0
  20. package/docs/assets/examples/embedding-map_light.png +0 -0
  21. package/docs/assets/examples/eval-dashboard_dark.png +0 -0
  22. package/docs/assets/examples/eval-dashboard_light.png +0 -0
  23. package/docs/assets/examples/gif-manifest.json +12 -0
  24. package/docs/assets/examples/manifest.json +108 -0
  25. package/docs/assets/examples/model-router_dark.png +0 -0
  26. package/docs/assets/examples/model-router_light.png +0 -0
  27. package/docs/assets/examples/presentation-frame_dark.png +0 -0
  28. package/docs/assets/examples/presentation-frame_light.png +0 -0
  29. package/docs/assets/examples/rag-graph_dark.png +0 -0
  30. package/docs/assets/examples/rag-graph_light.png +0 -0
  31. package/docs/assets/examples/release-card_dark.png +0 -0
  32. package/docs/assets/examples/release-card_light.png +0 -0
  33. package/docs/assets/examples/research-landscape_dark.png +0 -0
  34. package/docs/assets/examples/research-landscape_light.png +0 -0
  35. package/docs/assets/examples/sources.json +93 -0
  36. package/docs/assets/examples/spec-anatomy_dark.png +0 -0
  37. package/docs/assets/examples/spec-anatomy_light.png +0 -0
  38. package/docs/assets/examples/theme-system_dark.png +0 -0
  39. package/docs/assets/examples/theme-system_light.png +0 -0
  40. package/docs/assets/examples/token-matrix_dark.png +0 -0
  41. package/docs/assets/examples/token-matrix_light.png +0 -0
  42. package/docs/assets/icon.svg +16 -0
  43. package/docs/assets/logo.svg +30 -0
  44. package/examples/agent-pipeline.tsx +27 -0
  45. package/examples/animated-pipeline.tsx +72 -0
  46. package/examples/attention-head.tsx +27 -0
  47. package/examples/embedding-map.tsx +34 -0
  48. package/examples/eval-dashboard.tsx +44 -0
  49. package/examples/model-router.tsx +35 -0
  50. package/examples/presentation-frame.tsx +32 -0
  51. package/examples/rag-graph.tsx +36 -0
  52. package/examples/release-card.tsx +39 -0
  53. package/examples/research-landscape.tsx +34 -0
  54. package/examples/spec-anatomy.tsx +44 -0
  55. package/examples/theme-system.tsx +30 -0
  56. package/examples/token-matrix.tsx +49 -0
  57. package/package.json +84 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Bruno Volpato
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/PROMPT.md ADDED
@@ -0,0 +1,500 @@
1
+ # Vizmatic Agent Prompt
2
+
3
+ Use Vizmatic to create polished, theme-aware diagrams, figures, dashboards, presentation frames, and animated GIFs from structured React scene primitives.
4
+
5
+ ## Install
6
+
7
+ Use the package manager already present in the project.
8
+
9
+ ```bash
10
+ pnpm add vizmatic react
11
+ ```
12
+
13
+ If the npm package is not available yet, install from GitHub:
14
+
15
+ ```bash
16
+ pnpm add github:bvolpato/vizmatic react
17
+ ```
18
+
19
+ For npm/yarn/bun projects, use the equivalent package-manager command.
20
+
21
+ ## Create a frame
22
+
23
+ Create `frames/agent-pipeline.tsx`:
24
+
25
+ ```tsx
26
+ import React from "react"
27
+ import {
28
+ CalloutCard,
29
+ defineIllustration,
30
+ Flow,
31
+ Row,
32
+ Scene,
33
+ } from "vizmatic"
34
+
35
+ export const width = 1040
36
+ export const height = 560
37
+
38
+ const frame = defineIllustration((c) => (
39
+ <Scene
40
+ c={c}
41
+ title="Agent visual pipeline"
42
+ subtitle="prompt -> scene spec -> verified artifact"
43
+ gap={26}
44
+ >
45
+ <Flow
46
+ c={c}
47
+ connectorTone="purple"
48
+ stages={[
49
+ {
50
+ eyebrow: "input",
51
+ title: "Prompt",
52
+ subtitle: "intent and constraints",
53
+ tone: "blue",
54
+ lines: ["domain language", "audience", "theme tokens"],
55
+ width: 190,
56
+ },
57
+ {
58
+ eyebrow: "contract",
59
+ title: "Scene spec",
60
+ subtitle: "typed structure",
61
+ tone: "purple",
62
+ lines: ["cards", "flows", "charts", "tables"],
63
+ width: 190,
64
+ },
65
+ {
66
+ eyebrow: "render",
67
+ title: "Satori frame",
68
+ subtitle: "React primitives",
69
+ tone: "cyan",
70
+ lines: ["layout defaults", "safe text", "semantic tones"],
71
+ width: 190,
72
+ },
73
+ {
74
+ eyebrow: "output",
75
+ title: "PNG / GIF",
76
+ subtitle: "CI-ready asset",
77
+ tone: "green",
78
+ lines: ["autocrop", "overflow checks", "retina scale"],
79
+ width: 190,
80
+ },
81
+ ]}
82
+ />
83
+ <Row width="100%" gap={14}>
84
+ <CalloutCard
85
+ c={c}
86
+ title="Model writes structure"
87
+ detail="No hand-written SVG paths or brittle x/y layout for common cases."
88
+ tone="purple"
89
+ width={470}
90
+ />
91
+ <CalloutCard
92
+ c={c}
93
+ title="Design system stays in control"
94
+ detail="Theme tokens decide color, typography, radius, spacing, and contrast."
95
+ tone="green"
96
+ width={470}
97
+ />
98
+ </Row>
99
+ </Scene>
100
+ ))
101
+
102
+ export const create = frame.create
103
+ export default frame.default
104
+ ```
105
+
106
+ Render it:
107
+
108
+ ```bash
109
+ pnpm exec vizmatic render frames --out public/vizmatic --theme dark,light --watermark "Your Product" --watermark-image ./logo.svg --watermark-position top-right
110
+ ```
111
+
112
+ Render animated frames with `createScenes(theme)`:
113
+
114
+ ```bash
115
+ pnpm exec vizmatic gif frames/animated-pipeline.tsx --out public/vizmatic --theme dark,light --watermark "Your Product" --watermark-image ./logo.svg --watermark-position top-right --scale 1
116
+ ```
117
+
118
+ ## Create an animated frame
119
+
120
+ Animated frames keep the same static `create(theme)` export and add `createScenes(theme)` for GIF output.
121
+
122
+ ```tsx
123
+ import React from "react"
124
+ import {
125
+ CalloutCard,
126
+ defineIllustration,
127
+ Flow,
128
+ Scene,
129
+ getThemeColors,
130
+ type AnimatedScene,
131
+ type ThemeColors,
132
+ type ThemeMode,
133
+ } from "vizmatic"
134
+
135
+ export const width = 1040
136
+ export const height = 560
137
+
138
+ const stages = [
139
+ { title: "Prompt", tone: "blue" as const },
140
+ { title: "Scene spec", tone: "purple" as const },
141
+ { title: "PNG / GIF", tone: "green" as const },
142
+ ]
143
+
144
+ function buildFrame(c: ThemeColors, active: number) {
145
+ return (
146
+ <Scene c={c} title="Animated agent pipeline">
147
+ <Flow
148
+ c={c}
149
+ stages={stages.map((stage, index) => ({
150
+ ...stage,
151
+ title: index <= active ? stage.title : "Pending",
152
+ tone: index <= active ? stage.tone : "neutral",
153
+ }))}
154
+ />
155
+ <CalloutCard c={c} title="Scene changes over time" detail="Render with vizmatic gif." tone="green" />
156
+ </Scene>
157
+ )
158
+ }
159
+
160
+ const frame = defineIllustration((c) => buildFrame(c, stages.length - 1))
161
+
162
+ export function createScenes(theme: ThemeMode): AnimatedScene[] {
163
+ const c = getThemeColors(theme)
164
+ return stages.map((_, index) => ({
165
+ element: buildFrame(c, index),
166
+ duration: index === stages.length - 1 ? 1000 : 700,
167
+ transition: index === 0 ? "appear" : "fade",
168
+ }))
169
+ }
170
+
171
+ export const create = frame.create
172
+ export default frame.default
173
+ ```
174
+
175
+ ## Pick primitives first
176
+
177
+ Use Vizmatic primitives instead of raw SVG or absolute-positioned divs whenever possible. Drop to raw SVG only for custom geometry that a primitive cannot express.
178
+
179
+ Shared values:
180
+
181
+ - `ThemeMode`: `"dark" | "light"`.
182
+ - `ToneName`: `"blue" | "purple" | "green" | "warm" | "cyan" | "pink" | "red" | "critical" | "neutral" | "sunset" | "ocean" | "dark"`.
183
+ - `ColorName`: `"primary" | "secondary" | "positive" | "warning" | "critical" | "info" | "accent" | "neutral"`.
184
+ - `FlexAlign`: `"start" | "center" | "end" | "stretch"`.
185
+ - `FlexJustify`: `"start" | "center" | "end" | "space-between" | "space-around"`.
186
+ - Most visual components require `c: ThemeColors`; inside `defineIllustration((c) => ...)`, pass that same `c` down.
187
+
188
+ ## Component API
189
+
190
+ Frame helpers:
191
+
192
+ - `defineIllustration(build, defaultTheme?)`: `build: (c: ThemeColors) => ReactElement`, `defaultTheme?: ThemeMode = "dark"`. Returns `{ create(theme), default }`.
193
+ - `Canvas`: `children?`, `c`, `padding?: number = 40`, `justify?: "center" | "flex-start" | "space-between" | "space-around" = "center"`, `background?: string`.
194
+ - `Scene`: `c`, `children`, `title?`, `subtitle?`, `padding?: number = 40`, `gap?: number = 24`, `justify?: Canvas.justify = "flex-start"`, `align?: FlexAlign = "stretch"`, `contentWidth?: number | string = "100%"`, `background?`, `contentStyle?: React.CSSProperties`.
195
+ - `TitleBar`: `title`, `subtitle?`, `c`.
196
+
197
+ Layout primitives:
198
+
199
+ - `Row` / `Column`: `children`, `gap?: number = 12`, `align?: FlexAlign = "center"`, `justify?: FlexJustify = "center"`, `wrap?: boolean = false`, `width?: number | string`, `height?: number | string`, `style?: React.CSSProperties`.
200
+ - `Stack`: `children`, `direction?: "vertical" | "horizontal" = "vertical"`, `gap?: number = 12`, `align?: "start" | "center" | "end" | "stretch" = "center"`, `wrap?: boolean = false`.
201
+ - `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`.
202
+ - `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`.
203
+ - `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`.
204
+
205
+ Cards, labels, and compact UI:
206
+
207
+ - `TextLabel`: `text`, `c`, `variant?: keyof typography = "body"`, `color?`, `fontSize?`, `fontWeight?`, `width?`, `align?: "left" | "center" | "right" = "left"`, `math?: boolean = false`, `mono?: boolean = false`.
208
+ - `MathText`: `text`. Returns formatted unicode-ish math text for simple `_` and `^` notation.
209
+ - `formatMathText(text)`: `text: string`.
210
+ - `ToneStrip`: `tone`, `width?: number = 34`, `height?: number = 4`.
211
+ - `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`.
212
+ - `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 = 10`, `valueColor?`.
213
+ - `CalloutCard`: `c`, `children?`, `title?`, `detail?`, `tone?: ToneName = "blue"`, `width?`, `minHeight?`, `padding?: number | string = 12`, `filled?: boolean = true`, `align?: "left" | "center" = "center"`.
214
+ - `ValuePill`: `label`, `value`, `c`, `tone?: ToneName = "blue"`, `detail?`, `width?: number | string = 112`, `math?: boolean = false`.
215
+ - `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 = 9`, `mono?: boolean = true`, `filled?: boolean = false`, `math?: boolean = false`.
216
+ - `Badge`: `label`, `c`, `color?: ColorName = "primary"`.
217
+ - `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`.
218
+ - `EquationCard`: `title`, `formula`, `c`, `tone?: ToneName = "purple"`, `result?`, `detail?`, `width?: number | string = 190`, `height?`, `math?: boolean = false`, `align?: "left" | "center" = "left"`.
219
+ - `DetailList`: `items`, `c`, `tone?`, `gap?: number = 7`, `padding?: number | string = "7px 8px"`, `fontSize?: number = 10`, `mono?: boolean = false`, `math?: boolean = false`.
220
+
221
+ Lists, tables, status, and comparison:
222
+
223
+ - `ProgressRow`: `label`, `value: number`, `valueLabel?`, `tone?: ToneName = "blue"`, `muted?: boolean = false`, `c`, `labelWidth?: number = 42`, `valueWidth?: number = 38`, `barHeight?: number = 8`, `fontSize?: number = 10`. Keep `value` in `[0, 1]`.
224
+ - `ProgressList`: `rows: ProgressRowSpec[]`, `c`, `gap?: number = 8`, `labelWidth?`, `valueWidth?`, `barHeight?`, `fontSize?`. `ProgressRowSpec`: `label`, `value`, `valueLabel?`, `tone?`, `muted?`.
225
+ - `StatusRow`: `label`, `detail?`, `status?: "check" | "cross" | "warn" | "info" | "pending" | "dot" = "check"`, `tone?`, `c`, `boxed?: boolean = true`, `fontSize?: number = 11`, `width?`, `math?: boolean = false`.
226
+ - `StatusList`: `rows: StatusRowSpec[]`, `c`, `gap?: number = 7`, `boxed?: boolean = true`, `fontSize?`, `width?`, `math?: boolean = false`. `StatusRowSpec`: `label`, `detail?`, `status?`, `tone?`.
227
+ - `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?`.
228
+ - `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?`.
229
+ - `DataTable`: `rows: ReactNode[][]`, `c`, `cellWidth?: number = 54`, `firstColWidth?: number = cellWidth`, `cellHeight?: number = 28`, `gap?: number = 5`, `headerRows?: number = 1`, `headerCols?: number = 1`, `fontSize?: number = 10`, `math?: boolean = false`.
230
+ - `Grid`: `rows: Array<Array<ReactNode | GridCell>>`, `c`, `cellWidth?: number = 34`, `cellHeight?: number = 30`, `gap?: number = 5`, `radius?: number = 7`, `fontSize?: number = 10`, `math?: boolean = false`, `headerRows?: number = 0`, `headerCols?: number = 0`. `GridCell`: `label?`, `tone?`, `color?`, `backgroundColor?`, `borderColor?`, `opacity?`.
231
+ - `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?`.
232
+
233
+ Tiles:
234
+
235
+ - `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`.
236
+ - `TileGrid`: `tiles: TileSpec[]`, `c`, `columns?`, `gap?: number = 12`, `tileWidth?`, `minHeight?`, `align?: "left" | "center" = "center"`, `math?: boolean = false`.
237
+
238
+ Flows and process diagrams:
239
+
240
+ - `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?`.
241
+ - `FlowArrow`: `direction?: "down" | "right" | "up" | "left" = "right"`, `label?`, `length?: number = 40`, `c`, `tone?: ToneName = "blue"`, `color?`.
242
+ - `Connector`: same props as `FlowArrow`.
243
+ - `Pipeline`: `stages: PipelineStage[]`, `c`, `title?`. `PipelineStage`: `label`, `sublabel?`, `icon?`, `color?: ColorName`.
244
+
245
+ Graphs and networks:
246
+
247
+ - `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?`.
248
+ - `GraphDiagram`: `nodes: GraphDiagramNode[]`, `edges: GraphDiagramEdge[]`, `c`, `width?: number = 520`, `height?: number = 420`, `nodeWidth?: number = 150`, `nodeHeight?: number = 66`, `padding?: number = 28`. `GraphDiagramNode`: `id`, `label`, `detail?`, `x`, `y`, `tone?`, `muted?`, `width?`, `height?`. `GraphDiagramEdge`: `from`, `to`, `tone?`, `muted?`, `dashed?`, `label?`.
249
+
250
+ Matrices and heatmaps:
251
+
252
+ - `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"`.
253
+ - `Heatmap`: `data: number[][]`, `xLabels`, `yLabels`, `c`, `labels?`, `title?`, `cellSize?: number = 52`, `cellWidth?`, `cellHeight?`, `rowLabelWidth?`, `colorScale?: "heat" | "strength"`.
254
+ - `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?`.
255
+
256
+ Charts and plots:
257
+
258
+ - `ChartFrame`: `children`, `c`, `title?`, `subtitle?`, `legend?: ChartLegendItem[]`, `footer?`, `width?: number | string = "100%"`, `height?`, `padding?: number = 16`. `ChartLegendItem`: `label`, `color: ColorName | string`.
259
+ - `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?`.
260
+ - `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?`.
261
+ - `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?`.
262
+ - `QuadrantChart`: `points: ScatterPoint[]`, `regions`, `c`, `title?`, `subtitle?`, `width?: number = 700`, `height?: number = 360`, `xAxisLabel?`, `yAxisLabel?`, `footer?`. `regions`: `{ topLeft, topRight, bottomLeft, bottomRight }`, each `QuadrantRegion`: `label`, `detail?`, `color?`.
263
+ - `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?`.
264
+ - `StackedBar`: `segments: StackedBarSegment[]`, `c`, `width?: number = 480`, `height?: number = 68`, `title?`, `subtitle?`, `showLegend?: boolean = true`. `StackedBarSegment`: `label`, `value`, `color?`, `valueLabel?`.
265
+ - `MiniBarChart`: `data: MiniBarDatum[]`, `c`, `max?`, `minBarHeight?: number = 8`, `height?: number = 92`, `barWidth?: number = 22`, `gap?: number = 10`, `radius?: number = 7`, `fontSize?: number = 9`, `showValues?: boolean = false`. `MiniBarDatum`: `label`, `value`, `tone?`, `color?`, `valueLabel?`, `opacity?`.
266
+ - `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?`.
267
+ - `AxisPlotPoint`: `x`, `y`, `fill?`, `tone?`, `r?`, `stroke?`, `strokeWidth?`, `opacity?`.
268
+ - `AxisPlotVector`: `x1`, `y1`, `x2`, `y2`, `color?`, `tone?`, `strokeWidth?`, `opacity?`, `arrow?`, `arrowSize?`, `showStartDot?`, `showEndDot?`, `dotRadius?`.
269
+ - `AxisPlotPath`: `points: Array<{ x, y }>`, `color?`, `tone?`, `strokeWidth?`, `opacity?`, `interpolation?: "linear" | "step-after"`, `dashed?`.
270
+ - `ChartValueFormat`: `"decimal" | "percent" | "integer" | "compact" | ((value: number) => string)`.
271
+
272
+ SVG and geometry helpers:
273
+
274
+ - `SvgFrame`: `key?`, `x?: number = 0`, `y?: number = 0`, `width`, `height`, `c`, `rx?: number = 8`, `fill?`, `stroke?`, `strokeWidth?: number = 1`, `opacity?`.
275
+ - `SvgPoint`: `key?`, `cx`, `cy`, `r?: number = 5`, `fill`, `stroke?`, `strokeWidth?`, `opacity?`.
276
+ - `SvgMathText`: `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`.
277
+ - `SvgFrame` pairs well with `VectorArrow`, `VectorSegment`, `SvgPoint`, `DotPoint`, `DashedLine`, and `Legend` inside custom SVG.
278
+ - `Arrow`: `direction?: "down" | "right" | "up" | "left" = "down"`, `label?`, `length?: number = 40`, `c`, `color?`.
279
+ - `VectorArrow`: `key?`, `x1`, `y1`, `x2`, `y2`, `color`, `strokeWidth?: number = 2`, `arrowSize?: number = 2.2`, `opacity?: number = 1`.
280
+ - `VectorSegment`: `key?`, `x1`, `y1`, `x2`, `y2`, `color`, `strokeWidth?: number = 4`, `opacity?: number = 1`, `showStartDot?: boolean = false`, `showEndDot?: boolean = true`, `dotRadius?: number = 4.5`.
281
+ - `Box`: `label`, `c`, `color?: ColorName = "primary"`, `width?`, `height?`, `fontSize?: number = 14`, `gradient?: boolean = false`, `sublabel?`, `icon?`, `radius?: number = 8`, `outlined?: boolean = false`.
282
+ - `ArrowMarkerDef`: `id`, `color`, `size?: number = 5`.
283
+ - `DotPoint`: `x`, `y`, `label`, `color`, `c`, `size?: number = 12`, `labelOffset?: { x?: number; y?: number }`.
284
+ - `DashedLine`: `x1`, `y1`, `x2`, `y2`, `color`, `dotSpacing?: number = 8`, `dotSize?: number = 2`.
285
+ - `Legend`: `items: LegendItem[]`, `c`, `title?`. `LegendItem`: `label`, `color`, `style?: "solid" | "dashed"`.
286
+
287
+ Theme and render APIs:
288
+
289
+ - `getThemeColors(mode)`: `mode: ThemeMode`.
290
+ - `getToneColor(tone, c)`, `getToneGradient(tone)`, `getColor(name, c?)`, `getGradient(name)`, `heatColor(value)`.
291
+ - `renderToPng(element, options, createFn?, theme?)`: `element`, `options: RenderOptions`, `createFn?: (theme: "dark" | "light") => ReactNode`, `theme?: "dark" | "light"`.
292
+ - `WatermarkInput`: `boolean | string | WatermarkOptions`. `true` uses Vizmatic defaults. A string sets the watermark text.
293
+ - `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.
294
+ - `WatermarkOptions`: `text?: string | false`, `image?: string | WatermarkImageOptions`, `icon?: ReactNode | string | false`, `position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" = "top-right"`, `opacity?: number`, `color?: string`.
295
+ - `RenderOptions`: `width`, `height`, `outputPath`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `crop?: boolean = true`, `scale?: number = 2`.
296
+ - `renderToBuffer(element, width, height, options?)`: `options` supports `watermark?`, `brand?`, `scale?`.
297
+ - `renderToSvg(element, width, height, options?)`: `options` supports `watermark?`, `brand?`.
298
+ - `renderAnimatedGif(scenes, options)`: `scenes: AnimatedScene[]`, `options: AnimationOptions`.
299
+ - `AnimatedScene`: `element`, `duration` in ms, `transition?: "none" | "fade" | "appear"`, `transitionDuration?`, `label?`.
300
+ - `AnimationOptions`: `width`, `height`, `outputPath`, `loop?: number = 0`, `scale?: number = 1`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `theme?: "dark" | "light" = "dark"`.
301
+
302
+ ## Prop-aware examples
303
+
304
+ ### Window + code + status
305
+
306
+ ```tsx
307
+ import React from "react"
308
+ import { CodeBlock, StatusList, WindowFrame, defineIllustration, Row, Scene } from "vizmatic"
309
+
310
+ export const width = 1040
311
+ export const height = 560
312
+
313
+ const frame = defineIllustration((c) => (
314
+ <Scene c={c} title="Release gate" subtitle="tool output and checklist">
315
+ <Row gap={18} align="stretch">
316
+ <WindowFrame c={c} title="ci.log" variant="terminal" tone="green" width={520}>
317
+ <CodeBlock
318
+ c={c}
319
+ fontSize={12}
320
+ showLineNumbers
321
+ lines={[
322
+ { text: "pnpm typecheck", tone: "green", prefix: "$" },
323
+ { text: "pnpm test", tone: "green", prefix: "$" },
324
+ { text: "pnpm render:examples", tone: "cyan", prefix: "$" },
325
+ ]}
326
+ />
327
+ </WindowFrame>
328
+ <StatusList
329
+ c={c}
330
+ width={360}
331
+ rows={[
332
+ { label: "Types", detail: "clean", status: "check", tone: "green" },
333
+ { label: "Visuals", detail: "dark/light generated", status: "check", tone: "cyan" },
334
+ { label: "NPM", detail: "auth required", status: "warn", tone: "warm" },
335
+ ]}
336
+ />
337
+ </Row>
338
+ </Scene>
339
+ ))
340
+
341
+ export const create = frame.create
342
+ export default frame.default
343
+ ```
344
+
345
+ ### Matrix + chart
346
+
347
+ ```tsx
348
+ import React from "react"
349
+ import { Heatmap, Matrix, Row, Scene, StackedBar, defineIllustration } from "vizmatic"
350
+
351
+ export const width = 1040
352
+ export const height = 560
353
+
354
+ const frame = defineIllustration((c) => (
355
+ <Scene c={c} title="Attention audit" subtitle="weights, scores, and distribution">
356
+ <Row gap={18} align="stretch">
357
+ <Heatmap
358
+ c={c}
359
+ title="Attention"
360
+ xLabels={["q1", "q2", "q3"]}
361
+ yLabels={["k1", "k2", "k3"]}
362
+ data={[
363
+ [0.9, 0.2, 0.1],
364
+ [0.4, 0.8, 0.2],
365
+ [0.1, 0.3, 0.7],
366
+ ]}
367
+ />
368
+ <Matrix
369
+ c={c}
370
+ title="Scores"
371
+ format="decimal"
372
+ rowLabels={["A", "B", "C"]}
373
+ colLabels={["x", "y", "z"]}
374
+ data={[
375
+ [0.4, 0.7, 0.2],
376
+ [0.5, 0.2, 0.8],
377
+ ]}
378
+ />
379
+ <StackedBar
380
+ c={c}
381
+ width={300}
382
+ title="Token budget"
383
+ segments={[
384
+ { label: "prompt", value: 42, color: "primary" },
385
+ { label: "context", value: 38, color: "info" },
386
+ { label: "answer", value: 20, color: "positive" },
387
+ ]}
388
+ />
389
+ </Row>
390
+ </Scene>
391
+ ))
392
+
393
+ export const create = frame.create
394
+ export default frame.default
395
+ ```
396
+
397
+ ## Quality rules
398
+
399
+ - Use semantic tones, not hard-coded colors: `blue`, `purple`, `green`, `warm`, `cyan`, `pink`, `critical`, `ocean`, `neutral`.
400
+ - Keep canvas sizes explicit. Good defaults: `1040x560` for article figures, `1280x720` for slide frames, `900x520` for compact diagrams.
401
+ - Use `width`, `minWidth`, `height`, `minHeight`, `gap`, and `padding` props to stabilize layout.
402
+ - Keep text short. Use `TextLabel`, `Panel`, `StepCard`, `MetricCard`, `DataTable`, and `Grid` for wrapping-safe labels.
403
+ - Render both dark and light when shipping reusable assets: `--theme dark,light`.
404
+ - Use GIF only when motion explains state change. Keep scenes short, export `createScenes(theme)`, and keep a static `create(theme)` fallback.
405
+ - If render fails with `Canvas overflow detected`, increase canvas dimensions or reduce content density. Do not ignore the error.
406
+ - Verify generated PNGs/GIFs exist and are non-empty. Open at least one rendered image before finalizing.
407
+
408
+ ## Common recipes
409
+
410
+ ### RAG graph
411
+
412
+ ```tsx
413
+ import React from "react"
414
+ import { defineIllustration, GraphDiagram, Scene } from "vizmatic"
415
+
416
+ export const width = 1040
417
+ export const height = 560
418
+
419
+ const frame = defineIllustration((c) => (
420
+ <Scene c={c} title="RAG control graph" subtitle="retrieval is a graph, not a prompt append" align="center">
421
+ <GraphDiagram
422
+ c={c}
423
+ width={820}
424
+ height={390}
425
+ nodes={[
426
+ { id: "query", label: "Query", detail: "intent", x: 0.08, y: 0.52, tone: "blue" },
427
+ { id: "retrieve", label: "Retrieve", detail: "top-k docs", x: 0.40, y: 0.25, tone: "cyan" },
428
+ { id: "rerank", label: "Rerank", detail: "quality gate", x: 0.68, y: 0.25, tone: "warm" },
429
+ { id: "answer", label: "Answer", detail: "grounded draft", x: 0.92, y: 0.52, tone: "green" },
430
+ { id: "verify", label: "Verify", detail: "citations", x: 0.52, y: 0.78, tone: "critical" },
431
+ ]}
432
+ edges={[
433
+ { from: "query", to: "retrieve", label: "search", tone: "blue" },
434
+ { from: "retrieve", to: "rerank", label: "rank", tone: "cyan" },
435
+ { from: "rerank", to: "answer", label: "context", tone: "green" },
436
+ { from: "answer", to: "verify", label: "claims", tone: "critical" },
437
+ { from: "verify", to: "retrieve", label: "retry", dashed: true, tone: "warm" },
438
+ ]}
439
+ />
440
+ </Scene>
441
+ ))
442
+
443
+ export const create = frame.create
444
+ export default frame.default
445
+ ```
446
+
447
+ ### Evaluation dashboard
448
+
449
+ ```tsx
450
+ import React from "react"
451
+ import { BarChart, defineIllustration, LineChart, Row, Scene } from "vizmatic"
452
+
453
+ export const width = 1040
454
+ export const height = 620
455
+
456
+ const frame = defineIllustration((c) => (
457
+ <Scene c={c} title="Evaluation snapshot" subtitle="charts inherit theme, labels, and contrast">
458
+ <Row gap={18} align="stretch">
459
+ <BarChart
460
+ c={c}
461
+ width={440}
462
+ height={260}
463
+ title="Pass rate by task"
464
+ format="percent"
465
+ data={[
466
+ { label: "tools", value: 0.82, color: "positive" },
467
+ { label: "math", value: 0.71, color: "secondary" },
468
+ { label: "code", value: 0.77, color: "primary" },
469
+ { label: "long", value: 0.58, color: "warning" },
470
+ ]}
471
+ />
472
+ <LineChart
473
+ c={c}
474
+ width={440}
475
+ height={260}
476
+ title="Quality over releases"
477
+ format="percent"
478
+ labels={["v1", "v2", "v3", "v4", "v5"]}
479
+ series={[
480
+ { name: "quality", points: [0.55, 0.61, 0.69, 0.74, 0.81], color: "positive", area: true },
481
+ { name: "latency", points: [0.72, 0.69, 0.66, 0.62, 0.59], color: "warning" },
482
+ ]}
483
+ />
484
+ </Row>
485
+ </Scene>
486
+ ))
487
+
488
+ export const create = frame.create
489
+ export default frame.default
490
+ ```
491
+
492
+ ## Final answer checklist
493
+
494
+ After creating a Vizmatic visual, report:
495
+
496
+ - files created or changed
497
+ - render command used
498
+ - output image paths, including GIF paths when generated
499
+ - whether dark/light variants rendered
500
+ - any overflow or layout fixes made