# Prompt

# Vizmatic agent prompt

Use Vizmatic to create diagrams, figures, dashboards, presentation frames, animated GIFs, and MP4 videos from React scene primitives. Render dark and light files locally or in CI.

## Quick start

Vizmatic requires Node.js 20 or newer. Install the CLI:

```bash
npm install -g vizmatic
```

Create `frame.tsx`:

```tsx
<Scene title="Agent visual pipeline">
  <Flow
    connectorTone="purple"
    stages={[
      { title: "Prompt", tone: "blue" },
      { title: "Scene spec", tone: "purple" },
      { title: "PNG / SVG / GIF", tone: "green" },
    ]}
  />
</Scene>
```

Render dark and light assets:

```bash
vizmatic ./frame.tsx --out ./dist/frames --theme dark,light
```

Check the scene before publishing:

```bash
vizmatic check ./frame.tsx --theme dark,light --json
```

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.

The [browser playground](https://bvolpato.github.io/vizmatic/playground.html) supports component composition, inline text edits, undo/redo, and local drafts. Choose Freeform canvas for positioned `Board` / `CanvasItem` editing with move and resize handles and snapping. Structured editors cover pie segments, bar categories, scatter points, table cells, line series, interval data, and graph nodes/edges/groups; computed data stays in TSX. Save project writes a named `.vizmatic.json` file containing source, output theme, and canvas background, and Open project restores it. PNG/SVG exports preserve the full canvas.

For scenes already created inside a build or editor, use the typed `checkFrame` API instead of writing a frame file and launching the CLI. Pass a React element as `scene` or use `create(theme)` for theme-specific scenes. Set `failOn` to `"warning"` when warnings should fail CI. Reports include per-theme dimensions and diagnostics with stable codes plus element IDs or rendered locations where available. Use `vizmatic check <files> --json` when the CLI should discover and load frame modules.

## Install in a project

Use the package manager already present in the project.

Add Vizmatic to a project for scripts, editor types, or direct renderer APIs:

```bash
pnpm add vizmatic react
```

To use the current GitHub version:

```bash
pnpm add github:bvolpato/vizmatic react
```

Use the equivalent command for npm, Yarn, or Bun projects.

## Full frame example

Create `frames/agent-pipeline.tsx`:

```tsx
width = 1040;
height = 560;

<Scene
  title="Agent visual pipeline"
  subtitle="prompt -> TSX scene -> render -> files"
  gap={26}
>
  <Flow
    connectorTone="purple"
    stages={[
      {
        eyebrow: "input",
        title: "Prompt",
        subtitle: "intent and constraints",
        tone: "blue",
        lines: ["domain language", "audience", "theme tokens"],
        width: 190,
      },
      {
        eyebrow: "contract",
        title: "Scene spec",
        subtitle: "typed structure",
        tone: "purple",
        lines: ["cards", "flows", "charts", "tables"],
        width: 190,
      },
      {
        eyebrow: "render",
        title: "Node renderer",
        subtitle: "headless output",
        tone: "cyan",
        lines: ["layout", "theme", "checks"],
        width: 190,
      },
      {
        eyebrow: "output",
        title: "PNG / SVG / GIF",
        subtitle: "rendered files",
        tone: "green",
        lines: ["dark + light", "alpha", "manifest"],
        width: 190,
      },
    ]}
  />
  <Row width="100%" gap={14}>
    <CalloutCard
      title="Use scene primitives"
      detail="Common diagrams do not need hand-written SVG paths or x/y coordinates."
      tone="purple"
      width={470}
    />
    <CalloutCard
      title="Use theme tokens"
      detail="Tokens set color, typography, radius, spacing, and contrast."
      tone="green"
      width={470}
    />
  </Row>
</Scene>
```

Render it:

```bash
vizmatic frames --out public/vizmatic --theme dark,light --watermark "Your Product" --watermark-image ./logo.svg --watermark-position top-right
```

Generated `manifest.json` includes each output file plus its theme, path, width, and height.

The static CLI defaults to PNG. Add `--format svg` for vector output or `--format both` to render PNG and SVG together in every requested theme.

PNG and SVG renders have transparent backgrounds by default. Use the theme background when the image needs an opaque canvas:

```bash
vizmatic frames --out public/vizmatic --theme dark,light --background theme
```

Or set it in the frame:

```tsx
<Scene background={c.bg} title="Opaque article figure">
  <Flow stages={[{ title: "Theme fill", tone: "purple" }]} />
</Scene>
```

CSS alpha colors are preserved in PNG/SVG backgrounds. Use `<Scene background="rgba(15, 23, 42, 0.5)">` or `--background 'rgba(15, 23, 42, 0.5)'` for a semi-transparent canvas. Leave the background unset for fully transparent output. Contrast checks composite alpha text and nested backgrounds over known solid surfaces; a transparent canvas has no known host-page backdrop.

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.

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.

Frame modules can export a watermark element instead of using CLI flags:

```tsx
import { Watermark } from "vizmatic"

export const watermark = (
  <Watermark position="bottom-right" opacity={0.82}>
    <div style={{
      display: "flex",
      alignItems: "center",
      gap: 6,
      color: "#7c3aed",
      fontFamily: "Inter",
      fontWeight: 800,
      fontSize: 12,
    }}>
      <img src="data:image/svg+xml;base64,..." width={14} height={14} />
      Your Product
    </div>
  </Watermark>
)
```

Render a sampled state timeline with `createAnimation(theme)`:

```bash
vizmatic gif frames/animated-pipeline.tsx --out public/vizmatic --theme dark,light --fps 20 --watermark "Your Product" --watermark-image ./logo.svg --watermark-position top-right --scale 1
```

## Animated frames

An animated module exports `createAnimation(theme)` for GIF or MP4 output and keeps `create(theme)` for a static or reduced-motion fallback. Define state once, then describe holds, eased transitions, instant keyframes, and parallel property tracks. Vizmatic samples absolute timeline time and renders every frame.

For MP4, export `createAnimation(theme)` and run `vizmatic video frames/lesson.tsx --out public/videos --theme dark --fps 30`. This requires Node.js 20 or newer and FFmpeg with the `libx264` encoder; add `--audio narration.wav` for AAC audio. The CLI pads or trims audio to the animation duration. Exported canvas dimensions after `--scale` must be positive even integers. MP4 uses an opaque theme background by default and supports 1–120 fps independently of GIF cadence. The browser builder exports GIF; MP4 runs in Node.js. Keep `.vtt` or `.srt` captions as separate files and synchronize them to the finished timeline. Use `examples/videos/request-lifecycle.tsx` as a short, generic starting point and `examples/videos/signal-to-story.tsx` for a longer film with parallel tracks, path tracing, camera motion, and an ending held on screen. Animate the data or mechanism the lesson explains; avoid decorative logo or icon reveals. For package consumers, install Vizmatic and React in the project and FFmpeg separately. In the repository, `pnpm render:video` regenerates the showcase media.

```tsx
import React from "react"
import { Scene, defineAnimation, getThemeColors, hold, keyframe, tween, type ThemeMode } from "vizmatic"

export const width = 1040
export const height = 560

type State = { operation: number; progress: number }

function buildFrame(theme: ThemeMode, state: State) {
  const c = getThemeColors(theme)
  return (
    <Scene c={c} title={state.operation === 0 ? "Broadcast" : "AllReduce"}>
      <div style={{ display: "flex", width: "100%", height: 260, position: "relative" }}>
        <div style={{
          display: "flex",
          position: "absolute",
          left: 40 + state.progress * 720,
          top: 90,
          padding: "10px 16px",
          borderRadius: 8,
          background: c.accent,
          color: c.textOnColor,
        }}>chunk</div>
      </div>
    </Scene>
  )
}

export function createAnimation(theme: ThemeMode) {
  return defineAnimation<State>({
    initial: { operation: 0, progress: 0 },
    timeline: [
      hold(500, "Broadcast input"),
      tween({ progress: 1 }, { duration: 900, easing: "ease-in-out", label: "Broadcast" }),
      hold(500, "Broadcast output"),
      keyframe({ operation: 1, progress: 0 }),
      tween({ progress: 1 }, { duration: 900, easing: "ease-in-out", label: "AllReduce" }),
    ],
    fps: 20,
    render: (state) => buildFrame(theme, state),
  })
}

export function create(theme: ThemeMode = "dark") {
  return buildFrame(theme, { operation: 1, progress: 1 })
}

export default create("dark")
```

Top-level timeline steps run sequentially. Properties inside one `tween` move together. Use `parallel({ x: [...], opacity: [...] })` when property tracks need different delays or durations. Default interpolation supports finite numbers; use a custom `interpolate(from, to, progress)` for colors, points, or other values. Infinite loops should finish on the same visual state where they start. Fade moving content out and reset it with a zero-duration `keyframe` while hidden instead of reversing a one-way operation. `createScenes(theme)` remains supported for deliberate scene cuts and pixel `fade`/`appear` transitions.

## Choose primitives

Use Vizmatic primitives for common layouts. Use raw SVG only for geometry the component set cannot express.

Shared values:

- `ThemeMode`: `"dark" | "light"`.
- `ToneName`: `"blue" | "purple" | "green" | "warm" | "cyan" | "pink" | "red" | "critical" | "neutral" | "sunset" | "ocean" | "dark"`.
- `ColorName`: `"primary" | "secondary" | "positive" | "warning" | "critical" | "info" | "accent" | "neutral"`.
- `FlexAlign`: `"start" | "center" | "end" | "stretch"`.
- `FlexJustify`: `"start" | "center" | "end" | "space-between" | "space-around"`.
- Bare CLI frames omit `c` props. The local `c` object remains available for explicit values such as `background={c.bg}`.
- Full modules pass the `c: ThemeColors` value from `defineIllustration((c) => ...)` to visual components.
- PNG/SVG renders are alpha-transparent by default. Use `--background theme`, `background: "theme"`, or `<Scene background={c.bg}>` for opaque theme fill.
- Omitted CLI dimensions auto-grow on overflow. Explicit `width` / `height` remain fixed and fail on clipping.

## Component API

Frame helpers:

- `defineIllustration(build, defaultTheme?)`: `build: (c: ThemeColors) => ReactElement`, `defaultTheme?: ThemeMode = "dark"`. Returns `{ create(theme), default }`.
- `Canvas`: `children?`, `c`, `padding?: number = 40`, `justify?: "center" | "flex-start" | "space-between" | "space-around" = "center"`, `background?: string`. Default root background is alpha-transparent during PNG/SVG rendering.
- `Board`: `children?`, `c`, `width?: number = 960`, `height?: number = 540`, `background?: string`. Fixed relative canvas with a transparent default background; clips content outside its bounds. Match frame dimensions to the board. Dimensions must be finite, greater than zero, and at most 8192.
- `CanvasItem`: `children?`, `x: number`, `y: number`, `width?: number`, `height?: number`. Absolute position in logical board pixels. Coordinates must be finite. Explicit dimensions must be greater than zero and at most 8192; they supply the child's width/height props. With both dimensions set, chart primitives scale proportionally to fit their complete plotting layer, headings, legends, and footer inside the item. Use literal coordinates and dimensions for preview move/resize controls.
- `Scene`: `c`, `children`, `title?`, `subtitle?`, `padding?: number = 40`, `gap?: number = 24`, `justify?: "center" | "flex-start" | "space-between" | "space-around" = "flex-start"`, `align?: FlexAlign = "stretch"`, `contentWidth?: number | string = "100%"`, `background?`, `contentStyle?: React.CSSProperties`. Title/subtitle are optional and the title bar is omitted when no title is provided. Use `background={c.bg}` for an opaque theme frame.
- `TitleBar`: `title`, `subtitle?`, `c`.

Layout primitives:

- `Row` / `Column`: `children`, `gap?: number = 12`, `align?: FlexAlign = "center"`, `justify?: FlexJustify = "center"`, `wrap?: boolean = false`, `width?: number | string`, `height?: number | string`, `style?: React.CSSProperties`.
- `Stack`: `children`, `direction?: "vertical" | "horizontal" = "vertical"`, `gap?: number = 12`, `align?: "start" | "center" | "end" | "stretch" = "center"`, `wrap?: boolean = false`.
- `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`.
- `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`.
- `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`.

Cards, labels, and compact UI:

- `TextLabel`: `text`, `c`, `variant?: keyof typography = "body"`, `color?`, `fontSize?`, `fontWeight?`, `width?`, `align?: "left" | "center" | "right" = "left"`, `math?: boolean = false`, `mono?: boolean = false`.
- `MathText`: `text`. Returns formatted unicode-ish math text for simple `_` and `^` notation.
- `formatMathText(text)`: `text: string`.
- `Icon`: `name`, `c`, `tone?: ToneName = "blue"`, `color?`, `size?: number = 24`, `strokeWidth?: number = 2`, `label?`, `muted?: boolean = false`. `IconName` includes presentation icons plus architecture icons: `browser`, `bucket`, `cache`, `cloud`, `cluster`, `container`, `database`, `firewall`, `gateway`, `load-balancer`, `mobile`, `monitor`, `network`, `queue`, `server`, `storage`, `stream`, and `user`.
- `ToneStrip`: `tone`, `width?: number = 34`, `height?: number = 4`.
- `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`.
- `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?`.
- `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"`.
- `ValuePill`: `label`, `value`, `c`, `tone?: ToneName = "blue"`, `detail?`, `width?: number | string = 112`, `math?: boolean = false`.
- `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`.
- `Badge`: `label`, `c`, `color?: ColorName = "primary"`.
- `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`.
- `EquationCard`: `title`, `formula`, `c`, `tone?: ToneName = "purple"`, `result?`, `detail?`, `width?: number | string = 190`, `height?`, `math?: boolean = false`, `align?: "left" | "center" = "left"`.
- `DetailList`: `items`, `c`, `tone?`, `gap?: number = 7`, `padding?: number | string = "7px 8px"`, `fontSize?: number = 11`, `mono?: boolean = false`, `math?: boolean = false`.

Lists, tables, status, and comparison:

- `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]`.
- `ProgressList`: `rows: ProgressRowSpec[]`, `c`, `gap?: number = 8`, `labelWidth?`, `valueWidth?`, `barHeight?`, `fontSize?`. `ProgressRowSpec`: `label`, `value`, `valueLabel?`, `tone?`, `muted?`.
- `StatusRow`: `label`, `detail?`, `status?: "check" | "cross" | "warn" | "info" | "pending" | "dot" = "check"`, `tone?`, `c`, `boxed?: boolean = true`, `fontSize?: number = 11`, `width?`, `math?: boolean = false`.
- `StatusList`: `rows: StatusRowSpec[]`, `c`, `gap?: number = 7`, `boxed?: boolean = true`, `fontSize?`, `width?`, `math?: boolean = false`. `StatusRowSpec`: `label`, `detail?`, `status?`, `tone?`.
- `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?`.
- `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?`.
- `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?`.
- `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`.
- `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?`.
- `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?`.

Tiles:

- `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`.
- `TileGrid`: `tiles: TileSpec[]`, `c`, `columns?`, `gap?: number = 12`, `tileWidth?`, `minHeight?`, `align?: "left" | "center" = "center"`, `math?: boolean = false`.

Flows and process diagrams:

- `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?`.
- `FlowArrow`: `direction?: "down" | "right" | "up" | "left" = "right"`, `label?`, `length?: number = 40`, `c`, `tone?: ToneName = "blue"`, `color?`.
- `Connector`: same props as `FlowArrow`.
- `Pipeline`: `stages: PipelineStage[]`, `c`, `title?`. `PipelineStage`: `label`, `sublabel?`, `icon?`, `color?: ColorName`.

Graphs and networks:

- `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?`.
- `GraphDiagram` routing options: `routing?: "dagre" | "straight" | "orthogonal" = "dagre"`, `routingClearance?: number = 12`. Dagre preserves existing routes; straight connects facing node sides; orthogonal avoids node boxes and group headers with right-angle paths. Node layout remains automatic or manual independently of routing. `GraphDiagramNode` additionally accepts `ports?: GraphDiagramPort[]`; a port is `{ id: string, side: "top" | "right" | "bottom" | "left", offset?: number = 0.5 }`. Offset is finite and in `[0, 1]`, running left to right or top to bottom. `GraphDiagramEdge` additionally accepts `fromPort?`, `toPort?`, `fromSide?`, and `toSide?`. An endpoint cannot combine a port reference with a side. Explicit anchors opt an edge into orthogonal geometry even in Dagre mode. Missing references, duplicate port IDs, and invalid offsets fail validation.

- Orthogonal routing separates parallel relationships, supports self-loops with distinct endpoint anchors, and uses `edgeGap` for lane spacing. It runs offline with limits of 64 node/header obstacles, 256 edges, 18,000 grid points per search, 54,000 search states per search, and 160,000 search states per diagram. A blocked path, unavailable separate lane, same-anchor self-loop, or exhausted limit omits that connector and emits a checker error with code `layout.connector_unroutable`. Increase canvas size or spacing, choose different sides/ports, or reduce clearance; do not publish missing connectors. See `examples/orthogonal-routing.tsx`.

- `GraphDiagram`: `nodes: GraphDiagramNode[]`, `edges: GraphDiagramEdge[]`, `groups?: GraphDiagramGroup[]`, `c`, `width?: number = 520`, `height?: number = 420`, `nodeWidth?: number = 150`, `nodeHeight?: number = 66`, `labelFontSize?: number = 14`, `detailFontSize?: number = 11`, `arrowSize?: number = 5`, `padding?: number = 28`, `layout?: "auto" | "manual"`, `direction?: "LR" | "RL" | "TB" | "BT" = "LR"`, `nodeGap?: number = 34`, `rankGap?: number = 64`, `edgeGap?: number = 14`, `sizing?: "content" | "fixed" = "content"`, `iconSize?: number = 20`, `id?`, `ariaLabel?`, `title?`, `description?`. `GraphDiagramNode`: `id`, `label`, `detail?`, `href?`, `title?`, `x?`, `y?`, `tone?`, `muted?`, `width?`, `height?`, `group?`, `icon?: IconName | DiagramIconDefinition | ReactElement`, `iconSize?`. Icon size is clamped inside its node; custom React elements own their theme colors and accessible label. `GraphDiagramGroup`: `id`, `label`, `detail?`, `parent?`, `tone?`, `muted?`. Groups nest through `parent` and require automatic layout. Omit coordinates on every node for automatic layout; array order is the stable tie-breaker and dimensions expand to fit unless `sizing="fixed"`. Set both coordinates on every node for manual normalized positioning when no groups are present. Mixed coordinate modes fail. `GraphDiagramEdge`: `id?`, `from`, `to`, `tone?`, `muted?`, `dashed?`, `label?`, `href?`, `title?`, `kind?: "sync" | "async" | "event" | "data" | "dependency" | "association"`, `style?: "solid" | "dashed" | "dotted"`, `arrow?: "forward" | "backward" | "both" | "none"`. Association edges default to no arrow. `title`, `description`, and `id` add structured SVG metadata and deterministic graph, node, and edge IDs. Nodes and edges can link to HTTP(S), `mailto:`, `tel:`, fragment, or relative URLs; unsupported schemes fail. Use these properties for `renderToSvg` and playground SVG downloads.
- `SequenceDiagram`: `participants`, ordered `items`, `c`, and optional `width`, `height`, spacing, title, subtitle, and `ariaLabel`. Participants have `id`, `label`, optional `detail`, `tone`, `kind`, and `icon`. Items are messages (`from`, `to`, `label`, `kind?: "sync" | "async" | "return"`), notes, activations, or recursive fragments with `kind: "alt" | "loop" | "parallel"` and labeled branches.
- `DataflowDiagram`: `nodes`, `edges`, optional nested `boundaries`, `c`, GraphDiagram sizing/layout props including `id`, `title`, and `description`, and `ariaLabel`. Nodes require `id`, `label`, and `kind: "source" | "transform" | "store" | "sink"`; optional schema metadata renders in node detail, with optional `href` and `title` for SVG links and tooltips. Edges use `mode?: "batch" | "stream"`, optional schema/label metadata, and optional `id`, `href`, and `title`.
- `DeploymentDiagram`: `nodes`, `connections`, optional nested `boundaries`, `c`, GraphDiagram sizing/layout props including `id`, `title`, and `description`, and `ariaLabel`. Boundaries distinguish region, zone, VPC, subnet, namespace, host, cluster, and trust scopes. Nodes declare infrastructure kind, boundary, and ports, with optional `href` and `title`. Connections declare ingress, egress, internal, or cross-boundary direction plus protocol and port references; `id`, `href`, and `title` add stable SVG identity and links.
- `DeploymentPort`: `id`, `port?`, `protocol?`, `label?`, `direction?: "ingress" | "egress" | "bidirectional"`, `side?: GraphPortSide`, `offset?: number`. With explicit `routing="straight"` or `routing="orthogonal"`, connection `fromPort` / `toPort` references require declared node ports and anchor geometrically. Side defaults follow graph direction and ingress/egress use; explicit side/offset overrides them. Default Dagre deployment rendering keeps the existing label-only behavior.
- `TransformerTopology`: `blocks`, optional `routes`, `c`, `expandRepeats?`, GraphDiagram sizing/layout props including `id`, `title`, and `description`, and `ariaLabel`. Blocks use embedding, attention, norm, MLP, residual, router, output, or custom kinds with tensor shapes and repeat counts, plus optional `href` and `title`. Routes use activation, residual, KV-cache, expert, or collective semantics, plus optional `id`, `href`, and `title`. `formatTensorShape(shape)` formats reusable shape metadata.
- `defineDiagramIcon(id, render)`: defines a reusable custom graph icon. `render` receives `c`, `color`, `size`, and optional `label`.
- `defineIconRegistry(icons)`: preserves typed names for a set of custom or provider icons without global mutable state.
- `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?`.

Matrices and heatmaps:

- `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"`.
- `Heatmap`: `data: number[][]`, `xLabels`, `yLabels`, `c`, `labels?`, `title?`, `cellSize?: number = 52`, `cellWidth?`, `cellHeight?`, `rowLabelWidth?`, `colorScale?: "heat" | "strength"`.
- `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?`.

Charts and plots:

- `ChartFrame`: `children`, `c`, `title?`, `subtitle?`, `legend?: ChartLegendItem[]`, `footer?`, `width?: number | string = "100%"`, `height?`, `padding?: number = 16`. `ChartLegendItem`: `label`, `color: ColorName | string`.
- `PieChart`: `segments: DonutChartSegment[]`, `c`, `title?`, `subtitle?`, `width?: number = 360`, `height?: number = 240`, `size?`, `format?: ChartValueFormat = "decimal"`, `showLegend?: boolean = true`, `footer?`. Each segment has `label`, `value`, optional `color`, and optional `valueLabel`. Values must be finite and non-negative; zero slices are omitted. The full-circle pie shows part-to-whole proportions, with values and shares in the legend. Use `examples/pie-chart.tsx` for a complete frame.
- `DonutChart`: `segments: DonutChartSegment[]`, `c`, `title?`, `subtitle?`, `width?: number = 360`, `height?: number = 230`, `size?`, `thickness?`, `format?: ChartValueFormat = "decimal"`, `centerLabel?`, `centerValue?`, `showLegend?: boolean = true`, `footer?`. `DonutChartSegment`: `label`, `value`, `color?`, `valueLabel?`.
- `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?`.
- `ParetoBarChart`: `data: BarChartDatum[]`, `c`, `title?`, `subtitle?`, `width?: number = 520`, `height?: number = 300`, `format?: ChartValueFormat = "integer"`, `showGrid?: boolean = true`, `showValues?: boolean = true`, `footer?`. A classic categorical Pareto chart with descending bars and a cumulative percentage line, separate value/share axes, and stable tie order. Values must be finite and non-negative. Sorting preserves the input array. A positive total ends at 100%; an all-zero total stays at 0%. Use this for the causes behind a total, and `ParetoChart` for a non-dominated scatter frontier. See `examples/pareto-bar-chart.tsx`.
- `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?`.
- `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?`.
- `ParetoChart`: `points: ScatterPoint[]`, `c`, `title?`, `subtitle?`, `width?: number = 640`, `height?: number = 360`, `xMin?`, `xMax?`, `yMin?`, `yMax?`, `xAxisLabel?`, `yAxisLabel?`, `formatX?: ChartValueFormat = "decimal"`, `formatY?: ChartValueFormat = "decimal"`, `showGrid?: boolean = true`, `xScale?: "linear" | "log" = "linear"`, `xObjective?: "minimize" | "maximize" = "minimize"`, `yObjective?: "minimize" | "maximize" = "maximize"`, `frontierColor?`, `showGoal?: boolean = true`, `goalLabel?`, `footer?`. It detects non-dominated points automatically; logarithmic x scales omit non-positive points.
- `QuadrantChart`: `points: ScatterPoint[]`, `regions`, `c`, `title?`, `subtitle?`, `width?: number = 700`, `height?: number = 360`, `xMin?`, `xMax?`, `yMin?`, `yMax?`, `xThreshold?`, `yThreshold?`, `xAxisLabel?`, `yAxisLabel?`, `formatX?: ChartValueFormat = "decimal"`, `formatY?: ChartValueFormat = "decimal"`, `showTicks?: boolean = false`, `showGrid?: boolean = false`, `footer?`. Without explicit domains, points use normalized 0-1 coordinates and thresholds default to centered splits. `regions`: `{ topLeft, topRight, bottomLeft, bottomRight }`, each `QuadrantRegion`: `label`, `detail?`, `color?`, `emphasis?`.
- `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?`.
- `StackedBar`: `segments: StackedBarSegment[]`, `c`, `width?: number = 480`, `height?: number = 68`, `title?`, `subtitle?`, `showLegend?: boolean = true`. `StackedBarSegment`: `label`, `value`, `color?`, `valueLabel?`.
- `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?`.
- `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?`.
- `AxisPlotPoint`: `x`, `y`, `fill?`, `tone?`, `r?`, `stroke?`, `strokeWidth?`, `opacity?`.
- `AxisPlotVector`: `x1`, `y1`, `x2`, `y2`, `color?`, `tone?`, `strokeWidth?`, `opacity?`, `arrow?`, `arrowSize?`, `showStartDot?`, `showEndDot?`, `dotRadius?`.
- `AxisPlotPath`: `points: Array<{ x, y }>`, `color?`, `tone?`, `strokeWidth?`, `opacity?`, `interpolation?: "linear" | "step-after"`, `dashed?`.
- `ChartValueFormat`: `"decimal" | "percent" | "integer" | "compact" | ((value: number) => string)`.

SVG and geometry helpers:

- `SvgFrame`: `key?`, `x?: number = 0`, `y?: number = 0`, `width`, `height`, `c`, `rx?: number = 8`, `fill?`, `stroke?`, `strokeWidth?: number = 1`, `opacity?`.
- `SvgPoint`: `key?`, `cx`, `cy`, `r?: number = 5`, `fill`, `stroke?`, `strokeWidth?`, `opacity?`.
- `SvgMathText`: positioned HTML overlay with `text`, `x`, `y`, `fill`, `fontSize?: number = 13`, `fontFamily?: string = "JetBrains Mono"`, `fontWeight?: number = 800`, `textAnchor?: "start" | "middle" | "end" = "middle"`, `dominantBaseline?: string = "middle"`, `opacity?: number = 1`. Place it beside, not inside, raw SVG geometry in a `position: "relative"` container.
- `SvgFrame` pairs well with `VectorArrow`, `VectorSegment`, `SvgPoint`, `DotPoint`, `DashedLine`, and `Legend` inside custom SVG.
- `Arrow`: `direction?: "down" | "right" | "up" | "left" = "down"`, `label?`, `length?: number = 40`, `c`, `color?`.
- `VectorArrow`: `key?`, `x1`, `y1`, `x2`, `y2`, `color`, `strokeWidth?: number = 2`, `arrowSize?: number = 2.2`, `opacity?: number = 1`.
- `VectorSegment`: `key?`, `x1`, `y1`, `x2`, `y2`, `color`, `strokeWidth?: number = 4`, `opacity?: number = 1`, `showStartDot?: boolean = false`, `showEndDot?: boolean = true`, `dotRadius?: number = 4.5`.
- `Box`: `label`, `c`, `color?: ColorName = "primary"`, `width?`, `height?`, `fontSize?: number = 14`, `gradient?: boolean = false`, `sublabel?`, `icon?`, `radius?: number = 8`, `outlined?: boolean = false`.
- `ArrowMarkerDef`: `id`, `color`, `size?: number = 5`.
- `DotPoint`: `x`, `y`, `label`, `color`, `c`, `size?: number = 12`, `labelOffset?: { x?: number; y?: number }`.
- `DashedLine`: `x1`, `y1`, `x2`, `y2`, `color`, `dotSpacing?: number = 8`, `dotSize?: number = 2`.
- `Legend`: `items: LegendItem[]`, `c`, `title?`. `LegendItem`: `label`, `color`, `style?: "solid" | "dashed"`.

Theme and render APIs:

- `checkFrame(frame, options?)`: Check `{ scene: ReactNode }` or `{ create(theme): ReactNode }` inputs. Frame metadata accepts `source?`, `width?`, `height?`, and `autoSize?`. Options accept `themes?: ThemeMode[]`, `background?: "transparent" | "theme" | CSS color`, and `failOn?: "error" | "warning" | "info" | "never"`; defaults are both themes, transparent background, and errors only. `ok` means diagnostics pass `failOn`; `rendered` means every requested theme completed rendering. Reports include per-theme `dimensions` and `diagnostics`, plus `summary` severity counts.
- `CHECK_DIAGNOSTIC_CODES`, `CheckDiagnostic`, `CheckDiagnosticCode`, `CheckDiagnosticLocation`, `CheckAutoSize`, `CheckAutoSizeAxes`, `CheckFrameInput`, `CheckFrameReport`, `CheckOptions`: Stable code list and TypeScript contracts for programmatic checks. Locations contain a React `path` or rendered `x`, `y`, `width`, and `height`; available element identifiers appear as `elementId` and `relatedElementIds` on diagnostics.
- `getThemeColors(mode, preset?)`: `mode: ThemeMode`; `preset?: "default" | "engineering"`. Use `engineering` for flat technical-blog figures with a light gray palette, left-aligned black titles, pastel nodes, thin neutral connectors, compact corners, no shadows, Inter labels, and JetBrains Mono annotations. In a bare frame, set `preset = "engineering";` before the JSX. Add `background={c.bg}` to `Scene` for an opaque light gray canvas; omit it for alpha transparency.
- `getToneColor(tone, c)`, `getToneFill(tone, c)`, `getToneGradient(tone)`, `getColor(name, c?)`, `getGradient(name)`, `heatColor(value)`.
- `getReadableColor(name, c)`: returns the semantic color variant with greatest contrast against `c.bgCard`.
- `getReadableToneColor(tone, c, background?)`: maps a tone to a readable semantic color and falls back to readable foreground text when contrast is below 4.5:1. `background` defaults to `c.bgCard`.
- `getReadableTextColor(background, c)`: parses solid or alpha CSS colors and chooses a theme foreground meeting 4.5:1 contrast when possible.
- `createPlotArea(width, height, margin)`: returns `PlotArea` geometry with inner width and height clamped to at least one pixel.
- `renderToPng(element, options, createFn?, theme?)`: `element`, `options: RenderOptions`, `createFn?: (theme: "dark" | "light") => ReactNode`, `theme?: "dark" | "light"`.
- `renderToPngWithOutput(...)`: same arguments as `renderToPng`; returns logical `width` / `height`, physical `pixelWidth` / `pixelHeight`, and painted `contentBounds`.
- `CanvasOverflowError`: typed clipping failure from strict static or animated renders. Exposes `width`, `height`, `overflow`, and optional animation frame/scene/time/label metadata.
- `Watermark`: JSX marker component for frame-module exports. Props are `WatermarkOptions` plus `children?: ReactNode`; children become the complete watermark body.
- `WatermarkInput`: `boolean | string | WatermarkOptions | ReactElement<WatermarkElementProps>`. `true` uses Vizmatic defaults. A string sets the watermark text. A React element can be `<Watermark>...</Watermark>` or any custom element.
- `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.
- `WatermarkOptions`: `text?: string | false`, `image?: string | WatermarkImageOptions`, `icon?: ReactNode | string | false`, `element?: ReactNode`, `position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" = "top-right"`, `opacity?: number`, `color?: string`.
- `normalizeWatermark(input)`: converts boolean, string, object, or React-element `WatermarkInput` to `WatermarkOptions | undefined`.
- `wrapWithBrand(element, width, height, theme?, label?)`: compatibility wrapper around `wrapWithWatermark`; theme defaults to `"dark"` and label defaults to `"Vizmatic"`.
- `getFonts()`: lazily loads and caches bundled Satori font data for advanced integrations.
- `loadAdditionalAsset(code, segment)`: Satori missing-glyph callback; resolves emoji segments from the compressed offline Twemoji bundle or public fallback and returns an empty font list for other codes.
- `RenderOptions`: `width`, `height`, `outputPath`, `background?: "transparent" | "theme" | CSS color = "transparent"`, `theme?: "dark" | "light" = "dark"` for direct-render watermark defaults, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `crop?: boolean | "height" | "both" = true`, `scale?: number = 2`. Default autocrop retains 24 source pixels around detected content. Use `crop: "height"` when host layouts require stable width but should still trim extra vertical whitespace.
- `renderToBuffer(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`, `scale?`.
- `renderToSvg(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`.
- `defineAnimation({ initial, timeline, render, fps? })`: creates deterministic typed state animation. `fps` defaults to `20` and accepts integers from `1` to `50`.
- `hold(duration, label?)`: keep current state for milliseconds.
- `tween(to, { duration, easing?, interpolate?, label? })`: transition listed properties together. Easing is `"linear" | "ease-in" | "ease-out" | "ease-in-out"` or pure progress function.
- `keyframe(value, label?)`: apply instant partial state update.
- `parallel(tracks, label?)`: run property tracks concurrently; each track accepts `hold`, `tween`, and `keyframe` steps.
- `sampleAnimation(animation, time)`: evaluate state at exact millisecond.
- `sampleAnimationFrame(animation, time, { index, count, delay, fps })`: sample state and timeline context at an exact video timestamp.
- `sampleAnimationFrames(animation, { fps? })`: return deterministic state/frame samples with GIF-compatible delays.
- `analyzeAnimationCadence(animation, { fps? })`: return frame count, encoded duration, target interval, and delay range without rendering.
- `renderAnimationGif(animation, options)`: stream timeline samples into GIF.
- `renderAnimationVideo(animation, { width, height, outputPath, fps?, scale?, theme?, background?, watermark?, audioPath?, crf?, preset?, threads?, signal? })`: render typed TSX frames to H.264 MP4. Defaults to 30 fps and an opaque theme background; streams frames and checks overflow at each timestamp. FFmpeg is installed separately.
- `renderRgbaVideo(renderFrame, { width, height, duration, outputPath, fps?, audioPath?, crf?, preset?, signal? })`: encode caller-painted RGBA frames without buffering the whole film.
- `tracePolyline(points, progress)` and `pointAlongPath(points, progress)`: reveal and follow a path by arc length; `arcSwap(from, to, progress, options?)` exchanges positions along mirrored arcs; `smoothstep(progress)` clamps and eases progress.
- `renderAnimationGifWithOutput(animation, options)`: same arguments and returns dimensions, input/encoded frame counts, delta-frame count, duration, and byte size.
- `renderAnimatedGif(scenes, options)`: legacy `AnimatedScene[]` renderer for scene cuts and pixel transitions. It also accepts a defined animation.
- `renderAnimatedGifWithOutput(scenes, options)`: same arguments as `renderAnimatedGif`; returns dimensions and encoding metrics.
- `AnimatedScene`: `element`, `duration` in ms, `transition?: "none" | "fade" | "appear"`, `transitionDuration?`, `label?`.
- `AnimationOptions`: `width`, `height`, `outputPath`, `loop?: number = 0`, `scale?: number = 1`, `fps?: number`, `deltaFrames?: boolean = true`, `background?: "theme" | "transparent" | CSS color = "theme"`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `theme?: "dark" | "light" = "dark"`. Every actual frame is checked for overflow. Opaque GIFs encode changed rectangles; transparent GIFs stay full-frame for correct one-bit compositing. Use PNG/SVG when smooth alpha edges matter.

## Prop-aware examples

### Window + code + status

```tsx
width = 1040;
height = 560;

<Scene title="Release gate" subtitle="tool output and checklist">
  <Row gap={18} align="stretch">
    <WindowFrame title="ci.log" variant="terminal" tone="green" width={520}>
      <CodeBlock
        fontSize={12}
        showLineNumbers
        lines={[
          { text: "pnpm typecheck", tone: "green", prefix: "$" },
          { text: "pnpm test", tone: "green", prefix: "$" },
          { text: "pnpm render:examples", tone: "cyan", prefix: "$" },
        ]}
      />
    </WindowFrame>
    <StatusList
      width={360}
      rows={[
        { label: "Types", detail: "clean", status: "check", tone: "green" },
        { label: "Visuals", detail: "dark/light generated", status: "check", tone: "cyan" },
        { label: "NPM", detail: "auth required", status: "warn", tone: "warm" },
      ]}
    />
  </Row>
</Scene>
```

### Matrix + chart

```tsx
width = 1040;
height = 560;

<Scene title="Attention audit" subtitle="weights, scores, and distribution">
  <Row gap={18} align="stretch">
    <Heatmap
      title="Attention"
      xLabels={["q1", "q2", "q3"]}
      yLabels={["k1", "k2", "k3"]}
      data={[
        [0.9, 0.2, 0.1],
        [0.4, 0.8, 0.2],
        [0.1, 0.3, 0.7],
      ]}
    />
    <Matrix
      title="Scores"
      format="decimal"
      rowLabels={["A", "B", "C"]}
      colLabels={["x", "y", "z"]}
      data={[
        [0.4, 0.7, 0.2],
        [0.5, 0.2, 0.8],
      ]}
    />
    <StackedBar
      width={300}
      title="Token budget"
      segments={[
        { label: "prompt", value: 42, color: "primary" },
        { label: "context", value: 38, color: "info" },
        { label: "answer", value: 20, color: "positive" },
      ]}
    />
  </Row>
</Scene>
```

## Rendering rules

- Use semantic tones instead of hard-coded colors: `blue`, `purple`, `green`, `warm`, `cyan`, `pink`, `critical`, `ocean`, `neutral`.
- For Datadog Engineering-style article diagrams, set `preset = "engineering";` and render the light theme. Keep each figure focused on one transition or tradeoff.
- Use explicit sizes for final assets. Common sizes are `1040x560` for article figures, `1280x720` for slide frames, and `900x520` for compact diagrams.
- During exploration, dimensions can be omitted. Vizmatic starts at `960x540` and grows to fit content.
- 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.
- Use `width`, `minWidth`, `height`, `minHeight`, `gap`, and `padding` to keep layout stable.
- Keep text short. Use `TextLabel`, `Panel`, `StepCard`, `MetricCard`, `DataTable`, and `Grid` for wrapping-safe labels.
- Omit `x` and `y` from `GraphDiagram` nodes for automatic layered layout and nested groups. Add both only when an ungrouped graph needs editorial manual control.
- Render reusable assets in both themes with `--theme dark,light`.
- Run `vizmatic check <frame> --theme dark,light --json` before final render and fix every error.
- Use GIF only when motion explains state change. Prefer `createAnimation(theme)` with `hold` and `tween`, keep timelines short, match terminal and initial visuals for infinite loops, and keep static `create(theme)` fallback. Sampling follows exact cadence boundaries and includes terminal state. Use `analyzeAnimationCadence` when timing must be audited. Use `createScenes(theme)` only for deliberate cuts or crossfades.
- If render fails with `Canvas overflow detected`, increase the canvas, reduce content, or remove strict sizing. Do not ignore the error.
- Confirm generated files exist and open at least one image before finishing.

## Common recipes

### RAG graph

```tsx
width = 1040;
height = 560;

<Scene title="RAG control graph" subtitle="retrieval with a citation check" align="center">
  <GraphDiagram
    width={820}
    height={390}
    nodeWidth={132}
    rankGap={44}
    nodes={[
      { id: "query", label: "Query", detail: "intent", tone: "blue" },
      { id: "retrieve", label: "Retrieve", detail: "top-k docs", tone: "cyan" },
      { id: "rerank", label: "Rerank", detail: "quality gate", tone: "warm" },
      { id: "answer", label: "Answer", detail: "grounded draft", tone: "green" },
      { id: "verify", label: "Verify", detail: "citations", tone: "critical" },
    ]}
    edges={[
      { from: "query", to: "retrieve", label: "search", tone: "blue" },
      { from: "retrieve", to: "rerank", label: "rank", tone: "cyan" },
      { from: "rerank", to: "answer", label: "context", tone: "green" },
      { from: "answer", to: "verify", label: "claims", tone: "critical" },
    ]}
  />
</Scene>
```

### Evaluation dashboard

```tsx
width = 1040;
height = 620;

<Scene title="Evaluation snapshot" subtitle="charts inherit theme, labels, and contrast">
  <Row gap={18} align="stretch">
    <BarChart
      width={440}
      height={260}
      title="Pass rate by task"
      format="percent"
      data={[
        { label: "tools", value: 0.82, color: "positive" },
        { label: "math", value: 0.71, color: "secondary" },
        { label: "code", value: 0.77, color: "primary" },
        { label: "long", value: 0.58, color: "warning" },
      ]}
    />
    <LineChart
      width={440}
      height={260}
      title="Quality over releases"
      format="percent"
      labels={["v1", "v2", "v3", "v4", "v5"]}
      series={[
        { name: "quality", points: [0.55, 0.61, 0.69, 0.74, 0.81], color: "positive", area: true },
        { name: "latency", points: [0.72, 0.69, 0.66, 0.62, 0.59], color: "warning" },
      ]}
    />
  </Row>
</Scene>
```

## Final response

After creating a visual, report:

- files created or changed
- render command used
- output image paths, including GIF paths when generated
- whether dark/light variants rendered
- whether structured validation passed
- any overflow or layout fixes made

# Component catalog

# Vizmatic components

Package: vizmatic@0.4.0. Catalog: 75 runnable examples across 11 categories.

Each example is a focused, runnable starting point. The generated Props lists mirror exported TypeScript signatures; `type` is TypeScript text, not a JSON schema, and props may accept values that JSON cannot represent. `required` records signature requiredness. Exhaustive finite choices use `allowedValuesRef`; mixed unions may use `literalValuesRef` for available JSON literal presets while callback or other non-literal variants remain source-only. Shared values are stored in the `propEnums` object in `components.json`. Default values are not inferred.

## Foundations



Scene structure, responsive layout, and framed surfaces.



### Canvas

Root canvas with transparent or custom backgrounds and padding.

Props:
- `background`: `string` (optional)
- `c`: `ThemeColors` (required)
- `children`: `React.ReactNode` (optional)
- `justify`: `"center" | "flex-start" | "space-between" | "space-around"` (optional; allowed values: `propEnums.values1`)
- `padding`: `number` (optional)

```tsx
width = 960
height = 480

<Canvas
    padding={24}>
  <Column
    gap={14}>
  <TitleBar
    title='Canvas surface'
    subtitle='A theme aware root with alpha background support' />
  <MetricCard
    label='Render time'
    value='42 ms'
    tone='green'
    detail='p95 across 1,200 frames' />
  </Column>
  </Canvas>
```

### Board

Fixed-size canvas for freely positioned visuals in one coordinate space.

Props:
- `background`: `string` (optional)
- `c`: `ThemeColors` (required)
- `children`: `React.ReactNode` (optional)
- `height`: `number` (optional)
- `width`: `number` (optional)

```tsx
width = 960
height = 480

<Board
    width={960}
    height={480}
    background={c.bgSubtle}>
  <CanvasItem
    x={48}
    y={44}
    width={288}
    height={132}>
  <MetricCard
    label='API latency'
    value='82 ms'
    detail='budget: 120 ms'
    tone='green' />
  </CanvasItem>
  <CanvasItem
    x={368}
    y={184}
    width={264}
    height={132}>
  <MetricCard
    label='Queue depth'
    value='14'
    detail='steady over 5 min'
    tone='purple' />
  </CanvasItem>
  <CanvasItem
    x={672}
    y={52}
    width={240}
    height={116}>
  <MetricCard
    label='Deploy'
    value='healthy'
    detail='all regions'
    tone='blue' />
  </CanvasItem>
  </Board>
```

### CanvasItem

Positions and sizes a visual relative to its parent Board.

Props:
- `children`: `React.ReactNode` (optional)
- `height`: `number` (optional)
- `width`: `number` (optional)
- `x`: `number` (required)
- `y`: `number` (required)

```tsx
width = 1040
height = 640

<Scene title="CanvasItem example" subtitle="Edit this focused CanvasItem scene" padding={22} gap={18}>
  <Board
    width={960}
    height={480}
    background={c.bgSubtle}>
  <CanvasItem
    x={52}
    y={48}
    width={300}
    height={138}>
  <MetricCard
    label='API latency'
    value='82 ms'
    detail='budget: 120 ms'
    tone='green' />
  </CanvasItem>
  <CanvasItem
    x={404}
    y={196}
    width={360}
    height={148}>
  <Panel
    title='Worker pool'
    subtitle='positioned as one canvas item'
    tone='purple'
    width='100%'
    padding={16}>
  <StatusRow
    label='Workers'
    detail='8 / 8 ready'
    status='check' />
  </Panel>
  </CanvasItem>
  </Board>
</Scene>
```

### Scene

Primary vertical scene layout with optional title and subtitle.

Props:
- `align`: `FlexAlign` (optional; allowed values: `propEnums.FlexAlign`)
- `background`: `string` (optional)
- `c`: `ThemeColors` (required)
- `children`: `React.ReactNode` (required)
- `contentStyle`: `React.CSSProperties` (optional)
- `contentWidth`: `string | number` (optional)
- `gap`: `number` (optional)
- `justify`: `"center" | "flex-start" | "space-between" | "space-around" | undefined` (optional; allowed values: `propEnums.values1`)
- `padding`: `number` (optional)
- `subtitle`: `string` (optional)
- `title`: `string` (optional)

```tsx
width = 960
height = 480

<Scene
    title='Scene layout'
    subtitle='A title, content area, and consistent spacing'>
  <Row
    gap={14}>
  <MetricCard
    label='Build'
    value='ready'
    tone='green' />
  <MetricCard
    label='Review'
    value='2 items'
    tone='warm' />
  </Row>
  </Scene>
```

### TitleBar

Standalone heading and supporting copy.

Props:
- `c`: `ThemeColors` (required)
- `subtitle`: `string` (optional)
- `title`: `string` (required)

```tsx
width = 960
height = 480

<Scene title="TitleBar example" subtitle="Edit this focused TitleBar scene" padding={22} gap={18}>
  <Column
    gap={16}>
  <TitleBar
    title='Release overview'
    subtitle='One clear headline with supporting context' />
  <ProgressList
    rows={[{ label: 'Build', value: 1, tone: 'green' },
        { label: 'Review', value: 0.72, tone: 'purple' }]} />
  </Column>
</Scene>
```

### Row

Horizontal flex layout with stable gaps and alignment.

Props:
- `align`: `FlexAlign` (optional; allowed values: `propEnums.FlexAlign`)
- `children`: `React.ReactNode` (required)
- `gap`: `number` (optional)
- `height`: `string | number` (optional)
- `justify`: `FlexJustify` (optional; allowed values: `propEnums.FlexJustify`)
- `style`: `React.CSSProperties` (optional)
- `width`: `string | number` (optional)
- `wrap`: `boolean` (optional; allowed values: `propEnums.values2`)

```tsx
width = 960
height = 480

<Scene title="Row example" subtitle="Edit this focused Row scene" padding={22} gap={18}>
  <Row
    gap={12}
    align='stretch'>
  <StepCard
    title='Plan'
    subtitle='shape the story'
    tone='blue'
    width={220} />
  <StepCard
    title='Render'
    subtitle='check both themes'
    tone='purple'
    width={220} />
  <StepCard
    title='Ship'
    subtitle='publish the asset'
    tone='green'
    width={220} />
  </Row>
</Scene>
```

### Column

Vertical flex layout for stacked composition.

Props:
- `align`: `FlexAlign` (optional; allowed values: `propEnums.FlexAlign`)
- `children`: `React.ReactNode` (required)
- `gap`: `number` (optional)
- `height`: `string | number` (optional)
- `justify`: `FlexJustify` (optional; allowed values: `propEnums.FlexJustify`)
- `style`: `React.CSSProperties` (optional)
- `width`: `string | number` (optional)
- `wrap`: `boolean` (optional; allowed values: `propEnums.values2`)

```tsx
width = 960
height = 480

<Scene title="Column example" subtitle="Edit this focused Column scene" padding={22} gap={18}>
  <Column
    gap={10}
    align='stretch'>
  <StatusRow
    label='Layout'
    detail='ready'
    status='check' />
  <StatusRow
    label='Contrast'
    detail='inspect'
    status='pending' />
  <StatusRow
    label='Export'
    detail='PNG + SVG'
    status='info' />
  </Column>
</Scene>
```

### Stack

Compact vertical grouping for related content.

Props:
- `align`: `"center" | "start" | "end" | "stretch"` (optional; allowed values: `propEnums.FlexAlign`)
- `children`: `React.ReactNode` (required)
- `direction`: `"vertical" | "horizontal"` (optional; allowed values: `propEnums.values3`)
- `gap`: `number` (optional)
- `wrap`: `boolean` (optional; allowed values: `propEnums.values2`)

```tsx
width = 960
height = 480

<Scene title="Stack example" subtitle="Edit this focused Stack scene" padding={22} gap={18}>
  <Stack
    gap={10}
    align='stretch'>
  <BadgePill
    text='INPUT'
    tone='blue' />
  <Arrow
    direction='down'
    length={24} />
  <BadgePill
    text='OUTPUT'
    tone='green' />
  </Stack>
</Scene>
```

### Panel

Titled container for grouped visual content.

Props:
- `accentHeight`: `number` (optional)
- `accentWidth`: `number` (optional)
- `align`: `FlexAlign` (optional; allowed values: `propEnums.FlexAlign`)
- `background`: `string` (optional)
- `bodyStyle`: `React.CSSProperties` (optional)
- `borderColor`: `string` (optional)
- `c`: `ThemeColors` (required)
- `children`: `React.ReactNode` (optional)
- `footer`: `React.ReactNode` (optional)
- `gap`: `number` (optional)
- `height`: `string | number` (optional)
- `justify`: `FlexJustify` (optional; allowed values: `propEnums.FlexJustify`)
- `minHeight`: `string | number` (optional)
- `minWidth`: `string | number` (optional)
- `padding`: `string | number` (optional)
- `radius`: `number` (optional)
- `shadow`: `boolean` (optional; allowed values: `propEnums.values2`)
- `subtitle`: `React.ReactNode` (optional)
- `title`: `React.ReactNode` (required)
- `titleFontSize`: `number` (optional)
- `tone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)
- `width`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="Panel example" subtitle="Edit this focused Panel scene" padding={22} gap={18}>
  <Panel
    title='Service health'
    subtitle='Live state grouped in a titled surface'
    tone='green'
    width='100%'
    padding={18}>
  <StatusList
    rows={[{ label: 'API', detail: 'healthy', status: 'check' },
        { label: 'Queue', detail: '12 jobs', status: 'info' }]} />
  </Panel>
</Scene>
```

### Card

General-purpose surface with tone, padding, and shadow.

Props:
- `align`: `FlexAlign` (optional; allowed values: `propEnums.FlexAlign`)
- `background`: `string` (optional)
- `bodyStyle`: `React.CSSProperties` (optional)
- `borderColor`: `string` (optional)
- `c`: `ThemeColors` (required)
- `children`: `React.ReactNode` (optional)
- `footer`: `React.ReactNode` (optional)
- `gap`: `number` (optional)
- `height`: `string | number` (optional)
- `justify`: `FlexJustify` (optional; allowed values: `propEnums.FlexJustify`)
- `minHeight`: `string | number` (optional)
- `minWidth`: `string | number` (optional)
- `padding`: `string | number` (optional)
- `radius`: `number` (optional)
- `shadow`: `boolean` (optional; allowed values: `propEnums.values2`)
- `subtitle`: `React.ReactNode` (optional)
- `title`: `React.ReactNode` (optional)
- `tone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)
- `width`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="Card example" subtitle="Edit this focused Card scene" padding={22} gap={18}>
  <Card
    title='Inference API'
    subtitle='Regional endpoint'
    tone='purple'
    width={430}
    padding={20} shadow>
  <TextLabel
    text='p95 latency'
    fontSize={12} />
  <MetricCard
    label='Latency'
    value='82 ms'
    tone='green'
    width={180} />
  </Card>
</Scene>
```

### WindowFrame

Application or terminal window framing.

Props:
- `background`: `string` (optional)
- `bodyStyle`: `React.CSSProperties` (optional)
- `c`: `ThemeColors` (required)
- `children`: `React.ReactNode` (optional)
- `dots`: `boolean` (optional; allowed values: `propEnums.values2`)
- `height`: `string | number` (optional)
- `minHeight`: `string | number` (optional)
- `minWidth`: `string | number` (optional)
- `padding`: `string | number` (optional)
- `radius`: `number` (optional)
- `shadow`: `boolean` (optional; allowed values: `propEnums.values2`)
- `title`: `React.ReactNode` (optional)
- `tone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)
- `variant`: `"window" | "browser" | "terminal"` (optional; allowed values: `propEnums.values4`)
- `width`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="WindowFrame example" subtitle="Edit this focused WindowFrame scene" padding={22} gap={18}>
  <WindowFrame
    title='worker.log'
    variant='terminal'
    tone='green'
    width={620}>
  <Column
    gap={8}
    align='stretch'>
  <TextLabel
    text='$ vizmatic render scene.tsx' mono
    fontSize={13} />
  <TextLabel
    text='✓ dark and light previews created' mono
    fontSize={13}
    color={c.positiveLight} />
  </Column>
  </WindowFrame>
</Scene>
```
## Content



Labels, cards, code, comparisons, and reusable information blocks.



### ToneStrip

Short semantic color accent.

Props:
- `height`: `number` (optional)
- `tone`: `ToneName` (required; allowed values: `propEnums.ToneName`)
- `width`: `number` (optional)

```tsx
width = 960
height = 480

<Scene title="ToneStrip example" subtitle="Edit this focused ToneStrip scene" padding={22} gap={18}>
  <Row
    gap={14}
    align='center'>
  <ToneStrip
    tone='purple'
    width={64}
    height={8} />
  <TextLabel
    text='Accent follows the selected semantic tone.'
    fontSize={14} />
  </Row>
</Scene>
```

### Icon

Theme-aware technical icon set.

Props:
- `c`: `ThemeColors` (required)
- `color`: `string` (optional)
- `label`: `string` (optional)
- `muted`: `boolean` (optional; allowed values: `propEnums.values2`)
- `name`: `IconName` (required; allowed values: `propEnums.IconName`)
- `size`: `number` (optional)
- `strokeWidth`: `number` (optional)
- `tone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)

```tsx
width = 960
height = 480

<Scene title="Icon example" subtitle="Edit this focused Icon scene" padding={22} gap={18}>
  <Row
    gap={18}
    align='center'>
  <Icon
    name='layers'
    tone='purple'
    size={34} />
  <Icon
    name='code'
    tone='blue'
    size={34} />
  <Icon
    name='spark'
    tone='green'
    size={34} />
  </Row>
</Scene>
```

### TextLabel

Wrapping-safe SVG or flex label.

Props:
- `align`: `"center" | "left" | "right"` (optional; allowed values: `propEnums.values5`)
- `c`: `ThemeColors` (required)
- `color`: `string` (optional)
- `fontSize`: `number` (optional)
- `fontWeight`: `number` (optional)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `mono`: `boolean` (optional; allowed values: `propEnums.values2`)
- `text`: `string` (required)
- `variant`: `"code" | "title" | "subtitle" | "label" | "body" | "small" | "tiny" | "annotation"` (optional; allowed values: `propEnums.values6`)
- `width`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="TextLabel example" subtitle="Edit this focused TextLabel scene" padding={22} gap={18}>
  <Column
    gap={8}
    align='start'>
  <TextLabel
    text='A readable technical label'
    fontSize={20}
    fontWeight={800}
    color={c.textPrimary} />
  <TextLabel
    text='Use mono for identifiers, commands, and compact metadata.' mono
    fontSize={12} />
  </Column>
</Scene>
```

### MathText

Math-aware text formatting for React content.

Props:
- `text`: `string` (required)

```tsx
width = 960
height = 480

<Scene title="MathText example" subtitle="Edit this focused MathText scene" padding={22} gap={18}>
  <Column
    gap={10}
    align='start'>
  <TextLabel
    text={MathText({ text: 'x_i^2 + y_i^2' })}
    fontSize={22} mono />
  <TextLabel
    text='MathText formats inline notation for labels.'
    fontSize={12} />
  </Column>
</Scene>
```

### SvgMathText

Positioned math overlay aligned with custom SVG geometry.

Props:
- `dominantBaseline`: `string` (optional)
- `fill`: `string` (required)
- `fontFamily`: `string` (optional)
- `fontSize`: `number` (optional)
- `fontWeight`: `number` (optional)
- `opacity`: `number` (optional)
- `text`: `string` (required)
- `textAnchor`: `"start" | "end" | "middle"` (optional; allowed values: `propEnums.values7`)
- `x`: `number` (required)
- `y`: `number` (required)

```tsx
width = 960
height = 480

<Scene title="SvgMathText example" subtitle="Edit this focused SvgMathText scene" padding={22} gap={18}>
  <div
    style={{ position: 'relative', display: 'flex', width: 420, height: 100 }}>
  <SvgMathText
    text='E = mc^2'
    x={20}
    y={62}
    fill={c.textPrimary}
    fontSize={34}
    textAnchor='start' />
  </div>
</Scene>
```

### Badge

Compact semantic SVG label.

Props:
- `c`: `ThemeColors` (required)
- `color`: `ColorName` (optional; allowed values: `propEnums.ColorName`)
- `label`: `string` (required)

```tsx
width = 960
height = 480

<Scene title="Badge example" subtitle="Edit this focused Badge scene" padding={22} gap={18}>
  <Row
    gap={12}
    align='center'>
  <Badge
    label='stable'
    color='positive' />
  <Badge
    label='preview'
    color='warning' />
  <Badge
    label='blocked'
    color='critical' />
  </Row>
</Scene>
```

### BadgePill

Inline status, category, or metadata label.

Props:
- `c`: `ThemeColors` (required)
- `filled`: `boolean` (optional; allowed values: `propEnums.values2`)
- `fontSize`: `number` (optional)
- `height`: `string | number` (optional)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `minWidth`: `string | number` (optional)
- `mono`: `boolean` (optional; allowed values: `propEnums.values2`)
- `padding`: `string | number` (optional)
- `radius`: `number` (optional)
- `text`: `React.ReactNode` (required)
- `tone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)
- `width`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="BadgePill example" subtitle="Edit this focused BadgePill scene" padding={22} gap={18}>
  <Row
    gap={10}
    align='center'>
  <BadgePill
    text='API'
    tone='blue' />
  <BadgePill
    text='HEALTHY'
    tone='green' />
  <BadgePill
    text='P95 82 ms'
    tone='purple' />
  </Row>
</Scene>
```

### GradientChip

Emphasized label with tone gradient.

Props:
- `align`: `"center" | "left"` (optional; allowed values: `propEnums.values8`)
- `c`: `ThemeColors` (required)
- `gradient`: `string` (optional)
- `height`: `string | number` (optional)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `minHeight`: `string | number` (optional)
- `minWidth`: `string | number` (optional)
- `padding`: `string | number` (optional)
- `radius`: `number` (optional)
- `shadow`: `boolean` (optional; allowed values: `propEnums.values2`)
- `subtitle`: `React.ReactNode` (optional)
- `subtitleMono`: `boolean` (optional; allowed values: `propEnums.values2`)
- `title`: `React.ReactNode` (required)
- `tone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)
- `width`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="GradientChip example" subtitle="Edit this focused GradientChip scene" padding={22} gap={18}>
  <GradientChip
    title='Verified output'
    subtitle='dark + light themes'
    tone='green'
    width={320}
    minHeight={92}
    align='center' />
</Scene>
```

### ValuePill

Small label-value pair.

Props:
- `c`: `ThemeColors` (required)
- `detail`: `React.ReactNode` (optional)
- `label`: `React.ReactNode` (required)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `tone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)
- `value`: `React.ReactNode` (required)
- `width`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="ValuePill example" subtitle="Edit this focused ValuePill scene" padding={22} gap={18}>
  <Row
    gap={14}>
  <ValuePill
    label='Batch size'
    value='128'
    detail='tokens / step'
    tone='purple'
    width={170} />
  <ValuePill
    label='Throughput'
    value='940'
    detail='items / second'
    tone='green'
    width={190} />
  </Row>
</Scene>
```

### EquationCard

Formula, result, and supporting detail.

Props:
- `align`: `"center" | "left"` (optional; allowed values: `propEnums.values8`)
- `c`: `ThemeColors` (required)
- `detail`: `React.ReactNode` (optional)
- `formula`: `React.ReactNode` (required)
- `height`: `string | number` (optional)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `result`: `React.ReactNode` (optional)
- `title`: `React.ReactNode` (required)
- `tone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)
- `width`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="EquationCard example" subtitle="Edit this focused EquationCard scene" padding={22} gap={18}>
  <EquationCard
    title='Throughput'
    formula='items ÷ seconds'
    result='940/s'
    detail='measured over 5 minutes'
    tone='purple'
    width={300} math />
</Scene>
```

### StepCard

Numbered or staged process card.

Props:
- `align`: `"center" | "left"` (optional; allowed values: `propEnums.values8`)
- `c`: `ThemeColors` (required)
- `eyebrow`: `React.ReactNode` (optional)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `minHeight`: `string | number` (optional)
- `minWidth`: `string | number` (optional)
- `padding`: `string | number` (optional)
- `radius`: `number` (optional)
- `shadow`: `boolean` (optional; allowed values: `propEnums.values2`)
- `subtitle`: `React.ReactNode` (optional)
- `title`: `React.ReactNode` (required)
- `tone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)
- `width`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="StepCard example" subtitle="Edit this focused StepCard scene" padding={22} gap={18}>
  <Row
    gap={14}>
  <StepCard
    eyebrow='01'
    title='Collect'
    subtitle='read source data'
    tone='blue'
    width={220} />
  <StepCard
    eyebrow='02'
    title='Validate'
    subtitle='check invariants'
    tone='purple'
    width={220} />
  <StepCard
    eyebrow='03'
    title='Publish'
    subtitle='write artifacts'
    tone='green'
    width={220} />
  </Row>
</Scene>
```

### MetricCard

KPI value with label and context.

Props:
- `align`: `"center" | "left"` (optional; allowed values: `propEnums.values8`)
- `c`: `ThemeColors` (required)
- `detail`: `React.ReactNode` (optional)
- `label`: `React.ReactNode` (required)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `minHeight`: `string | number` (optional)
- `minWidth`: `string | number` (optional)
- `padding`: `string | number` (optional)
- `radius`: `number` (optional)
- `shadow`: `boolean` (optional; allowed values: `propEnums.values2`)
- `tone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)
- `value`: `React.ReactNode` (required)
- `valueColor`: `string` (optional)
- `valueFontSize`: `number` (optional)
- `valueMono`: `boolean` (optional; allowed values: `propEnums.values2`)
- `width`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="MetricCard example" subtitle="Edit this focused MetricCard scene" padding={22} gap={18}>
  <Row
    gap={14}>
  <MetricCard
    label='Build success'
    value='98.7%'
    detail='last 30 days'
    tone='green'
    width={220}
    minHeight={120} />
  <MetricCard
    label='Open issues'
    value='4'
    detail='2 need review'
    tone='warm'
    width={220}
    minHeight={120} />
  </Row>
</Scene>
```

### CalloutCard

Focused takeaway, warning, or recommendation.

Props:
- `align`: `"center" | "left"` (optional; allowed values: `propEnums.values8`)
- `c`: `ThemeColors` (required)
- `children`: `React.ReactNode` (optional)
- `detail`: `React.ReactNode` (optional)
- `detailFontSize`: `number` (optional)
- `filled`: `boolean` (optional; allowed values: `propEnums.values2`)
- `minHeight`: `string | number` (optional)
- `padding`: `string | number` (optional)
- `title`: `React.ReactNode` (optional)
- `titleFontSize`: `number` (optional)
- `tone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)
- `width`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="CalloutCard example" subtitle="Edit this focused CalloutCard scene" padding={22} gap={18}>
  <CalloutCard
    title='Recommendation'
    detail='Keep the source editable and verify both color themes before publishing.'
    tone='cyan'
    width={560}
    minHeight={132} />
</Scene>
```

### DetailList

Compact list of supporting facts.

Props:
- `c`: `ThemeColors` (required)
- `fontSize`: `number` (optional)
- `gap`: `number` (optional)
- `items`: `React.ReactNode[]` (required)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `mono`: `boolean` (optional; allowed values: `propEnums.values2`)
- `padding`: `string | number` (optional)
- `tone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)

```tsx
width = 960
height = 480

<Scene title="DetailList example" subtitle="Edit this focused DetailList scene" padding={22} gap={18}>
  <DetailList
    tone='blue'
    items={['TypeScript source', 'Theme aware colors', 'PNG and SVG export']}
    fontSize={13} />
</Scene>
```

### CodeBlock

Code or command excerpt with optional line numbers.

Props:
- `background`: `string` (optional)
- `c`: `ThemeColors` (required)
- `fontSize`: `number` (optional)
- `lines`: `(React.ReactNode | CodeLineSpec)[]` (required)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `minWidth`: `string | number` (optional)
- `padding`: `string | number` (optional)
- `radius`: `number` (optional)
- `shadow`: `boolean` (optional; allowed values: `propEnums.values2`)
- `showLineNumbers`: `boolean` (optional; allowed values: `propEnums.values2`)
- `title`: `React.ReactNode` (optional)
- `tone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)
- `width`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="CodeBlock example" subtitle="Edit this focused CodeBlock scene" padding={22} gap={18}>
  <CodeBlock
    title='render.tsx'
    tone='purple'
    fontSize={13} showLineNumbers
    lines={[{ text: 'const frame = <Scene />', tone: 'purple' },
        { text: 'await render(frame)' },
        { text: 'writeFile(output)', tone: 'green' }]} />
</Scene>
```

### Comparison

Side-by-side alternatives or before/after states.

Props:
- `align`: `FlexAlign` (optional; allowed values: `propEnums.FlexAlign`)
- `c`: `ThemeColors` (required)
- `divider`: `React.ReactNode` (optional)
- `gap`: `number` (optional)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `minHeight`: `string | number` (optional)
- `sides`: `ComparisonSideSpec[]` (required)
- `sideWidth`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="Comparison example" subtitle="Edit this focused Comparison scene" padding={22} gap={18}>
  <Comparison divider
    gap={10}
    minHeight={150}
    sides={[{ title: 'Before', tone: 'warm', lines: ['manual spacing', 'one theme'] },
        { title: 'After', tone: 'green', lines: ['shared layout', 'dark + light'] }]} />
</Scene>
```

### KeyValueList

Aligned technical metadata rows.

Props:
- `c`: `ThemeColors` (required)
- `divider`: `boolean` (optional; allowed values: `propEnums.values2`)
- `fontSize`: `number` (optional)
- `gap`: `number` (optional)
- `keyMono`: `boolean` (optional; allowed values: `propEnums.values2`)
- `keyWidth`: `string | number` (optional)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `minWidth`: `string | number` (optional)
- `rows`: `KeyValueRow[]` (required)
- `title`: `React.ReactNode` (optional)
- `width`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="KeyValueList example" subtitle="Edit this focused KeyValueList scene" padding={22} gap={18}>
  <KeyValueList
    title='Render settings'
    rows={[{ key: 'format', value: 'PNG + SVG', tone: 'blue' },
        { key: 'themes', value: 'dark, light', tone: 'green' },
        { key: 'latency', value: '42 ms' }]}
    width={430} />
</Scene>
```

### Tile

Single labeled unit for feature or system maps.

Props:
- `align`: `"center" | "left"` (optional; allowed values: `propEnums.values8`)
- `c`: `ThemeColors` (required)
- `children`: `React.ReactNode` (optional)
- `eyebrow`: `React.ReactNode` (optional)
- `icon`: `React.ReactNode` (optional)
- `lines`: `React.ReactNode[]` (optional)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `minHeight`: `string | number` (optional)
- `padding`: `string | number` (optional)
- `radius`: `number` (optional)
- `shadow`: `boolean` (optional; allowed values: `propEnums.values2`)
- `subtitle`: `React.ReactNode` (optional)
- `title`: `React.ReactNode` (required)
- `tone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)
- `width`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="Tile example" subtitle="Edit this focused Tile scene" padding={22} gap={18}>
  <Tile
    title='Search index'
    subtitle='retrieval service'
    eyebrow='READY'
    icon='⌕'
    tone='cyan'
    lines={['p95 18 ms', '3 replicas']}
    width={260}
    minHeight={128} />
</Scene>
```

### TileGrid

Dense grid of related labeled units.

Props:
- `align`: `"center" | "left"` (optional; allowed values: `propEnums.values8`)
- `c`: `ThemeColors` (required)
- `columns`: `number` (optional)
- `gap`: `number` (optional)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `minHeight`: `string | number` (optional)
- `tiles`: `TileSpec[]` (required)
- `tileWidth`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="TileGrid example" subtitle="Edit this focused TileGrid scene" padding={22} gap={18}>
  <TileGrid
    columns={3}
    gap={12}
    tileWidth={210}
    minHeight={112}
    tiles={[{ title: 'Ingest', subtitle: 'events', tone: 'blue' },
        { title: 'Transform', subtitle: 'schemas', tone: 'purple' },
        { title: 'Serve', subtitle: 'features', tone: 'green' }]} />
</Scene>
```

### Watermark

Frame metadata for text, image, or custom branding.

Props:
- `children`: `React.ReactNode` (optional)
- `color`: `string` (optional)
- `element`: `React.ReactNode` (optional)
- `icon`: `React.ReactNode` (optional)
- `image`: `string | WatermarkImageOptions` (optional)
- `opacity`: `number` (optional)
- `position`: `WatermarkPosition` (optional; allowed values: `propEnums.WatermarkPosition`)
- `text`: `string | false` (optional)

```tsx
width = 960
height = 480

<Scene title="Watermark example" subtitle="Edit this focused Watermark scene" padding={22} gap={18}>
  <Row
    width={680}
    height={300}
    align='center'
    justify='center'>{wrapWithWatermark(<Scene
    title='Published report'
    subtitle='Watermark stays anchored to the rendered frame'
    padding={22}>
  <MetricCard
    label='Verified runs'
    value='1,284'
    detail='this week'
    tone='green'
    width={250} />
  </Scene>, 640, 260, 'dark', <Watermark
    text='Vizmatic'
    color={c.textSecondary}
    opacity={0.9}
    position='bottom-right' />)}</Row>
</Scene>
```
## Flows



Processes, timelines, status, and progress.



### StatusRow

Single operational state with detail.

Props:
- `boxed`: `boolean` (optional; allowed values: `propEnums.values2`)
- `c`: `ThemeColors` (required)
- `detail`: `React.ReactNode` (optional)
- `fontSize`: `number` (optional)
- `label`: `React.ReactNode` (required)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `status`: `StatusKind` (optional; allowed values: `propEnums.StatusKind`)
- `tone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)
- `width`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="StatusRow example" subtitle="Edit this focused StatusRow scene" padding={22} gap={18}>
  <Column
    gap={10}
    width={620}
    align='stretch'>
  <StatusRow
    label='Build'
    detail='passed'
    status='check' />
  <StatusRow
    label='Review'
    detail='2 comments'
    status='pending' />
  <StatusRow
    label='Security'
    detail='attention'
    status='warn' />
  </Column>
</Scene>
```

### StatusList

Grouped checks, warnings, and pending work.

Props:
- `boxed`: `boolean` (optional; allowed values: `propEnums.values2`)
- `c`: `ThemeColors` (required)
- `fontSize`: `number` (optional)
- `gap`: `number` (optional)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `rows`: `StatusRowSpec[]` (required)
- `width`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="StatusList example" subtitle="Edit this focused StatusList scene" padding={22} gap={18}>
  <StatusList
    width={620}
    rows={[{ label: 'Build', detail: 'passed', status: 'check' },
        { label: 'Review', detail: '2 comments', status: 'pending' },
        { label: 'Security', detail: 'attention', status: 'warn' }]} />
</Scene>
```

### Timeline

Ordered events in horizontal or vertical form.

Props:
- `c`: `ThemeColors` (required)
- `direction`: `"vertical" | "horizontal"` (optional; allowed values: `propEnums.values3`)
- `events`: `TimelineEventSpec[]` (required)
- `eventWidth`: `string | number` (optional)
- `gap`: `number` (optional)
- `markerSize`: `number` (optional)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `subtitle`: `React.ReactNode` (optional)
- `title`: `React.ReactNode` (optional)
- `width`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="Timeline example" subtitle="Edit this focused Timeline scene" padding={22} gap={18}>
  <Timeline
    title='Release timeline'
    subtitle='Key steps from draft to publish'
    width={820}
    direction='horizontal'
    eventWidth={230}
    events={[{ time: '09:10', title: 'Draft', detail: 'write the scene', tone: 'blue' },
        { time: '09:24', title: 'Validate', detail: 'check layout', tone: 'purple' },
        { time: '09:31', title: 'Publish', detail: 'export assets', tone: 'green' }]} />
</Scene>
```

### Flow

Connected horizontal or vertical stages.

Props:
- `align`: `FlexAlign` (optional; allowed values: `propEnums.FlexAlign`)
- `c`: `ThemeColors` (required)
- `connectorLength`: `number` (optional)
- `connectorTone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)
- `direction`: `"vertical" | "horizontal"` (optional; allowed values: `propEnums.values3`)
- `gap`: `number` (optional)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `stages`: `FlowStageSpec[]` (required)

```tsx
width = 960
height = 480

<Scene title="Flow example" subtitle="Edit this focused Flow scene" padding={22} gap={18}>
  <Flow
    gap={12}
    connectorLength={30}
    stages={[{ title: 'Request', subtitle: 'source data', tone: 'blue', width: 190 },
        { title: 'Transform', subtitle: 'build scene', tone: 'purple', width: 190 },
        { title: 'Deliver', subtitle: 'render files', tone: 'green', width: 190 }]} />
</Scene>
```

### Pipeline

Compact process pipeline with shared title.

Props:
- `c`: `ThemeColors` (required)
- `stages`: `PipelineStage[]` (required)
- `title`: `string` (optional)

```tsx
width = 960
height = 480

<Scene title="Pipeline example" subtitle="Edit this focused Pipeline scene" padding={22} gap={18}>
  <Pipeline
    title='Release pipeline'
    stages={[{ label: 'Build', sublabel: 'TSX', icon: '◇', color: 'secondary' },
        { label: 'Check', sublabel: 'themes', icon: '✓', color: 'info' },
        { label: 'Export', sublabel: 'PNG', icon: '↓', color: 'positive' }]} />
</Scene>
```

### ProgressRow

Labeled progress bar and value.

Props:
- `barHeight`: `number` (optional)
- `c`: `ThemeColors` (required)
- `fontSize`: `number` (optional)
- `label`: `React.ReactNode` (required)
- `labelWidth`: `number` (optional)
- `muted`: `boolean` (optional; allowed values: `propEnums.values2`)
- `tone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)
- `value`: `number` (required)
- `valueLabel`: `React.ReactNode` (optional)
- `valueWidth`: `number` (optional)

```tsx
width = 960
height = 480

<Scene title="ProgressRow example" subtitle="Edit this focused ProgressRow scene" padding={22} gap={18}>
  <Column
    width={620}
    gap={14}
    align='stretch'>
  <ProgressRow
    label='Layout'
    value={0.96}
    valueLabel='96%'
    tone='green' />
  <ProgressRow
    label='Contrast'
    value={0.82}
    valueLabel='82%'
    tone='purple' />
  </Column>
</Scene>
```

### ProgressList

Comparable progress across several measures.

Props:
- `barHeight`: `number` (optional)
- `c`: `ThemeColors` (required)
- `fontSize`: `number` (optional)
- `gap`: `number` (optional)
- `labelWidth`: `number` (optional)
- `rows`: `ProgressRowSpec[]` (required)
- `valueWidth`: `number` (optional)

```tsx
width = 960
height = 480

<Scene title="ProgressList example" subtitle="Edit this focused ProgressList scene" padding={22} gap={18}>
  <ProgressList
    labelWidth={100}
    rows={[{ label: 'Layout', value: 0.96, tone: 'green' },
        { label: 'Contrast', value: 0.82, tone: 'purple' },
        { label: 'Labels', value: 1, tone: 'blue' }]} />
</Scene>
```
## Diagrams



Networks, system architecture, directed graphs, and hierarchies.



### LayeredNetwork

Layered neural network or staged DAG.

Props:
- `activePath`: `number[]` (optional)
- `annotations`: `string[]` (optional)
- `ariaLabel`: `string` (optional)
- `c`: `ThemeColors` (required)
- `formula`: `string` (optional)
- `height`: `number` (optional)
- `layers`: `LayeredNetworkLayer[]` (required)
- `legend`: `string` (optional)
- `nodeSize`: `number` (optional)
- `showFormula`: `boolean` (optional; allowed values: `propEnums.values2`)
- `width`: `number` (optional)

```tsx
width = 960
height = 560

<Scene title="LayeredNetwork example" subtitle="Edit this focused LayeredNetwork scene" padding={22} gap={18}>
  <LayeredNetwork
    width={820}
    height={360}
    layers={[{ title: 'Input', nodes: ['x₁', 'x₂', 'x₃'], tone: 'blue' },
        { title: 'Hidden', nodes: ['h₁', 'h₂', 'h₃'], tone: 'purple' },
        { title: 'Output', nodes: ['y'], tone: 'green' }]}
    activePath={[1, 0, 0]}
    formula='y = f(Wx + b)' />
</Scene>
```

### GraphDiagram

Auto-laid architecture graph with nested groups, icons, and semantic edges.

Props:
- `ariaLabel`: `string` (optional)
- `arrowSize`: `number` (optional)
- `c`: `ThemeColors` (required)
- `description`: `string` (optional)
- `detailFontSize`: `number` (optional)
- `direction`: `"LR" | "RL" | "TB" | "BT"` (optional; allowed values: `propEnums.values9`)
- `edgeGap`: `number` (optional)
- `edges`: `GraphDiagramEdge[]` (required)
- `groups`: `GraphDiagramGroup[]` (optional)
- `height`: `number` (optional)
- `iconSize`: `number` (optional)
- `id`: `string` (optional)
- `labelFontSize`: `number` (optional)
- `layout`: `"auto" | "manual"` (optional; allowed values: `propEnums.values10`)
- `nodeGap`: `number` (optional)
- `nodeHeight`: `number` (optional)
- `nodes`: `GraphDiagramNode[]` (required)
- `nodeWidth`: `number` (optional)
- `padding`: `number` (optional)
- `rankGap`: `number` (optional)
- `routing`: `GraphRouting` (optional; allowed values: `propEnums.GraphRouting`): Dagre retains existing routes. Orthogonal routes avoid node boxes and group headers.
- `routingClearance`: `number` (optional): Minimum node clearance in logical pixels for orthogonal routing.
- `sizing`: `"content" | "fixed"` (optional; allowed values: `propEnums.values11`)
- `title`: `string` (optional)
- `width`: `number` (optional)

```tsx
width = 960
height = 480

<Scene title="GraphDiagram example" subtitle="Edit this focused GraphDiagram scene" padding={22} gap={18}>
  <GraphDiagram
    width={820}
    height={360}
    routing='dagre'
    routingClearance={12}
    nodes={[{ id: 'api', label: 'API', tone: 'blue' },
        { id: 'queue', label: 'Queue', tone: 'purple' },
        { id: 'worker', label: 'Worker', tone: 'green' }]}
    edges={[{ from: 'api', to: 'queue', label: 'enqueue' },
        { from: 'queue', to: 'worker', label: 'consume' }]} />
</Scene>
```

### TreeDiagram

Auto-laid hierarchy, taxonomy, or decision tree.

Props:
- `ariaLabel`: `string` (optional)
- `c`: `ThemeColors` (required)
- `height`: `number` (optional)
- `levelGap`: `number` (optional)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `nodeHeight`: `number` (optional)
- `nodeWidth`: `number` (optional)
- `padding`: `number` (optional)
- `root`: `TreeNodeSpec` (required)
- `siblingGap`: `number` (optional)
- `subtitle`: `React.ReactNode` (optional)
- `title`: `React.ReactNode` (optional)
- `width`: `number` (optional)

```tsx
width = 960
height = 480

<Scene title="TreeDiagram example" subtitle="Edit this focused TreeDiagram scene" padding={22} gap={18}>
  <TreeDiagram
    width={820}
    height={340}
    root={{ id: 'root', label: 'Product', tone: 'purple', children: [{ id: 'api', label: 'API', tone: 'blue' },
        { id: 'web', label: 'Web app', tone: 'green' }] }} />
</Scene>
```
## Sequence



Time-ordered interactions, lifelines, activations, notes, and control fragments.



### SequenceDiagram

Typed participants, messages, notes, activations, and alt, loop, or parallel fragments.

Props:
- `activations`: `SequenceActivation[]` (optional)
- `ariaLabel`: `string` (optional)
- `c`: `ThemeColors` (required)
- `fragmentIndent`: `number` (optional)
- `fragments`: `SequenceFragment[]` (optional)
- `height`: `number` (optional)
- `items`: `SequenceItem[]` (optional): Ordered event input. When present, it is the source of row order.
- `lifelineDash`: `string` (optional)
- `messages`: `SequenceMessage[]` (optional)
- `notes`: `SequenceNote[]` (optional)
- `noteWidth`: `number` (optional)
- `padding`: `number` (optional)
- `participantGap`: `number` (optional)
- `participants`: `SequenceParticipant[]` (required)
- `participantWidth`: `number` (optional)
- `rowHeight`: `number` (optional)
- `subtitle`: `React.ReactNode` (optional)
- `title`: `React.ReactNode` (optional)
- `width`: `number` (optional)

```tsx
width = 960
height = 560

<Scene title="SequenceDiagram example" subtitle="Edit this focused SequenceDiagram scene" padding={22} gap={18}>
  <SequenceDiagram
    width={820}
    height={360}
    participants={[{ id: 'client', label: 'Client', kind: 'actor' },
        { id: 'api', label: 'API', kind: 'boundary' },
        { id: 'db', label: 'Database', kind: 'database' }]}
    messages={[{ id: 'request', from: 'client', to: 'api', kind: 'sync', label: 'GET /items' },
        { id: 'query', from: 'api', to: 'db', kind: 'sync', label: 'SELECT items' },
        { id: 'response', from: 'api', to: 'client', kind: 'return', label: '200 OK' }]} />
</Scene>
```
## Dataflow



Typed lineage across sources, transforms, stores, and sinks.



### DataflowDiagram

Schema-aware batch and streaming lineage compiled into a stable directed graph.

Props:
- `ariaLabel`: `string` (optional)
- `arrowSize`: `number` (optional)
- `boundaries`: `DataflowBoundary[]` (optional)
- `c`: `ThemeColors` (required)
- `description`: `string` (optional)
- `detailFontSize`: `number` (optional)
- `direction`: `"LR" | "RL" | "TB" | "BT" | undefined` (optional; allowed values: `propEnums.values9`)
- `edgeGap`: `number` (optional)
- `edges`: `DataflowEdge[]` (required)
- `height`: `number` (optional)
- `iconSize`: `number` (optional)
- `id`: `string` (optional)
- `labelFontSize`: `number` (optional)
- `nodeGap`: `number` (optional)
- `nodeHeight`: `number` (optional)
- `nodes`: `DataflowNode[]` (required)
- `nodeWidth`: `number` (optional)
- `padding`: `number` (optional)
- `rankGap`: `number` (optional)
- `routing`: `GraphRouting | undefined` (optional; allowed values: `propEnums.GraphRouting`)
- `routingClearance`: `number | undefined` (optional)
- `sizing`: `"content" | "fixed" | undefined` (optional; allowed values: `propEnums.values11`)
- `title`: `string` (optional)
- `width`: `number` (optional)

```tsx
width = 1040
height = 560

<Scene title="DataflowDiagram example" subtitle="Edit this focused DataflowDiagram scene" padding={22} gap={18}>
  <DataflowDiagram
    width={820}
    height={390}
    routing='dagre'
    routingClearance={12}
    direction='LR'
    nodes={[{ id: 'source', label: 'Events', kind: 'source', tone: 'blue', schema: 'Event.v1' },
        { id: 'transform', label: 'Validate', kind: 'transform', tone: 'purple' },
        { id: 'sink', label: 'Warehouse', kind: 'store', tone: 'green' }]}
    edges={[{ from: 'source', to: 'transform', mode: 'stream', label: 'Event.v1' },
        { from: 'transform', to: 'sink', mode: 'batch', label: 'Valid.v1' }]} />
</Scene>
```
## Deployment



Infrastructure boundaries, workloads, ports, protocols, and trust direction.



### DeploymentDiagram

Nested region, network, and runtime boundaries with typed network connections.

Props:
- `ariaLabel`: `string` (optional)
- `arrowSize`: `number` (optional)
- `boundaries`: `DeploymentBoundary[]` (optional)
- `c`: `ThemeColors` (required)
- `connections`: `DeploymentConnection[]` (optional)
- `description`: `string` (optional)
- `detailFontSize`: `number` (optional)
- `direction`: `"LR" | "RL" | "TB" | "BT"` (optional; allowed values: `propEnums.values9`)
- `edgeGap`: `number` (optional)
- `height`: `number` (optional)
- `iconSize`: `number` (optional)
- `id`: `string` (optional)
- `labelFontSize`: `number` (optional)
- `layout`: `"auto" | "manual"` (optional; allowed values: `propEnums.values10`)
- `nodeGap`: `number` (optional)
- `nodeHeight`: `number` (optional)
- `nodes`: `DeploymentNode[]` (required)
- `nodeWidth`: `number` (optional)
- `padding`: `number` (optional)
- `rankGap`: `number` (optional)
- `routing`: `GraphRouting` (optional; allowed values: `propEnums.GraphRouting`): Dagre retains existing routes. Orthogonal routes avoid node boxes and group headers.
- `routingClearance`: `number` (optional): Minimum node clearance in logical pixels for orthogonal routing.
- `sizing`: `"content" | "fixed"` (optional; allowed values: `propEnums.values11`)
- `title`: `string` (optional)
- `width`: `number` (optional)

```tsx
width = 1040
height = 560

<Scene title="DeploymentDiagram example" subtitle="Edit this focused DeploymentDiagram scene" padding={22} gap={18}>
  <DeploymentDiagram
    width={820}
    height={390}
    routing='dagre'
    routingClearance={12}
    direction='LR'
    boundaries={[{ id: 'region', label: 'us-east-1', kind: 'region', tone: 'blue' },
        { id: 'private', label: 'private subnet', kind: 'subnet', parent: 'region', tone: 'purple' }]}
    nodes={[{ id: 'edge', label: 'Gateway', kind: 'gateway', tone: 'cyan' },
        { id: 'api', label: 'API', kind: 'service', boundary: 'private', tone: 'green' }]}
    connections={[{ id: 'https', from: 'edge', to: 'api', kind: 'cross-boundary', protocol: 'HTTPS', label: 'HTTPS/443' }]} />
</Scene>
```
## ML topology



Transformer blocks, tensor shapes, repeated layers, and distributed routes.



### TransformerTopology

Transformer computation topology with tensor metadata and collective routes.

Props:
- `ariaLabel`: `string` (optional)
- `arrowSize`: `number` (optional)
- `blocks`: `TransformerBlock[]` (required)
- `c`: `ThemeColors` (required)
- `description`: `string` (optional)
- `detailFontSize`: `number` (optional)
- `direction`: `"LR" | "RL" | "TB" | "BT"` (optional; allowed values: `propEnums.values9`)
- `edgeGap`: `number` (optional)
- `expandRepeats`: `boolean` (optional; allowed values: `propEnums.values2`): Expand repeat counts into individually addressable graph nodes.
- `height`: `number` (optional)
- `iconSize`: `number` (optional)
- `id`: `string` (optional)
- `labelFontSize`: `number` (optional)
- `layout`: `"auto" | "manual"` (optional; allowed values: `propEnums.values10`)
- `nodeGap`: `number` (optional)
- `nodeHeight`: `number` (optional)
- `nodeWidth`: `number` (optional)
- `padding`: `number` (optional)
- `rankGap`: `number` (optional)
- `routes`: `TransformerRoute[]` (optional)
- `routing`: `GraphRouting` (optional; allowed values: `propEnums.GraphRouting`): Dagre retains existing routes. Orthogonal routes avoid node boxes and group headers.
- `routingClearance`: `number` (optional): Minimum node clearance in logical pixels for orthogonal routing.
- `sizing`: `"content" | "fixed"` (optional; allowed values: `propEnums.values11`)
- `title`: `string` (optional)
- `width`: `number` (optional)

```tsx
width = 1040
height = 560

<Scene title="TransformerTopology example" subtitle="Edit this focused TransformerTopology scene" padding={22} gap={18}>
  <TransformerTopology
    width={820}
    height={390}
    routing='dagre'
    routingClearance={12}
    direction='LR'
    blocks={[{ id: 'embed', label: 'Embed', kind: 'embedding', outputShape: { dims: ['B', 'T', 'd'], dtype: 'bf16' } },
        { id: 'attn', label: 'Attention', kind: 'attention', shape: { dims: ['B', 'T', 'd'], dtype: 'bf16' } },
        { id: 'logits', label: 'Logits', kind: 'output', outputShape: { dims: ['B', 'T', 'V'], dtype: 'bf16' } }]}
    routes={[{ id: 'hidden', from: 'embed', to: 'attn', kind: 'activation', label: 'hidden state' },
        { id: 'scores', from: 'attn', to: 'logits', kind: 'activation', label: 'scores' }]} />
</Scene>
```
## Data



Tables, grids, matrices, and compact distributions.



### Matrix

Numeric or symbolic matrix with headers.

Props:
- `c`: `ThemeColors` (required)
- `cellHeight`: `number` (optional)
- `cellSize`: `number` (optional)
- `cellWidth`: `number` (optional)
- `colLabels`: `string[]` (optional)
- `colorize`: `boolean` (optional; allowed values: `propEnums.values2`)
- `colorScale`: `"heat" | "strength"` (optional; allowed values: `propEnums.values12`)
- `data`: `number[][]` (required)
- `format`: `"decimal" | "percent" | "integer"` (optional; allowed values: `propEnums.values13`)
- `labels`: `React.ReactNode[][]` (optional)
- `rowLabels`: `string[]` (optional)
- `rowLabelWidth`: `number` (optional)
- `title`: `string` (optional)

```tsx
width = 960
height = 480

<Scene title="Matrix example" subtitle="Edit this focused Matrix scene" padding={22} gap={18}>
  <Matrix
    title='Attention weights'
    rowLabels={['q₁', 'q₂', 'q₃']}
    colLabels={['k₁', 'k₂', 'k₃']}
    data={[[0.82, 0.14, 0.04],
        [0.18, 0.66, 0.16],
        [0.06, 0.21, 0.73]]}
    cellWidth={58}
    cellHeight={42}
    rowLabelWidth={34} />
</Scene>
```

### Heatmap

Color-scaled matrix for intensity and correlation.

Props:
- `c`: `ThemeColors` (required)
- `cellHeight`: `number` (optional)
- `cellSize`: `number` (optional)
- `cellWidth`: `number` (optional)
- `colorScale`: `"heat" | "strength"` (optional; allowed values: `propEnums.values12`)
- `data`: `number[][]` (required)
- `labels`: `React.ReactNode[][]` (optional)
- `rowLabelWidth`: `number` (optional)
- `title`: `string` (optional)
- `xLabels`: `string[]` (required)
- `yLabels`: `string[]` (required)

```tsx
width = 960
height = 480

<Scene title="Heatmap example" subtitle="Edit this focused Heatmap scene" padding={22} gap={18}>
  <Heatmap
    title='Similarity'
    xLabels={['api', 'docs', 'sdk']}
    yLabels={['setup', 'auth', 'tests']}
    data={[[0.92, 0.4, 0.2],
        [0.3, 0.86, 0.55],
        [0.18, 0.52, 0.95]]}
    cellWidth={62}
    cellHeight={42}
    rowLabelWidth={48}
    colorScale='strength' />
</Scene>
```

### TiledMatrix

Matrix with named regions and boundaries.

Props:
- `ariaLabel`: `string` (optional)
- `c`: `ThemeColors` (required)
- `cellSize`: `number` (optional)
- `cols`: `number` (required)
- `crossedOut`: `boolean` (optional; allowed values: `propEnums.values2`)
- `gap`: `number` (optional)
- `muted`: `boolean` (optional; allowed values: `propEnums.values2`)
- `regions`: `TiledMatrixRegion[]` (optional)
- `rows`: `number` (required)
- `subtitle`: `React.ReactNode` (optional)
- `title`: `React.ReactNode` (optional)
- `tone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)

```tsx
width = 960
height = 480

<Scene title="TiledMatrix example" subtitle="Edit this focused TiledMatrix scene" padding={22} gap={18}>
  <TiledMatrix
    title='Block sparse attention'
    subtitle='Named regions within one matrix'
    rows={8}
    cols={10}
    cellSize={25}
    gap={3}
    tone='cyan'
    regions={[{ rowStart: 0, rowEnd: 4, colStart: 0, colEnd: 4, tone: 'purple' },
        { rowStart: 4, rowEnd: 8, colStart: 4, colEnd: 10, tone: 'green' }]} />
</Scene>
```

### DataTable

Structured rows and columns with headers.

Props:
- `c`: `ThemeColors` (required)
- `cellHeight`: `number` (optional)
- `cellWidth`: `number` (optional)
- `firstColWidth`: `number` (optional)
- `fontSize`: `number` (optional)
- `gap`: `number` (optional)
- `headerCols`: `number` (optional)
- `headerRows`: `number` (optional)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `rows`: `React.ReactNode[][]` (required)

```tsx
width = 960
height = 480

<Scene title="DataTable example" subtitle="Edit this focused DataTable scene" padding={22} gap={18}>
  <DataTable
    cellWidth={94}
    firstColWidth={120}
    cellHeight={34}
    rows={[[ 'Service', 'p95', 'State' ],
        [ 'API', '82 ms', 'ready' ],
        [ 'Worker', '140 ms', 'ready' ]]} />
</Scene>
```

### Grid

General labeled cell grid.

Props:
- `c`: `ThemeColors` (required)
- `cellHeight`: `number` (optional)
- `cellWidth`: `number` (optional)
- `fontSize`: `number` (optional)
- `gap`: `number` (optional)
- `headerCols`: `number` (optional)
- `headerRows`: `number` (optional)
- `math`: `boolean` (optional; allowed values: `propEnums.values2`)
- `radius`: `number` (optional)
- `rows`: `(React.ReactNode | GridCell)[][]` (required)

```tsx
width = 960
height = 480

<Scene title="Grid example" subtitle="Edit this focused Grid scene" padding={22} gap={18}>
  <Grid
    cellWidth={72}
    cellHeight={42}
    headerRows={1}
    headerCols={1}
    rows={[[ 'Region', 'US', 'EU' ],
        [ 'API',
        { label: 'ready', tone: 'green' },
        { label: 'watch', tone: 'warm' } ],
        [ 'Queue',
        { label: 'ready', tone: 'green' },
        { label: 'ready', tone: 'green' }]]} />
</Scene>
```

### MiniBarChart

Compact categorical bars for dense layouts.

Props:
- `barWidth`: `number` (optional)
- `c`: `ThemeColors` (required)
- `data`: `MiniBarDatum[]` (required)
- `fontSize`: `number` (optional)
- `gap`: `number` (optional)
- `height`: `number` (optional)
- `max`: `number` (optional)
- `minBarHeight`: `number` (optional)
- `radius`: `number` (optional)
- `showValues`: `boolean` (optional; allowed values: `propEnums.values2`)

```tsx
width = 960
height = 480

<Scene title="MiniBarChart example" subtitle="Edit this focused MiniBarChart scene" padding={22} gap={18}>
  <MiniBarChart
    height={170}
    barWidth={48}
    gap={18} showValues
    data={[{ label: 'plan', value: 74, tone: 'blue' },
        { label: 'build', value: 92, tone: 'purple' },
        { label: 'check', value: 86, tone: 'cyan' },
        { label: 'ship', value: 98, tone: 'green' }]} />
</Scene>
```
## Charts



Common comparisons, trends, distributions, and analytical plots.



### ChartFrame

Shared chart title, subtitle, legend, and footer.

Props:
- `c`: `ThemeColors` (required)
- `children`: `React.ReactNode` (required)
- `footer`: `string` (optional)
- `height`: `string | number` (optional)
- `legend`: `ChartLegendItem[]` (optional)
- `padding`: `number` (optional)
- `subtitle`: `string` (optional)
- `title`: `string` (optional)
- `width`: `string | number` (optional)

```tsx
width = 960
height = 480

<Scene title="ChartFrame example" subtitle="Edit this focused ChartFrame scene" padding={22} gap={18}>
  <ChartFrame
    title='Weekly quality'
    subtitle='A reusable title, legend, and footer'
    width={680}
    footer='Source: evaluation runs'>
  <BarChart
    width={620}
    height={220}
    data={[{ label: 'Mon', value: 0.72, color: 'secondary' },
        { label: 'Wed', value: 0.84, color: 'primary' },
        { label: 'Fri', value: 0.96, color: 'positive' }]}
    format='percent' />
  </ChartFrame>
</Scene>
```

### DonutChart

Part-to-whole composition with center label.

Props:
- `c`: `ThemeColors` (required)
- `centerLabel`: `React.ReactNode` (optional)
- `centerValue`: `React.ReactNode` (optional)
- `footer`: `string` (optional)
- `format`: `ChartValueFormat` (optional; literal presets: `propEnums.ChartValueFormat` (other non-literal variants remain TSX-only))
- `height`: `number` (optional)
- `segments`: `DonutChartSegment[]` (required)
- `showLegend`: `boolean` (optional; allowed values: `propEnums.values2`)
- `size`: `number` (optional)
- `subtitle`: `string` (optional)
- `thickness`: `number` (optional)
- `title`: `string` (optional)
- `width`: `number` (optional)

```tsx
width = 960
height = 520

<Scene title="Aster Studio · first-session activation" subtitle="SAMPLE DATA · 2,400 new workspaces" padding={22} gap={18}>
  <DonutChart
    title='72% created a project before leaving'
    subtitle='What 2,400 new teams did in their first 10 minutes'
    width={840}
    height={300}
    size={244}
    thickness={38}
    format='integer'
    centerValue='72%'
    centerLabel='activated'
    segments={[{ label: 'Created a project', value: 1728, color: 'positive' },
        { label: 'Explored templates', value: 432, color: 'primary' },
        { label: 'Left before setup', value: 240, color: 'critical' }]} />
</Scene>
```

### PieChart

Part-to-whole composition with a full circular radius.

Props:
- `c`: `ThemeColors` (required)
- `footer`: `string` (optional)
- `format`: `ChartValueFormat` (optional; literal presets: `propEnums.ChartValueFormat` (other non-literal variants remain TSX-only))
- `height`: `number` (optional)
- `segments`: `DonutChartSegment[]` (required)
- `showLegend`: `boolean` (optional; allowed values: `propEnums.values2`)
- `size`: `number` (optional)
- `subtitle`: `string` (optional)
- `title`: `string` (optional)
- `width`: `number` (optional)

```tsx
width = 960
height = 570

<Scene title="Aster Studio · launch-day acquisition" subtitle="SAMPLE DATA · 42,600 first-touch visits" padding={22} gap={18}>
  <PieChart
    title='Community made the biggest first impression'
    subtitle='42,600 first-touch visits on launch day'
    width={840}
    height={320}
    size={250}
    format='integer'
    segments={[{ label: 'Community', value: 18700, color: 'positive' },
        { label: 'Search', value: 12400, color: 'primary' },
        { label: 'Social', value: 7900, color: 'secondary' },
        { label: 'Partners', value: 3600, color: 'warning' }]}
    footer='Sample launch data · first touch only' />
</Scene>
```

### StackedBar

Part-to-whole values along one dimension.

Props:
- `c`: `ThemeColors` (required)
- `height`: `number` (optional)
- `segments`: `StackedBarSegment[]` (required)
- `showLegend`: `boolean` (optional; allowed values: `propEnums.values2`)
- `subtitle`: `string` (optional)
- `title`: `string` (optional)
- `width`: `number` (optional)

```tsx
width = 960
height = 340

<Scene title="Aster Studio · device mix" subtitle="SAMPLE DATA · 48,000 launch sessions" padding={22} gap={18}>
  <StackedBar
    title='Mobile already brings 38% of launch traffic'
    subtitle='Share of 48,000 sessions by device'
    width={840}
    height={76}
    segments={[{ label: 'Desktop', value: 54, valueLabel: '54%', color: 'primary' },
        { label: 'Mobile', value: 38, valueLabel: '38%', color: 'positive' },
        { label: 'Tablet', value: 8, valueLabel: '8%', color: 'warning' }]} />
</Scene>
```

### BarChart

Categorical comparison with labels and values.

Props:
- `c`: `ThemeColors` (required)
- `data`: `BarChartDatum[]` (required)
- `footer`: `string` (optional)
- `format`: `ChartValueFormat` (optional; literal presets: `propEnums.ChartValueFormat` (other non-literal variants remain TSX-only))
- `height`: `number` (optional)
- `max`: `number` (optional)
- `min`: `number` (optional)
- `showGrid`: `boolean` (optional; allowed values: `propEnums.values2`)
- `showValues`: `boolean` (optional; allowed values: `propEnums.values2`)
- `subtitle`: `string` (optional)
- `title`: `string` (optional)
- `width`: `number` (optional)
- `yAxisLabel`: `string` (optional)

```tsx
width = 960
height = 600

<Scene title="Aster Studio · signups in week one" subtitle="SAMPLE DATA · daily new workspaces" padding={22} gap={18}>
  <BarChart
    title='Friday set a new signup record'
    subtitle='Daily new workspaces · target was 250'
    width={840}
    height={360}
    min={0}
    max={380}
    format='integer'
    yAxisLabel='new workspaces'
    footer='Sample launch week · 1,626 workspaces total'
    data={[{ label: 'Mon', value: 186, color: 'primary' },
        { label: 'Tue', value: 204, color: 'primary' },
        { label: 'Wed', value: 231, color: 'secondary' },
        { label: 'Thu', value: 278, color: 'positive' },
        { label: 'Fri', value: 356, color: 'positive' },
        { label: 'Sat', value: 242, color: 'secondary' },
        { label: 'Sun', value: 129, color: 'neutral' }]} />
</Scene>
```

### LineChart

One or more trends across an ordered axis.

Props:
- `c`: `ThemeColors` (required)
- `footer`: `string` (optional)
- `format`: `ChartValueFormat` (optional; literal presets: `propEnums.ChartValueFormat` (other non-literal variants remain TSX-only))
- `height`: `number` (optional)
- `labels`: `string[]` (optional)
- `max`: `number` (optional)
- `min`: `number` (optional)
- `series`: `LineChartSeries[]` (required)
- `showGrid`: `boolean` (optional; allowed values: `propEnums.values2`)
- `showPoints`: `boolean` (optional; allowed values: `propEnums.values2`)
- `subtitle`: `string` (optional)
- `title`: `string` (optional)
- `width`: `number` (optional)
- `yAxisLabel`: `string` (optional)

```tsx
width = 960
height = 600

<Scene title="Aster Studio · guided setup experiment" subtitle="SAMPLE DATA · activation over seven days" padding={22} gap={18}>
  <LineChart
    title='The checklist added 19 points of activation'
    subtitle='Share of new workspaces with a first project · week after launch'
    width={840}
    height={360}
    labels={['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']}
    min={0}
    max={1}
    yAxisLabel='activated'
    format='percent'
    footer='Sample experiment · guided setup vs. original flow'
    series={[{ name: 'Original flow', points: [0.36, 0.39, 0.42, 0.45, 0.47, 0.5, 0.51], color: 'neutral' },
        { name: 'Guided checklist', points: [0.35, 0.4, 0.48, 0.55, 0.61, 0.68, 0.7], color: 'positive', area: true }]} />
</Scene>
```

### ScatterPlot

Point distribution across two numeric axes.

Props:
- `c`: `ThemeColors` (required)
- `footer`: `string` (optional)
- `formatX`: `ChartValueFormat` (optional; literal presets: `propEnums.ChartValueFormat` (other non-literal variants remain TSX-only))
- `formatY`: `ChartValueFormat` (optional; literal presets: `propEnums.ChartValueFormat` (other non-literal variants remain TSX-only))
- `height`: `number` (optional)
- `points`: `ScatterPoint[]` (required)
- `showGrid`: `boolean` (optional; allowed values: `propEnums.values2`)
- `subtitle`: `string` (optional)
- `title`: `string` (optional)
- `width`: `number` (optional)
- `xAxisLabel`: `string` (optional)
- `xMax`: `number` (optional)
- `xMin`: `number` (optional)
- `yAxisLabel`: `string` (optional)
- `yMax`: `number` (optional)
- `yMin`: `number` (optional)

```tsx
width = 960
height = 620

<Scene title="Aster Studio · onboarding flows" subtitle="SAMPLE DATA · time to first project and activation" padding={22} gap={18}>
  <ScatterPlot
    title='Shorter paths reach activation more often'
    subtitle='Six onboarding flows · time to first project vs. completion rate'
    width={840}
    height={380}
    xMin={0}
    xMax={9}
    yMin={0}
    yMax={1}
    xAxisLabel='minutes to first project'
    yAxisLabel='activated workspaces'
    formatX='integer'
    formatY='percent'
    footer='Sample cohort · one point per guided path'
    points={[{ x: 1.1, y: 0.86, label: 'One-click', color: 'positive', size: 10 },
        { x: 2.3, y: 0.79, label: 'Template', color: 'primary' },
        { x: 3.6, y: 0.73, label: 'Guided', color: 'secondary' },
        { x: 4.7, y: 0.65, label: 'Team invite', color: 'info' },
        { x: 5.8, y: 0.55, label: 'Import', color: 'warning' },
        { x: 7.6, y: 0.39, label: 'Blank start', color: 'neutral' }]} />
</Scene>
```

### ParetoBarChart

Descending category counts with a cumulative percentage line.

Props:
- `c`: `ThemeColors` (required)
- `data`: `BarChartDatum[]` (required)
- `footer`: `string` (optional)
- `format`: `ChartValueFormat` (optional; literal presets: `propEnums.ChartValueFormat` (other non-literal variants remain TSX-only))
- `height`: `number` (optional)
- `showGrid`: `boolean` (optional; allowed values: `propEnums.values2`)
- `showValues`: `boolean` (optional; allowed values: `propEnums.values2`)
- `subtitle`: `string` (optional)
- `title`: `string` (optional)
- `width`: `number` (optional)

```tsx
width = 960
height = 610

<Scene title="Aster Studio · onboarding support" subtitle="SAMPLE DATA · 240 first-week tickets" padding={22} gap={18}>
  <ParetoBarChart
    title='Three fixes could remove 84% of support tickets'
    subtitle='First-week onboarding issues · 240 tickets, sorted by count'
    width={840}
    height={370}
    format='integer'
    footer='The line tracks cumulative share of all tickets.'
    data={[{ label: 'Setup', value: 91, color: 'critical' },
        { label: 'Invites', value: 65, color: 'warning' },
        { label: 'Import', value: 46, color: 'secondary' },
        { label: 'Billing', value: 24, color: 'primary' },
        { label: 'Other', value: 14, color: 'neutral' }]} />
</Scene>
```

### ParetoChart

Automatic non-dominated frontier across competing numeric objectives.

Props:
- `c`: `ThemeColors` (required)
- `footer`: `string` (optional)
- `formatX`: `ChartValueFormat` (optional; literal presets: `propEnums.ChartValueFormat` (other non-literal variants remain TSX-only))
- `formatY`: `ChartValueFormat` (optional; literal presets: `propEnums.ChartValueFormat` (other non-literal variants remain TSX-only))
- `frontierColor`: `string` (optional)
- `goalLabel`: `string` (optional)
- `height`: `number` (optional)
- `points`: `ScatterPoint[]` (required)
- `showGoal`: `boolean` (optional; allowed values: `propEnums.values2`)
- `showGrid`: `boolean` (optional; allowed values: `propEnums.values2`)
- `subtitle`: `string` (optional)
- `title`: `string` (optional)
- `width`: `number` (optional)
- `xAxisLabel`: `string` (optional)
- `xMax`: `number` (optional)
- `xMin`: `number` (optional)
- `xObjective`: `ParetoObjective` (optional; allowed values: `propEnums.ParetoObjective`)
- `xScale`: `ParetoXScale` (optional; allowed values: `propEnums.ParetoXScale`)
- `yAxisLabel`: `string` (optional)
- `yMax`: `number` (optional)
- `yMin`: `number` (optional)
- `yObjective`: `ParetoObjective` (optional; allowed values: `propEnums.ParetoObjective`)

```tsx
width = 960
height = 620

<Scene title="Aster Studio · renderer trade-offs" subtitle="SYNTHETIC BENCHMARK · render time and image score" padding={22} gap={18}>
  <ParetoChart
    title='Studio is the quickest preset above 90 quality'
    subtitle='Sample render benchmark · image score vs. seconds per frame'
    width={840}
    height={380}
    xMin={0}
    xMax={9}
    yMin={65}
    yMax={105}
    xAxisLabel='render time · seconds'
    yAxisLabel='image score · / 100'
    formatX='decimal'
    formatY='integer'
    xObjective='minimize'
    yObjective='maximize'
    footer='Synthetic benchmark · aim for the upper-left frontier.'
    points={[{ x: 0.6, y: 71, label: 'Swift', color: 'info' },
        { x: 1.3, y: 82, label: 'Balanced', color: 'primary' },
        { x: 2.2, y: 91, label: 'Studio', color: 'positive', size: 10 },
        { x: 4.7, y: 96, label: 'Cinema', color: 'secondary' },
        { x: 7.6, y: 98, label: 'Ultra', color: 'primary' },
        { x: 3.4, y: 79, label: 'Legacy', color: 'neutral' },
        { x: 3.8, y: 88, label: 'Oversharp', color: 'warning' }]}
    frontierColor='positive'
    goalLabel='less time · higher score' />
</Scene>
```

### QuadrantChart

Numeric decision map split by configurable policy thresholds.

Props:
- `c`: `ThemeColors` (required)
- `footer`: `string` (optional)
- `formatX`: `ChartValueFormat` (optional; literal presets: `propEnums.ChartValueFormat` (other non-literal variants remain TSX-only))
- `formatY`: `ChartValueFormat` (optional; literal presets: `propEnums.ChartValueFormat` (other non-literal variants remain TSX-only))
- `height`: `number` (optional)
- `points`: `ScatterPoint[]` (required)
- `regions`: `{ topLeft: QuadrantRegion; topRight: QuadrantRegion; bottomLeft: QuadrantRegion; bottomRight: QuadrantRegion; }` (required)
- `showGrid`: `boolean` (optional; allowed values: `propEnums.values2`)
- `showTicks`: `boolean` (optional; allowed values: `propEnums.values2`)
- `subtitle`: `string` (optional)
- `title`: `string` (optional)
- `width`: `number` (optional)
- `xAxisLabel`: `string` (optional)
- `xMax`: `number` (optional)
- `xMin`: `number` (optional)
- `xThreshold`: `number` (optional)
- `yAxisLabel`: `string` (optional)
- `yMax`: `number` (optional)
- `yMin`: `number` (optional)
- `yThreshold`: `number` (optional)

```tsx
width = 960
height = 620

<Scene title="Aster Studio · next sprint" subtitle="SAMPLE ROADMAP · effort and retention impact" padding={22} gap={18}>
  <QuadrantChart
    title='Templates are a quick win; team spaces are the big bet'
    subtitle='Effort vs. estimated lift in week-four retention'
    width={840}
    height={380}
    xMin={0}
    xMax={1}
    yMin={0}
    yMax={1}
    xAxisLabel='engineering effort'
    yAxisLabel='retention lift'
    formatX='percent'
    formatY='percent' showTicks showGrid
    footer='Sample roadmap discussion · thresholds split the four regions.'
    regions={{ topLeft: { label: 'Quick wins', detail: 'High impact, lower effort', color: 'positive', emphasis: true }, topRight: { label: 'Big bets', detail: 'Worth a larger investment', color: 'primary' }, bottomLeft: { label: 'Polish later', detail: 'Small lift, easy work', color: 'neutral' }, bottomRight: { label: 'Too costly', detail: 'Revisit with new evidence', color: 'warning' } }}
    points={[{ x: 0.2, y: 0.79, label: 'Templates', color: 'positive', size: 10 },
        { x: 0.78, y: 0.82, label: 'Team spaces', color: 'primary', size: 10 },
        { x: 0.81, y: 0.24, label: 'Billing portal', color: 'warning' },
        { x: 0.22, y: 0.22, label: 'Icon polish', color: 'neutral' },
        { x: 0.44, y: 0.67, label: 'Guided tour', color: 'secondary' }]} />
</Scene>
```

### IntervalPlot

Low, midpoint, and high ranges by category.

Props:
- `axisLabel`: `string` (optional)
- `c`: `ThemeColors` (required)
- `data`: `IntervalDatum[]` (required)
- `footer`: `string` (optional)
- `format`: `ChartValueFormat` (optional; literal presets: `propEnums.ChartValueFormat` (other non-literal variants remain TSX-only))
- `height`: `number` (optional)
- `max`: `number` (optional)
- `min`: `number` (optional)
- `subtitle`: `string` (optional)
- `title`: `string` (optional)
- `width`: `number` (optional)

```tsx
width = 960
height = 600

<Scene title="Aster Studio · export timing" subtitle="DEMO TIMINGS · 100 sample renders" padding={22} gap={18}>
  <IntervalPlot
    title='SVG stays quick; animation takes the longest'
    subtitle='Median and observed range across 100 sample renders'
    width={840}
    height={360}
    min={0}
    max={1000}
    axisLabel='render time · milliseconds'
    format='integer'
    footer='Same 1,200 × 630 source frame · demo timings'
    data={[{ label: 'SVG', low: 120, mid: 180, high: 260, color: 'positive' },
        { label: 'PNG', low: 220, mid: 360, high: 510, color: 'primary' },
        { label: 'GIF', low: 420, mid: 650, high: 940, color: 'warning' }]} />
</Scene>
```

### Legend

Reusable color key for charts and diagrams.

Props:
- `c`: `ThemeColors` (required)
- `items`: `LegendItem[]` (required)
- `title`: `string` (optional)

```tsx
width = 960
height = 480

<Scene title="Legend example" subtitle="Edit this focused Legend scene" padding={22} gap={18}>
  <Legend
    title='Result types'
    items={[{ label: 'Success', color: 'positive' },
        { label: 'Queued', color: 'warning' },
        { label: 'Blocked', color: c.critical, style: 'dashed' }]} />
</Scene>
```
## Drawing



Low-level SVG geometry for custom technical figures.



### Box

Rounded SVG box with label and tone.

Props:
- `c`: `ThemeColors` (required)
- `color`: `ColorName` (optional; allowed values: `propEnums.ColorName`)
- `fontSize`: `number` (optional)
- `gradient`: `boolean` (optional; allowed values: `propEnums.values2`): Use gradient background instead of solid
- `height`: `number` (optional)
- `icon`: `string` (optional): Optional icon/emoji before label
- `label`: `string` (required)
- `outlined`: `boolean` (optional; allowed values: `propEnums.values2`): Outlined style instead of filled
- `radius`: `number` (optional): Border radius
- `sublabel`: `string` (optional): Optional sub-label below main label
- `width`: `number` (optional)

```tsx
width = 960
height = 480

<Scene title="Box example" subtitle="Edit this focused Box scene" padding={22} gap={18}>
  <Row
    gap={14}
    align='center'>
  <Box
    label='Input'
    sublabel='request'
    color='primary' gradient
    width={180}
    height={100} />
  <Arrow
    direction='right'
    length={50} />
  <Box
    label='Output'
    sublabel='result'
    color='positive'
    width={180}
    height={100} />
  </Row>
</Scene>
```

### Arrow

Straight labeled SVG arrow.

Props:
- `c`: `ThemeColors` (required)
- `color`: `string` (optional)
- `direction`: `"left" | "right" | "down" | "up"` (optional; allowed values: `propEnums.values14`)
- `label`: `string` (optional)
- `length`: `number` (optional)

```tsx
width = 960
height = 480

<Scene title="Arrow example" subtitle="Edit this focused Arrow scene" padding={22} gap={18}>
  <Arrow
    direction='right'
    label='request'
    length={220}
    color={c.infoLight} />
</Scene>
```

### ArrowMarkerDef

Reusable SVG arrowhead definition.

Props:
- `color`: `string` (required)
- `id`: `string` (required)
- `size`: `number` (optional)

```tsx
width = 960
height = 480

<Scene title="ArrowMarkerDef example" subtitle="Edit this focused ArrowMarkerDef scene" padding={22} gap={18}>
  <Column
    gap={8}
    align='center'>
  <svg
    width='460'
    height='170'
    viewBox='0 0 460 170'>
  <defs>
  <ArrowMarkerDef
    id='catalog-arrow'
    color={c.infoLight}
    size={8} />
  </defs>
  <path
    d='M 42 85 C 140 8 280 162 410 85'
    fill='none'
    stroke={c.infoLight}
    strokeWidth={4}
    markerEnd='url(#catalog-arrow)' />
  </svg>
  <TextLabel
    text='Reusable SVG arrow marker'
    fontSize={14} />
  </Column>
</Scene>
```

### FlowArrow

Straight directional connector with label and tone.

Props:
- `c`: `ThemeColors` (required)
- `color`: `string` (optional)
- `direction`: `"left" | "right" | "down" | "up"` (optional; allowed values: `propEnums.values14`)
- `label`: `string` (optional)
- `length`: `number` (optional)
- `tone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)

```tsx
width = 960
height = 480

<Scene title="FlowArrow example" subtitle="Edit this focused FlowArrow scene" padding={22} gap={18}>
  <FlowArrow
    direction='right'
    label='verified result'
    length={240}
    tone='green' />
</Scene>
```

### Connector

Alias for flow connectors in diagram code.

Props:
- `c`: `ThemeColors` (required)
- `color`: `string` (optional)
- `direction`: `"left" | "right" | "down" | "up"` (optional; allowed values: `propEnums.values14`)
- `label`: `string` (optional)
- `length`: `number` (optional)
- `tone`: `ToneName` (optional; allowed values: `propEnums.ToneName`)

```tsx
width = 960
height = 480

<Scene title="Connector example" subtitle="Edit this focused Connector scene" padding={22} gap={18}>
  <Connector
    direction='right'
    label='dependency'
    length={240}
    tone='purple' />
</Scene>
```

### VectorArrow

Vector with optional endpoints and arrowhead.

Props:
- `arrowSize`: `number` (optional)
- `color`: `string` (required)
- `key`: `React.Key` (optional)
- `opacity`: `number` (optional)
- `strokeWidth`: `number` (optional)
- `x1`: `number` (required)
- `x2`: `number` (required)
- `y1`: `number` (required)
- `y2`: `number` (required)

```tsx
width = 960
height = 480

<Scene title="VectorArrow example" subtitle="Edit this focused VectorArrow scene" padding={22} gap={18}>
  <Column
    gap={8}
    align='center'>
  <svg
    width='460'
    height='180'
    viewBox='0 0 460 180'>
  <VectorArrow
    x1={64}
    y1={140}
    x2={390}
    y2={38}
    color={c.positiveLight}
    strokeWidth={5} />
  <SvgPoint
    cx={64}
    cy={140}
    r={8}
    fill={c.positiveLight} />
  </svg>
  <TextLabel
    text='Vector with arrowhead'
    fontSize={15} />
  </Column>
</Scene>
```

### VectorSegment

Line segment for geometric constructions.

Props:
- `color`: `string` (required)
- `dotRadius`: `number` (optional)
- `key`: `React.Key` (optional)
- `opacity`: `number` (optional)
- `showEndDot`: `boolean` (optional; allowed values: `propEnums.values2`)
- `showStartDot`: `boolean` (optional; allowed values: `propEnums.values2`)
- `strokeWidth`: `number` (optional)
- `x1`: `number` (required)
- `x2`: `number` (required)
- `y1`: `number` (required)
- `y2`: `number` (required)

```tsx
width = 960
height = 480

<Scene title="VectorSegment example" subtitle="Edit this focused VectorSegment scene" padding={22} gap={18}>
  <Column
    gap={8}
    align='center'>
  <svg
    width='460'
    height='180'
    viewBox='0 0 460 180'>
  <VectorSegment
    x1={64}
    y1={130}
    x2={396}
    y2={54}
    color={c.secondaryLight}
    strokeWidth={5} showStartDot showEndDot />
  </svg>
  <TextLabel
    text='Segment with endpoint dots'
    fontSize={15} />
  </Column>
</Scene>
```

### SvgFrame

SVG plotting frame with border and fill.

Props:
- `c`: `ThemeColors` (required)
- `fill`: `string` (optional)
- `height`: `number` (required)
- `key`: `React.Key` (optional)
- `opacity`: `number` (optional)
- `rx`: `number` (optional)
- `stroke`: `string` (optional)
- `strokeWidth`: `number` (optional)
- `width`: `number` (required)
- `x`: `number` (optional)
- `y`: `number` (optional)

```tsx
width = 960
height = 480

<Scene title="SvgFrame example" subtitle="Edit this focused SvgFrame scene" padding={22} gap={18}>
  <Column
    gap={8}
    align='center'>
  <svg
    width='460'
    height='180'
    viewBox='0 0 460 180'>
  <SvgFrame
    x={18}
    y={18}
    width={424}
    height={144}
    rx={18}
    fill={c.bgCard}
    stroke={c.borderLight}
    strokeWidth={2} />
  </svg>
  <TextLabel
    text='Theme aware plot frame'
    fontSize={15} />
  </Column>
</Scene>
```

### SvgPoint

Labeled point for SVG figures.

Props:
- `cx`: `number` (required)
- `cy`: `number` (required)
- `fill`: `string` (required)
- `key`: `React.Key` (optional)
- `opacity`: `number` (optional)
- `r`: `number` (optional)
- `stroke`: `string` (optional)
- `strokeWidth`: `number` (optional)

```tsx
width = 960
height = 480

<Scene title="SvgPoint example" subtitle="Edit this focused SvgPoint scene" padding={22} gap={18}>
  <Column
    gap={8}
    align='center'>
  <svg
    width='460'
    height='180'
    viewBox='0 0 460 180'>
  <SvgFrame
    width={460}
    height={180}
    c={c} />
  <SvgPoint
    cx={230}
    cy={90}
    r={26}
    fill={c.positiveLight}
    stroke={c.bg}
    strokeWidth={5} />
  </svg>
  <TextLabel
    text='SVG point with outline'
    fontSize={15} />
  </Column>
</Scene>
```

### DotPoint

Point marker with optional text label.

Props:
- `c`: `ThemeColors` (required)
- `color`: `string` (required)
- `label`: `string` (required)
- `labelOffset`: `{ x?: number; y?: number; }` (optional)
- `size`: `number` (optional)
- `x`: `number` (required)
- `y`: `number` (required)

```tsx
width = 960
height = 480

<Scene title="DotPoint example" subtitle="Edit this focused DotPoint scene" padding={22} gap={18}>
  <div
    style={{ position: 'relative', display: 'flex', width: 460, height: 220 }}>{DotPoint({ x: 230, y: 100, label: 'deploy', color: c.infoLight, size: 14 })}<TextLabel
    text='Labeled coordinate point'
    fontSize={15} />
  </div>
</Scene>
```

### DashedLine

Dotted or dashed SVG guide line.

Props:
- `color`: `string` (required)
- `dotSize`: `number` (optional)
- `dotSpacing`: `number` (optional)
- `x1`: `number` (required)
- `x2`: `number` (required)
- `y1`: `number` (required)
- `y2`: `number` (required)

```tsx
width = 960
height = 480

<Scene title="DashedLine example" subtitle="Edit this focused DashedLine scene" padding={22} gap={18}>
  <div
    style={{ position: 'relative', display: 'flex', width: 460, height: 220 }}>{DashedLine({ x1: 36, y1: 110, x2: 424, y2: 110, color: c.warningLight, dotSpacing: 12, dotSize: 3 })}<TextLabel
    text='Threshold'
    fontSize={15} />
  </div>
</Scene>
```

### AxisPlot

Coordinate plane for points, vectors, and paths.

Props:
- `axisColor`: `string` (optional)
- `c`: `ThemeColors` (required)
- `children`: `React.ReactNode` (optional)
- `frameFill`: `string` (optional)
- `frameRx`: `number` (optional)
- `frameStroke`: `string` (optional)
- `gridCount`: `number` (optional)
- `height`: `number` (required)
- `padding`: `number` (optional)
- `paths`: `AxisPlotPath[]` (optional)
- `points`: `AxisPlotPoint[]` (optional)
- `showAxes`: `boolean` (optional; allowed values: `propEnums.values2`)
- `showFrame`: `boolean` (optional; allowed values: `propEnums.values2`)
- `showGrid`: `boolean` (optional; allowed values: `propEnums.values2`)
- `vectors`: `AxisPlotVector[]` (optional)
- `width`: `number` (required)
- `xAxisLabel`: `string` (optional)
- `xMax`: `number` (optional)
- `xMin`: `number` (optional)
- `yAxisLabel`: `string` (optional)
- `yMax`: `number` (optional)
- `yMin`: `number` (optional)

```tsx
width = 960
height = 560

<Scene title="AxisPlot example" subtitle="Edit this focused AxisPlot scene" padding={22} gap={18}>
  <AxisPlot
    width={700}
    height={380}
    xMin={-1}
    xMax={1}
    yMin={-1}
    yMax={1} showGrid
    xAxisLabel='x'
    yAxisLabel='y'
    points={[{ x: -0.5, y: 0.3, r: 6, tone: 'blue' },
        { x: 0.6, y: 0.7, r: 7, tone: 'green' }]}
    vectors={[{ x1: 0, y1: 0, x2: 0.45, y2: 0.55, tone: 'purple', arrow: true }]} />
</Scene>
```
## Shared prop value sets

Finite allowed values referenced by component props:

- `propEnums.values1`: ["center","flex-start","space-between","space-around"]
- `propEnums.FlexAlign`: ["center","start","end","stretch"]
- `propEnums.FlexJustify`: ["center","space-between","space-around","start","end"]
- `propEnums.values2`: [false,true]
- `propEnums.values3`: ["vertical","horizontal"]
- `propEnums.ToneName`: ["critical","neutral","blue","purple","green","warm","cyan","pink","red","sunset","ocean","dark"]
- `propEnums.values4`: ["window","browser","terminal"]
- `propEnums.IconName`: ["warning","browser","terminal","agent","bucket","cache","chart","check","cluster","code","cloud","container","database","file","firewall","gateway","git","globe","image","layers","lock","load-balancer","mobile","monitor","network","play","queue","server","spark","storage","stream","tool","user"]
- `propEnums.values5`: ["center","left","right"]
- `propEnums.values6`: ["code","title","subtitle","label","body","small","tiny","annotation"]
- `propEnums.values7`: ["start","end","middle"]
- `propEnums.ColorName`: ["primary","secondary","positive","warning","critical","info","accent","neutral"]
- `propEnums.values8`: ["center","left"]
- `propEnums.WatermarkPosition`: ["top-left","top-right","bottom-left","bottom-right"]
- `propEnums.StatusKind`: ["info","check","cross","warn","pending","dot"]
- `propEnums.values9`: ["LR","RL","TB","BT"]
- `propEnums.values10`: ["auto","manual"]
- `propEnums.GraphRouting`: ["dagre","straight","orthogonal"]
- `propEnums.values11`: ["content","fixed"]
- `propEnums.values12`: ["heat","strength"]
- `propEnums.values13`: ["decimal","percent","integer"]
- `propEnums.ChartValueFormat`: ["decimal","percent","integer","compact"]
- `propEnums.ParetoObjective`: ["minimize","maximize"]
- `propEnums.ParetoXScale`: ["linear","log"]
- `propEnums.values14`: ["left","right","down","up"]