vizmatic 0.1.32 → 0.1.34

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 CHANGED
@@ -1,10 +1,10 @@
1
1
  # Vizmatic agent prompt
2
2
 
3
- Use Vizmatic to create polished, theme-aware diagrams, figures, dashboards, presentation frames, and animated GIFs from structured React scene primitives.
3
+ Use Vizmatic to create diagrams, figures, dashboards, presentation frames, and animated GIFs from React scene primitives. Render dark and light files locally or in CI.
4
4
 
5
5
  ## Quick start
6
6
 
7
- Vizmatic requires Node.js 20 or newer. Install the CLI once:
7
+ Vizmatic requires Node.js 20 or newer. Install the CLI:
8
8
 
9
9
  ```bash
10
10
  npm install -g vizmatic
@@ -31,33 +31,33 @@ Render dark and light assets:
31
31
  vizmatic ./frame.tsx --out ./dist/frames --theme dark,light
32
32
  ```
33
33
 
34
- Validate the scene with structured diagnostics before publishing:
34
+ Check the scene before publishing:
35
35
 
36
36
  ```bash
37
37
  vizmatic check ./frame.tsx --theme dark,light --json
38
38
  ```
39
39
 
40
- Fix errors before rendering final assets. Warnings identify concerns such as low text contrast or asset fallbacks; overflow errors include affected edges and suggested dimensions.
40
+ Fix all errors before the final render. Warnings report low contrast, text below 11px, overlapping labels, uneven panel whitespace, connector congestion, and asset fallbacks. Overflow errors name the affected edges and suggest dimensions.
41
41
 
42
- ## Project installation
42
+ ## Install in a project
43
43
 
44
44
  Use the package manager already present in the project.
45
45
 
46
- Install in the project when the project needs scripts, editor types, or direct renderer APIs:
46
+ Add Vizmatic to a project for scripts, editor types, or direct renderer APIs:
47
47
 
48
48
  ```bash
49
49
  pnpm add vizmatic react
50
50
  ```
51
51
 
52
- Optional edge build from GitHub:
52
+ To use the current GitHub version:
53
53
 
54
54
  ```bash
55
55
  pnpm add github:bvolpato/vizmatic react
56
56
  ```
57
57
 
58
- For npm/yarn/bun projects, use the equivalent package-manager command.
58
+ Use the equivalent command for npm, Yarn, or Bun projects.
59
59
 
60
- ## Larger example
60
+ ## Full frame example
61
61
 
62
62
  Create `frames/agent-pipeline.tsx`:
63
63
 
@@ -67,7 +67,7 @@ height = 560;
67
67
 
68
68
  <Scene
69
69
  title="Agent visual pipeline"
70
- subtitle="prompt -> scene spec -> verified artifact"
70
+ subtitle="prompt -> TSX scene -> render -> files"
71
71
  gap={26}
72
72
  >
73
73
  <Flow
@@ -91,32 +91,32 @@ height = 560;
91
91
  },
92
92
  {
93
93
  eyebrow: "render",
94
- title: "Satori frame",
95
- subtitle: "React primitives",
94
+ title: "Node renderer",
95
+ subtitle: "headless output",
96
96
  tone: "cyan",
97
- lines: ["layout defaults", "safe text", "semantic tones"],
97
+ lines: ["layout", "theme", "checks"],
98
98
  width: 190,
99
99
  },
100
100
  {
101
101
  eyebrow: "output",
102
- title: "PNG / GIF",
103
- subtitle: "CI-ready asset",
102
+ title: "PNG / SVG / GIF",
103
+ subtitle: "rendered files",
104
104
  tone: "green",
105
- lines: ["autocrop", "overflow checks", "retina scale"],
105
+ lines: ["dark + light", "alpha", "manifest"],
106
106
  width: 190,
107
107
  },
108
108
  ]}
109
109
  />
110
110
  <Row width="100%" gap={14}>
111
111
  <CalloutCard
112
- title="Model writes structure"
113
- detail="No hand-written SVG paths or brittle x/y layout for common cases."
112
+ title="Use scene primitives"
113
+ detail="Common diagrams do not need hand-written SVG paths or x/y coordinates."
114
114
  tone="purple"
115
115
  width={470}
116
116
  />
117
117
  <CalloutCard
118
- title="Design system stays in control"
119
- detail="Theme tokens decide color, typography, radius, spacing, and contrast."
118
+ title="Use theme tokens"
119
+ detail="Tokens set color, typography, radius, spacing, and contrast."
120
120
  tone="green"
121
121
  width={470}
122
122
  />
@@ -130,9 +130,9 @@ Render it:
130
130
  vizmatic frames --out public/vizmatic --theme dark,light --watermark "Your Product" --watermark-image ./logo.svg --watermark-position top-right
131
131
  ```
132
132
 
133
- The generated `manifest.json` keeps `outputs` for compatibility and adds `outputDetails` with each file's theme, path, width, and height.
133
+ Generated `manifest.json` includes each output file plus its theme, path, width, and height.
134
134
 
135
- PNG and SVG renders use alpha-transparent canvas backgrounds by default. Use the actual theme background when the host needs a full-frame image:
135
+ PNG and SVG renders have transparent backgrounds by default. Use the theme background when the image needs an opaque canvas:
136
136
 
137
137
  ```bash
138
138
  vizmatic frames --out public/vizmatic --theme dark,light --background theme
@@ -146,11 +146,11 @@ Or set it in the frame:
146
146
  </Scene>
147
147
  ```
148
148
 
149
- If a direct CLI frame omits `width` or `height`, Vizmatic starts at `960x540` and grows to fit content when overflow is detected. Generated wrappers that export the default `960x540` size get the same fit-to-content behavior. Add `autoSize = false` when exact dimensions should stay strict and fail on clipping.
149
+ 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.
150
150
 
151
- For direct CLI frames, skip imports, `defineIllustration`, and `c` props by default. The CLI injects Vizmatic primitives and theme colors. Reference `c` only when you need explicit theme tokens such as `background={c.bg}`. `Scene` title/subtitle are optional; omit both for visual-only figures, badges, inline blog diagrams, or frames where surrounding copy already supplies the title. Use the full module form when you need custom dependencies, direct renderer APIs, advanced reusable JSX helpers, or animation exports.
151
+ 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.
152
152
 
153
- Frame modules can also export a watermark element when code-owned branding is clearer than CLI flags:
153
+ Frame modules can export a watermark element instead of using CLI flags:
154
154
 
155
155
  ```tsx
156
156
  import { Watermark } from "vizmatic"
@@ -179,9 +179,9 @@ Render animated frames with `createScenes(theme)`:
179
179
  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
180
180
  ```
181
181
 
182
- ## Create an animated frame
182
+ ## Animated frames
183
183
 
184
- Animated frames keep the same static `create(theme)` export and add `createScenes(theme)` for GIF output.
184
+ An animated module exports `createScenes(theme)` for GIF output and keeps `create(theme)` for a static frame.
185
185
 
186
186
  ```tsx
187
187
  import React from "react"
@@ -236,9 +236,9 @@ export const create = frame.create
236
236
  export default frame.default
237
237
  ```
238
238
 
239
- ## Pick primitives first
239
+ ## Choose primitives
240
240
 
241
- 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.
241
+ Use Vizmatic primitives for common layouts. Use raw SVG only for geometry the component set cannot express.
242
242
 
243
243
  Shared values:
244
244
 
@@ -247,8 +247,8 @@ Shared values:
247
247
  - `ColorName`: `"primary" | "secondary" | "positive" | "warning" | "critical" | "info" | "accent" | "neutral"`.
248
248
  - `FlexAlign`: `"start" | "center" | "end" | "stretch"`.
249
249
  - `FlexJustify`: `"start" | "center" | "end" | "space-between" | "space-around"`.
250
- - In bare CLI frames, omit `c` props; the CLI injects theme colors into Vizmatic components. The local `c` token object is still available for explicit values like `background={c.bg}`.
251
- - In full modules, most visual components require `c: ThemeColors`; inside `defineIllustration((c) => ...)`, pass that same `c` down.
250
+ - Bare CLI frames omit `c` props. The local `c` object remains available for explicit values such as `background={c.bg}`.
251
+ - Full modules pass the `c: ThemeColors` value from `defineIllustration((c) => ...)` to visual components.
252
252
  - PNG/SVG renders are alpha-transparent by default. Use `--background theme`, `background: "theme"`, or `<Scene background={c.bg}>` for opaque theme fill.
253
253
  - Omitted CLI dimensions auto-grow on overflow. Explicit `width` / `height` remain fixed and fail on clipping.
254
254
 
@@ -277,26 +277,26 @@ Cards, labels, and compact UI:
277
277
  - `Icon`: `name`, `c`, `tone?: ToneName = "blue"`, `color?`, `size?: number = 24`, `strokeWidth?: number = 2`, `label?`, `muted?: boolean = false`. `IconName`: `"agent" | "chart" | "check" | "code" | "database" | "file" | "git" | "globe" | "image" | "layers" | "lock" | "play" | "spark" | "terminal" | "tool" | "warning"`.
278
278
  - `ToneStrip`: `tone`, `width?: number = 34`, `height?: number = 4`.
279
279
  - `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`.
280
- - `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?`.
280
+ - `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?`.
281
281
  - `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"`.
282
282
  - `ValuePill`: `label`, `value`, `c`, `tone?: ToneName = "blue"`, `detail?`, `width?: number | string = 112`, `math?: boolean = false`.
283
- - `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`.
283
+ - `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`.
284
284
  - `Badge`: `label`, `c`, `color?: ColorName = "primary"`.
285
285
  - `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`.
286
286
  - `EquationCard`: `title`, `formula`, `c`, `tone?: ToneName = "purple"`, `result?`, `detail?`, `width?: number | string = 190`, `height?`, `math?: boolean = false`, `align?: "left" | "center" = "left"`.
287
- - `DetailList`: `items`, `c`, `tone?`, `gap?: number = 7`, `padding?: number | string = "7px 8px"`, `fontSize?: number = 10`, `mono?: boolean = false`, `math?: boolean = false`.
287
+ - `DetailList`: `items`, `c`, `tone?`, `gap?: number = 7`, `padding?: number | string = "7px 8px"`, `fontSize?: number = 11`, `mono?: boolean = false`, `math?: boolean = false`.
288
288
 
289
289
  Lists, tables, status, and comparison:
290
290
 
291
- - `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]`.
291
+ - `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]`.
292
292
  - `ProgressList`: `rows: ProgressRowSpec[]`, `c`, `gap?: number = 8`, `labelWidth?`, `valueWidth?`, `barHeight?`, `fontSize?`. `ProgressRowSpec`: `label`, `value`, `valueLabel?`, `tone?`, `muted?`.
293
293
  - `StatusRow`: `label`, `detail?`, `status?: "check" | "cross" | "warn" | "info" | "pending" | "dot" = "check"`, `tone?`, `c`, `boxed?: boolean = true`, `fontSize?: number = 11`, `width?`, `math?: boolean = false`.
294
294
  - `StatusList`: `rows: StatusRowSpec[]`, `c`, `gap?: number = 7`, `boxed?: boolean = true`, `fontSize?`, `width?`, `math?: boolean = false`. `StatusRowSpec`: `label`, `detail?`, `status?`, `tone?`.
295
295
  - `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?`.
296
296
  - `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?`.
297
297
  - `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?`.
298
- - `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`.
299
- - `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?`.
298
+ - `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`.
299
+ - `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?`.
300
300
  - `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?`.
301
301
 
302
302
  Tiles:
@@ -314,7 +314,7 @@ Flows and process diagrams:
314
314
  Graphs and networks:
315
315
 
316
316
  - `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?`.
317
- - `GraphDiagram`: `nodes: GraphDiagramNode[]`, `edges: GraphDiagramEdge[]`, `c`, `width?: number = 520`, `height?: number = 420`, `nodeWidth?: number = 150`, `nodeHeight?: number = 66`, `labelFontSize?: number = 14`, `detailFontSize?: number = 9`, `arrowSize?: number = 5`, `padding?: number = 28`. `GraphDiagramNode`: `id`, `label`, `detail?`, `x`, `y`, `tone?`, `muted?`, `width?`, `height?`. `GraphDiagramEdge`: `from`, `to`, `tone?`, `muted?`, `dashed?`, `label?`.
317
+ - `GraphDiagram`: `nodes: GraphDiagramNode[]`, `edges: GraphDiagramEdge[]`, `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"`. `GraphDiagramNode`: `id`, `label`, `detail?`, `x?`, `y?`, `tone?`, `muted?`, `width?`, `height?`. 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. Mixed coordinate modes fail. `GraphDiagramEdge`: `from`, `to`, `tone?`, `muted?`, `dashed?`, `label?`.
318
318
  - `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?`.
319
319
 
320
320
  Matrices and heatmaps:
@@ -333,7 +333,7 @@ Charts and plots:
333
333
  - `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?`.
334
334
  - `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?`.
335
335
  - `StackedBar`: `segments: StackedBarSegment[]`, `c`, `width?: number = 480`, `height?: number = 68`, `title?`, `subtitle?`, `showLegend?: boolean = true`. `StackedBarSegment`: `label`, `value`, `color?`, `valueLabel?`.
336
- - `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?`.
336
+ - `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?`.
337
337
  - `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?`.
338
338
  - `AxisPlotPoint`: `x`, `y`, `fill?`, `tone?`, `r?`, `stroke?`, `strokeWidth?`, `opacity?`.
339
339
  - `AxisPlotVector`: `x1`, `y1`, `x2`, `y2`, `color?`, `tone?`, `strokeWidth?`, `opacity?`, `arrow?`, `arrowSize?`, `showStartDot?`, `showEndDot?`, `dotRadius?`.
@@ -447,20 +447,21 @@ height = 560;
447
447
  </Scene>
448
448
  ```
449
449
 
450
- ## Quality rules
450
+ ## Rendering rules
451
451
 
452
452
  - Use semantic tones instead of hard-coded colors: `blue`, `purple`, `green`, `warm`, `cyan`, `pink`, `critical`, `ocean`, `neutral`.
453
453
  - For Datadog Engineering-style article diagrams, set `preset = "engineering";` and render the light theme. Keep each figure focused on one transition or tradeoff.
454
- - Keep canvas sizes explicit. Good defaults: `1040x560` for article figures, `1280x720` for slide frames, `900x520` for compact diagrams.
455
- - For exploratory direct CLI frames, dimensions may be omitted; Vizmatic starts at `960x540` and grows to fit content if overflow is detected.
454
+ - Use explicit sizes for final assets. Common sizes are `1040x560` for article figures, `1280x720` for slide frames, and `900x520` for compact diagrams.
455
+ - During exploration, dimensions can be omitted. Vizmatic starts at `960x540` and grows to fit content.
456
456
  - 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.
457
- - Use `width`, `minWidth`, `height`, `minHeight`, `gap`, and `padding` props to stabilize layout.
457
+ - Use `width`, `minWidth`, `height`, `minHeight`, `gap`, and `padding` to keep layout stable.
458
458
  - Keep text short. Use `TextLabel`, `Panel`, `StepCard`, `MetricCard`, `DataTable`, and `Grid` for wrapping-safe labels.
459
- - Render both dark and light when shipping reusable assets: `--theme dark,light`.
459
+ - Omit `x` and `y` from `GraphDiagram` nodes for automatic layered layout. Add both only when editorial composition needs manual control.
460
+ - Render reusable assets in both themes with `--theme dark,light`.
460
461
  - Run `vizmatic check <frame> --theme dark,light --json` before final render and fix every error.
461
462
  - Use GIF only when motion explains state change. Keep scenes short, export `createScenes(theme)`, and keep a static `create(theme)` fallback.
462
- - If render fails with `Canvas overflow detected`, the frame has strict dimensions. Increase canvas dimensions, reduce content density, or remove strict sizing for CLI auto-fit. Do not ignore the error.
463
- - Verify generated PNGs/GIFs exist and are non-empty. Open at least one rendered image before finalizing.
463
+ - If render fails with `Canvas overflow detected`, increase the canvas, reduce content, or remove strict sizing. Do not ignore the error.
464
+ - Confirm generated files exist and open at least one image before finishing.
464
465
 
465
466
  ## Common recipes
466
467
 
@@ -470,23 +471,24 @@ height = 560;
470
471
  width = 1040;
471
472
  height = 560;
472
473
 
473
- <Scene title="RAG control graph" subtitle="retrieval is a graph, not a prompt append" align="center">
474
+ <Scene title="RAG control graph" subtitle="retrieval with a citation check" align="center">
474
475
  <GraphDiagram
475
476
  width={820}
476
477
  height={390}
478
+ nodeWidth={132}
479
+ rankGap={44}
477
480
  nodes={[
478
- { id: "query", label: "Query", detail: "intent", x: 0.08, y: 0.52, tone: "blue" },
479
- { id: "retrieve", label: "Retrieve", detail: "top-k docs", x: 0.40, y: 0.25, tone: "cyan" },
480
- { id: "rerank", label: "Rerank", detail: "quality gate", x: 0.68, y: 0.25, tone: "warm" },
481
- { id: "answer", label: "Answer", detail: "grounded draft", x: 0.92, y: 0.52, tone: "green" },
482
- { id: "verify", label: "Verify", detail: "citations", x: 0.52, y: 0.78, tone: "critical" },
481
+ { id: "query", label: "Query", detail: "intent", tone: "blue" },
482
+ { id: "retrieve", label: "Retrieve", detail: "top-k docs", tone: "cyan" },
483
+ { id: "rerank", label: "Rerank", detail: "quality gate", tone: "warm" },
484
+ { id: "answer", label: "Answer", detail: "grounded draft", tone: "green" },
485
+ { id: "verify", label: "Verify", detail: "citations", tone: "critical" },
483
486
  ]}
484
487
  edges={[
485
488
  { from: "query", to: "retrieve", label: "search", tone: "blue" },
486
489
  { from: "retrieve", to: "rerank", label: "rank", tone: "cyan" },
487
490
  { from: "rerank", to: "answer", label: "context", tone: "green" },
488
491
  { from: "answer", to: "verify", label: "claims", tone: "critical" },
489
- { from: "verify", to: "retrieve", label: "retry", dashed: true, tone: "warm" },
490
492
  ]}
491
493
  />
492
494
  </Scene>
@@ -527,9 +529,9 @@ height = 620;
527
529
  </Scene>
528
530
  ```
529
531
 
530
- ## Final answer checklist
532
+ ## Final response
531
533
 
532
- After creating a Vizmatic visual, report:
534
+ After creating a visual, report:
533
535
 
534
536
  - files created or changed
535
537
  - render command used