figure-gate¶
figure-gate reads a matplotlib figure you have already built and tells you which publication requirements it fails. It checks colorblind-safe color, composition, and whether your type is still legible at the size the figure prints.
report(fig) prints one line per check:
Composition audit
[FAIL] Clipping clipped: ['x', 'y'] [FIX] add constrained_layout or widen the figure
[PASS] Type size smallest 10.0pt on page (floor 6.0)
[WARN] Alt text no description attached [FIX] describe(fig, "...") ...
...
-> FIX THE MARKED CHECKS
Thirteen rows can fail a build. The other eight are advisory: they report WARN
and never FAIL. For a program rather than a person, audit(fig) returns
(ok, rows), 21 rows, one per check, each a (name, status, detail) triple, and
audit_json(fig) serialises the same verdict.
figure-gate verifies figures. It does not draw them, restyle them, or judge whether a figure is good. Each check forbids one named defect, so a figure that passes every row has avoided 21 named defects and nothing more.
Every threshold is a module-level constant you can read, change, or set from a
figure-gate.toml.
Try it¶
pip install figure-gate # or: uv add figure-gate
check-palette "#E69F00,#56B4E9,#009E73" --pairs all
check-figure # self-test on a deliberately broken figure
check-figure prints a failing report and exits 0: its self-test passes only
when the checker rejects the broken figure.
Copying the scripts in works too, and is the route if you want the thresholds beside the figures they gate. The install page covers all three routes.

python examples/demo.py builds that figure and audits it.
python examples/gallery.py builds the harder forms. Writing those
twenty-four exposed defects in the checks themselves, listed on the
gallery page.
Documentation¶
The documentation site is organised by what you came to do.
Learning¶
Start here if you have not run the checkers before:
- Gate your first figure: build a figure that fails, read the report, make it pass
Doing a task¶
Step-by-step directions for a goal you already have:
- Install figure-gate: copy the scripts, install the package, or install from conda-forge
- How-to guides: fix a failing row, gate a test suite, place at half width, attach alt text
Looking something up¶
What each check measures and what each function takes:
- The gates: every row, its threshold, and whether it can fail a build
- Commands: both command-line tools, their flags, and their exit codes
- Compatibility: Python and matplotlib floors, optional dependencies, import lines by version
- API reference: signatures and defaults, generated from the scripts when the site builds
Understanding why¶
Background, evidence, and the decisions behind the thresholds:
- How the checkers decide: the measurement model, the evidence, and what a passing run does not mean
- Figure style guide: the measurement behind each threshold, and the rules tried and reverted
- Choosing a form: the decision no styling rule rescues, built on Cleveland and McGill's ordering
- Gallery: twenty-four audited figures covering the forms that are hard to check
Use it with Claude Code¶
This repository is also a plugin marketplace, so Claude Code applies the same checks when it builds a figure for you. See Install it as a Claude Code skill.
Where this sits¶
Style sheets set a figure's defaults before it is drawn: SciencePlots and LovelyPlots for journal looks, tueplots and mpl_sizes for conference page sizes. Accessibility tools work from the finished chart: matplotalt generates alt text, and Chart4Blind converts a chart image into an accessible one. None of them reports which requirements a built figure fails.
vislint_mpl did, in 2018 (McNutt & Kindlmann). It took the figure and axes objects and listed the rules they failed, each with a reason. It was a research prototype; its repository is archived.
Set the defaults with a style sheet, then check the result with figure-gate.
Stability¶
Below version 1.0, a minor release may break the public API, and every break is named in the changelog. The version policy says what the public API covers.
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.
- A note naming the real failure that motivated it.
See CONTRIBUTING.md and SECURITY.md.
Citing¶
@software{prakash_figure_gate,
author = {Prakash, Naren},
title = {figure-gate},
doi = {10.5281/zenodo.21784217},
url = {https://github.com/narenp12/figure-gate}
}
License¶
MIT. See LICENSE.