On this page

Guides

Theming

Every color, size and motion setting of a chart is a CSS custom property called --ch-<name>, a token. Import tally-charts/theme.css once and the tokens are defined for the light and the dark theme; change one on any element and every chart below it follows. This page lists the tokens, shows how to aim at a single part of a chart, and explains how to force a theme on part of the page.

Tokens #

The theme tokens change between the light and the dark theme. The values are read from theme.css, so the table is always the shipped one. Default values can be tuned in a minor release, for example to keep a contrast ratio; the names and their meaning are stable.

TokenLightDark
--ch-accent#24356b#7f9be6
--ch-accent-soft#a9b6de#6f80b4
--ch-loss#e8505b#ff6b74
--ch-warn#be802f#ffb24d
--ch-gain#3a93b8#5cc0e6
--ch-neutral#8e8e95#7c7c86
--ch-ink#111114#f4f4f6
--ch-ink-muted#6b6b73#a0a0aa
--ch-grid#e4e4e9#2a2a31
--ch-surface#fafafa#121215
--ch-tooltip-bg#ffffff#1d1d22
--ch-tooltip-ink#111114#f4f4f6
--ch-tooltip-shadow0 1px 2px rgb(0 0 0 / 0.06), 0 6px 20px rgb(0 0 0 / 0.08)0 1px 2px rgb(0 0 0 / 0.4), 0 6px 20px rgb(0 0 0 / 0.5)
--ch-hatch-tint0.140.2

The shared tokens have one value for both themes: sizes, hatching, motion and the sequential ramp.

TokenLightDark
--ch-hatch-angle4545
--ch-hatch-width1.5px1.5px
--ch-hatch-gap66
--ch-share-gap2px2px
--ch-font-numerictabular-numstabular-nums
--ch-radius3px3px
--ch-duration400ms400ms
--ch-easecubic-bezier(0.2, 0, 0, 1)cubic-bezier(0.2, 0, 0, 1)
--ch-dim-opacity0.350.35
--ch-tone-text-mix55%55%

Tokens without a default in theme.css #

These tokens are public too, but theme.css does not declare them for every chart, so they are not in the tables above. Set them on any element to change the charts below it.

  • --ch-zone-marker: the color of the ZoneMeter marker.
  • --ch-seq-base: the base color of the sequential ramp. It defaults to --ch-loss.
  • --ch-seq-mix-1, --ch-seq-mix-2, --ch-seq-mix-3, --ch-seq-mix-4 and --ch-seq-mix-5: the share of the base color in each level.
  • --ch-seq-1, --ch-seq-2, --ch-seq-3, --ch-seq-4 and --ch-seq-5: the five levels, computed from the base and the mixes on every chart, legend and heatmap. Read them, but steer them with the base and the mixes, because overriding them has no effect.
  • --ch-heatmap-cell-height: the height of a Heatmap cell. Default 44px.
  • --ch-heatmap-min-cell: the narrowest a Heatmap column gets before the grid scrolls sideways. Default 56px.

data-ch-seq-tone="<tone>" on an ancestor picks that tone's base and its shares for the current theme. Heatmap's tone prop sets it for you. The attribute must sit on, or below, the element that sets data-ch-theme, or the ramp is computed in the outer theme.

Overriding tokens #

Tokens are inherited, so a style on a container (or a rule in your own stylesheet) reaches every chart inside it. A token can be set to a color, a number or another token: below, --ch-accent is pointed at --ch-loss, and --ch-radius and --ch-hatch-gap are plain numbers. The chart on the left is untouched.

Revenue by month, default tokens
View of Revenue by month, default tokens
Revenue by month, default tokens
MonthRevenue
Jan118
Feb126
Mar141
Apr137
May152
Jun164
Revenue by month, overridden tokens
MonthRevenue
Jan118
Feb126
Mar141
Apr137
May152
Jun164

Colors that follow the theme belong in a token or in var(--ch-*), not in a fixed hex value, or the chart will look wrong in the other theme. The --ch-seq-1 to --ch-seq-5 tokens are computed from --ch-seq-base and the --ch-seq-mix-* tokens, so steer those instead of overriding the computed ones.

Colored text (row and value labels, bridge notes, waffle group labels, pill values) mixes the tone with --ch-ink, so that it stays readable on the surface. --ch-tone-text-mix is the share of the tone in that mix: 55% by default. Raise it for more color, lower it for more contrast.

Parts and state attributes #

To change something a token does not cover, select the part with [data-ch-part="…"], for example tooltip or callout-stem. The part names are stable. The classes ch-* and the --_ch-* variables are private and can change in any release, so never select those.

The state and variant attributes are stable too, names and values:

  • data-ch-tone: the tone of a mark or a piece (accent, accent-soft, loss, warn, gain or neutral).
  • data-ch-fill: how a mark is filled (solid, hatch or hatch-fade).
  • data-ch-active: set on the mark the pointer or the keyboard is on.
  • data-ch-dimmed: set on the marks that are not the active one.
  • data-ch-direction: the way a bar grows (up, down, left or right).
  • data-ch-theme: light or dark, set by you on an ancestor.
  • data-ch-palette: the palette, set by you on an ancestor.
  • data-ch-seq-tone: the tone whose ramp a sequential scale uses.
  • data-ch-level: the step (a number) of a mark in a stepped scale, for example a heatmap cell.
/* Stable: a part, a state attribute and tokens. */
[data-ch-part="tooltip"] {
  --ch-tooltip-bg: #111;
  border-radius: 4px;
}

[data-ch-part="bar"][data-ch-active="true"] {
  opacity: 0.9;
}

/* Fragile: a class and a private variable. */
.ch-tooltip {
  --_ch-swatch-color: red;
}

When there is no part for what you want to change, prefer a token. If neither exists, that is a gap in the public surface and worth an issue, not a reason to reach for a class.

Forcing a theme #

Charts follow prefers-color-scheme until an ancestor sets data-ch-theme="light" or data-ch-theme="dark"; the attribute wins over the system setting, and a nested one wins over an outer one. That makes a dark panel on a light page a single attribute. Give the panel the theme's own --ch-surface and --ch-ink so the box matches the chart.

Active users, in a dark panel
View of Active users, in a dark panel

Next: Palettes swaps three of the tone colors, and Dark mode connects the theme to a toggle in your app.