figure-gate

Two scripts that read a built matplotlib figure and report which gates it fails, and a third that answers the rows that failed. audit(fig) returns (ok, rows), 21 rows, one per gate, each a (label, status, detail) triple where status is True, False, or "warn". check(colors) gates a palette the same way in 5 rows and returns the same shape. suggest(rows) turns the rows that did not pass into remedies, in the order the gates reported them. 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, and python examples/gallery.py covers the harder forms. Writing those eleven found seven defects in the checks themselves.

Documentation

Everything below the quickstart lives on the docs site:

• Getting started: install or vendor, the two settings that need your document's values, and the code to call.
• The gates: what each row measures, its threshold, and what a passing run does not mean.
• The style guide: the measurement behind each threshold, and the rules tried and reverted.
• Choosing a form: the decision no styling rule rescues.
• API reference: signatures and defaults, generated from the scripts when the site builds.

uv add figure-gate          # or: conda install -c conda-forge figure-gate

from figure_gate import check_figure as cf

Copying the files into your own project is the other route, and the default one the docs teach; vendored, the import is import check_figure.

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 the API promises

The public API is every name without a leading underscore in check_figure.py, check_palette.py and suggest_fixes.py. That is broader than the handful you would guess, and it is deliberately the same set the release gate compares, so the statement and the enforcement cannot drift apart.

Below 1.0, a minor bump may break it. Every break is named in the changelog under its release heading, and no change reaches main whose ## Unreleased section fails to name what moved: CI runs audit_api.py against the last tag on every pull request, and a symbol that changed without being written down fails the build.

The number of rows is not part of the contract. The shape is: audit returns (ok, rows), each row a (label, status, detail) triple whose status is True, False or "warn", and check returns the same shape. Gates get added; check_banking arrived after 0.6.0 and moved the count.

What is not enforced is the sentence rather than the symbol. The gate checks that a changed name appears in ## Unreleased next to a word admitting a change. It cannot check that the sentence describes the change accurately.

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.