vizmatic 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/PROMPT.md +500 -0
- package/README.md +530 -0
- package/dist/chunk-ADU7JROD.js +627 -0
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +303 -0
- package/dist/index.d.ts +1433 -0
- package/dist/index.js +4702 -0
- package/docs/PROMPT.md +500 -0
- package/docs/assets/examples/.gitkeep +1 -0
- package/docs/assets/examples/agent-pipeline_dark.png +0 -0
- package/docs/assets/examples/agent-pipeline_light.png +0 -0
- package/docs/assets/examples/animated-pipeline_dark.gif +0 -0
- package/docs/assets/examples/animated-pipeline_dark.png +0 -0
- package/docs/assets/examples/animated-pipeline_light.gif +0 -0
- package/docs/assets/examples/animated-pipeline_light.png +0 -0
- package/docs/assets/examples/attention-head_dark.png +0 -0
- package/docs/assets/examples/attention-head_light.png +0 -0
- package/docs/assets/examples/embedding-map_dark.png +0 -0
- package/docs/assets/examples/embedding-map_light.png +0 -0
- package/docs/assets/examples/eval-dashboard_dark.png +0 -0
- package/docs/assets/examples/eval-dashboard_light.png +0 -0
- package/docs/assets/examples/gif-manifest.json +12 -0
- package/docs/assets/examples/manifest.json +108 -0
- package/docs/assets/examples/model-router_dark.png +0 -0
- package/docs/assets/examples/model-router_light.png +0 -0
- package/docs/assets/examples/presentation-frame_dark.png +0 -0
- package/docs/assets/examples/presentation-frame_light.png +0 -0
- package/docs/assets/examples/rag-graph_dark.png +0 -0
- package/docs/assets/examples/rag-graph_light.png +0 -0
- package/docs/assets/examples/release-card_dark.png +0 -0
- package/docs/assets/examples/release-card_light.png +0 -0
- package/docs/assets/examples/research-landscape_dark.png +0 -0
- package/docs/assets/examples/research-landscape_light.png +0 -0
- package/docs/assets/examples/sources.json +93 -0
- package/docs/assets/examples/spec-anatomy_dark.png +0 -0
- package/docs/assets/examples/spec-anatomy_light.png +0 -0
- package/docs/assets/examples/theme-system_dark.png +0 -0
- package/docs/assets/examples/theme-system_light.png +0 -0
- package/docs/assets/examples/token-matrix_dark.png +0 -0
- package/docs/assets/examples/token-matrix_light.png +0 -0
- package/docs/assets/icon.svg +16 -0
- package/docs/assets/logo.svg +30 -0
- package/examples/agent-pipeline.tsx +27 -0
- package/examples/animated-pipeline.tsx +72 -0
- package/examples/attention-head.tsx +27 -0
- package/examples/embedding-map.tsx +34 -0
- package/examples/eval-dashboard.tsx +44 -0
- package/examples/model-router.tsx +35 -0
- package/examples/presentation-frame.tsx +32 -0
- package/examples/rag-graph.tsx +36 -0
- package/examples/release-card.tsx +39 -0
- package/examples/research-landscape.tsx +34 -0
- package/examples/spec-anatomy.tsx +44 -0
- package/examples/theme-system.tsx +30 -0
- package/examples/token-matrix.tsx +49 -0
- package/package.json +84 -0
package/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
|