Chart model
One chart model shared by images, Figma, embeds, the editor, SDK, and MCP.
The chart model describes what a chart means without tying it to one output. Semantic config, row data, presentation, sizing, and output policy stay separate so each part can be changed without rewriting the others.
Two public shapes
ChartConfigcontains one chart type and its semantic field roles. It is data-free and includes its chart version.ChartDocumentpairs config with data, a matching outer version, and optional presentation, size, and output policy. Use it unchanged for validation, rendering, and saving, as well as Studio and Figma.
For new charts, use 2026-09-26. If you have a 2026-03-20 config, see older config compatibility for the supported chart mappings and conversion results.
Build a chart
Config and document
Reusable semantics and one complete input for every chart action.
Chart types
Choose among six purpose-driven chart families.
Annotations
Attach explanatory notes to data and chart positions.
Reference lines
Add fixed targets and calculated statistics.
Data and roles
Bind flat rows through chart-specific semantic roles.
Validation
Read structural, semantic, and compatibility diagnostics.
Scales and axes
Control domains, formats, axes, and scale intent.
Color
Use categorical, sequential, and diverging color roles.
Themes
Apply one of six curated visual systems.
Sizing and output
Choose automatic, canvas, or plot sizing.
Chart-specific fields
Each chart type offers the fields that make sense for it: required data roles, axes, labels, reference lines, annotations, color behavior, and chart-specific style options.
Annotation text
Notes follow their chart's typography and stay attached to a datum, category, slice, or coordinate. Annotations explains attachment, placement, connectors, width, space reservation, appearance, and visual editing.
Reference lines
Reference lines covers fixed targets, calculated statistics, domains, labels, layers, and filtering.
Annotations and references remain part of the shared chart definition, letting Szum reject ambiguous combinations early and keep SVG, PNG, embeds, Studio, MCP previews, and Figma in agreement.
Defaults stay effective, not authored
Omitting an optional value is meaningful. Szum and the selected theme apply effective defaults without rewriting the authored document. That keeps source concise, lets theme changes work as designed, and avoids freezing presentation details accidentally.
Use explicit values when they carry intent–for example, a fixed size, a known color domain, or a required axis label. Otherwise prefer omission.
Compatibility
Current Szum tools create 2026-09-26 documents. Validation, rendering, save, and update operations also accept the documented subset of 2026-03-20 configs. See older config compatibility for chart mappings, conversion classifications, loss acceptance, and unsupported behavior.
For complete current examples, see the cookbook.