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 cycler

Quick 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: ![Chart title](chart.png)
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.chart manifest.json specification.

chart-designer