Theming

A theme is the set of CSS custom properties the renderer writes onto the chart wrapper. It covers the HTML chrome around the plot — legend, tooltip, headline, footer, editor UI — and the chart’s default font families. Everything the chart itself draws is on the Styling page.

What you want to change	Where it lives
Marks, grid lines, tick marks, panel border, graph background, axis/tick/data-label type	`styles()` on the spec — Styling
Legend, tooltip, headline, footer, editor UI, default font families	`themeOverrides` on `GraphProvider`
Series colors	the color scale, plus `customPalettes`

Color scheme

colorScheme picks the base token set:

<GraphProvider input={spec} data={data} colorScheme="dark">
  <GraphRenderer />
</GraphProvider>

ColorScheme

default:"light"

'light' or 'dark', exported from @graphysdk/viz-engine.

One prop, two surfaces: the same value decides which half of every { light, dark } stylesheet color and every token() pair resolves inside the plot, and which tones the default palette spreads over touching geoms. A chart switches scheme in one place.

Overriding tokens

themeOverrides is a partial map of theme tokens layered over the base set. Each override is written as a CSS custom property — --graphy-tooltip-background for tooltipBackground, and so on — on the chart’s wrapper element. Most tokens take a CSS string; the measured font token takes a structured object so text measurement and paint stay in sync.

import type { ThemeOverrides } from '@graphysdk/react';

const overrides: ThemeOverrides = {
  fontFamilyDefault: "'Inter', sans-serif",
  fontFamilyHeading: "'Golos Text', sans-serif",
  legendTextColor: '#4A4A4A',
  tooltipBackground: '#111318',
  tooltipBorderRadius: '8px',
  fontLegendLabel: {
    family: "'Inter', sans-serif",
    size: { value: 10.5, unit: 'px' },
    weight: 500,
  },
};

<GraphProvider
  input={spec}
  data={data}
  colorScheme="light"
  themeOverrides={overrides}
>
  <GraphRenderer />
</GraphProvider>;

An omitted field keeps the base theme’s value, so { weight: 600 } on a font token changes only the weight. themeOverrides re-paints without recompiling the spec. The token contract itself is exported as vars, for hosts that would rather write their own CSS against the custom properties:

import { vars } from '@graphysdk/react';

The measured font token

fontLegendLabel is the one measured font token: the legend band is the only region with a font token of its own that the layout solve measures in JS, so it has to be described structurally rather than as a CSS shorthand. Other measured chrome text — the headline, difference arrows — is measured with fontFamilyDefault. Tick, axis, data-label and rule-label type comes from the stylesheet. A structured font override (FontTokenOverride) accepts any subset of:

string

CSS font-family.

number

Numeric font weight.

FontStyle

e.g. 'normal' or 'italic'.

{ value: number; unit: 'px' | 'em' }

Font size.

number

Unitless multiplier; sizes HTML line boxes (canvas measurement ignores it).

Fonts

Font families reach the chart from three places:

fontFamilyDefault and fontFamilyHeading — the chrome’s body and heading families.
The family field of fontLegendLabel — the legend band.
style.axisLabel, style.tickLabel, style.dataLabel and style.geom.rule.label, each taking a fontFamily — the type inside the plot. See Styling.

The SDK references fonts, it doesn’t load them. Load them on the page (via @font-face or a font service) before the first measurement — text measured while a family is still loading is measured with fallback metrics, and the layout keeps those numbers.

What the chrome tokens cover

Category	Tokens
Legend	`legendBackground`, `legendBorderColor`, `legendTextColor`, `legendFocusOutlineColor`, `legendSwatchGap`, `legendPillPaddingInline/Block`, `legendPillBorderWidth`
Tooltip	`tooltipBackground`, `tooltipBorderColor`, `tooltipValueTextColor`, `tooltipBorderRadius`, `tooltipPaddingInline/Block`, `tooltipRowGap`, `tooltipShadow`
Headline	`headlineRowGap`
Hover overlay	`hoverGuideLineColor`, `hoverGuideFillColor`
Annotations	`annotationFrameBorderColor`
Base typography	`fontFamilyDefault`, `fontFamilyHeading`, `fontWeight`, `fontSize`, `fontLineHeight*`, plus per-element shorthands such as `fontPieLabel`
Semantic colors	`textPrimary`, `textSecondary`, `textDisabled`, `iconPrimary`, `iconSecondary`, `border100/50/10`, `defaultBackground`, `raisedBackground`, `sunkenBackground`, `overlayBackground`
Elevation, radii, space	`elevationXs…Lg`, `radiiXs…Lg`, `spaceXxs…Xl`, `zIndex*`
Editor UI	`toolbarBackgroundColor`, `toolbarButtonBackgroundColor`, `toolbarSeparatorColor`, `editorControlHeight`, `fontEditor`

Structural and paint-only tokens

Most tokens only paint. A handful also move layout, because the layout solve reads them in JS and reserves space from the same numbers: legendSwatchGap, legendPillPaddingInline, legendPillPaddingBlock, legendPillBorderWidth, headlineRowGap and fontLegendLabel. Overriding one of those moves reserved space and paint together. Give them a plain pixel length — a value in any other unit is skipped by the layout solve, which keeps the built-in number instead, and reserved space then disagrees with what paints.

Tokens that carry no paint

A few token names describe paint the stylesheet owns. Setting them has no visible effect; reach for the style entry instead.

Token	What actually paints it
`gridLineColor`	`style.gridLine({ color })`
`gridLineWidth`	`style.gridLine({ strokeWidth })`
`axisTickColor`	`style.tickLine({ color })`
`originLineColor`	`style.gridLine` / `style.panelBorder`
`graphBackground`	`style.graph({ background })`
`legendSwatchWidth` / `Height`	`style.legendItem.swatch({ size })`
`legendItemGap`	`style.legend({ gap })`

graphBackground is worth calling out: the renderer resolves the stylesheet’s graph background and writes it into the CSS variable after themeOverrides is applied, so the stylesheet value is what a chart paints.

// paints the background
styles({ defaults: [style.graph({ background: '#0B1020' })] });

Two token namespaces

textPrimary, textSecondary and gridLineColor each name a theme token and a stylesheet token. They are independent tables: the theme’s pair colors HTML chrome text, while the stylesheet’s textPrimary paints axis and data labels and its textSecondary paints tick labels. If you set one by name and nothing moves, check which namespace you reached for.

Series colors

Series colors are not theme tokens. They come from the chart’s color scale, and customPalettes on GraphProvider supplies the host-owned palettes a scale can reference by id:

<GraphProvider
  input={spec}
  data={data}
  customPalettes={{
    brand: [
      { id: 'primary', hex: '#0B5FFF' },
      { id: 'accent', hex: '#E5484D' },
    ],
  }}
>
  <GraphRenderer />
</GraphProvider>

scale.color.palette({ palette: { type: 'custom', id: 'brand' } });

A stylesheet overrides entry that declares color sits above the scale, so it wins over the palette. See Styling.

Styling — the stylesheet on the spec: marks, grid, axes, background
Provider & renderer — where colorScheme, themeOverrides and customPalettes are set

Get Started

Core concepts

Chart types

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

Color scheme

Overriding tokens

The measured font token

Fonts

What the chrome tokens cover

Structural and paint-only tokens

Tokens that carry no paint

Two token namespaces

Series colors

​Color scheme

​Overriding tokens

​The measured font token

​Fonts

​What the chrome tokens cover

​Structural and paint-only tokens

​Tokens that carry no paint

​Two token namespaces

​Series colors

​Related

Color scheme

Overriding tokens

The measured font token

Fonts

What the chrome tokens cover

Structural and paint-only tokens

Tokens that carry no paint

Two token namespaces

Series colors

Related