Color

Use categorical identity, sequential magnitude, and diverging change with themes as the visual baseline.

Themes provide the default categorical, sequential, and diverging colors. Add color policy only when color carries semantic meaning, must remain stable across charts, or must follow a known visual identity.

Choose color by meaning

Color model	Use it for	Legend and interaction
Literal	One intentional color for every mark	No color legend or filtering identity
Categorical	Distinct series, groups, or categories	Discrete legend; identities can be filtered
Sequential	Ordered numeric magnitude from low to high	Continuous legend; not filterable
Diverging	Numeric change around a meaningful midpoint	Continuous legend; not filterable

Column, bar, line, area, and pie charts derive categorical identity from their existing series or category roles. Scatter can instead bind an independent field to categorical, sequential, or diverging color.

Categorical color

Column, bar, line, area, and pie charts derive color identity from their series or categories. The optional color preference controls domain order, explicit colors, and the legend title.

{
  "color": {
    "domain": ["Current", "Previous"],
    "range": ["#23314c", "#b84233"],
    "legend": { "title": "Period" }
  }
}

Every property is optional, so color can carry a single decision such as { "legend": false }.

A literal color for every mark is either one string shared by both schemes or a { light, dark } object. Column, bar, line and area accept it; pie always colors by category.

{ "color": "#23314c" }

{ "color": { "light": "#23314c", "dark": "#9db8e8" } }

An omitted member inherits the selected theme's color for that scheme. Theme palette and continuous-range overrides use complete arrays per scheme; see Themes.

domain fixes semantic identity and order. range assigns colors by domain position. An authored range must cover the complete effective domain; Szum reports an error rather than cycling an incomplete range. Omit the range to let the selected theme provide and extend its palette.

Use an explicit domain when the same series should retain its color across different data subsets or chart updates. A domain value absent from the current rows remains part of the color policy but does not create data.

Scatter color

Scatter makes the encoded field explicit because color may carry information independent from point identity.

Categorical

{
  "color": {
    "type": "categorical",
    "field": "region",
    "domain": ["Americas", "EMEA", "APAC"],
    "range": ["#23314c", "#b84233", "#c2902f"],
    "legend": { "title": "Region" }
  }
}

Sequential

Use sequential color when a numeric field moves from low to high without a meaningful center:

{
  "color": {
    "type": "sequential",
    "field": "growth",
    "domain": [0, 100],
    "range": ["#e8eef6", "#23314c"],
    "format": ".0f",
    "legend": { "title": "Growth" }
  }
}

The sequential domain contains two ascending numbers. An authored range accepts two colors for the endpoints or three colors for the low, middle, and high positions. Omit the domain to derive it from the observed data. Omit the range to use the selected theme's designed colors.

Diverging

Use diverging color when values move in two meaningful directions around a center, such as change from zero, variance from a target, or a positive and negative balance.

domain is required and contains the low and high bounds. midpoint must sit strictly inside that domain. An authored range accepts three colors for the low endpoint, midpoint, and high endpoint. A five-color range adds one inner color halfway along each side of the domain. Omit the range to use the selected theme's designed colors.

 1{
 2  "version": "2026-09-26",
 3  "config": {
 4    "version": "2026-09-26",
 5    "title": "Branch performance against target",
 6    "type": "scatter",
 7    "x": {
 8      "field": "customers"
 9    },
10    "y": {
11      "field": "revenue"
12    },
13    "color": {
14      "type": "diverging",
15      "field": "delta",
16      "domain": [
17        -20,
18        20
19      ],
20      "midpoint": 0,
21      "legend": {
22        "title": "Versus target (%)"
23      }
24    },
25    "xAxis": {
26      "title": "Customers"
27    },
28    "yAxis": {
29      "title": "Revenue (USD thousands)"
30    },
31    "theme": "editorial"
32  },
33  "data": [
34    {
35      "customers": 80,
36      "revenue": 90,
37      "delta": -18
38    },
39    {
40      "customers": 120,
41      "revenue": 130,
42      "delta": -12
43    },
44    {
45      "customers": 150,
46      "revenue": 190,
47      "delta": 4
48    },
49    {
50      "customers": 180,
51      "revenue": 170,
52      "delta": -6
53    },
54    {
55      "customers": 210,
56      "revenue": 270,
57      "delta": 16
58    },
59    {
60      "customers": 250,
61      "revenue": 290,
62      "delta": 9
63    },
64    {
65      "customers": 280,
66      "revenue": 310,
67      "delta": 1
68    },
69    {
70      "customers": 320,
71      "revenue": 390,
72      "delta": 20
73    }
74  ],
75  "presentation": {
76    "background": "opaque",
77    "colorScheme": "system",
78    "systemFallback": "light"
79  }
80}

{
  "version": "2026-09-26",
  "config": {
    "version": "2026-09-26",
    "title": "Branch performance against target",
    "type": "scatter",
    "x": {
      "field": "customers"
    },
    "y": {
      "field": "revenue"
    },
    "color": {
      "type": "diverging",
      "field": "delta",
      "domain": [
        -20,
        20
      ],
      "midpoint": 0,
      "legend": {
        "title": "Versus target (%)"
      }
    },
    "xAxis": {
      "title": "Customers"
    },
    "yAxis": {
      "title": "Revenue (USD thousands)"
    },
    "theme": "editorial"
  },
  "data": [
    {
      "customers": 80,
      "revenue": 90,
      "delta": -18
    },
    {
      "customers": 120,
      "revenue": 130,
      "delta": -12
    },
    {
      "customers": 150,
      "revenue": 190,
      "delta": 4
    },
    {
      "customers": 180,
      "revenue": 170,
      "delta": -6
    },
    {
      "customers": 210,
      "revenue": 270,
      "delta": 16
    },
    {
      "customers": 250,
      "revenue": 290,
      "delta": 9
    },
    {
      "customers": 280,
      "revenue": 310,
      "delta": 1
    },
    {
      "customers": 320,
      "revenue": 390,
      "delta": 20
    }
  ],
  "presentation": {
    "background": "opaque",
    "colorScheme": "system",
    "systemFallback": "light"
  }
}

Edit me!

Do not use a diverging scale merely to add visual variety. Without a meaningful midpoint, sequential color communicates the ordering more honestly.

Scheme-aware authored colors

An individual authored color can be one string used in both schemes or an object with independent Light and Dark members:

{ "color": { "light": "#23314c", "dark": "#9db8e8" } }

Chart-level categorical and continuous ranges apply that same choice at each position:

{
  "color": {
    "domain": ["Current", "Previous"],
    "range": [
      { "light": "#23314c", "dark": "#9db8e8" },
      { "light": "#b84233", "dark": "#ff8f7d" }
    ]
  }
}

When one position omits the active scheme, the selected theme supplies the color at that position. The authored range must still contain enough positions to cover the complete categorical domain.

Theme palette and continuous-range overrides use a different boundary: each scheme owns one complete collection. See Themes for that shape and its fallback behavior.

Legend visibility and title

The color channel owns legend. Use true to show it with default settings, { title: "…" } to show and title it, or false to hide it. Omit the preference for automatic behavior. Scatter size.legend uses the same convention.

Automatic display shows a useful categorical or continuous legend when color encodes meaning. A categorical legend becomes redundant when direct labels identify every observed series or category; continuous legends remain available because their gradient communicates a quantitative scale. Hiding a legend does not remove color encoding or categorical filtering identity.

Interactive legend filtering applies only to categorical color. It recompiles the visible chart while preserving the complete authored color domain, so hidden identities retain their colors when restored.

Literal colors

Source data is not treated as CSS merely because a field contains values such as "#ff0000". A categorical color field still treats that string as an identity, while sequential and diverging color fields require numbers. Explicit presentation colors belong in color, range, or themeOverrides.

This separation avoids accidental presentation changes when source strings change and keeps validation able to distinguish data from design policy.

Automatic behavior

Domain order controls stable assignment and legend order.
Missing categorical color values are diagnosed rather than silently merged with a real category.
Authored categorical ranges cover the complete effective domain; theme palettes extend when more colors are needed.
Interactive legend filtering uses the same series or category identity as static labels and Figma groups.
Sequential domains may derive from observed values; diverging domains and midpoints remain explicit.
Light and Dark presentation resolve paint before rendering without changing authored domains or filtering identity.

See Themes for every built-in palette and theme override property.

On this page