figure-gate

Two scripts that read a built matplotlib figure and report which gates it fails. audit(fig) returns (ok, rows) — 19 rows, one per gate, each a (label, status, detail) triple where status is True, False, or "warn". check(colors) does the same for a palette in 5 rows. Every threshold is a module-level constant you can read and change.

There is also an Agent Skill wrapper that applies the same checks when Claude Code builds a figure.

git clone https://github.com/narenp12/figure-gate && cd figure-gate
python skill/scripts/check_palette.py "#E69F00,#56B4E9,#009E73" --pairs all
python skill/scripts/check_figure.py     # self-test on a broken figure

python examples/demo.py builds that figure and audits it, with every decision commented against the failure it avoids. python examples/gallery.py covers the harder forms: a shared-axis grid, a filled field with a colorbar, an axis-free schematic, three statistical forms, a log-log convergence plot with a slope triangle, and a dense attractor. Writing those six found five defects in the checks themselves.

Why the two scripts talk to each other

A figure on matplotlib's default tab10 cycle, with a twinx second axis, returned 19 passing rows from the composition checks. check_palette.py rated that same cycle's orange and green at dE 1.4 under protanopia — one hue to that reader, against a floor of 8. The composition checker had no access to the colors it was drawing.

check_series_color closes that. It reads the hues off the figure's own artists, decides from the mark types whether the figure needs adjacent separation (lines, bars) or all-pairs separation (scatter), and runs them through the palette gates. That is row 11 of the 19.

What each gate measures

check_palette.py — takes hex strings on the command line or via check(), imports nothing outside the standard library. Distances are OKLab dE x100.

--ordinal swaps those five rows for four that apply to a ramp: lightness monotone, adjacent dL gap, light-end contrast, and step uniformity (largest/smallest dL). Protanopia and deuteranopia are gated, together about 8% of males. Tritan separation is measured and printed in the detail string but not gated: prevalence is around 0.01%, and the Vienot matrix used here is validated only for the red-green forms, so the number is indicative rather than decisive.

check_figure.py — renders the figure through an Agg canvas and measures the result. audit() returns these 19 rows in this order.

Thresholds cite a published floor where one exists — SIAM's one point, WCAG's 4.5:1, the Nature/Science/PNAS type minima. The rest were measured, and skill/references/style-guide.md records the measurement and the figure that motivated each one.

The gate that catches people

Type size is measured on the printed page, not on the canvas. A figure authored at 14 inches (1008pt) and placed on a 750pt slide renders at 750/1008 = 0.74x, so a 9pt label arrives at 6.7pt — under the 7.5pt floor, and under it by an amount no one notices on a monitor. page_scale derives that ratio per figure and the type gate measures what renders, so sizes set through rcParams or by a helper are caught along with the ones set inline.

Placing at a fraction of the content width changes the ratio again: audit(fig, placed_frac=0.48) mirrors \includegraphics[width=0.48\textwidth], and without it a half-width figure is certified at twice the type size it ships at. For a venue in the table, audit(fig, venue="neurips") supplies the width; python check_figure.py --venues prints all twelve with their content widths in points.

Install

Copy three files. check_palette.py needs only the standard library; check_figure.py needs matplotlib; scipy is optional and changes only speed (check_overplotting uses a KD-tree when scipy imports and an O(n^2) numpy path when it does not).

git clone https://github.com/narenp12/figure-gate
cp figure-gate/skill/assets/figure.mplstyle       your-project/diagrams/
cp figure-gate/skill/scripts/check_palette.py     your-project/diagrams/
cp figure-gate/skill/scripts/check_figure.py      your-project/diagrams/

Installing instead of vendoring pins a version and puts the same two checkers on PATH as check-palette and check-figure:

uv add figure-gate          # or: uv tool install figure-gate

Copying is the default because a vendored checker is one you can read and edit beside the figures it gates, and the thresholds are meant to be edited.

Two settings need your document's values:

1. font.serif in figure.mplstyle — your document's body typeface.
2. CONTENT_WIDTH_PT at the top of check_figure.py — the usable width of the page, in points. Left None, the scale is 1.0 and the page calculation does nothing, which is correct if you author each figure at the width it is placed at. venue= overrides it per call.

As a Claude Code skill

cp -r figure-gate/skill ~/.claude/skills/research-figures

Claude then runs these checks when you ask for a figure for a paper or a deck. skill/SKILL.md is the workflow; skill/references/style-guide.md is the measurement behind each threshold.

Use it

from pathlib import Path

import numpy as np
import matplotlib
matplotlib.use("agg")
import matplotlib.pyplot as plt
from matplotlib import colormaps

from check_figure import report

plt.style.use(str(Path(__file__).parent / "figure.mplstyle"))

x = np.linspace(0, 12, 300)
y = np.exp(-0.12 * x)

okabe = colormaps["okabe_ito"]          # matplotlib >= 3.11
fig, ax = plt.subplots(figsize=(7, 4), constrained_layout=True)
ax.plot(x, y, color=okabe(1))           # line width comes from the sheet

report(fig, "my-figure")                # prints 19 rows, returns True if ok

Two details that are load-bearing. The style sheet is resolved relative to __file__, because plt.style.use("figure.mplstyle") resolves against the working directory and breaks the first time a test runner or build script invokes the module from elsewhere. And the backend is set explicitly: the checks measure rendered geometry, and the examples in this repository all call matplotlib.use("agg") before importing pyplot for that reason.

audit is the same checks without the printing, which is what a test wants:

from check_figure import audit

@pytest.mark.parametrize("name", sorted(FIGURES))
def test_figure_is_composed(name):
    ok, rows = audit(build(name))
    assert ok, "\n".join(f"{k}: {d}" for k, s, d in rows if not s)

Where this sits

Prescriptive style sheets already exist and are good: SciencePlots and LovelyPlots for journal looks, tueplots and mpl_sizes for exact conference sizing. Accessibility tooling exists too: matplotalt generates alt text, Chart4Blind converts a chart image into an accessible one, contrast reporters check colors in isolation.

Each of those acts before or beside the figure. None of them reads the built result and reports what it fails, which is the only thing here — so a style sheet and this are complementary: set defaults with one, verify them with the other.

What it does not do

Every check is an elimination gate: each one forbids a single enumerated failure, and none looks at the figure as a whole. 19 passing rows means the figure avoids 19 named defects. It does not mean the figure is good, and the checker cannot see that an arrow points at the wrong object, that reading order runs backwards, or that a label is true of the concept and false of the curve beside it. Render it and look at it.

The rules also do not transfer to interactive web charts, where hover, responsive reflow and dark mode change most of the constraints.

Design notes

Use what matplotlib ships. viridis for sequential, RdBu for diverging, okabe_ito for categorical, style sheets for defaults, constrained_layout for layout. Earlier versions hand-rolled all four and each was worse: RdBu's poles clear every gate in check_palette.py unmodified, and a windowed custom ramp discarded 35% of viridis for no measured gain.

WARN is not FAIL. Five rows are advisory. A sub-3:1 hue is legal when it carries a direct label; a heatmap panel legitimately measures 0.98 ink coverage. Failing those would train people to ignore the row, and an ignored gate is worth less than no gate.

Gates are tested for their ability to fail. The suite is 166 tests, and each check has one asserting it catches a figure with exactly that defect. The style sheet has its own tests because # starts a comment in matplotlib's style format: grid.color: #e1e0d9 parses as an empty value, matplotlib keeps its default, and every other test stays green.

The full reasoning — measurements behind each threshold, and the rules that were tried and reverted — is in skill/references/style-guide.md.

Which form the data wants is the decision no styling rule rescues, and it is in skill/references/choosing-a-form.md, built on Cleveland & McGill's ordering of the elementary perceptual tasks. Only its mechanical subset is gated: a script can rule out a pie or a truncated bar baseline, but it cannot tell you a box plot is hiding an n of 8.

Requirements

• check_palette.py — Python 3.8+, standard library only. Tested on 3.8, 3.9, 3.11 and 3.13. Copied, it runs on 3.8; installed from PyPI it does not, because the package carries check_figure.py too and that needs 3.9.
• check_figure.py — Python 3.9+, matplotlib 3.8+.
• colormaps["okabe_ito"] needs matplotlib 3.11+. On older versions the palette is eight hex strings, listed in the style guide.

Those are the versions CI runs the palette checker on, with no pip install at all, because "standard library only" is a load-bearing claim. The test job runs against the current matplotlib and pins one row to 3.8.4, so a break in either direction shows up.

Contributing

New gates are welcome at the bar the project holds itself to: a test proving the gate fails on a figure with that defect, a test proving it does not over-fire on the nearest legitimate case, and a note naming the real failure that motivated it. See CONTRIBUTING.md and SECURITY.md.

License

MIT — see LICENSE.