Scales and axes

Scale choices belong to semantic field roles. Axis preferences control how the resulting scale is presented. Keeping those decisions separate prevents an axis setting from changing what the data means.

Family defaults

Omit scale for the family default:

• column and bar categories use band; values use linear and include zero;
• line categories use band; values use linear without forcing zero;
• area categories use band; values use linear and include zero;
• scatter x and y use linear.

Set an explicit scale when the source field carries different intent.

Family semantics restrict invalid combinations. Column and bar categories may use band or UTC while their value roles stay linear; line and area categories may use band, UTC, linear, or log; area values stay linear; line values may use UTC, linear, or log; scatter roles may independently use band, UTC, linear, or log. Inferred column, bar, and area value domains include zero.

Dates and time

Use utc when chronological distance matters:

{
  "category": {
    "field": "date",
    "scale": { "type": "utc" },
    "format": "%b %d"
  },
  "categoryAxis": { "format": "%b %d" }
}

Date strings are parsed as UTC rather than local browser time, keeping server images, embeds, and Figma output consistent. Year strings such as "2026" are treated as years; %Y formats annual ticks.

UTC columns and bars derive one consistent width from the minimum adjacent observed temporal distance and leave missing periods as visible gaps. Existing spacing.category and grouped spacing.series controls still apply. This keeps ordinary temporal bars concise without adding interval, binning, or time-unit syntax. A line may also use UTC on its value role when the vertical measure is itself a date or time.

Logarithmic scales

Use log only for positive finite values. It is useful when ratios or orders of magnitude matter more than absolute distance.

{
  "type": "scatter",
  "x": { "field": "parameters", "scale": { "type": "log" } },
  "y": { "field": "compute", "scale": { "type": "log" } }
}

Zero and negative values are invalid on a log role. Column, bar, and area value roles reject log because their filled geometry encodes distance from a baseline.

Axis preferences

Cartesian families expose categoryAxis and valueAxis; scatter exposes xAxis and yAxis.

{
  "values": {
    "type": "long",
    "field": "revenue",
    "scale": { "type": "linear", "domain": [0, 100], "nice": false }
  },
  "valueAxis": {
    "title": "Revenue ($M)",
    "format": ".0f"
  }
}

Omit the axis preference to use Szum's defaults. Set it to true to show default settings, or provide an object such as { title: "Revenue" } to show customized settings. Set it to false to hide the axis without removing its scale from layout or semantics. Configuration objects do not need a display property.

Axis lines and plot border

Set line on a visible axis to show or hide its line independently of ticks, labels, and grids. Set plotBorder on a Cartesian config to show or hide the full rectangle around the plotting area:

{
  "categoryAxis": { "line": false },
  "valueAxis": { "line": true },
  "plotBorder": false
}

Scatter uses xAxis.line and yAxis.line. Pie has no axis-line or plot-border settings. Omit a setting to follow the theme: Technical supplies a full border; Noir supplies none.

A visible plot border includes all four edges even when an axis or its line is hidden. Hiding the border leaves independently visible axis lines in place. Overlapping edges draw once. Both use the theme's axis stroke color and width, customizable through themeOverrides.colors.axes.line and themeOverrides.axes.lineWidth.

Axis-line and plot-border visibility are available on every plan. Custom stroke colors and widths use the existing paid theme-customization feature.

Explicit domains

Continuous domains use a two-number extent. Band domains use an array of category values. An explicit domain is appropriate when charts must share a comparison frame or when domain order is part of the story.

A continuous domain crops the chart without removing data. Lines and areas keep their true crossings; bars and intervals are cut at the window edge. Cropping does not recalculate stacks, percentages or statistics. Labels attached outside the window are omitted. Tooltips retain original values for visible observations and partially visible bars; crossings do not create interpolated observations.

Do not use a clipped domain to exaggerate column, bar, or area differences. Szum preserves an explicit compatible domain exactly but emits a non-blocking warning when a length-encoding value domain excludes zero. MCP actions require the user to approve that exact warning; raw HTTP callers should review it after validation. Line and scatter may use non-zero domains when doing so is analytically honest.

Visible references contribute to automatic continuous domains by default, so a benchmark remains visible after filtering reduces the data extent. Set contributeToDomain: false on a reference to keep the automatic domain data-driven. Explicit domains and normalized-share bounds always win; an out-of-range reference is omitted without an automatic footnote. Reference statistics are calculated before domain contribution, and references never become observations. Text annotations do not expand automatic domains.

Tick formatting

Numeric ticks and values use D3 format syntax. Common forms include:

• ",.0f" – grouped whole numbers;
• ".1f" – one decimal place;
• ".2~s" – compact SI notation;
• ".0%" – a fraction displayed as a percentage.

UTC axes use D3 time-format syntax, such as %Y, %b, or %b %d.

Role format controls values used by labels and tooltips. Axis format controls axis ticks. Set both when the two contexts need the same explicit presentation; otherwise let Szum choose an automatic format for each.

Automatic behavior

Szum validates field compatibility, derives the observed domain, applies the chart type's baseline rule, and includes compiled stack extents and eligible reference values. It may expand automatic continuous domains to readable bounds; explicit domains retain their authored bounds. Tick density adapts to the available space without deleting source rows or changing the scale.