Customize the look

Every color of a chart is a CSS custom property on its root, --chartlet-accent, --chartlet-text and so on. A token is such a property without its prefix: accent, text, color-1. All the ways to restyle a chart set tokens; they differ in where you write them down.

Way	Where	Use it for
Bundled theme	"theme": "dark" or --theme dark	A ready-made palette
Tokens in the specification	"tokens": { … }	One chart that needs its own colors
Theme file	--theme brand.json, the theme option	Many charts that share a look
Host-page CSS	.report .chartlet-root { --chartlet-accent: … }	Charts inlined in a page that owns its colors
Layer colors	"color" on a layer of a time chart	One series in one chart

Tokens change colors only. Layout, text, data and the accessible description stay as they are.

Bundled themes

light (the default), dark and, for diagrams, blueprint ship with chartlet as theme files, the same kind of file you write yourself. Choose one in the specification or when rendering:

{ "schemaVersion": 1, "type": "bar", "title": "Monthly revenue", "theme": "dark", … }

chartlet render revenue.json --theme dark

The files are in themes/ of the repository and list every token with its value. Copy one as the start of your own.

Tokens in the specification

tokens sets single colors of one chart, on top of its theme:

{
  "schemaVersion": 1,
  "type": "bar",
  "title": "Monthly revenue",
  "tokens": { "accent": "#c2410c", "grid": "#e7d9cf" },
  "data": [ … ]
}

A value is a hex color (#rgb, #rrggbb, #rrggbbaa) or rgb()/rgba() with numbers. An unknown name or another value is refused: invalid_token at /tokens/<name>.

A chart with a background token paints that background itself, as a dark chart does, so that the SVG stands alone on any page.

Theme file

A theme file is a JSON file with a theme to start from and the tokens that differ:

{
  "$schema": "https://raw.githubusercontent.com/casoon/chartlet/main/schema/chartlet-theme.schema.json",
  "theme": "light",
  "tokens": {
    "text": "#1f2a1f",
    "accent": "#0f766e",
    "color-1": "#0f766e",
    "color-2": "#c2410c"
  }
}

Render any number of specifications with it, and they share one look:

chartlet render revenue.json --theme brand.json

import { renderChart } from '@casoon/chartlet';
import brand from './brand.json' with { type: 'json' };

renderChart(spec, { theme: brand });      // a theme file as an object
renderChart(spec, { theme: 'dark' });     // a bundled theme by its name

<Chart theme={brand} … /> takes the same, and so does the theme input of the chartlet_render tool. --watch reads the file again whenever the chart is rendered.

A theme file only fills in what a specification leaves open: a theme or a token the specification names itself wins. A token that equals what the chart’s theme already gives is left out of the output, so --theme dark adds nothing to a dark chart.

Host-page CSS

Charts rendered as HTML or inline SVG read their colors from the page, so a page can set the same properties itself:

.report .chartlet-root {
  --chartlet-accent: #0f766e;
  --chartlet-text: var(--color-text);
}

A dark chart keeps its palette on .chartlet-root.chartlet-theme-dark; add the class to your selector to override it. A token written in the specification is addressed by the chart’s ID and wins over such a rule. A chart as an <img> or in a PDF cannot see the page’s CSS; use tokens there.

Layer colors

A layer of a time chart names its own color, "color": "#0f766e", or one of the page, "color": "var(--brand, #0f766e)". This colors that layer only and works next to everything above.

Which tokens exist

Tokens	Colors
text, muted, grid, zero, accent, background	Text, secondary text and axis labels, grid lines, the zero line, the accent of single-series marks, the chart’s ground
color-1 … color-4	The series palette: bars, lines and groups
role-blue, role-green, role-amber, role-teal, role-violet, role-gray, role-red, each also with -fill	Stroke and fill of the roles in diagrams
node, lane, lane-head, shadow	Boxes, lanes and shadows of diagrams
heat-0 … heat-5	The scale of node values in diagrams
diverging-0 … diverging-16	Warming stripes and calendar heatmaps
rise, fall	Candlesticks
net-5 … net-8, parl-5 … parl-8, part-5 … part-8	Further groups of networks, parliaments and architecture perspectives

A token a chart does not use has no effect. The JSON Schemas list the names: chartlet.schema.json for tokens in a specification, and chartlet-theme.schema.json for a theme file.

Print, social images and PNG

Tokens are resolved like the theme’s own colors, so the print and social variants and PNG output carry them, which CSS of the host page cannot do:

chartlet render revenue.json --theme brand.json --variant print -o revenue.print.svg

Contrast

The bundled palettes keep their contrast ratios on their own backgrounds (see Support). Colors you set are measured: a pair that lies on top of each other in the chart, with at least one color from tokens, and a ratio below WCAG 2.2’s is reported as low_contrast at the token. The chart is still rendered.

Pair	Needs	Measured
text, muted on background	4.5:1	Always
accent on background	3:1	Bar and line charts with one series
color-1 … color-4 on background	3:1	The series a bar, line or time chart draws
A role’s outline on its fill and on background, text on its fill	3:1, 3:1, 4.5:1	Diagrams, for the roles the diagram draws

A translucent color is measured as it looks over the background. Colors of other chart types, such as the scales of stripes and calendars, are not measured.