Customize

Every color of a chart is a CSS custom property, such as --chartlet-accent. A token is that name without its prefix: accent, text, color-1. All five ways below set tokens, so you learn one set of names and choose where to write them down. The guide lists every token.

1. A bundled theme

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

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

chartlet render revenue.json --theme dark
chartlet render release-flow.json --theme blueprint

Monthly revenue

Source: Example data

Show chart data

Data for Monthly revenue
Category	Value
January	120
February	180
March	150

Focus

Show all Commit pushed Code review Build Run tests All green? Fix failures Deploy to staging Approved? Deploy to production Released

From commit to release

Source: Team handbook, release process

Show chart data

Data for From commit to release
Step	Kind	Lane	Group	Leads to
Commit pushed	start	Development		Code review
Code review	step	Development		Build (merged)
Build	step	Continuous integration	Quality gates	Run tests
Run tests	step	Continuous integration	Quality gates	All green?
All green?	decision	Continuous integration	Quality gates	Deploy to staging (yes), Fix failures (no)
Fix failures	step	Development		Build (retry)
Deploy to staging	step	Operations		Approved?
Approved?	decision	Operations		Deploy to production (yes), Code review (changes requested)
Deploy to production	step	Operations		Released
Released	end	Operations

2. Tokens in the specification

tokens sets single colors of one chart, on top of its theme. An unknown name or a value that is not a color is refused with invalid_token.

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

Monthly revenue

Source: Example data

Show chart data

Data for Monthly revenue
Category	Value
January	120
February	180
March	150

3. A theme file for many charts

A theme file names the theme to start from and the tokens that differ. Link it when you render and every chart shares the look, whatever its type; here the same file colors a bar chart, a time series and a flow chart. A specification keeps the last word: a token it sets itself wins over the file.

brand.json

{
  "$schema": "../../schema/chartlet-theme.schema.json",
  "theme": "light",
  "tokens": {
    "text": "#1f2a1f",
    "muted": "#46564a",
    "grid": "#d7e2d3",
    "zero": "#6b7d6f",
    "accent": "#0f766e",
    "color-1": "#0f766e",
    "color-2": "#c2410c",
    "color-3": "#4d7c0f",
    "color-4": "#1f2a1f",
    "role-blue": "#0f766e",
    "role-blue-fill": "#e6f4f1",
    "role-amber": "#b45309",
    "role-amber-fill": "#fff4e0"
  }
}

chartlet render revenue.json --theme brand.json
chartlet render channels.json --theme brand.json
chartlet render release-flow.json --theme brand.json

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

const { content } = renderChart(spec, { theme: brand });

Monthly revenue

Source: Example data

Show chart data

Data for Monthly revenue
Category	Value
January	120
February	180
March	150

Series Direct Partners Marketplace

Revenue by channel

Source: Example data

Show chart data

Data for Revenue by channel
Category	Direct	Partners	Marketplace
Q1	420	180	96
Q2	455	205	88
Q3	480	198	121
Q4	512	236	140

Focus

Show all Commit pushed Code review Build Run tests All green? Fix failures Deploy to staging Approved? Deploy to production Released

From commit to release

Source: Team handbook, release process

Show chart data

Data for From commit to release
Step	Kind	Lane	Group	Leads to
Commit pushed	start	Development		Code review
Code review	step	Development		Build (merged)
Build	step	Continuous integration	Quality gates	Run tests
Run tests	step	Continuous integration	Quality gates	All green?
All green?	decision	Continuous integration	Quality gates	Deploy to staging (yes), Fix failures (no)
Fix failures	step	Development		Build (retry)
Deploy to staging	step	Operations		Approved?
Approved?	decision	Operations		Deploy to production (yes), Code review (changes requested)
Deploy to production	step	Operations		Released
Released	end	Operations

4. The CSS of the host page

A chart inlined in a page reads its colors from the page, so the page can set the same properties. Nothing in the specification changes. This works for HTML and inline SVG; an image or a PDF cannot see the page, which is what ways 2 and 3 are for.

.host .chartlet-root {
  --chartlet-accent: #7c3aed;
  --chartlet-grid: #e4dcf5;
}

Monthly revenue

Source: Example data

Show chart data

Data for Monthly revenue
Category	Value
January	120
February	180
March	150

5. Every chart of a folder, in print too

Because the theme file stays outside the specifications, a folder of charts gets one look with a loop, and changing the file restyles all of them. Tokens also reach the print and social variants and PNG output, which resolve every color to a literal value: the chart below is the print variant with the same file.

for spec in charts/*.json; do
  chartlet render "$spec" --theme brand.json -o "out/$(basename "$spec" .json).svg"
done

import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
import { renderChart } from '@casoon/chartlet';

const brand = JSON.parse(readFileSync('brand.json', 'utf8'));
for (const file of readdirSync('charts').filter((name) => name.endsWith('.json'))) {
  const spec = JSON.parse(readFileSync(`charts/${file}`, 'utf8'));
  const { content } = renderChart(spec, { format: 'svg', theme: brand });
  writeFileSync(`out/${file.replace('.json', '.svg')}`, content);
}