Chart Designer
A design-system for matplotlib charts. You get brand colors, typography, and named figure sizes — then write standard matplotlib code for everything else.
Dependencies
uv pip install matplotlib numpy cyclerQuick Start
import sys; sys.path.insert(0, "scripts")
from chart_theme import load_theme
import matplotlib.pyplot as plt
theme = load_theme(brand_path="path/to/brand-decathlon")
with theme.apply():
fig, ax = plt.subplots(figsize=theme.sizes["full-width"])
ax.bar(["Q1", "Q2", "Q3", "Q4"], [120, 150, 180, 210],
color=theme.palette.categorical[:4])
ax.set_title("Revenue by Quarter")
fig.savefig("chart.png")
plt.close()How It Works
1. load_theme() — Load brand tokens
from chart_theme import load_theme
theme = load_theme(brand_path="path/to/brand-decathlon")
# Reads manifest.json → tokens.chart → palette, typography, axis, grid
# Without a brand kit, returns sensible defaults.2. theme.apply() — Activate brand rcParams
with theme.apply():
fig, ax = plt.subplots(...)
# Inside this block, matplotlib uses brand fonts, colors, grid style.
# All standard matplotlib code works — bar, plot, scatter, imshow, etc.
fig.savefig("output.png")
# Outside the block, rcParams are restored to previous values.3. theme.sizes — Named figure dimensions
fig, ax = plt.subplots(figsize=theme.sizes["full-width"])Pre-defined sizes optimized for A4 PDF integration. See the table below.
API Reference
load_theme(brand_path=None, dpi=200) → ChartTheme
Loads a brand kit's manifest.json and returns a configured theme. Pass None for sensible defaults without a brand kit.
ChartTheme
| Attribute | Type | Description |
|---|---|---|
palette | BrandPalette | Color palettes (categorical, sequential, diverging) |
rcparams | dict | matplotlib rcParams dict (applied by theme.apply()) |
sizes | dict | Named figure size tuples — see table below |
dpi | int | Output resolution (default 200) |
brand_name | str | Brand name from manifest |
BrandPalette
| Attribute / Method | Description |
|---|---|
categorical | list[str] — 8 hex colors for discrete series |
sequential | list[str] — 7 hex colors light→dark |
diverging | list[str] — 7 hex colors neg↔pos |
highlight | str — call-out emphasis color |
highlight_contrast | str — text on highlight background |
categorical_colormap() | ListedColormap from categorical palette |
sequential_colormap() | LinearSegmentedColormap from sequential palette |
diverging_colormap() | LinearSegmentedColormap from diverging palette |
Figure Sizes
Named sizes optimized for A4 PDF integration (25mm margins):
| Name | Width × Height | Use case |
|---|---|---|
full-width | 6.29" × 3.93" | Default, spans content area |
full-width-tall | 6.29" × 5.24" | Complex charts needing height |
half-width | 3.0" × 2.5" | Side-by-side pairs |
two-thirds | 4.19" × 3.0" | Medium placement |
square | 4.0" × 4.0" | Pie, donut, heatmap |
spark | 3.0" × 1.0" | Inline sparkline |
PDF Factory Integration
- Generate chart PNG using this skill
- Reference the PNG in your markdown:
 - Render the document with pdf-factory — the image is embedded automatically
- SVG output is also supported and will be auto-converted to PNG by pdf-factory
Use <figure> and <figcaption> for captioned charts:
<figure>
<img src="chart.png" alt="Revenue by Quarter">
<figcaption>Figure 1: Quarterly revenue growth (FY 2026)</figcaption>
</figure>QA Checklist
After generating any chart, open the output image and verify:
- Labels readable — No overlapping text on any element: axis labels, tick labels, legends, annotations, pie/donut category names, percentage values. If labels overlap, adjust the chart type, font size, rotation, or layout
- Data accurate — Values in the chart match the source data; spot-check at least two data points
- Legend clear — Multi-series charts have a legend with all series labeled
- No clipping — Title, subtitle, axis labels, and legend are fully visible, not cut off at edges
- Contextual fit — Chart type suits the data story (don't use pie for > 6 categories; use horizontal bar for long labels)
- Brand consistent — When using a brand kit, chart uses brand palette and typography
References
- Chart type cookbook — Read when implementing a specific chart type. Complete matplotlib examples for bar, line, pie, scatter, heatmap, and more.
- Chart token schema — Read when creating a custom brand kit or debugging token resolution. Full
tokens.chartmanifest.json specification.